Configuration files and command-line options have two important relationships:

For any configuration line of the form:

Keyword Value

you may type:

    $ ssh -o "Keyword Value" ...

For example, the configuration file lines:

    User sally
    Port 220

can be specified on the command line as:

    $ ssh -o "User sally" -o "Port 220" server.example.com

As in the configuration file, an equals sign (with optional whitespace) is permitted between the keyword and the value:

    $ ssh -o User=sally -o Port=220 server.example.com

If you use an equals sign, and the value for the keyword contains special characters that would be misinterpreted by the shell, surround the value with quotes.

The -o option may appear multiple times on the same command line, for both ssh and scp:

    #  OpenSSH
    $ scp -o "User sally" -o "Port 220" myfile server.example.com:

The other relationship between command-line options and configuration keywords is found in the -F option, which instructs a client to use a different configuration file instead of the default. For example:

    $ ssh -F /usr/local/ssh/other_config

Client configuration files come in two flavors. A single, global client configuration file, usually created by a system administrator, governs client behavior for an entire computer. The file is traditionally /etc/ssh/ssh_config (OpenSSH) or /etc/ssh2/ssh2_config (Tectia). (Don’t confuse these with the server configuration files in the same directories.) Each user may also create a local client configuration file within his or her account, usually ~/.ssh/config (OpenSSH) or ~/.ssh2/ssh2_config (Tectia). This file controls the behavior of clients run in the user’s login session.^[103]

Values in a user’s local file take precedence over those in the global file. For instance, if the global file turns on data compression, and your local file turns it off, the local file wins for clients run in your account. We cover precedence in more detail later. [7.2]

Client configuration files are divided into sections. Each section contains settings for one remote host or for a set of related remote hosts, such as all hosts in a given domain.

The beginning of a section is marked differently in different SSH implementations. For OpenSSH, the keyword Host begins a new section, followed by a string called a host specification. The string may be a hostname:

    Host server.example.com

an IP address:

    Host 123.61.4.10

a nickname for a host: [7.1.2.5]

    Host my-nickname

or a wildcard pattern representing a set of hosts, where ? matches any single character and * any sequence of characters (just like filename wildcards in your favorite Unix shell):

    Host *.example.com
    Host 128.220.19.*

Some further examples of wildcards:

    Host *.edu          Any hostname in the edu domain
    Host a*             Any hostname whose name begins with "a"
    Host *1*            Any hostname (or IP address!) with 1 in it
    Host *              Any hostname or IP address

Tectia, in contrast, does not use a Host keyword. A new section is marked by a host specification string followed by a colon. This string may likewise be a computer name:

    server.example.com:

an IP address:

    123.61.4.10:

a nickname:

    my-nickname:

or a wildcard pattern:

    *.example.com:
    128.220.19.*:

You then follow the host-specification line with one or more settings, i.e., configuration keywords and values, as in the example we saw earlier. The following table contrasts OpenSSH and Tectia configuration files:

The settings apply only to the hosts named in the host specification. The section ends at the next host specification or the end of the file, whichever comes first.

Because wildcards are permitted in host specifications, a single hostname might match two or more sections in the configuration file. For example, if one section begins:^[104]

    Host *.edu

and another begins:

    Host *.harvard.edu

and you connect to server.harvard.edu, which section applies? Believe it or not, they both do. Every matching section applies, and if a keyword is set more than once with different values, only one value applies. For OpenSSH, the earliest value takes precedence, whereas for Tectia the latest value wins.

Suppose your client configuration file contains two sections to control data compression, password authentication, and the ssh escape character:

    Host *.edux
     Compression yes
     PasswordAuthentication yes

    Host *.harvard.edu
     Compression no
     EscapeChar %

and you connect to server.harvard.edu:

    $ ssh server.harvard.edu

Notice that the string server.harvard.edu matches both Host patterns, *.edu and *.harvard.edu. As we’ve said, the keywords in both sections apply to your connection. Therefore, the preceding ssh command sets values for the keywords Compression, PasswordAuthentication, and EscapeChar.

