ASSH: An Advance Way to Interact with SSH

ASSH or Advanced SSH Config is a wrapper for SSH that allows dynamic and advanced management of SSH configurations.

Standard SSH configurations can quickly become complex and difficult to manage, especially in environments with many servers. ASSH offers a solution to this problem by introducing an abstraction layer. This supercharges the utilization of SSH config file feature.

For example, if you have a set of servers divided into development, testing, and production environments. With ASSH, you can define these environments in a clear and organized manner, making it easier to switch between them as needed.

# assh.yml
defaults:
  user: talha
groups:
  development:
    hosts:
      - dev1.example.com
      - dev2.example.com
  testing:
    hosts:
      - test1.example.com
      - test2.example.com
  production:
    hosts:
      - prod1.example.com
      - prod2.example.com

ASSH allows you to define groups of servers based on their environments which makes it easier to connect with a specific environment without listing out individual hosts. For example, to connect to dev server:

assh development

Sounds exciting? Let's see more on assh.

How ASSH Works

Let's dive into the key concepts of ASSH to better understand how this tool enriches the SSH experience. ASSH is not just a wrapper; it's a clever reinvention of how we interact with SSH.

ASSH works by interposing itself between your SSH client and your SSH connections. It intercepts SSH commands and manipulates them according to the configurations specified in your ~/.ssh/config. This allows for great flexibility and in-depth customization of your connections.

The core of ASSH is based on two main components:

The Configuration Parser: ASSH reads and interprets the SSH configuration file. It adds an extra layer of functionality while respecting the basic syntax and functionality of the original SSH file.

The SSH Proxy: When an SSH connection is initiated, ASSH acts as a proxy. It can dynamically change connection parameters, distribute the load among multiple hosts, or even bounce through multiple servers to reach the final destination.

One of the most powerful aspects of ASSH is its ability to handle complex configurations with simplicity. For example, you can configure connections through proxy servers, set automatic reconnection rules, or even manage groups of hosts with similar configurations.

With ASSH, you have the ability to define advanced rules for each host or host group in your configuration file. These rules may include:

• Balancing and Failover: Distribute connections across multiple hosts to balance the load or provide redundancy.
• Chaining and Jump Hosts: Connect to a host through one or more intermediaries, which is particularly useful in complex or secure environments.
• Custom Hooks: Run specific scripts or commands at different times during your SSH connection, like before login, after logout, etc.

Installing ASSH

Whether you're on Linux, macOS, or Windows, the installation process is designed to be as simple as possible. ASSH is easily installable through common package managers.

On Linux, the process may vary slightly depending on your distribution, but ASSH is generally available through standard package managers. ASSH can also be installed with asdf-vm:

asdf plugin add assh
asdf install assh latest
asdf global assh latest

ASSH Configuration Files

After installing ASSH, it is essential to understand how configuration files are defined.

The file ~/.ssh/config is a standard text file that defines settings for SSH connections. This file may include information like hostnames, IP addresses, usernames, ports, and other configuration options.

Here is an example of what a basic entry in this file might look like:

Host myserver
HostName myserver.example.com
User myuser
Port 22
IdentityFile ~/.ssh/id_ed25519

In this example, myserver is an alias for the SSH connection to the server myserver.example.com. This file also specifies the username, port, and SSH identity file to use for this connection.

Host *.example.com
 User myuser
 IdentityFile ~/.ssh/id_ed25519
 ControlMaster auto
 ControlPath ~/.ssh/cm-%r@%h:%p
 ControlPersist 5m

In this example, *.example.com is a template for SSH connecting to servers whose domain name ends with .example.com. This template also specifies the user name, SSH identity file, and connections settings to use for this connection. In this example ControlMaster enables SSH connection multiplexing. Here it is set to auto which tells SSH to try to use an existing connection to the same host instead of creating a new one and ControlPath as the name suggests specifies the location for the control socket. Similarly, ControlPresist specfies how long master connection will remain open after the client connections are shut.

Building SSH File

ASSH uses its own configuration file, named .assh.yml, to build the SSH file. In this configuration file assh adds its own options and functionalities. For example, with ASSH, you can define templates for common configurations, use hooks to trigger specific actions and much more.

Let's see this in detail with a first, fairly simplistic example:

hosts:
 on1.talha.local:
 User:talha

In this example, on1.talha.local will log in with user talha.

Generating the SSH File

The first thing to do before starting anything is to save the current file:

cp ~/.ssh/config ~/.ssh.config.orig

To build or update your SSH configuration file, use the following command:

assh config build

This command allows ASSH to generate an enriched SSH configuration file, taking into account advanced ASSH features . Here is the content generated with the file above:

