OpenSSH/Cookbook/The Client Configuration File

SSH Client Configuration Files
Use of the client configuration file, ssh_config(5), is perhaps the most underrated and unrecognized feature, despite its great utility and flexibility. The configuration file can be used to create shortcuts for specific systems or scenarios by applying designated settings. The client, ssh(1), prioritizes settings applied at the command-line as run-time options. Then the settings from user's own configuration file, usually ~/.ssh/config, are applied. Then, finally, global client settings are applied, usually fron the system-wide configuration file, /etc/ssh/ssh_config, if it exits. So as mentioned in the chapter on Client Configuration Files, the prioritization is as follows:


 * 1) run time arguments via the shell
 * 2) user's own configuration
 * 3) system-wide configuration

Even within the user's configuration file and the system's global configuration file, the first match is applied. Therefore specific configurations must always go towards the beginning of the file and more general settings towards the end.

Basics of SSH Client Configuration
Each stanza in the configuration file begins with either a Host or Match directive. The directives within the stanza are then applied, if relevant. More on Match later. Below two hosts are each set up with their own shortcuts using a basic Host directive. The settings for the two hosts are followed by a two more general stanzas applicable to two whole domains. Lastly is a stanza with applying IdentitiesOnly to all outgoing connections.

The specific configurations are first and get more general until the end where IdentitiesOnly gets applied to all outgoing sessions. Hosts in the example.org domain use the default SSH port of 22, while that is overridden for those in the example.com domain which uses port 2022 instead. Keys are automatically added to the agent when used with the example.org domain but not with the example.com domain.

The first host can be reached with  and the second host with. In general, it is a good idea to set IdentitiesOnly so that only the one designated key is tried when authenticating. Otherwise, the keys are tried in whatever order they might be found in the agent which can be unpredictable. The result without IdentitiesOnly can be that the connection gets blocked from having too many failed logins attempts before the right key even gets tried.

Multiple Shortcuts
Each stanza can have multiple shortcuts.

Above, the same host can be reached with,  , or.

Different Keys for Different Accounts on the Same Systems
Sometime it is necessary to access multiple accounts on the same remote system, each with a separate key. The Match block in ssh_config(5) can pair each account with its corresponding key.

Above, different keys are applied to the same remote host depending on which of the three accounts is used.

Automatically Fire Up Local VNC After Establishing A Tunnel
The LocalCommand directive can launch a local program upon successful authentication. If that is combined with other directives, there are a lot of possibilities. Here once a VNC tunnel gets established, the client is connected to it.

The LocalForward creates the tunnel, while the PermitLocalCommand and LocalCommand connects the client to the tunnel once the tunnel is complete. Should the tunnel fail, ExitOnForwareFailure ensures that the SSH session ends so that the failure can be properly investigated rather than the client connected to nothing.

VNC Through A Jointly Accessible External Host - Approach One
Networking through one or more layers of NAT can be a problem That is especially the case as Carrier Grade NAT becomes more common in the legacy IPv4 networks provided by an increasing number of service providers. It is possible to connect two endpoints via a publicly accessible third machine on common ground. If there are three systems, A, B, and C, where A needs to connect to C, neither A nor C can connect directly to the other yet both can reach host B, then it is possible to make a tunnel via B if both A and C can reach it. Both A and C need to have working accounts on C, even if just for forwarding. Full shell access is not required.

On host B, accounts are needed for C and A.

On host C:

Start the VNC server and then have the system establish an SSH connection to host B with. The configuration of host B really needs no modification, unless if the key for the tunnel should be locked down or other restrictions desired.

On host A:

Start the SSH connection by entering  and Remmina will connect automatically to host C via the tunnel on Host C.

System-wide Client Defaults
The system-wide client configuration file, /etc/ssh/sshd_config, is a convenient way to provide what are effectively new, local default settings. As mentioned many times, configuration options are applied with a first match priority therefore any system-wide, global options should be a general as possible. System-wide defaults shine when customizing the local environment, including LAN access be means such as Kerberos authentication or even Host-based Authentication, the latter is covered in its own chapter.

The above allows host-based authentication for a specific subnet. It also sets IdentitiesOnly globally.

The above sets system-wide options for all systems in the pool.example.org domain, such that Kerberos authentication is possible.

The manual page for ssh_config(5) has a section on "tokens" which can be used in the stanzas in place of system information, such as the remote host name, the remote account name, or the local account name, to name just a few. These are useful when setting the system-wide client configuration file in /etc/ssh/ssh_config or /etc/ssh/ssh_config.d/* for all local accounts.

Tokens
Some client configuration directives can make use of tokens to stand in for certain values, as determined at run time.

LocalCommand accepts all tokens.

Hostname accepts the tokens %% and %h.

ProxyCommand and ProxyJump accept the tokens %%, %h, %n, %p, and %r.

CertificateFile, ControlPath, IdentityAgent, IdentityFile, KnownHostsCommand, LocalForward, Match exec, RemoteCommand, RemoteForward, RevokedHostKeys, and UserKnownHostsFile accept the tokens %%, %C, %d, %h, %i, %j, %k, %L, %l, %n, %p, %r, and %u.

KnownHostsCommand additionally accepts the tokens %%, %C, %d, %f, %H, %h, %I, %i, %j, %K, %k, %L, %l, %n, %p, %r, %t, and %u,

The client tokens are described as follows, and are somewhat different from the tokens used in server configuration:

As always, check ssh_config(5) on the systems in question to known what actually supported by the installed version of OpenSSH.