But notice, in the example, that the two sections set different values for Compression. What happens? The rule is that the first value prevails -- in this case, yes. So, in the previous example, the values used for server.harvard.edu are:

    Compression yes               The first of the Compression lines
    PasswordAuthentication yes    Unique to first section
    EscapeChar %                  Unique to second section

and as shown in Figure 7-2. Compression no is ignored because it is the second Compression line encountered. Likewise, if 10 different Host lines match server.harvard.edu, all 10 of those sections apply, and if a particular keyword is set multiple times, only the first value is used.

Figure 7-2. OpenSSH client configuration file with multiple matches (Tectia not shown)

While this feature might seem confusing, it has useful properties. Suppose you want some settings applied to all remote hosts. Simply create a section beginning with:

    Host *

and place the common settings within it. This section should be either the first or the last in the file. If first, its settings take precedence over any others. This can be used to guard against your own errors. For example, if you want to make sure you never, ever, accidentally use the old SSH-1 protocol, at the beginning of your configuration file put:

    # First section of file
    Host *
     Protocol 2

Alternatively, if you place Host * as the last section in the configuration file, its settings are used only if no other section overrides them. This is useful for changing SSH’s default behavior, while still permitting overrides. For example, by default, data compression is disabled. You can make it enabled by default by ending your configuration file with:

    # Last section of file
    Host *
     Compression yes

Voilá, you have changed the default behavior of ssh and scp for your account! Any other section, earlier in the configuration file, can override this default simply by setting Compression to no.

Suppose your client configuration file contains a section for the remote host myserver.example.com :

    Host myserver.example.com
     ...

One day, while logged onto ourclient.example.com, you decide to establish an SSH connection to myserver.example.com. Since both computers are in the same domain, example.com, you can omit the domain name on the command line and simply type:

    $ ssh myserver

This does establish the SSH connection, but you run into an unexpected nuance of configuration files. ssh compares the command-line string “myserver” to the Host string “myserver.example.com”, determines that they don’t match, and doesn’t apply the section of the configuration file. Yes, the software requires an exact textual match between the hostnames on the command line and in the configuration file.

You can get around this limitation by declaring myserver to be a nickname for myserver.example.com. In OpenSSH, this is done with the Host and HostName keywords. Simply use Host with the nickname and HostName with the fully qualified hostname:

    # OpenSSH
    Host myserver
     HostName myserver.example.com
     ...

ssh will now recognize that this section applies to your command ssh myserver. You may define any nickname you like for a given computer, even if it isn’t related to the original hostname:

    # OpenSSH
    Host simple
     HostName myserver.example.com
     ...

Then you can use the nickname on the command line:

    $ ssh simple

For Tectia, the syntax is different but the effect is the same. Use the nickname in the host specification, and provide the full name to the Host keyword:

    # Tectia
    simple:
     Host myserver.example.com
     ...

Then type:

    $ ssh simple

Nicknames are convenient for testing new client settings. Suppose you have an OpenSSH configuration for server.example.com:

    Host server.example.com
     ...

and you want to experiment with different settings. You could just modify the settings in place, but if they don’t work, you’d have to waste time changing them back. The following steps demonstrate a more convenient way:

You can do the same with Tectia:

    # Original
    server.example.com:
     ...
    # Copy for testing
    my-test:
     Host server.example.com
     ...

You probably noticed in the previous examples that we use the # symbol to represent comments:

    # This is a comment

In fact, any line beginning with # in the configuration file is treated as a comment and ignored. Likewise, blank lines (empty or containing only whitespace) are also ignored.

You might also have noticed that the lines following a host specification are indented:

    # OpenSSH
    Host server.example.com
     Keyword1 value1
     Keyword2 value2

    # Tectia
    server.example.com:
     Keyword1 value1
     Keyword2 value2

Indenting is considered good style because it visually indicates the beginning of a new section. It isn’t required, but we recommend it.