1.1.0

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