Skip to content

xupeng/advanced-ssh-config

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

assh - Advanced SSH config

Travis GoDoc License GitHub release

Table of Contents

  1. Overview
  2. Features
  1. Configuration
  2. Usage
  3. Install
  4. Getting started
  5. Changelog
  6. Alternative version
  7. 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:

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

ASSH logo - Advanced SSH Config logo

About

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

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Go 96.6%
  • Makefile 2.4%
  • Ruby 1.0%