assh

Overview

A transparent wrapper that adds support for regex, aliases, gateways, dynamic hostnames, graphviz, json output, yaml configuration, and more to SSH.

lib-ssh wraps assh as a ProxyCommand; it means that it works seamlessly with:

ssh
scp
rsync
git
Desktop applications depending on lib-ssh or ssh (i.e., Tower, Atom.io, SSH Tunnel Manager)

For specific examples, see 3rd Party Integration

Features

Configuration features

regex support
aliases gate -> gate.domain.tld
gateways -> transparent ssh connection chaining
includes: split configuration in multiple files, note that OpenSSH as of v7.3 has native support for this
local command execution: finally the reverse of RemoteCommand
templates: equivalent to host but you can't connect directly to a template, perfect for inheritance
inheritance: make hosts inherits from host hosts or templates
variable expansion: resolve variables from the environment
smart proxycommand: RAW tcp connection when possible with netcat and socat as default fallbacks
rate limit: configure a per-host or global rate-limiting
JSON output
Graphviz: graphviz reprensentation of the hosts

Using Gateway from command line

assh can use the ProxyCommand with netcat feature of OpenSSH transparently and without the pain of using extended configuration.

Connect to hosta using hostb as a gateway.

flowchart 
    direction TB

    y[you]
    a[hosta]
    b[hostb]
    fw((firewall))

    style fw fill:#f00,color:#fff

    y ==x fw
    fw .-> a
    
    y --> b
    b --> a

Loading

$ ssh hosta/hostb
user@hosta $

Equivalent to ssh -o ProxyCommand="ssh hostb nc %h %p" hosta

Connect to hosta using hostb as a gateway using hostc as a gateway.

flowchart 
    direction TB

    y[you]
    a[hosta]
    b[hostb]
    c[hostc]
    fw((firewall))

    style fw fill:#f00,color:#fff

    y ==x fw
    fw ..-> a
    
    y --> c
    c --> b
    b --> a

Loading

$ ssh hosta/hostb/hostc
user@hosta $

Equivalent to ssh -o ProxyCommand="ssh -o ProxyCommand='ssh hostc nc %h %p' hostb nc %h %p" hosta

Using Gateways from configuration file

You can define an equivalent of the "ProxyCommand with netcat" feature of OpenSSH, with a simpler syntax, more advanced workflows, and a unique fallback feature.

Let's consider the following assh.yml file

hosts:
  hosta:
    Hostname: 1.2.3.4

  hostb:
    Hostname: 5.6.7.8
    Gateways: hosta

  hostc:
    Hostname: 9.10.11.12
    Gateways: hostb

  hostd:
    Hostname: 13.14.15.16
    GatewayConnectTimeout: 2
    Gateways:
    - direct
    - hosta

ssh hosta -> ssh 1.2.3.4
ssh hostb -> ssh -o ProxyCommand="ssh hostb nc %h %p" hosta
ssh hostc -> ssh -o ProxyCommand="ssh -o ProxyCommand='ssh hostc nc %h %p' hostb nc %h %p" hosta
ssh hostd ->
- assh will try to ssh 13.14.15.16
- then, fallback on ssh -o ProxyCommand="ssh hostd nc %h %p" hosta
- this method allows you to have the best performances when it is possible, but ensure your commands will work if you are outside of your company for instance

Under the hood features

Automatically regenerates ~/.ssh/config file when needed
Inspect parent process to determine log level (if you use ssh -vv, assh will automatically run in debug mode)
Automatically creates ControlPath directories so you can use slashes in your ControlPath option, can be enabled with the ControlMasterMkdir: true configuration in host or globally.

Hooks

Events

BeforeConnect

BeforeConnect is called just before assh tries to connect to the remote SSH port.

Note: BeforeConnect will be called for each SSH connection; if you use multiple gateways, it will be called for each gateways until one succeed to connect.