# sshgen
> [!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.8.0
## Table of Contents
<!-- TOC -->
* [sshgen](#sshgen)
* [Table of Contents](#table-of-contents)
* [Features](#features)
* [Installation](#installation)
* [Using pip](#using-pip)
* [Using pipx](#using-pipx)
* [Usage](#usage)
* [License](#license)
* [Changelog](#changelog)
<!-- TOC -->
## 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
```shell
pip install --user git+https://github.com/pythoninja/sshgen@v0.8.0
```
Or
```shell
pip install --user sshgen
```
### Using pipx
```shell
pipx install git+https://github.com/pythoninja/sshgen@v0.8.0
```
Or just run without installing:
```shell
pipx run sshgen
```
[(Go to top)](#table-of-contents)
## 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:
```yaml
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:
```shell
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):
```shell
SSHGEN_DEBUG=1 sshgen generate
```
After executing the command, you will see the following output:
```text
[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:
<details><summary>Verbose output example</summary>
<p>
```text
[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
```
</p>
</details>
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](https://github.com/pythoninja/sshgen/tree/master/examples) directory.
[(Go to top)](#table-of-contents)
## License
There are no specific requirements for usage and distribution. For more information, refer to
the [LICENSE](https://github.com/pythoninja/sshgen/blob/master/LICENSE).
[(Go to top)](#table-of-contents)
## Changelog
For the changelog, please see [CHANGELOG.md](https://github.com/pythoninja/sshgen/blob/master/CHANGELOG.md).
[(Go to top)](#table-of-contents)
Raw data
{
"_id": null,
"home_page": "https://github.com/pythoninja/sshgen",
"name": "sshgen",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "ssh, config, ansible, cli, generator",
"author": "pythoninja",
"author_email": "pythoninja@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/fa/e5/492a31a9444b0807b69451ed38140ef065727d6bca24713f6fd946651eea/sshgen-0.8.0.tar.gz",
"platform": null,
"description": "# sshgen\n\n> [!IMPORTANT]\n> This repository contains software that is currently in the Beta stage.\n\nSSH configuration generator based on your Ansible hosts YAML file.\n\nCurrent version: v0.8.0\n\n## Table of Contents\n\n<!-- TOC -->\n* [sshgen](#sshgen)\n * [Table of Contents](#table-of-contents)\n * [Features](#features)\n * [Installation](#installation)\n * [Using pip](#using-pip)\n * [Using pipx](#using-pipx)\n * [Usage](#usage)\n * [License](#license)\n * [Changelog](#changelog)\n<!-- TOC -->\n\n## Features\n\n1. Generates a `config` file to merge with your existing SSH configuration or include as a separate `.conf` file (since v0.6.0).\n2. Custom configuration for ssh-agent.\n3. Custom SSH aliases for quick connections.\n4. Skip selected hosts from results file.\n\n## Installation\n\n### Using pip\n\n```shell\npip install --user git+https://github.com/pythoninja/sshgen@v0.8.0\n```\n\nOr\n\n```shell\npip install --user sshgen\n```\n\n### Using pipx\n\n```shell\npipx install git+https://github.com/pythoninja/sshgen@v0.8.0\n```\n\nOr just run without installing:\n\n```shell\npipx run sshgen\n```\n\n[(Go to top)](#table-of-contents)\n\n## Usage\n\nBefore using this tool, make sure you have an Ansible `hosts.yml` in your current working directory.\n\nConsider the following example `hosts.yml` file, which defines 2 host groups with a total of 4 hosts:\n\n```yaml\ngroup1: # host_group\n hosts:\n host1: # host\n ansible_host: 127.0.0.1\n ansible_user: root\n _meta:\n _auth_type: IdentityAgent\n _auth_path: ~/.1password/agent.sock\n _aliases: [ \"base\", \"another-alias\" ]\n _skip: false\n\n host2:\n ansible_host: 127.0.0.2\n ansible_user: manager\n ansible_password:\n ansible_port: 19020\n _meta:\n _skip: true\n\ngroup2:\n hosts:\n host3:\n ansible_host: 172.19.0.1\n ansible_user: postgres\n ansible_password:\n ansible_port: 19222\n\n host4:\n ansible_host: 172.99.99.99\n ansible_user: postgres\n _meta:\n _auth_type: IdentityAgent\n _auth_path: ~/.1password/agent.sock\n _aliases: [ \"base\", \"another-alias\" ]\n _skip: false\n```\n\nTo use `sshgen`, you can either invoke it as a Python module using `python -m sshgen --help` or directly use the\ncommand `sshgen --help`.\n\nBy default, `sshgen` looks for the `hosts.yml` file in your current working directory. To generate the SSH\nconfiguration, run the following command:\n\n```shell\nsshgen generate\n```\n\nTo display addition logs (verbose mode), add `--verbose` flag:\n\n```\nsshgen --verbose generate\n```\n\nOr use `SSHGEN_DEBUG=1` (`SSHGEN_VERBOSE=1`) environment variable (since v0.5.0):\n\n```shell\nSSHGEN_DEBUG=1 sshgen generate\n```\n\nAfter executing the command, you will see the following output:\n\n```text\n[2024-03-10 10:00:00] [INFO] - Generated SSH config file was saved to /my_dir/config\n[2024-03-10 10:00:00] [INFO] - Total processed hosts: 3, total skipped hosts: 1\n```\n\nCheck the file contents `cat /my_dir/config`:\n\n```\nHost host1 base another-alias # group1\n HostName 127.0.0.1\n User root\n Port 22\n IdentityAgent ~/.1password/agent.sock\n\nHost host3 # group2\n HostName 172.19.0.1\n User postgres\n Port 19222\n IdentityFile ~/.ssh/ssh_key\n IdentitiesOnly yes\n\nHost host4 postgres-server # group2\n HostName 172.99.99.99\n User postgres\n Port 22\n IdentityAgent ~/.1password/agent.sock\n```\n\nIf you run using verbose mode, you should see additional information:\n\n<details><summary>Verbose output example</summary>\n<p>\n\n```text\n[2024-03-10 10:00:00] [DEBUG] - Loading ansible hosts file: /home/user/code/python/sshgen/examples/hosts.yml\n[2024-03-10 10:00:00] [DEBUG] - Total hosts found (include skipped): 4\n[2024-03-10 10:00:00] [DEBUG] - Using template file /home/user/code/python/sshgen/sshgen/templates/ssh_config.template to generate ssh config\n[2024-03-10 10:00:00] [DEBUG] - Filtering hosts where _skip metafield was defined\n[2024-03-10 10:00:00] [DEBUG] - Host host1 should be skipped: False\n[2024-03-10 10:00:00] [DEBUG] - Host host2 should be skipped: True\n[2024-03-10 10:00:00] [DEBUG] - Host host3 should be skipped: False\n[2024-03-10 10:00:00] [DEBUG] - Host host4 should be skipped: False\n[2024-03-10 10:00:00] [DEBUG] - Processing host1 from group group1\n[2024-03-10 10:00:00] [DEBUG] - Adding SSH port 22 for host host1\n[2024-03-10 10:00:00] [DEBUG] - Adding aliases ['base', 'another-alias'] for host host1\n[2024-03-10 10:00:00] [DEBUG] - Adding custom auth methods for host host1\n[2024-03-10 10:00:00] [DEBUG] - Processing host3 from group group2\n[2024-03-10 10:00:00] [DEBUG] - Adding SSH port 19222 for host host3\n[2024-03-10 10:00:00] [DEBUG] - Processing host4 from group group2\n[2024-03-10 10:00:00] [DEBUG] - Adding SSH port 22 for host host4\n[2024-03-10 10:00:00] [DEBUG] - Adding aliases ['base', 'another-alias'] for host host4\n[2024-03-10 10:00:00] [DEBUG] - Adding custom auth methods for host host4\n[2024-03-10 10:00:00] [INFO] - Generated SSH config file was saved to /home/user/code/python/sshgen/config\n[2024-03-10 10:00:00] [DEBUG] - Skipped hosts list: 127.0.0.2\n[2024-03-10 10:00:00] [INFO] - Total processed hosts: 3, total skipped hosts: 1\n```\n\n</p>\n</details>\n\nThere are two ways to use the generated file:\n1. Copy and insert the output into your `~/.ssh/config` file.\n2. Copy file to the conf directory, e.g. `~/.ssh/config.d/00-custom.conf` (if it's not exist, create one).\nEdit your `~/.ssh/config` and add `Include` directive **to the top**:\n\n```\n#### Custom configuration\n\nInclude ~/.ssh/config.d/*.conf\n\n#### End of custom configuration\n```\n\nAfter that, you can use any of the defined aliases to SSH\ninto the corresponding hosts. For example, running `ssh base` will connect you to the host with the IP address 127.0.0.1\nas the root user and utilizing 1password as your SSH agent.\n\nFor more examples, please refer to the [examples](https://github.com/pythoninja/sshgen/tree/master/examples) directory.\n\n[(Go to top)](#table-of-contents)\n\n## License\n\nThere are no specific requirements for usage and distribution. For more information, refer to\nthe [LICENSE](https://github.com/pythoninja/sshgen/blob/master/LICENSE).\n\n[(Go to top)](#table-of-contents)\n\n## Changelog\n\nFor the changelog, please see [CHANGELOG.md](https://github.com/pythoninja/sshgen/blob/master/CHANGELOG.md).\n\n[(Go to top)](#table-of-contents)\n",
"bugtrack_url": null,
"license": "Unlicense",
"summary": "SSH config generator based on Ansible hosts yaml file",
"version": "0.8.0",
"project_urls": {
"Changelog": "https://github.com/pythoninja/sshgen/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/pythoninja/sshgen",
"Repository": "https://github.com/pythoninja/sshgen"
},
"split_keywords": [
"ssh",
" config",
" ansible",
" cli",
" generator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d9b4ce7bf4c1d187d5ba6ef8319fe919503e56f440309169348e1cbc828f8f00",
"md5": "dd0c74fc03b18fc1b1652a049c26099c",
"sha256": "9b17080a6ba1ae590c4989134571ce71caeb40dfe5cc93c895c8f8b74bb87437"
},
"downloads": -1,
"filename": "sshgen-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dd0c74fc03b18fc1b1652a049c26099c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 12181,
"upload_time": "2024-09-07T17:21:48",
"upload_time_iso_8601": "2024-09-07T17:21:48.730318Z",
"url": "https://files.pythonhosted.org/packages/d9/b4/ce7bf4c1d187d5ba6ef8319fe919503e56f440309169348e1cbc828f8f00/sshgen-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fae5492a31a9444b0807b69451ed38140ef065727d6bca24713f6fd946651eea",
"md5": "bf30b7c85b2fd2c09e5e85a8bc8472d9",
"sha256": "7b1c5d3a1917bd87e8730aaf64ec80d50afe8f5fbf0a7863e7bb3877a1389895"
},
"downloads": -1,
"filename": "sshgen-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "bf30b7c85b2fd2c09e5e85a8bc8472d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 10398,
"upload_time": "2024-09-07T17:21:49",
"upload_time_iso_8601": "2024-09-07T17:21:49.951348Z",
"url": "https://files.pythonhosted.org/packages/fa/e5/492a31a9444b0807b69451ed38140ef065727d6bca24713f6fd946651eea/sshgen-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-07 17:21:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pythoninja",
"github_project": "sshgen",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sshgen"
}
JSON
