Important
This repository contains software that is currently in the Beta stage.
SSH configuration generator based on your Ansible hosts YAML file.
Current version: v0.7.3
- Generates a
config
file to merge with your existing SSH configuration or include as a separate.conf
file (since v0.6.0). - Custom configuration for ssh-agent.
- Custom SSH aliases for quick connections.
- Skip selected hosts from results file.
pip install --user git+https://github.com/pythoninja/[email protected]
Or
pip install --user sshgen
pipx install git+https://github.com/pythoninja/[email protected]
Or just run without installing:
pipx run sshgen
Before using this tool, make sure you have an Ansible hosts.yml
in your current working directory.
Consider the following example hosts.yml
file, which defines 2 host groups with a total of 4 hosts:
group1: # host_group
hosts:
host1: # host
ansible_host: 127.0.0.1
ansible_user: root
_meta:
_auth_type: IdentityAgent
_auth_path: ~/.1password/agent.sock
_aliases: [ "base", "another-alias" ]
_skip: false
host2:
ansible_host: 127.0.0.2
ansible_user: manager
ansible_password:
ansible_port: 19020
_meta:
_skip: true
group2:
hosts:
host3:
ansible_host: 172.19.0.1
ansible_user: postgres
ansible_password:
ansible_port: 19222
host4:
ansible_host: 172.99.99.99
ansible_user: postgres
_meta:
_auth_type: IdentityAgent
_auth_path: ~/.1password/agent.sock
_aliases: [ "base", "another-alias" ]
_skip: false
To use sshgen
, you can either invoke it as a Python module using python -m sshgen --help
or directly use the
command sshgen --help
.
By default, sshgen
looks for the hosts.yml
file in your current working directory. To generate the SSH
configuration, run the following command:
sshgen generate
To display addition logs (verbose mode), add --verbose
flag:
sshgen --verbose generate
Or use SSHGEN_DEBUG=1
(SSHGEN_VERBOSE=1
) environment variable (since v0.5.0):
SSHGEN_DEBUG=1 sshgen generate
After executing the command, you will see the following output:
[2024-03-10 10:00:00] [INFO] - Generated SSH config file was saved to /my_dir/config
[2024-03-10 10:00:00] [INFO] - Total processed hosts: 3, total skipped hosts: 1
Check the file contents cat /my_dir/config
:
Host host1 base another-alias # group1
HostName 127.0.0.1
User root
Port 22
IdentityAgent ~/.1password/agent.sock
Host host3 # group2
HostName 172.19.0.1
User postgres
Port 19222
IdentityFile ~/.ssh/ssh_key
IdentitiesOnly yes
Host host4 postgres-server # group2
HostName 172.99.99.99
User postgres
Port 22
IdentityAgent ~/.1password/agent.sock
If you run using verbose mode, you should see additional information:
Verbose output example
[2024-03-10 10:00:00] [DEBUG] - Loading ansible hosts file: /home/user/code/python/sshgen/examples/hosts.yml
[2024-03-10 10:00:00] [DEBUG] - Total hosts found (include skipped): 4
[2024-03-10 10:00:00] [DEBUG] - Using template file /home/user/code/python/sshgen/sshgen/templates/ssh_config.template to generate ssh config
[2024-03-10 10:00:00] [DEBUG] - Filtering hosts where _skip metafield was defined
[2024-03-10 10:00:00] [DEBUG] - Host host1 should be skipped: False
[2024-03-10 10:00:00] [DEBUG] - Host host2 should be skipped: True
[2024-03-10 10:00:00] [DEBUG] - Host host3 should be skipped: False
[2024-03-10 10:00:00] [DEBUG] - Host host4 should be skipped: False
[2024-03-10 10:00:00] [DEBUG] - Processing host1 from group group1
[2024-03-10 10:00:00] [DEBUG] - Adding SSH port 22 for host host1
[2024-03-10 10:00:00] [DEBUG] - Adding aliases ['base', 'another-alias'] for host host1
[2024-03-10 10:00:00] [DEBUG] - Adding custom auth methods for host host1
[2024-03-10 10:00:00] [DEBUG] - Processing host3 from group group2
[2024-03-10 10:00:00] [DEBUG] - Adding SSH port 19222 for host host3
[2024-03-10 10:00:00] [DEBUG] - Processing host4 from group group2
[2024-03-10 10:00:00] [DEBUG] - Adding SSH port 22 for host host4
[2024-03-10 10:00:00] [DEBUG] - Adding aliases ['base', 'another-alias'] for host host4
[2024-03-10 10:00:00] [DEBUG] - Adding custom auth methods for host host4
[2024-03-10 10:00:00] [INFO] - Generated SSH config file was saved to /home/user/code/python/sshgen/config
[2024-03-10 10:00:00] [DEBUG] - Skipped hosts list: 127.0.0.2
[2024-03-10 10:00:00] [INFO] - Total processed hosts: 3, total skipped hosts: 1
There are two ways to use the generated file:
- Copy and insert the output into your
~/.ssh/config
file. - Copy file to the conf directory, e.g.
~/.ssh/config.d/00-custom.conf
(if it's not exist, create one). Edit your~/.ssh/config
and addInclude
directive to the top:
#### Custom configuration
Include ~/.ssh/config.d/*.conf
#### End of custom configuration
After that, you can use any of the defined aliases to SSH
into the corresponding hosts. For example, running ssh base
will connect you to the host with the IP address 127.0.0.1
as the root user and utilizing 1password as your SSH agent.
For more examples, please refer to the examples directory.
There are no specific requirements for usage and distribution. For more information, refer to the LICENSE.
For the changelog, please see CHANGELOG.md.