SSH, The Secure Shell: The Definitive Guide, 2nd Edition

Installing OpenSSH

OpenSSH is a free implementation of the SSH-1 and SSH-2 protocols, obtained from the OpenSSH web site:

OpenSSH is a very complete implementation and includes:

• Client programs for remote logins, remote command execution, and secure file copying across a network, all with many runtime options

• A highly configurable SSH server

• Command-line interfaces for all programs, facilitating scripting with standard Unix tools (shells, Perl, etc.)

• Numerous, selectable encryption algorithms and authentication mechanisms

• An SSH agent, which caches keys for ease of use

• Support for SOCKS proxies

• Support for TCP port forwarding and X11 forwarding

• History and logging features to aid in debugging

• Example configuration files /etc/ssh/ssh_config and /etc/ssh/sshd_config

Since it is developed by the OpenBSD Project, the main version of OpenSSH is specifically for the OpenBSD Unix operating system, and is in fact included in the base OpenBSD installation. As a separate but related effort, another team maintains a “portable” version that compiles on a variety of Unix flavors and tracks the main development effort. The supported platforms include Linux, Solaris AIX, IRIX, HP/UX, FreeBSD, NetBSD, and Windows via the Cygwin compatibility library. The portable version carries a “p” suffix. For example, 3.9p1 is the first release of the portable version of OpenSSH 3.9.

4.2.1 Prerequisites

OpenSSH depends on two other software packages: OpenSSL and zlib. OpenSSL is a cryptographic library available at http://www.openssl.org/; all the cryptography used in OpenSSH is pulled from OpenSSL. zlib is a library of data-compression routines, available at http://www.gzip.org/zlib/. These packages must be on your system before you build OpenSSH.

4.2.2 Downloading and Extracting the Files

Distributions are packaged in gzipped tar format and are extracted with the tar command in the usual way. [4.1.4] The results are stored in a directory with a name like openssh-3.9p1.

4.2.2.1 Verifying with GnuPG

