This file describes how to install the Secure Shell (ssh). Secure Shell is a replacement for rlogin and rsh. It seamlessly encrypts all communications, provides improved security, and has useful new features. INSTALLATION 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. The source is written in ANSI C, and requires an ANSI C compiler or GCC. A copy of GCC is available on all major FTP sites (e.g., in ftp:/prep.ai.mit.edu/pub/gnu). 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: --enable-deprecated-linux-pw-encrypt Enable using of deprecated linx pw_encrypt function. --enable-warnings Enable -Wall if using gcc. --with-x use the X Window System --with-idea Use IDEA (default). --without-idea Don't use IDEA: avoids patent problems in commercial use --with-blowfish Include blowfish (default). --without-blowfish Don't include blowfish --with-des Include single-DES support. --without-des Don't allow single DES (default) --with-arcfour Include arcfour (DO NOT ENABLE, unless you know the security implications of this settings. See README.CIPHERS for more info). --without-arcfour Don't include arcfour (default) --with-none Include support for unencrypted connections --without-none Don't allow unencrypted connections (default) --with-login[=PATH] Use login -f to finish login connections. --with-rsh=PATH Specify where to find rsh. --without-rsh Do not use rsh under any conditions. --with-path=PATH Default path passed to user shell by sshd. --with-etcdir=PATH Directory containing ssh system files (default /etc). --with-securid[=PATH] Enable support for Security Dynamics SecurID card. --with-tis[=DIR] Enable support for TIS authentication server. --with-kerberos5=[KRB_PREFIX] Compile in Kerberos5 support. --enable-kerberos-tgt-passing Pass Kerberos ticket-granting-ticket. --with-libwrap[=PATH] Compile in libwrap (tcp_wrappers) support. --with-socks Compile with SOCKS firewall traversal support. --with-socks5[=PATH] Compile with SOCKS5 firewall traversal support. --with-socks4[=PATH] Compile with SOCKS4 firewall traversal support. --with-rsaref[=PATH] Use RSAREF (try to avoid patent problems in U.S.) --without-rsaref Use normal RSA routines (default). --enable-group-writeability Allow group writeability in auth-rsa. --disable-server-port-forwardings Disable all port forwardings in server (except X11) --disable-client-port-forwardings Disable all port forwardings in client (except X11) --disable-server-x11-forwarding Disable X11 forwarding in server --disable-client-x11-forwarding Disable X11 forwarding in client --enable-suid-ssh Install ssh as suid root (default) --disable-suid-ssh Install ssh without suid bit --disable-asm Disable assembly language optimizations. 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 A/UX 3.1.1 BSD 4.4; several platforms BSD/OS 1.1, 2.0.1, 3.0; i486 BSD/386 1.1; i386 BSDI 2.1, 3.0; x86 (using gnu make) ConvexOS 10.1; Convex Digital Unix 4.0, 4.0A, 4.0B; Alpha DGUX 5.4R2.10; DGUX DolphinOS 3.8 FreeBSD 1.x, 2.x, 3.0; Pentium HPUX 7.x, 9.x, 10.0; HPPA IRIX 5.2, 5.3, 6.2, 6.3, 6.4; SGI Indy, O2 R5000, Onyx 2 R10000 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 3.0.3, 4.0, 5.0; Alpha Linux/Mach3, Macintosh(PowerPC) Linux/m68k (1.2.x, 2.0.x, 2.1.x) Mach3; Mips Mach3/Lites; i386 Machten 2.2VM (m68k); Macintosh NCR Unix 3.00; NCR S40 NetBSD 1.0A, 1.1, 1.2, 1.3; Pentium, Sparc, Mac68k, Alpha, Mips OpenBSD 2.0; x86, mac68k. 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, i386 Solaris 2.3, 2.4, 2.5, 2.5.1, 2.6; 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: - Do "ln -s libc.sa /usr/lib/libg.sa" as root. - Install gcc-2.7.0. - Configure ssh with "CFLAGS=-O ./configure" (i.e., without debug info). 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. Solaris x86 note: The Solaris x86 uses syntax for assembler that is not supported by gmp provided by ssh. The gmp configure will automatically detect this and disable assembler code. Gcc 2.7.2 note: Gcc 2.7.2 has a bugs that will cause "Internal compiler error: program cc1 got fatal signal 6" when compiling some gmp files. Updating to gcc 2.7.2.3 or newer will fix the problem. HP-UX 10.* note: If you are using HP's compilers and get compression failures, try compiling zlib-1.0.4/inftrees.c without optimization. SINIX note: You may have to add "xserver10 6010/tcp", "xserver11 6011/tcp" etc lines to your /etc/services file to get x11 forwarding work properly. IRIX note: the gcc for 6.x series machines might not work properly, so if the ssh-keygen doesn't finish, try using system cc. 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. REPORTING PROBLEMS AND OTHER CONTACTS Please report any bugs, problems, and enhancements to ssh-bugs@cs.hut.fi. There is a mailing list for ssh. It is ssh@clinet.fi. If you would like to join, send a message to majordomo@clinet.fi with "subscribe ssh" in body. The WWW home page for ssh is http://www.cs.hut.fi/ssh. Copyright (c) 1995 Tatu Ylonen , Espoo, Finland.