Download Configuring Custom SSH Connection Options: A Comprehensive Guide and more Summaries Combinatorics in PDF only on Docsity!
How To Configure Custom Connection
Options for your SSH Client
By: Justin Ellingwood
Introduction
SSH, or secure shell, is the most common way of connecting to Linux hosts for remote administration. Although the basics of connecting to a single host are often rather straight forward, this can become unwieldy and a much more complicated task when you begin working with a large number of remote systems.
Fortunately, OpenSSH allows you to provide customized client-side connection options. These can be saved to a configuration file that can be used to define per-host values. This can help keep the different connection options you use for each host separated and organized, and can keep you from having to provide extensive options on the command line whenever you need to connect.
In this guide, we'll cover the basics of the SSH client configuration file, and go over some common options.
Prerequisites
To complete this guide, you will need a working knowledge of SSH and some of the options that you can provide when connecting. You may also wish to configure SSH key-based authentication for some of your users or hosts, at the very least for testing purposes.
The SSH Config File Structure and Interpretation Algorithm
Each user on your local system can maintain a client-side SSH configuration file. These can contain any options that you would use on the command line to specify connection parameters, allowing you to store your common connection items and process them automatically on connection. It is always possible to override the values defined in the configuration file at the time of the connection through normal flags to the ssh command.
The Location of the SSH Client Config File
The client-side configuration file is called config and it is located in your user's home directory within the .ssh configuration directory. Often, this file is not created by
default, so you may need to create it yourself:
touch ~/.ssh/config
Configuration File Structure
The config file is organized by hosts. Each host definition can define connection
options for the specific matching host. Wildcards are also available to allow for options that should have a broader scope.
Each of the sections starts with a header defining the hosts that should match the configuration options that will follow. The specific configuration items for that matching host are then defined below. Only items that differ from the default values need to be specified, as the host will inherit the defaults for any undefined items. A section is defined from the Host header to the following Host header.
Typically, for organizational purposes and readability, the options being set for each host are indented. This is not a hard requirement, but a useful convention that allows for easier interpretation at a glance.
The general format will look something like this:
Host firsthost SSH_OPTION_1 custom_value SSH_OPTION_2 custom_value SSH_OPTION_3 custom_value
Host secondhost ANOTHER_OPTION custom_value
Host *host ANOTHER_OPTION custom_value
Host * CHANGE_DEFAULT custom_value
Here, we have four sections that will be applied on each connection attempt depending on whether the host in question matches.
Interpretation Algorithm
It is very important to understand the way that SSH will interpret the file to apply the configuration values defined within. This has large implications when using wildcards and the Host * generic host definition.
SSH will match the hostname given on the command line with each of the Host
headers that define configuration sections. It will do this from the top of the file
Host secondhost ANOTHER_OPTION custom_value
Host *host ANOTHER_OPTION custom_value
Host * CHANGE_DEFAULT custom_value
Here, we can see that the first two sections are defined by literal hostnames (or aliases), meaning that they do not use any wildcards. If we connect using ssh firsthost, the very first section will be the first to be applied. This will set
SSH_OPTION_1, SSH_OPTION_2, and SSH_OPTION_3 for this connection.
It will check the second section and find that it does not match and move on. It will then find the third section and find that it matches. It will check ANOTHER_OPTION to
see if it already has a value for that from previous sections. Finding that it doesn't, it will apply the value from this section. It will then match the last section since the Host
- definition matches every connection. Since it doesn't have a value for the mock
CHANGE_DEFAULT option from other sections, it will take the value from this section. The connection is then made with the options collected from this process.
Let's try this again, pretending to call ssh secondhost from the command line.
Again, it will start at the first section and check whether it matches. Since this matches only a connection to firsthost, it will skip this section. It will move on to the
second section. Upon finding that this section matches the request, it will collect the value of ANOTHER_OPTION for this connection.
SSH then looks at the third definition and find that the wildcard matches the current connection. It will then check whether it already has a value for ANOTHER_OPTION.
Since this option was defined in the second section, which was already matched, the value from the third section is dropped and has no effect.
SSH then checks the fourth section and applies the options within that have not been defined by previously matched sections. It then attempts the connection using the values it has gathered.
Basic Connection Options
Now that you have an idea about the general format you should use when designing your configuration file, let's discuss some common options and the format to use to specify them on the command line.
The first ones we will cover are the basic information necessary to connect to a
remote host. Namely, the hostname, username, and port that the SSH daemon is running on.
To connect as a user named apollo to a host called example.com that runs its SSH
daemon on port 4567 from the command line, we could give the variable information in a variety of ways. The most common would probably be:
ssh -p 4567 [email protected]
However, we could also use the full option names with the -o flag, like this:
ssh -o "User=apollo" -o "Port=4567" -o "HostName=example.com" anything
Here, we have set all of the options we wish to use with the -o flag. We have even specified the host as "anything" as an alias just as we could in the config file as we described above. The actual hostname is taken from the HostName option that we are setting.
The capitalized option names that we are using in the second form are the same that we must use in our config file. You can find a full list of available options by typing:
man ssh_config
To set these in our config file, we first must decide which hosts we want these options to be used for. Since we are discussing options that are specific to the host in question, we should probably use a literal host match.
We also have an opportunity at this point to assign an alias for this connection. Let's take advantage of that so that we do not have to type the entire hostname each time. We will use the alias "home" to refer to this connection and the associated options:
Host home
Now, we can define the connection details for this host. We can use the second format we used above to inform us as to what we should put in this section.
Host home HostName example.com User apollo Port 4567
We define options using a key-value system. Each pair should be on a separate line. Keys can be separated from their associated values either by white space, or by an equal sign with optional white space. Thus, these are all identical as interpreted by our SSH client:
Port 4567 Port= Port = 4567
your default username for the majority of new systems you connect to.
What if there are some systems that do not use this username? There are a few different ways that you can approach this, depending on how widely the username is shared.
If the "apollo" username is used on almost all of your hosts, it's probably best to leave it in the generic Host * section. This will apply to any hosts that have not received a username from sections above. For our anomalous machines that use a different username, we can override the default by providing an alternative. This will take precedence as long as it is defined before the generic section:
Host home HostName example.com Port 4567
Host work HostName company.com
Host oddity HostName weird.com User zeus
Host * User apollo
For the oddity host, SSH will connect using the username "zeus". All other connections will not receive their username until they hit the generic Host *
definition.
What happens if the "apollo" username is shared by a few connections, but isn't common enough to use as a default value? If we are willing to rename the aliases that we are using to have a more common format, we can use a wildcard to apply additional options to just these two hosts.
We can change the home alias to something like hapollo and the work connection to
something like wapollo. This way, both hosts share the apollo portion of their alias,
allowing us to target it with a different section using wildcards:
Host hapollo HostName example.com Port 4567
Host wapollo
HostName company.com
Host *apollo User apollo
Host * User diffdefault
Here, we have moved the shared User definition to a host section that matches SSH
connections trying to connect to hosts that end in apollo. Any connection not ending in apollo (and without its own Host section defining a User) will receive the username
diffdefault.
Note that we have retained the ordering from most specific to least specific in our file. It is best to think of less specific Host sections as fallbacks as opposed to defaults due to the order in which the file is interpreted.
Common SSH Configuration Options
So far, we have discussed some of the basic options necessary to establish a connection. We have covered these options:
HostName : The actual hostname that should be used to establish the connection. This replaces any alias defined in the Host header. This option is not necessary if the Host definition specifies the actual valid hostname to connect to.
User : The username to be used for the connection.
Port : The port that the remote SSH daemon is running on. This option is only necessary if the remote SSH instance is not running on the default port 22.
There are many other useful options worth exploring. We will discuss some of the more common options, separated according to function.
General Tweaks and Connection Items
Some other tweaks that you may wish to configure on a broad level, perhaps in the Host * section, are below.
ServerAliveInterval : This option can be configured to let SSH know when to send a
packet to test for a response from the sever. This can be useful if your connection is unreliable and you want to know if it is still available.
LogLevel : This configures the level of detail in which SSH will log on the client-side.
This can be used for turning off logging in certain situations or increasing the verbosity when trying to debug. From least to most verbose, the levels are QUIET,
different machine. We have also set up any host that begins with cloud* to not check hosts and not log failures. For other hosts, we have sane fallback values.
Connection Forwarding
One common use of SSH is forwarding connections, either allowing a local connection to tunnel through the remote host, or allowing the remote machine access to tunnel through the local machine. SSH can also do dynamic forwarding using protocols like SOCKS5 which include the forwarding information for the remote host.
The options that control this behavior are:
LocalForward : This option is used to specify a connection that will forward a local port's traffic to the remote machine, tunneling it out into the remote network. The first argument should be the local port you wish to direct traffic to and the second argument should be the address and port that you wish to direct that traffic to on the remote end.
RemoteForward : This option is used to define a remote port where traffic can be
directed to in order to tunnel out of the local machine. The first argument should be the remote port where traffic will be directed on the remote system. The second argument should be the address and port to point the traffic to when it arrives on the local system.
DynamicForward : This is used to configure a local port that can be used with a dynamic forwarding protocol like SOCKS5. Traffic using the dynamic forwarding protocol can then be directed at this port on the local machine and on the remote end, it will be routed according to the included values.
These options can be used to forward ports in both directions, as you can see here:
This will allow us to use port 8080 on the local machine
in order to access example.com at port 80 from the remote machine
Host local_to_remote LocalForward 8080 example.com:
This will allow us to offer access to internal.com at port 443
to the remote machine through port 7777 on the other side
Host remote_to_local RemoteForward 7777 internal.com:
Other Forwarding
Along with connection forwarding, SSH allows other types of forwarding as well.
We can forward any SSH keys stored in an agent on our local machine, allowing us to
connect from the remote system as using credentials stored on our local system. We can also start applications on a remote system and forward the graphical display to our local system using X11 forwarding.
These are the directives that are associated with these capabilities:
ForwardAgent : This option allows authentication keys stored on our local machine to be forwarded onto the system you are connecting to. This can allow you to hop from host-to-host using your home keys.
ForwardX11 : If you want to be able to forward a graphical screen of an application running on the remote system, you can turn this option on.
These both are "yes" or "no" options.
Specifying Keys
If you have SSH keys configured for your hosts, these options can help you manage which keys to use for each host.
IdentityFile : This option can be used to specify the location of the key to use for each host. If your keys are in the default locations, each will be tried and you will not need to adjust this. If you have a number of keys, each devoted to different purposes, this can be used to specify the exact path where the correct key can be found.
IdentitiesOnly : This option can be used to force SSH to only rely on the identities provided in the config file. This may be necessary if an SSH agent has alternative
keys in memory that are not valid for the host in question.
These options are especially useful if you have to keep track of a large number of keys for different hosts and use one or more SSH agents to assist.
Multiplexing SSH Over a Single TCP Connection
SSH has the ability to use a single TCP connection for multiple SSH connections to the same host machine. This can be useful if it takes awhile to establish a TCP handshake to the remote end as it removes this overhead from additional SSH connections.
The following options can be used to configure multiplexing with SSH:
ControlMaster : This option tells SSH whether to allow multiplexing when possible.
Generally, if you wish to use this option, you should set it to "auto" in either the host section that is slow to connect or in the generic Host * section.
ControlPath : This option is used to specify the socket file that is used to control the connections. It should be to a location on the filesystem. Generally, this is given using
