xupeng/advanced-ssh-config

:computer: assh: a transparent wrapper (ProxyCommand) that adds regex, aliases, gateways, includes, dynamic hostnames to SSH and ssh-config

assh - Advanced SSH config

Table of Contents

1. Overview
2. Features

• Configuration features
• Using Gateway from command line
• Under the hood features

3. Configuration
4. Usage
5. Install
6. Getting started
7. Changelog
8. Alternative version
9. License

Overview

A transparent wrapper that adds regex, aliases, gateways, includes, dynamic hostnames to SSH.

Advanced SSH config is wrapped in lib-ssh 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)

Features

Configuration features

• regex support
• aliases gate -> gate.domain.tld
• gateways -> transparent ssh connection chaining
• includes: split configuration in multiple files
• 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 environment
• smart proxycommand: RAW tcp connection when possible with netcat and socat as default fallbacks

Using Gateway from command line

Connect to hosta using hostb as gateway.

$ ssh hosta/hostb
user@hosta $

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

---

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

$ ssh hosta/hostb/hostc
user@hosta $

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

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 be ran in debug mode)
• Automatically creates ControlPath directories so you can use slashes in your ControlPath option

Configuration

The ~/.ssh/config file is now managed by assh, take care to keep a backup your ~/.ssh/config file.

~/.ssh/assh.yml is a YAML file containing:

• an hosts dictionary containing multiple HOST definitions
• a defaults section containing global flags
• and an includes section containing path to other configuration files

hosts:

  homer:
    # ssh homer ->  ssh 1.2.3.4 -p 2222 -u robert
    HostName: 1.2.3.4
    User: robert
    Port: 2222

  bart:
    # ssh bart ->   ssh 5.6.7.8 -u bart           <- direct access
    #            or ssh 5.6.7.8/homer -u bart     <- using homer as a gateway
    HostName: 5.6.7.8
    User: bart
    Gateways:
    - direct                   # tries a direct access first
    - homer                    # fallback on homer gateway

  maggie:
    # ssh maggie ->   ssh 5.6.7.8 -u maggie       <- direct access
    #              or ssh 5.6.7.8/homer -u maggie   <- using homer as a gateway
    User: maggie
    Inherits:
    - bart                     # inherits rules from "bart"

  bart-access:
    # ssh bart-access ->  ssh home.simpson.springfield.us -u bart
    Inherits:
    - bart-template
    - simpson-template

  lisa-access:
    # ssh lisa-access ->  ssh home.simpson.springfield.us -u lisa
    Inherits:
    - lisa-template
    - simpson-template

  schooltemplate:
    User: student
    IdentityFile: ~/.ssh/school-rsa
    ForwardX11: yes

  schoolgw:
    # ssh school ->   ssh gw.school.com -l student -o ForwardX11=no -i ~/.ssh/school-rsa
    Hostname: gw.school.com
    ForwardX11: no
    Inherits:
    - schooltemplate

  "expanded-host[0-7]*":
    # ssh somehost2042 ->       ssh somehost2042.some.zone
    HostName: "%h.some.zone"

  vm-*.school.com:
    # ssh vm-42.school.com ->   ssh vm-42.school.com/gw.school.com -l student -o ForwardX11=yes -i ~/.ssh/school-rsa
    Gateways:
    - schoolgw
    Inherits:
    - schooltemplate

  "*.scw":
    # ssh toto.scw -> 1. dynamically resolves the IP address
    #                 2. ssh {resolved ip address} -u root -p 22 -o UserKnownHostsFile=null -o StrictHostKeyChecking=no
    # requires github.com/scaleway/scaleway-cli
    ResolveCommand: /bin/sh -c "scw inspect -f {{.PublicAddress.IP}} server:$(echo %h | sed s/.scw//)"
    User: root
    Port: 22
    UserKnownHostsFile: /dev/null
    StrictHostKeyChecking: no

  my-env-host:
    User: user-$USER
    HostName: ${HOSTNAME}${HOSTNAME_SUFFIX}

templates:
  # Templates are similar to Hosts, you can inherits from them
  # but you cannot ssh to a template
  bart-template:
    User: bart
  lisa-template:
    User: lisa
  simpson-template:
    Host: home.simpson.springfield.us