#This file was automatically generated by assh vn/a (n/a) #on 2024-02-28 01:21:27 +0100 CET, based on ~/.ssh/assh.yml
#
# more info: https://github.com/moul/assh

# host-based configuration
Host on1.talha.local
User talha

# global configuration
Host *
ProxyCommand /home/bob/.asdf/installs/assh/2.16.0/bin/assh connect --port=%p %h

If you read correctly the wrapper assh is used each time the ssh.

Validating Configuration

To check that everything is in order, you can test your configuration by establishing an SSH connection to one of your servers:

ssh on1.talha.local

If the connection is successful, ASSH is correctly installed and configured.

Advance Settings

The default settings in ASSH serve as the base configuration for all hosts that do not explicitly specify certain settings. This is particularly useful in environments with many servers, as it helps maintain a uniform and centralized configuration.

To configure default settings in ASSH, you must define a section defaults in your file. Here is an example of configuring the default settings:

defaults
 User defaultuser
 Port 22
 IdentityFile ~/.ssh/id_ed25519
 ForwardAgent yes
 ControlMaster auto
 ControlPath ~/.ssh/multiplex/%r@%h:%p
 ControlPersist 10m

In this example, all hosts will inherit these default settings unless they are overridden in the host-specific configuration.

Although the default settings are applied to all hosts, you can still override them for specific hosts. For example:

Host specialserver
 HostName special.example.com
 User specialuser
 Port 2222

In this case, specialserver will use a different user and port than those defined in the default settings.

Creating Templates

A template in ASSH is a kind of configuration template that can be applied to multiple entries in your ~/.ssh/config. This allows you to define a base configuration and reuse it for different hosts, avoiding redundancy and making configurations easier to maintain.

To create a template in ASSH, you start by defining a section Templates in your configuration file. For example :

templates: 
 my-template:    
 User: bart

In this example, my-template is a template that defines a common parameter: the user.

To apply this template to a host, simply reference the template name in the host configuration:

Host server1  
 Inherits my-template  
 HostName server1.example.com

Host server2  
 Inherits my-template  
 HostName server2.example.com

Here, server1 and server2 both inherit the settings defined in my-template, which ensures consistency in configuration while reducing duplication.

Other ASSH CLI Commands

The ASSH Command Line Interface (CLI) offers several commands under assh config which you can efficiently manage your SSH configurations. These commands allow you to build, visualize and manipulate the configuration in an advanced way.

Graphical Visualization of Hosts

The command assh config graphvizgenerates a graphical representation of your hosts and their relationships, in Graphviz format.

assh config graphviz
digraph G {
        "10.0.0.*"->"vr1.talha.local"[ color=red, label=1 ];
        "machine*"->"vr1.talha.local"[ color=red, label=1 ];
        "10.0.0.*" [ color=blue ];
        "machine*" [ color=blue ];
        "vr1.talha.local" [ color=blue ];
}

This can be extremely useful for visualizing complex configurations, especially when you have dependencies or relationships between different hosts, such as gateways or cascading configurations.

Output in JSON

The command assh config json provides a JSON representation of your configuration. This is a useful feature for integration with other tools or for automated processing.

assh config json

{
  "hosts": {
    "10.0.0.*": {
      "User": "root",
      "Gateways": [
        "vr1.talha.local"
      ]
    },
    "192.168.3.*": {
      "User": "ubuntu"
    },
    "machine*": {
      "User": "talha",
      "Gateways": [
        "vr1.talha.local"
      ]
    },
    "on1.talha.local": {
      "User": "talha"
    },
    "proxmox": {
      "User": "root",
      "Aliases": [
        "proxmox.talha.local"
      ]
    },
    "proxmox2": {
      "User": "root",
      "Aliases": [
        "proxmox2.talha.local"
      ]
    },
    "vr1.talha.local": {
      "User": "root"
    }
  },
  "templates": {},
  "defaults": {
    "StrictHostKeyChecking": "no",
    "UserKnownHostsFile": [
      "/dev/null"
    ],
    "Hooks": {}
  },
  "asshknownhostfile": "~/.ssh/assh_known_hosts"
}

This command can be used to parse and process your SSH configuration in scripts or applications that consume JSON data.

Searching Configuration

Finally, the command assh config searchallows you to search for specific entries in your configuration using search text.

assh config search proxmox

Listing results for proxmox:
    proxmox -> root@proxmox:22
    proxmox2 -> root@proxmox2:22

This command is extremely useful when you are working with a large number of hosts and need to find specific information quickly.

Final Words

ASSH is a revolutionizing tool that changes the way you manage your SSH configuration. From initial configuration and default settings to advanced use of templates, and the CLI, ASSH proves to be an indispensable ally for any system administrator.