Secure Shell - How to Install

INSTALL

For most machines and configurations, the following is all you need.

  • ./configure
  • make
  • make install
  • In a networked environment with shared binary directory, it is enough to do "make install" on one machine, and then "make hostinstall" on others to generate host keys and install configuration files.

    Then check (and edit if needed) the following files:

  • /etc/sshd_config (server configuration file)
  • /etc/ssh_config (client configuration file - defaults for users)
  • You may also want to create the /etc/ssh_known_hosts for your site and update it periodically. See the manual page for make-ssh-known-hosts on how to do this easily. The file format is documented on the sshd manual page.

    You should also edit /etc/rc.local or equivalent to start sshd at boot.

    CONFIGURATION OPTIONS

    The package comes with an Autoconf-generated configure script. The script accepts several options

    All standard options, including:

    --prefix=PREFIX
    where to install files (default: subdirs of /usr/local)
    --exec_prefix=PREFIX
    where to install executables (default: same as prefix)
    --srcdir=DIR
    find sources in DIR (default: where configure is)

    Specific options:

    --with-rsh=PATH
    Use rsh specified by PATH when needed
    --with-etcdir=PATH
    Store system files in the given dir (default: /etc)
    --with-path=PATH
    Default path to pass to user shell.
    --with-rsaref
    Use rsaref2 from rsaref2 subdirectory (see below).
    --with-libwrap[=PATH]
    Use libwrap (tcp_wrappers) and identd (see below).
    --with-socks4[=PATH]
    Include SOCKS (firewall traversal) support.
    --with-socks5[=PATH]
    Include SOCKS5 (firewall traversal) support.
    --without-idea
    Don't include IDEA (see below).
    --with-securid[=PATH]
    Support for the SecurID card (see README.SECURID).
    --enable-warnings
    Adds -Wall to CFLAGS if using gcc.

    You may also want to configure the following variables:

  • CC=compiler
  • specify name of the C compiler (default: gcc or cc)

  • CFLAGS=flags
  • specify flags to C compiler (default: -O -g or just -O)

  • LDFLAGS=flags
  • specify flags to linker (default: none)

    Alternate values can be given to configure in the environment, e.g.:

  • CC=xcc CFLAGS="-O2" LDFLAGS="-L/lib/zzz" ./configure
  • (Note that if you have already configured, and later decide to give some values on the command line, you may need to say "make distclean" before reconfiguring.)

    CONFIGURATION FILES

    The server has a configuration file /etc/sshd_config, which specifies the permitted authentication methods, hosts, port number, etc. The defaults are acceptable for most sites, but you may want to check this file. Its format is documented on the sshd manual page.

    The client reads a configuration file /etc/ssh_config, which gives site-wide defaults for various options. Options in this file can be overridden by per-user configuration files. The file is documented on the ssh manual page.

    MAKEFILE

    The Makefile is generated from Makefile.in by running configure. It supports the following targets:

  • all: compile everything
  • install: install in $exec_prefix/bin and $prefix/man/man1.
  • hostinstall: generate host key and install config files
  • uninstall: remove installed files
  • clean: remove object files and executables
  • distclean: remove anything not in the distribution
  • PORTABILITY

    This software has been used at least in the following environments.

  • 386BSD 0.1; i386
  • AIX 3.2.5, 4.1, 4.2; RS6000, PowerPC
  • BSD 4.4; several platforms
  • BSD/OS 1.1, 2.0.1; i486
  • BSD/386 1.1; i386
  • BSDI 2.1; x86
  • ConvexOS 10.1; Convex
  • DGUX 5.4R2.10; DGUX
  • FreeBSD 1.x, 2.x; Pentium
  • HPUX 7.x, 9.x, 10.0; HPPA
  • IRIX 5.2, 5.3; SGI Indy
  • IRIX 6.0.1; Mips-R8000
  • Linux 1.2.x, 2.0.x Slackware 2.x, 3.x, RedHat 2.1, 3.0; i486, Sparc
  • Linux/Mach3, Macintosh(PowerPC)
  • Mach3; Mips
  • Mach3/Lites; i386
  • Machten 2.2VM (m68k); Macintosh
  • NCR Unix 3.00; NCR S40
  • NetBSD 1.0A, 1.1, 1.2; Pentium, Sparc, Mac68k, Alpha
  • NextSTEP 3.3; 68040
  • OSF/1 3.0, 3.2, 3.2; Alpha
  • Sequent Dynix/ptx 3.2.0 V2.1.0; i386
  • SCO Unix; i386 (client only)
  • SINIX 5.42; Mips R4000
  • Solaris 2.3, 2.4, 2.5; Sparc, i386
  • Sony NEWS-OS 3.3 (BSD 4.3); m68k
  • SunOS 4.1.1, 4.1.2, 4.1.3, 4.1.4; Sparc, Sun3
  • SysV 4.x; several platforms
  • Ultrix 4.1; Mips
  • Unicos 8.0.3; Cray C90
  • Please report back any other environments where you have used ssh, and send back any patches you had to do so that they can be integrated to the distribution. The proper address is ssh-bugs@cs.hut.fi. Always remember to mention the ssh version number and machine type in your bug reports. Please include also the output of the -v option from the client side, and the output of the -d option from the server, if applicable.

    Linux note: Some linux systems have a bug which causes an error about libc.so.4 when compiling ssh. This can be solved by any of the following ways:

    More information on this problem is available in ftp://ftp.netcom.com/pub/ze/zenon/linux. (This is pretty obsolete, no one seems to use gcc 2.7.0 anymore. Since autodetecting this problem started to cause other problems on new RedHat distributions, I removed the autodetection. -ttsalo)

    RedHat Linux (and other group naming scheme) note: In order for RSA authentication to work, users' home and .ssh directories must not be group writeable.

    BSDI BSD/OS note: Apparently the gcc that comes with BSD/OS is broken. Use "CC=cc ./configure" or "setenv CC cc; ./configure" when configuring to force it to use cc instead of gcc. (Note: BSDI 2.1 comes with good gcc.)

    ConvexOS note: Convex "make" is broken. Install GNU make first if you have trouble compiling ssh.

    Ultrix note: Ultrix /bin/sh is broken. Run configure with "/bin/sh5 configure [options]" if you are on Ultrix.

    IRIX 6.2 note: GMP-2.0.2 does not compile properly with assembly routines; thus, they have been disabled in this release of SSH. This makes key generation rather slow.

    COMPILING WITH RSAREF2

    If you are using ssh in the United States, you may want to use the RSAREF2 library from RSADSI. This may make it legal to use ssh without a separate license for non-commercial purposes. RSAREF2 is not included in the distribution; however, it is available on any major ftp site around the world (e.g., ftp://ftp.funet.fi/pub/crypt/cryptography/asymmetric/rsa/rsaref2.tar.gz). The RSAREF2 distribution should be unpacked into "rsaref2" subdirectory in the ssh distribution directory (a symbolic link to rsaref2 is not sufficient). Configure should be given the --with-rsaref option. (Note that there is no need to *compile* rsaref2 manually; the ssh Makefile will compile those files it needs.)

    Using RSAREF outside the United States is not recommended and only causes legal complications.

    RSAREF2 does not work for large key sizes (> 1024). This may be the problem if you get "RSAPrivateDecrypt failed".

    On alpha, one should edit rsaref2/source/global.h, and make UINT4 "unsigned int" instead of "unsigned long int".

    LIBWRAP AND IDENTD

    Sshd does not normally use identd or tcp-wrappers. However, it can be compiled to use these by adding --with-libwrap on the command line. This requires that the tcp_wrappers libwrap.a library and the associated tcpd.h have been installed somewhere where the compiler can find them. With libwrap support, ssh will process the /etc/hosts.allow and /etc/hosts.deny files, and use identd if required by them. The name of the user on the client side (as returned by identd) will be logged if requested by the configuration files. See tcp_wrappers documentation for more information.

    COMPILING WITHOUT IDEA

    The IDEA cipher can be freely used for non-commercial use. However, commercial use may require a license in a number of countries.

    Ssh can be compiled without IDEA by using the --without-idea configure option. This disables IDEA, and causes 3DES to be used for encrypting key/identity files and as the default session cipher. (The default session cipher can be changed by editing SSH_FALLBACK_CIPHER in ssh.h.)

    If one disables IDEA after having used it for some time, it is possible that there are key files around that were encrypted with IDEA.

    Key files can be converted to use 3DES by creating a special version of ssh-keygen that includes IDEA (was compiled without --without-idea), but that generates key files encrypted with 3DES (edit SSH_AUTHFILE_CIPHER to be SSH_CIPHER_3DES even when WITHOUT_IDEA is not defined). Any operation with re-encrypts the key file can be used, such as changing the comment or changing the passphrase.

    STARTING THE SERVER

    The server should be started at boot from /etc/rc or equivalent. It need not be given any arguments; however, an optional "-b bits" flag may be used to specify RSA key size (default is 768). Key sizes less than 512 can be broken; larger key sizes generally mean more security but require more time to generate and use. 1024 bits is secure for any practical time with current technology.

    The server is not started using inetd, because it needs to generate the RSA key before serving the connection, and this can take about a minute on slower machines. On a fast machine, and small (breakable) key size (< 512 bits) it may be feasible to start the server from inetd on every connection. The server must be given "-i" flag if started from inetd.

    REPLACING RLOGIN AND RSH

    This software has been designed so that it can be installed with the names rlogin, rsh, and rcp, and it will use the Secure Shell protocol whenever the remote machine supports it, and will automatically execute rlogin/rsh (after displaying a warning that there is no encryption) if the remote host does not support Secure Shell.

    Rlogin/rsh replacement is done as follows:

  • ./configure --with-rsh=RSH-PATH --program-transform-name='s/^s/r/'
  • make install
  • where RSH-PATH is the complete pathname of the real rsh program. The rlogin program is searched from the same directory, with the name "rlogin". Note that this means that you need to copy both rsh and rlogin to the same directory, with these names. It is not sufficient to just rename them to e.g. rsh.old.

    This will create links for rlogin, rsh, and rcp. If you are installing them in the same directory where rlogin etc. normally are (e.g., /usr/bin), you must first move the original programs to some other directory (e.g., /usr/lib/rsh).

    When doing this, you should also build a file containing the host keys of all machines in your organization, and copy this file to /etc/ssh_known_hosts on every machine. This will make .rhosts and /etc/hosts.equiv authentication work for users without any changes to the user configuration, but will be much more secure than conventional .rhosts and /etc/hosts.equiv authentication. This will also protect the users against router attacks where someone (perhaps remotely) reconfigures the routers to direct connections to a certain host to a different machine, which can then grab any passwords which the user types thinking he/she is connected to the real machine.

    CLIENT SUID ROOT, SERVER RUN AS ROOT

    This package installs two programs that need special privileges. Ssh is the client program, and it is by default installed as suid root, because it needs to create a privileged port in order to use .rhosts files for authentication. If it is not installed as suid root, it will still be usable, but .rhosts authentication will not be available. Also, the private host key file is readable by root only.

    Sshd is the daemon that listens for connections. It should preferably be run as root, because it is by normally listening on a privileged port, and it needs to be able to do setuid(), update utmp, chown ptys etc. when a user logs in. If it is not run as root, explicit "-p port" option must be given to specify an alternate port (same port must also be specified for clients), "-h host_key_file_path" must be given to specify an alternate host key file, and it cannot be used to log in as any other user than the user running it (because it cannot call setuid()). Also, if your system uses shadow passwords, password authentication will not work when running as someone else than root.

    Both the server and the client have been carefully screened for possible security problems, and are believed to be secure. However, there can be no guarantee. If you find any problems, please report them immediately.

    COMMON PROBLEMS

    This section lists some common installation problems.

    Shadow passwords

    There are many different shadow password schemes. Ssh currently recognizes and supports many of them; however, there are probably still many that it does not understand. This may not be visible at compile time. If your system uses shadow passwords, and password authentication does not work even if sshd is running as root, this is probably your problem. Please contact the author if this happens. Code to recognize (configure.in) and use (auth-passwd.c) the shadow password mechanism on new systems is highly welcome.

    login.c does not compile, or logging of logins does not work properly

    Mechanisms for updating wtmp, utmp, lastlog, and similar mechanisms are not standardized. Ssh substitutes many of the functions of the conventional login program. These functions are implemented in login.c. You may need to modify this file to make it work on exotic systems. Please send any modifications and bug fixes back to the author for inclusion in the distribution. If you just want to try ssh, and cannot get this file to compile, if is safe to define all of the functions as empty; however, in that case logins will not be logged.

    Sshd does not start or dies immediately

    The easiest thing to do is to give the -d option to sshd. It will then send debugging output to stderr (and syslog). The -d option also has other side effects, e.g. the daemon will not fork and will only serve a single connection before exiting. However, it is very useful for debugging problems.

    Sshd sends debugging output to the system log. Check your system log (and syslogd configuration) to see why it dies. One possible reason is that your system does not have a proper host key in /etc/ssh_host_key. You can either generate a key with ssh-keygen (it is automatically generated by "make install"), or specify an alternative key with the -h option to the server. Another reason could be that the port which the server tries to listen is already reserved by some other program.

    Rhosts authentication does not work

    By default, the server does not accept normal .rhosts or /etc/hosts.equiv authentication, because they are fundamentally insecure and can be spoofed by anyone with access to the local network. Rhosts authentication can be enabled at compile time by giving the --with-rhosts option to configure.

    The preferred alternative is to collect the public host keys of the entire site to a file, and copy this to /etc/ssh_known_hosts on every machine in the organization running sshd. This will prevent all IP spoofing attacks and provides improved security (provided rshd, rlogind, and rexecd are disabled).

    Opening connections is too slow

    On very slow machines, encrypting and decrypting the session key may be too slow. For example, on a heavily loaded sun3 it took several minutes to log in with the default key sizes. When we changed it to use shorter host key (512 bits) and server key (384 bits), login time dropped to about a second. A symptom of this problem is that "ssh -v hostname" waits for a long time after printing "Sent encrypted session key".

    Shorter host keys can be generated with "ssh-keygen -b 512", giving /etc/ssh_host_key as the file in which to save the key (with empty passphrase). The server key size can be specified with the -b option on sshd command line (typically, in /etc/rc.local). The server must be restarted for changes to take effect.

    The program complains "Could not set controlling tty" or something similar

    There are many different styles of pseudo ttys. Ssh currently supports about five different styles (plus variations of them). It is quite possible that there are more variations, some of which are not supported by existing code. Fixing the problem may require adding new code in pty.c and configure.in. You are encouraged to write the needed code and send a patch to the author, or at least report the problem.

    General problem solving

    The client has -v option, which sends verbose output to stdout. It is very helpful in solving problems.

    The server has -d option, which causes it to send verbose debugging output to system log and stderr. This option also causes the server to only serve a single connection and not fork, which helps debugging.


    Back to Info Page

    Last modification: 12. 2. 1997 by Jiri Klouda