Server Configuration: An Overview

As mentioned at the beginning of the chapter, the behavior of the server, sshd, may be controlled at three levels:

Compile-time configuration ("Installation and Compile-Time Configuration") is accomplished when sshd is built. For example, a server may be compiled with or without support for rhosts authentication.
Serverwide configuration, the subject of this chapter, is performed by a system administrator and applies to a running instance of the server. For instance, an administrator may deny SSH access by all hosts in a given domain or make the server listen on a particular port.Serverwide configuration can be dependent on compile-time configuration. For example, a server's trusted-host authentication options work only if the server is compiled with trusted-host authentication support included. Otherwise, the options have no effect. We identify such dependencies throughout the tutorial. Figure 5-1 highlights the serverwide configuration tasks.
Figure 5-1. Serverwide configuration (highlighted parts)
Per-account configuration ("Per-Account Server Configuration") is performed by the end user, specifically, the owner of the account to which an SSH connection has been requested. For example, users may permit or deny access to their own accounts from particular hosts, overriding the serverwide configuration.

Suppose user deborah on the machine client.unc.edu invokes an SSH client. The clients's behavior is determined by the compile-time options selected when the software was built, the machinewide client configuration file on client.unc.edu, deborah's own client configuration file, and the command-line options used by deborah when invoking the client. An SSH server running on server.unc.edu accepts deborah's connection to the account charlie. The server's behavior is determined by the compile-time options used when sshd was built, the machinewide server configuration file on server.unc.edu, the command-line options used when the SSH server was run, and charlie's personal server configuration file (e.g., an authorized_keys file), plus several files that set environment variables for the successful login session.With three levels of server configuration, and multiple entry points for modifying the behavior at each level, things can get complicated. In particular, different options may work together or cancel each other. For example, user charlie can configure his account on server.unc.edu to accept connections from client.unc.edu, while the system administrator of server.unc.edu can configure the SSH server to reject them. (In this case, Charlie loses.) Administrators must understand not only how to configure the server themselves, but also how their choices interact with compile-time and per-account settings.

Server Configuration Files

Serverwide configuration is accomplished in two ways: through a server configuration file, or through command-line options. In a server configuration file, numerous configuration variables, called keywords, may have their values set. For example, to set the TCP port on which the server will listen, a configuration file can contain the line:

# SSH1, SSH2, OpenSSH Port 1022

The configuration file is typically /etc/sshd_config for SSH1 and OpenSSH or /etc/ssh2/sshd2_config for SSH2. The file contains keywords and their values, as in the Port example, with one pair (keyword and value) per line. Keywords are case-insensitive: Port, port, and PoRt are all treated identically. Comments may appear in the file as well: any line beginning with a hash sign (#) is a comment:

# This is a comment

To use a configuration file other than the default, invoke sshd with the -f command-line option, providing the alternative filename as an argument:

# SSH1, SSH2, OpenSSH $ sshd -f /usr/local/ssh/my_config

For SSH2, the configuration file format has the following extensions in addition to keywords:

Sections
The label *: often appears at the beginning of the configuration file, since it is present in the sample configuration file distributed with SSH2. This actually serves no purpose and is confusing; see the following sidebar.
Subsystems
Keywords beginning with the string "subsystem-", such as:
```
# SSH2 only subsystem-sftp sftp-server
```
indicate a subsystem, a predefined command that SSH2 clients may invoke by name. Subsystems are a layer of abstraction and a convenience feature. ["Subsystems"]

What's That *: ?
The sshd2_config file supplied with SSH2 contains the following lines at the top, just above the keyword settings:
# The "*" defines for all hosts *:
This is unnecessary and misleading. In the client configuration file, a colon introduces a labelled section of the configuration file ["Configuration file sections"], which limits the following configuration statements (up to the next label, or the end of the file) to apply only when the client is connecting to a host whose name matches the label.The section label syntax is also recognized in the server configuration file, but it serves no purpose. The way the code is written, the only label that can ever match on the server side is *, and that is the effective default label, anyway, so it is unnecessary.The section label is misleading because it suggests you can label a section in the server configuration file like this:
client.host.net: AllowUsers smith
By analogy with the client configuration file, you might expect that this restricts logins from the machine client.host.net to only accessing the account "smith". This won't work. In fact, statements labelled with anything besides * will be silently ignored by sshd. Beware!

Command-Line Options

Additionally, when invoking the server, you may supply command-line options. For example, the port value may be specified on the command line with the -p option:

# SSH1, SSH2, OpenSSH $ sshd -p 1022

Command-line options override settings in the configuration file. Thus, if the configuration file says port 1022 but the server is invoked with -p 2468, the port used will be 2468.Most command-line options duplicate the features found in the configuration file, for convenience, while a few provide unique functionality. For instance, the -f option instructs sshd to use a different configuration file, a feature that's useless to put in a configuration file.On the other hand, keywords don't necessarily have command-line equivalents. Most SSH1 and OpenSSH keywords don't. Any SSH2 keyword, however, may be set by the -o server command-line option. For example, to set the TCP port number by this method:

# SSH2 only $ sshd2 -o "Port 1022"

Changing the Configuration

sshd reads its configuration file at startup. Therefore, if you modify the file while the server is running, the changes don't affect the server. You must force the server to reread the file in order accept the changes. This is done by sending a SIGHUP signal to the server process.[56] The pid of the server is found in a file, usually /etc/sshd.pid for SSH1, /var/run/sshd2_22.pid for SSH2, or /var/run/sshd.pid for OpenSSH. ["Process ID file"]

[56] The SSH2 server supports SIGHUP restarts in Version 2.0.12 and up.

Suppose the PID file is /etc/sshd.pid, the default for sshd1. To send the SIGHUP signal, run the Unix kill command:

$ cat /etc/sshd.pid 119384 $ kill -HUP 119384

or more succinctly, with backquotes:

$ kill -HUP `cat /etc/sshd.pid`

The SIGHUP signal restarts sshd (with a different pid) but doesn't terminate existing SSH connections, so the signal is safe to send while clients are connected. The new sshd process reads and conforms to the new configuration.The SIGHUP technique works only for settings in the configuration file, not command-line options. To change those, you must kill and restart the server with the new options. For example:

# SSH1, SSH2, OpenSSH $ kill 119384 $ sshd new_options

A Tricky Reconfiguration Example

Because command-line options override their configuration file equivalents, some interesting situations can arise. Suppose the configuration file defines the number of bits in the server key to be 1024:

# SSH1, OpenSSH ServerKeyBits 1024

but the server is invoked with the -b command-line option, overriding this value with 512:

# SSH1, OpenSSH $ sshd -b 512

The server uses a 512-bit key. Now, suppose you restart sshd with SIGHUP:

# SSH1 only $ kill -HUP `cat /etc/sshd.pid` # OpenSSH only $ kill -HUP `cat /var/run/sshd.pid`

forcing sshd to reread the configuration file. What do you think happens to the key length? Does the server set the length to 1024 after rereading the configuration file, or does the command-line option remain in effect for a 512-bit key? In fact, the command-line option takes precedence again, and the key remains 512 bits. sshd saves its argument vector (argv) and reapplies it on restart.