Along with each OpenSSH distribution is a GnuPG (Gnu Privacy Guard) signature. The file openssh-3.9p1.tar.gz, for example, is accompanied by openssh-3.9p1.tar.gz.sig containing the GnuPG signature. To verify the file is genuine, you need GnuPG installed (http://www.gnupg.org/). Then:

1. If you have not done so previously, obtain the GnuPG public key for the distribution, available from various keyservers on the Internet, such as:

   http://www.keyserver.net

   http://pgp.mit.edu

   Add the key to your GnuPG key ring by running:

       $ gpg --keyserver keyserver --search-keys openssh

   and following the instructions.

2. Download both the distribution file (e.g., openssh-3.9p1.tar.gz) and the signature file (e.g., openssh-3.9p1.tar.gz.sig).

3. Verify the signature with the command:

       $ gpg --verify openssh-3.9p1.tar.gz.sig openssh-3.9p1.tar.gz

   If no warning messages are produced, the distribution file is genuine.

Always check the GnuPG signatures.

4.2.3 Building and Installing

Building and installing OpenSSH follows the familiar pattern for Unix open source software: configure, make, and make install. [4.1.6] Read the file INSTALL in the top-level source directory for full instructions.

4.2.4 Configuration Options

OpenSSH’s configure script understands a wide range of options to customize its operation. We cover the most significant ones.

4.2.4.1 File locations

    --prefix              Determine where to install the software

The make install command installs OpenSSH in the /usr/local hierarchy by default, placing ssh into /usr/local/bin, sshd into /usr/local/sbin, configuration files into /usr/local/etc, and so forth. You can specify a different installation hierarchy, such as /usr, with:

    $ configure --prefix=/usr

Other options offer more fine-grained control over installation directories, such as --bindir for the executables normally placed in a bin directory, --sbindir for the sbin files, --sysconfdir for the etc files, --mandir for manpages, and so on: run configure - -help for the full list.

    --with-default-path=PATH         Default server PATH
    --with-superuser-path=PATH                         Superuser's server PATH

You can set the default command search path for OpenSSH when attempting to run a subprogram, and an alternative path for the superuser.

    --with-ssl-dir=PATH                           Set path to OpenSSL installation

If OpenSSL isn’t installed in the usual place, /usr/local/ssl, use this option to indicate its location.

    --with-xauth=PATH              Set path to xauth program

In OpenSSH, the default location of the xauth program for X authentication is a compile-time parameter.

    --with-pid-dir=PATH     Specify location of ssh.pid file

The location of the OpenSSH pid file, where it stores the pid of the currently running daemon, can be changed via the --with-pid-dir option. The default is /var/run/sshd.pid.

4.2.4.2 Random number generation

    --with-random=FILE         Read random bits from given file, normally /dev/urandom

    --with-rand-helper         Use external program to generate randomness

OpenSSH normally relies on the OpenSSL library to provide a stream of random bits for its cryptographic needs. The OpenSSL pseudo-random number generator (PRNG) needs to be “seeded” to start with, and then periodically, with an initial segment of unpredictable bits (as truly random as is available). If the operating system supplies random bits, OpenSSL uses this to seed itself; for example, many Unix variants provide random bits via a device driver accessible through /dev/random or /dev/urandom.

If your platform doesn’t provide any randomness source, you need to build OpenSSH with:

    configure --with-rand-helper

OpenSSH then runs the external program ssh-rand-helper to seed the PRNG.

    --with-prngd-port=PORT           Read entropy from PRNGD/EGD TCP localhost:PORT
    --with-prngd-socket=FILE         Read entropy from PRNGD/EGD socket FILE (default= /var/run/egd-pool)

If your system is running the Entropy Gathering Daemon (EGD) package (http://www.lothar.com/tech/crypto/), you can use it with the --with-prngd-port and --with-prngd-socket options.

The ssh-rand-helper program uses a configurable set of commands that monitor changing aspects of system operation, mixing their output together to produce its random bits. You can control which commands are used and how, with the file /etc/ssh/ssh_prng_cmds.

    --with-egd-pool=FILE             Read randomness from EGD pool FILE (default none)

If you install EGD as described earlier, use the --with-egd-pool option to have OpenSSH use EGD as its randomness source.

4.2.4.3 Networking

    --with-ipaddr-display      Use IP address instead of hostname in $DISPLAY

In X forwarding, use DISPLAY values of the form 192.168.10.1:10.0 instead of hostname:10.0. This option works around certain buggy X libraries that do weird things with the hostname version, using some sort of IPC mechanism for talking to the X server rather than TCP.

--with-ipv4-default                  Use IPv4 unless "-6" is given
--with-4in6                          Check for and convert IPv4 in IPv6 mapped addresses

OpenSSH supports IPv6, the next-generation TCP/IP protocol suite that is still in the development and very early deployment stages on the Internet (the current version of IP is IPv4). The default configuration of OpenSSH attempts to use IPv6 where possible, and sometimes this results in problems. If you encounter errors mentioning “af=10” or “address family 10,” that’s IPv6, and you should try the -4 runtime option, or compiling --with-ipv4-default.

4.2.4.4 Authentication

--with-pam        Enable PAM support
--without-pam     Disable PAM support

PAM, the Pluggable Authentication Modules system, is a generic framework for authentication, authorization, and accounting (AAA). The idea is that programs call PAM to perform AAA functions, rather than implementing these functions themselves. This allows the sysadmin to configure individual programs to use various kinds of authentication, apply account restrictions, do logging, etc., via dynamically loaded libraries. PAM-aware services can be configured to do almost anything in the way of AAA, in a consistent manner and without having to change the services themselves. See the manpage for pam or visit http://www.kernel.org/pub/linux/libs/pam/ for more information on PAM.

In order for OpenSSH to use PAM, the support must be compiled in. PAM is very common these days, so most OpenSSH binary packages include support; if your’s doesn’t, use the --with-pam option. Actually, configure detects PAM if you have it, so the option is often not necessary.

In addition, you must set the UsePAM configuration keyword in the SSH server:

    # sshd_config
    UsePAM yes

(This is off by default.) Setting UsePAM causes sshd to do three separate things:

• Enable the PAM “device” for keyboard-interactive authentication [5.4.6]

• Verify password authentication using PAM

• Execute all system PAM modules configured for ssh (usually found in /etc/pam.d/ssh)

Note that the execution action is a very powerful feature; you can customize sshd’s behavior in many ways with PAM modules. Look on your system for the PAM modules available and their documentation, e.g., /lib/security and /usr/share/doc/libpam-doc.

Generally, if a program uses PAM, some host configuration is necessary to describe how PAM should behave for that program. The PAM configuration files are usually in the directory /etc/pam.d, or in the single file /etc/pam.conf. Most OpenSSH packages automatically add the requisite PAM configuration for sshd; otherwise, you’ll need to do it, usually by copying the appropriate sshd.pam file from the contrib directory to /etc/pam.d/sshd. Samples for various operating systems are included in the contrib directory of the OpenSSH source. Note that you don’t need to restart sshd if you change its PAM configuration; the configuration files are checked on every use of PAM.

    --with-md5-passwords      Enable use of MD5 passwords
    --without-shadow          Disable shadow password support

These options control OpenSSH’s treatment of the Unix account database (a.k.a. passwd map). They are relevant only if OpenSSH isn’t using PAM, since otherwise PAM deals with reading the account information, not the OpenSSH code proper.

Enable --with-md5-passwords if your system uses MD5 instead of the traditional crypt function to hash passwords, and you are not using PAM.

“Shadow passwords” refers to the practice of keeping the hashed password in a restricted file, /etc/shadow (/etc/passwd must be world-readable). Use --without-shadow to suppress reading of the /etc/shadow file, should it be necessary.

    --with-kerberos5=PATH     Enable Kerberos-5 support
    --with-skey               Enable S/Key support

The --with-kerberos5 option installs Kerberos support [11.4], and the --with-skey option enables support for the S/Key one-time password system for password authentication. [5.4.5]

4.2.4.5 Access control

    --with-tcp-wrappers         Include TCP-wrappers support
    --without-tcp-wrappers      Remove TCP-wrappers support

These options include support for TCP-wrappers, providing the path to the wrapper library, libwrap.a. If the library and header file for TCP-wrappers are not installed in the standard locations, you can provide a pathname as an argument. The pathname can either be a build directory that contains both the library and header file:

    $ configure --with-tcp-wrappers=/var/tmp/build/tcp-wrappers

or it can be an installation directory with lib and include subdirectories:

    $ configure --with-tcp-wrappers=/usr/local/tcp-wrappers

If your Unix installation doesn’t include the TCP-wrappers library, you can retrieve and compile it yourself fromftp://ftp.porcupine.org/pub/security/index.html.For more information on TCP-wrappers, read the manpages for tcpd and hosts_access.