Skip to main content

Add some magic to SSH and .ssh/config

Project description

Advanced SSH config
===================

|Travis| |PyPI version| |PyPI downloads| |License| |Requires.io|
|Gitter|

|ASSH logo - Advanced SSH Config logo|

Enhances ``ssh_config`` file capabilities

**NOTE**: This program is called by
`ProxyCommand <http://en.wikibooks.org/wiki/OpenSSH/Cookbook/Proxies_and_Jump_Hosts#ProxyCommand_with_Netcat>`__
from `lib-ssh <https://www.libssh.org>`__.

--------------

It works *transparently* with :

- ssh
- scp
- rsync
- git
- and even desktop applications depending on ``lib-ssh`` (for instance
`Tower <http://www.git-tower.com>`__, `Atom.io <https://atom.io>`__,
`SSH Tunnel Manager <http://projects.tynsoe.org/fr/stm/>`__)

--------------

The ``.ssh/config`` file is automatically generated, you need to update
``.ssh/config.advanced`` file instead; With new features and a better
regex engine for the hostnames.

Usage
-----

.. code:: console

$ assh --help
Usage: assh [OPTIONS] COMMAND [arg...]

Commands:
build Build .ssh/config based on .ssh/config.advanced
connect <host> Open a connection to <host>
info <host> Print connection informations
init Build a .ssh/config.advanced file based on .ssh/config
generate-etc-hosts Print a /etc/hosts file of .ssh/config.advanced
stats Print statistics

Options:
--version show program's version number and exit
-h, --help show this help message and exit
-p PORT, --port=PORT SSH port
-c CONFIG_FILE, --config=CONFIG_FILE
ssh_config file
-f, --force
-v, --verbose
-l LOG_LEVEL, --log_level=LOG_LEVEL
--dry-run

Commmand line features
----------------------

**Gateway chaining**

.. code:: bash

ssh foo.com/bar.com

Connect to ``bar.com`` using ssh and create a proxy on ``bar.com`` to
``foo.com``. Then connect to ``foo.com`` using the created proxy on
``bar.com``.

.. code:: bash

ssh foo.com/bar.com/baz.com

Connect to ``foo.com`` using ``bar.com/baz.com`` which itself uses
``baz.com``.

Configuration features
----------------------

- **regex for hostnames**: ``gw.school-.*.domain.net``
- **aliases**: ``gate`` -> ``gate.domain.tld``
- **gateways**: transparent ssh connections chaining
- **includes**: split configuration into multiple files, support
globbing
- **local command execution**: finally a way to execute a command
locally on connection
- **inheritance**: ``inherits = gate.domain.tld``
- **variable expansion**: ``User = $USER`` (take $USER from
environment)
- **smart proxycommand**: connect using ``netcat``, ``socat`` or custom
handler

Config example
--------------

``~/.ssh/config.advanced``

.. code:: ini

# Simple example
[foo.com]
user = pacman
port = 2222

[bar]
hostname = 1.2.3.4
gateways = foo.com # `ssh bar` will use `foo.com` as gateway

[^vm-[0-9]*\.joe\.com$]
gateways = bar # `ssh vm-42.joe.com will use `bar` as gateway which
# itself will use `foo.com` as gateway

[default]
ProxyCommand = assh --port=%p connect %h

--------------

.. code:: ini

# Complete example
[foo]
user = pacman
port = 2222
hostname = foo.com

[bar]
hostname = 1.2.3.4
gateways = foo
# By running `ssh bar`, you will ssh to `bar` through a `ssh foo`

[^vm-[0-9]*\.joe\.com$]
IdentityFile = ~/.ssh/root-joe

gateways = direct joe.com joe.com/bar
# Will try to ssh without proxy, then fallback to joe.com proxy, then
# fallback to joe.com through bar

DynamicForward = 43217
LocalForward = 1723 localhost:1723
ForwardX11 = yes

[default]
Includes = ~/.ssh/config.advanced2 ~/.ssh/config.advanced3 ~/.ssh/configs/*/host.config
# The `Includes` directive must be in the `[default]` section

Port = 22
User = root
IdentityFile = ~/.ssh/id_rsa
ProxyCommand = assh connect %h --port=%p
Gateways = direct
PubkeyAuthentication = yes
VisualHostKey = yes
ControlMaster = auto
ControlPath = ~/.ssh/controlmaster/%h-%p-%r.sock
EscapeChar = ~

Installation
------------

Download the latest build

.. code:: console

$ curl -L https://github.com/moul/advanced-ssh-config/releases/download/v1.1.0/assh-`uname -s`-`uname -m` > /usr/local/bin/assh
$ chmod +x /usr/local/bin/assh

Using Pypi

.. code:: console

$ pip install advanced-ssh-config

Or by cloning

.. code:: console

$ git clone https://github.com/moul/advanced-ssh-config
$ cd advanced-ssh-config
$ make install

First run
---------

Automatically generate a new ``.ssh/config.advanced`` based on your
current ``.ssh/config`` file:

.. code:: console

$ assh init > ~/.ssh/config.advanced
$ assh build -f

Tests
-----

.. code:: console

$ make test

Docker
------

Build

.. code:: console

$ docker build -t moul/advanced-ssh-config .

Run

.. code:: console

$ docker run -rm -i -t moul/advanced-ssh-config
or
$ docker run -rm -i -t -v $(pwd)/:/advanced_ssh_config moul/advanced-ssh-config
or
$ docker run -rm -i -t -v moul/advanced-ssh-config python setup.py test

Contributors
------------

- `Christo DeLange <https://github.com/dldinternet>`__

--

© 2009-2015 Manfred Touron - `MIT
License <https://github.com/moul/advanced-ssh-config/blob/master/License.txt>`__.

.. |Travis| image:: https://img.shields.io/travis/moul/advanced-ssh-config.svg
:target: https://travis-ci.org/moul/advanced-ssh-config
.. |PyPI version| image:: https://img.shields.io/pypi/v/advanced-ssh-config.svg
:target: https://pypi.python.org/pypi/advanced-ssh-config/
.. |PyPI downloads| image:: https://img.shields.io/pypi/dm/advanced-ssh-config.svg
:target:
.. |License| image:: https://img.shields.io/pypi/l/advanced-ssh-config.svg?style=flat
:target: https://github.com/moul/advanced-ssh-config/blob/develop/LICENSE.md
.. |Requires.io| image:: https://img.shields.io/requires/github/moul/advanced-ssh-config.svg
:target: https://requires.io/github/moul/advanced-ssh-config/requirements/
.. |Gitter| image:: https://img.shields.io/badge/chat-gitter-ff69b4.svg
:target: https://gitter.im/moul/advanced-ssh-config
.. |ASSH logo - Advanced SSH Config logo| image:: https://raw.githubusercontent.com/moul/advanced-ssh-config/develop/assets/assh.jpg
:target: https://github.com/moul/advanced-ssh-config

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

advanced-ssh-config-1.1.0.tar.gz (17.7 kB view hashes)

Uploaded source

Built Distributions

advanced_ssh_config-1.1.0-py2.7.egg (49.4 kB view hashes)

Uploaded 2 7

advanced_ssh_config-1.1.0-py2.6.egg (49.6 kB view hashes)

Uploaded 2 6

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page