Skip to main content

sshgen

SSH configuration generator based on your Ansible hosts YAML file.

Current version: v0.9.0

Table of Contents

Features

  1. Generates a config file to merge with your existing SSH configuration or include as a separate .conf file (since v0.6.0).
  2. Custom configuration for ssh-agent.
  3. Custom SSH aliases for quick connections.
  4. Skip selected hosts from results file.

Installation

Using pip

pip install --user git+https://github.com/pythoninja/sshgen@v0.9.0

Or

pip install --user sshgen

Using pipx

pipx install git+https://github.com/pythoninja/sshgen@v0.9.0

Or just run without installing:

pipx run sshgen

(Go to top)

Usage

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:

  1. Copy and insert the output into your ~/.ssh/config file.
  2. 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 add Include 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.

(Go to top)

License

There are no specific requirements for usage and distribution. For more information, refer to the LICENSE.

(Go to top)

Changelog

For the changelog, please see CHANGELOG.md.

(Go to top)

Metadata

Release files for sshgen 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sshgen 0.9.0
File Size Uploaded Provenance Actions
sshgen-0.9.0.tar.gz 9.9 kB Without provenance Details for sshgen-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sshgen 0.9.0
File Interpreter ABI Platform Actions
sshgen-0.9.0-py3-none-any.whl Python 3 none any Details for sshgen-0.9.0-py3-none-any.whl

Total release size: 22.2 kB

Release files / sshgen-0.9.0.tar.gz

Download URL sshgen-0.9.0.tar.gz
Size 9.9 kB
Tags Source
SHA-256 checksum
How to use checksums
5b4b398c6f095e0de1fffb6b92a993df9b0e1d5574860dbdec98e5959a030194
BLAKE2b-256 checksum
How to use checksums
fc0f6db5dc6e94febd87d663a2d95bd97dd690f55a9e0fa4e856786a0d355ba1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.0.0 CPython/3.12.3 Linux/6.8.0-1017-azure

Release files / sshgen-0.9.0-py3-none-any.whl

Download URL sshgen-0.9.0-py3-none-any.whl
Size 12.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
88ecb2465ec7ea1a379684b7db3a0e4eb09130abcaaf2b1862308f9be85f4289
BLAKE2b-256 checksum
How to use checksums
e328c55c94898f4361eb9451973b583f426fe8aeba95e0e9218ded4d83beed9b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.0.0 CPython/3.12.3 Linux/6.8.0-1017-azure

Security for sshgen 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page