defaults:
  # Defaults are applied to each hosts
  ControlMaster: auto
  ControlPath: ~/tmp/.ssh/cm/%h-%p-%r.sock
  ControlPersist: yes
  Port: 22
  User: bob

includes:
- ~/.ssh/assh.d/*.yml
- /etc/assh.yml
- $ENV_VAR/blah-blah-*/*.yml

---

A HOST and the defaults section may

Usage

assh usage

NAME:
   assh - advanced ssh config

USAGE:
   assh [global options] command [command options] [arguments...]

VERSION:
   2.0.0 (HEAD)

AUTHOR(S):
   Manfred Touron <https://github.com/moul/advanced-ssh-config>

COMMANDS:
   proxy         Open an SSH connection to HOST
   stats         Print statistics
   help, h       Shows a list of commands or help for one command

GLOBAL OPTIONS:
  --debug, -D       Enable debug mode
  --verbose, -V     Enable verbose mode
  --help, -h        show help
  --version, -v     print the version

Install

Get the latest version using GO (recommended way):

go get -u github.com/moul/advanced-ssh-config/cmd/assh

---

Get the latest version using homebrew (Mac OS X):

brew install https://raw.githubusercontent.com/moul/advanced-ssh-config/master/contrib/homebrew/assh.rb --HEAD

or the latest released version:

brew install https://raw.githubusercontent.com/moul/advanced-ssh-config/master/contrib/homebrew/assh.rb

---

Get a released version on: https://github.com/moul/advanced-ssh-config/releases

Getting started

1. Backup your old ~/.ssh/config: cp ~/.ssh/config ~/.ssh/config.backup
2. Create a new ~/.ssh/assh.yml file
3. Run assh build > ~/.ssh/config to validate the syntax of your ~/.ssh/assh.yml file and automatically build your ~/.ssh/config file
4. You are ready!

Changelog

master (unreleased)

• No entry

Full commits list

v2.2.0 (2016-02-03)

• Avoid exiting when an included file contains errors (#95)
• Anonymize paths in assh info
• Support of assh proxy --dry-run option
• Fix: do not resolve variables in hostnames twice (#103)

Full commits list

v2.1.0 (2015-10-05)

• Expand environment variables (#86)
• Add homebrew support (#73)
• Add a 'ssh info' command (#71)
• Templates support (#52)
• Configuration is now case insensitive (#51)
• Fix: resolving host fields for gateways (#79)
• Fix: inheritance was not working for non assh-related fields (#54)
• Fix: expanding variables in HostName (#56)

Full commits list

v2.0.0 (2015-09-07)

• First Golang version
• Compatibility issue: complete switch from .ini file format to .yml, the ~/.ssh/assh.yml file needs to be manually crafted
• Features
  • Parses ~/.ssh/assh.yml and generates ~/.ssh/config dynamically
  • CLI: Use gateways from CLI without any configuration needed
  • Config: Declares gateways in coniguration
  • Config: Host inheritance
  • Config: Support of includes
  • Config: Support of Regex
  • Config: Handling all sshconfig fields
  • Config: Support of host ProxyCommand (inception)
  • Under the hood: Inspecting parent process verbose/debug mode
  • Under the hook: dynamic proxy using raw TCP, netcat

Full commits list

v1 (2015-07-22)

• Last Python version

POC (2010-08-26)

• First Python version (POC)

Docker

Experimental: assh may run in Docker, however you will have limitations:

• The assh containers does not have any binaries except assh, you can't use ProxyCommand, ResolveCommand...
• Docker may run on another host, ssh localhost will ssh to Docker host

docker run -it --rm -v ~/.ssh:/.ssh moul/assh --help

assh in Docker is slower and has more limitations, but it may be useful for testing or if you plan to use a Docker host as a remote Gateway

Alternative version

• v1 (2009-2015) - The original implementation. It worked quite well, but was a lot slower, less portable, harder to install for the user and harder to work on to develop new features and fix bugs

License

© 2009-2016 Manfred Touron - MIT License