Annotation of src/usr.bin/ssh/INSTALL, Revision 1.1
1.1 ! deraadt 1: This is a hacked-up version of ssh-1.2.12.
! 2:
! 3: The GMP and DES sources are now external to the distribution. To build
! 4: this software it is necessary to first have GMP and a DES
! 5: implementation installed somewhere. Some systems comes with GMP and
! 6: DES preinstalled. If your system doesn't; pick up the GMP sources from
! 7: your favorite GNU ftp site (ftp://prep.ai.mit.edu/pub/gnu/). There is
! 8: a free DES implementation made by Eric Young that can be found under
! 9: the name libdes-x.x.x.tar.gz, for example at
! 10: ftp://ftp.psy.uq.oz.au/pub/Crypto/DES/.
! 11:
! 12: The distribution optionally supports Kerberos version 4 authentication
! 13: and AFS. If you want to build with Kerberos support and your system
! 14: comes with Kerberos preinstalled add the switch --with-krb4=/usr to
! 15: configure. Otherwise, first build and install Kerberos and then use
! 16: --with-krb4=/usr/whatever-directory. If you don't want Kerberos
! 17: support use --without-krb4 (the default). Kerberos can be found at
! 18: ftp://ftp.pdc.kth.se/pub/krb/src/.
! 19:
! 20: Compression support is now optional. If you don't have zlib installed
! 21: configure using --without-zlib or first install zlib. We have
! 22: succesfully used zlib-1.0.4.tar.gz
! 23:
! 24: For more detailed installation instructions read the rest of this file
! 25: and README.AFS-KERBEROS.
! 26:
! 27: ----------------------------------------------------------------------------
! 28: This file describes how to install the Secure Shell (ssh). Secure Shell is
! 29: a replacement for rlogin and rsh. It seamlessly encrypts all communications,
! 30: provides improved security, and has useful new features.
! 31:
! 32:
! 33: INSTALLATION
! 34:
! 35: For most machines and configurations, the following is all you need.
! 36:
! 37: ./configure
! 38: make
! 39: make install
! 40:
! 41: Then check (and edit if needed) the following files:
! 42: /etc/sshd_config (server configuration file)
! 43: /etc/ssh_config (client configuration file - defaults for users)
! 44:
! 45: You may also want to create the /etc/ssh_known_hosts for your site and update
! 46: it periodically. See the manual page for make-ssh-known-hosts on how to
! 47: do this easily. The file format is documented on the sshd manual page.
! 48:
! 49: The source is written in ANSI C, and requires an ANSI C compiler or GCC.
! 50: A copy of GCC is available on all major FTP sites (e.g., in
! 51: ftp:/prep.ai.mit.edu/pub/gnu).
! 52:
! 53:
! 54: CONFIGURATION OPTIONS
! 55:
! 56: The package comes with an Autoconf-generated configure script. The
! 57: script accepts several options
! 58: All standard options, including:
! 59: --prefix=PREFIX where to install files (default: subdirs of /usr/local)
! 60: --exec_prefix=PREFIX where to install executables (default: same as prefix)
! 61: --srcdir=DIR find sources in DIR (default: where configure is)
! 62: Specific options:
! 63: --with-rsh=PATH Use rsh specified by PATH when needed
! 64: --with-etcdir=PATH Store system files in the given dir (default: /etc)
! 65: --with-path=PATH Default path to pass to user shell.
! 66: --with-rsaref Use rsaref2 from rsaref2 subdirectory (see below).
! 67: --with-libwrap[=PATH] Use libwrap (tcp_wrappers) and identd (see below).
! 68: --with-socks[=PATH] Include SOCKS (firewall traversal) support.
! 69: --without-idea Don't include IDEA (see below).
! 70: --with-securid[=PATH] Support for the SecurID card (see README.SECURID).
! 71: --enable-warnings Adds -Wall to CFLAGS if using gcc.
! 72:
! 73: You may also want to configure the following variables:
! 74: CC=compiler specify name of the C compiler (default: gcc or cc)
! 75: CFLAGS=flags specify flags to C compiler (default: -O -g or just -O)
! 76: LDFLAGS=flags specify flags to linker (default: none)
! 77:
! 78: Alternate values can be given to configure in the environment, e.g.:
! 79: CC=xcc CFLAGS="-O2" LDFLAGS="-L/lib/zzz" ./configure
! 80: (Note that if you have already configured, and later decide to give
! 81: some values on the command line, you may need to say "make distclean"
! 82: before reconfiguring.)
! 83:
! 84:
! 85: CONFIGURATION FILES
! 86:
! 87: The server has a configuration file /etc/sshd_config, which specifies the
! 88: permitted authentication methods, hosts, port number, etc. The defaults are
! 89: acceptable for most sites, but you may want to check this file. Its format
! 90: is documented on the sshd manual page.
! 91:
! 92: The client reads a configuration file /etc/ssh_config, which gives
! 93: site-wide defaults for various options. Options in this file can be
! 94: overridden by per-user configuration files. The file is documented on
! 95: the ssh manual page.
! 96:
! 97:
! 98: MAKEFILE
! 99:
! 100: The Makefile is generated from Makefile.in by running configure. It supports
! 101: the following targets:
! 102: all: compile everything
! 103: install: install in $exec_prefix/bin and $prefix/man/man1.
! 104: uninstall: remove installed files
! 105: clean: remove object files and executables
! 106: distclean: remove anything not in the distribution
! 107:
! 108:
! 109: PORTABILITY
! 110:
! 111: This software has been used at least in the following environments.
! 112:
! 113: 386BSD 0.1; i386
! 114: AIX 3.2.5, 4.1; RS6000, PowerPC
! 115: BSD 4.4; several platforms
! 116: BSD/OS 1.1, 2.0.1; i486
! 117: BSD/386 1.1; i386
! 118: ConvexOS 10.1; Convex
! 119: DGUX 5.4R2.10; DGUX
! 120: FreeBSD 1.x, 2.x; Pentium
! 121: HPUX 9.0x, 10.0; HPPA
! 122: IRIX 5.2, 5.3; SGI Indy
! 123: IRIX 6.0.1; Mips-R8000
! 124: Linux 1.2.8 Slackware 2.1.0; i486
! 125: Mach3; Mips
! 126: Mach3/Lites; i386
! 127: Machten 2.2
! 128: NetBSD 1.0A; Pentium, Sparc
! 129: OSF/1 3.0, 3.2, 3.2a; Alpha
! 130: Sequent Dynix/ptx 3.2.0 V2.1.0; i386
! 131: SCO Unix; i386 (client only)
! 132: SINIX 5.42; Mips R4000
! 133: Solaris 2.3, 2.4; Sparc
! 134: Sony NEWS-OS 3.3 (BSD 4.3); m68k
! 135: SunOS 4.1.2, 4.1.3, 4.1.4; Sparc
! 136: SysV 4.x; several platforms
! 137: Ultrix x.x; Mips
! 138: Unicos 8.0.3; Cray C90
! 139:
! 140: Please report back any other environments where you have used ssh,
! 141: and send back any patches you had to do so that they can be integrated
! 142: to the distribution. The proper address is ossh-bugs@sics.se.
! 143: Always remember to mention the ssh version number and machine type in
! 144: your bug reports. Please include also the output of the -v option
! 145: from the client side, and the output of the -d option from the server,
! 146: if applicable.
! 147:
! 148: Not all compilers work in all environments. If you have problems, try
! 149: compiling with gcc-2.7. *** SPARC NOTE: gcc-2.7.0 appears to generate
! 150: bad code on Sparc (Solaris 2.3) when compiling without -O. Try
! 151: gcc-2.6.3 or compile with -O. ***
! 152:
! 153: Solaris 2.4 note: you need to install "kernel jumbo patch number
! 154: 101945-32" (dated August 31, 1995) for ssh to work. The symptom is
! 155: that ssh dies with a "Resource temporarily unavailable" error.
! 156:
! 157: Linux note: Some linux systems have a bug which causes an error about
! 158: libc.so.4 when compiling ssh. This can be solved by any of the
! 159: following ways:
! 160: - Do "ln -s libc.sa /usr/lib/libg.sa" as root.
! 161: - Install gcc-2.7.0.
! 162: - Configure ssh with "CFLAGS=-O ./configure" (i.e., without debug info).
! 163: More information on this problem is available in
! 164: ftp://ftp.netcom.com/pub/ze/zenon/linux.
! 165:
! 166: BSDI BSD/OS note: Apparently the gcc that comes with BSD/OS is
! 167: broken. Use "CC=cc ./configure" or "setenv CC cc; ./configure" when
! 168: configuring to force it to use cc instead of gcc.
! 169:
! 170: ConvexOS note: Convex "make" is broken. Install GNU make first if you
! 171: have trouble compiling ssh.
! 172:
! 173:
! 174: COMPILING WITH RSAREF2
! 175:
! 176: If you are using ssh in the United States, you may want to use the
! 177: RSAREF2 library from RSADSI. This may make it legal to use ssh
! 178: without a separate license for non-commercial purposes. RSAREF2 is
! 179: not included in the distribution; however, it is available on any
! 180: major ftp site around the world (e.g.,
! 181: ftp://ftp.funet.fi/pub/crypt/cryptography/asymmetric/rsa/rsaref2.tar.gz).
! 182: The RSAREF2 distribution should be unpacked into "rsaref2"
! 183: subdirectory in the ssh distribution directory (a symbolic link to
! 184: rsaref2 is not sufficient). Configure should be given the
! 185: --with-rsaref option. (Note that there is no need to *compile*
! 186: rsaref2 manually; the ssh Makefile will compile those files it needs.)
! 187:
! 188: Using RSAREF outside the United States is not recommended and only
! 189: causes legal complications.
! 190:
! 191: RSAREF2 does not work for large key sizes (> 1024). This may be the
! 192: problem if you get "RSAPrivateDecrypt failed".
! 193:
! 194: On alpha, one should edit rsaref2/source/global.h, and make UINT4
! 195: "unsigned int" instead of "unsigned long int".
! 196:
! 197:
! 198: LIBWRAP AND IDENTD
! 199:
! 200: Ssh does not normally use identd or tcp-wrappers. However, it can be
! 201: compiled to use these by adding --with-libwrap on the command line.
! 202: This requires that the tcp_wrappers libwrap.a library and the
! 203: associated tcpd.h have been installed somewhere where the compiler can
! 204: find them. With libwrap support, ssh will process the
! 205: /etc/hosts.allow and /etc/hosts.deny files, and use identd if required
! 206: by them. The name of the user on the client side (as returned by
! 207: identd) will be logged if requested by the configuration files. See
! 208: tcp_wrappers documentation for more information.
! 209:
! 210:
! 211: COMPILING WITHOUT IDEA
! 212:
! 213: The IDEA cipher can be freely used for non-commercial use. However,
! 214: commercial use may require a license in a number of countries.
! 215:
! 216: Ssh can be compiled without IDEA by using the --without-idea configure
! 217: option. This disables IDEA, and causes 3DES to be used for encrypting
! 218: key/identity files and as the default session cipher. (The default
! 219: session cipher can be changed by editing SSH_FALLBACK_CIPHER in
! 220: ssh.h.)
! 221:
! 222: If one disables IDEA after having used it for some time, it is
! 223: possible that there are key files around that were encrypted with IDEA.
! 224:
! 225: Key files can be converted to use 3DES by creating a special version
! 226: of ssh-keygen that includes IDEA (was compiled without
! 227: --without-idea), but that generates key files encrypted with 3DES
! 228: (edit SSH_AUTHFILE_CIPHER to be SSH_CIPHER_3DES even when WITHOUT_IDEA
! 229: is not defined). Any operation with re-encrypts the key file can be
! 230: used, such as changing the comment or changing the passphrase.
! 231:
! 232:
! 233: STARTING THE SERVER
! 234:
! 235: The server should be started at boot from /etc/rc or equivalent. It
! 236: need not be given any arguments; however, an optional "-b bits" flag
! 237: may be used to specify RSA key size (default is 768). Key sizes less
! 238: than 512 can be broken; larger key sizes generally mean more security
! 239: but require more time to generate and use. 1024 bits is secure for
! 240: any practical time with current technology.
! 241:
! 242: The server is not started using inetd, because it needs to generate
! 243: the RSA key before serving the connection, and this can take about a
! 244: minute on slower machines. On a fast machine, and small (breakable)
! 245: key size (< 512 bits) it may be feasible to start the server from
! 246: inetd on every connection. The server must be given "-i" flag if
! 247: started from inetd.
! 248:
! 249:
! 250: REPLACING RLOGIN AND RSH
! 251:
! 252: This software has been designed so that it can be installed with the
! 253: names rlogin, rsh, and rcp, and it will use the Secure Shell
! 254: protocol whenever the remote machine supports it, and will
! 255: automatically execute rlogin/rsh (after displaying a warning that
! 256: there is no encryption) if the remote host does not support Secure
! 257: Shell.
! 258:
! 259: Rlogin/rsh replacement is done as follows:
! 260: ./configure --with-rsh=RSH-PATH --program-transform-name='s/^s/r/'
! 261: make install
! 262:
! 263: where RSH-PATH is the complete pathname of the real rsh program. (You
! 264: may want to copy the old rsh program to a suitable location).
! 265:
! 266: This will create links for rlogin, rsh, and rcp. If you are
! 267: installing them in the same directory where rlogin etc. normally are
! 268: (e.g., /usr/bin), you must first move the original programs to some
! 269: other directory (e.g., /usr/lib/rsh).
! 270:
! 271: When doing this, you should also build a file containing the host keys of all
! 272: machines in your organization, and copy this file to /etc/ssh_known_hosts
! 273: on every machine. This will make .rhosts and /etc/hosts.equiv authentication
! 274: work for users without any changes to the user configuration, but will be
! 275: much more secure than conventional .rhosts and /etc/hosts.equiv authentication.
! 276: This will also protect the users against router attacks where someone (perhaps
! 277: remotely) reconfigures the routers to direct connections to a certain host
! 278: to a different machine, which can then grab any passwords which the user
! 279: types thinking he/she is connected to the real machine.
! 280:
! 281:
! 282: CLIENT SUID ROOT, SERVER RUN AS ROOT
! 283:
! 284: This package installs two programs that need special privileges. Ssh
! 285: is the client program, and it is by default installed as suid root,
! 286: because it needs to create a privileged port in order to use .rhosts
! 287: files for authentication. If it is not installed as suid root, it will
! 288: still be usable, but .rhosts authentication will not be available. Also, the
! 289: private host key file is readable by root only.
! 290:
! 291: Sshd is the daemon that listens for connections. It should preferably
! 292: be run as root, because it is by normally listening on a privileged
! 293: port, and it needs to be able to do setuid(), update utmp, chown ptys
! 294: etc. when a user logs in. If it is not run as root, explicit "-p
! 295: port" option must be given to specify an alternate port (same port
! 296: must also be specified for clients), "-h host_key_file_path" must be
! 297: given to specify an alternate host key file, and it cannot be used to
! 298: log in as any other user than the user running it (because it cannot
! 299: call setuid()). Also, if your system uses shadow passwords, password
! 300: authentication will not work when running as someone else than root.
! 301:
! 302: Both the server and the client have been carefully screened for
! 303: possible security problems, and are believed to be secure. However,
! 304: there can be no guarantee. If you find any problems, please report
! 305: them immediately.
! 306:
! 307:
! 308: COMMON PROBLEMS
! 309:
! 310: This section lists some common installation problems.
! 311:
! 312: Shadow passwords
! 313:
! 314: There are many different shadow password schemes. Ssh currently recognizes
! 315: and supports many of them; however, there are probably still many that
! 316: it does not understand. This may not be visible at compile time.
! 317: If your system uses shadow passwords, and password authentication does not
! 318: work even if sshd is running as root, this is probably your problem.
! 319: Please contact the author if this happens. Code to recognize (configure.in)
! 320: and use (auth-passwd.c) the shadow password mechanism on new systems
! 321: is highly welcome.
! 322:
! 323: login.c does not compile, or logging of logins does not work properly
! 324:
! 325: Mechanisms for updating wtmp, utmp, lastlog, and similar mechanisms
! 326: are not standardized. Ssh substitutes many of the functions of the
! 327: conventional login program. These functions are implemented in login.c.
! 328: You may need to modify this file to make it work on exotic systems.
! 329: Please send any modifications and bug fixes back to the author for inclusion
! 330: in the distribution. If you just want to try ssh, and cannot get this file
! 331: to compile, if is safe to define all of the functions as empty; however,
! 332: in that case logins will not be logged.
! 333:
! 334: Sshd does not start or dies immediately
! 335:
! 336: The easiest thing to do is to give the -d option to sshd. It will
! 337: then send debugging output to stderr (and syslog). The -d option
! 338: also has other side effects, e.g. the daemon will not fork and will
! 339: only serve a single connection before exiting. However, it is very
! 340: useful for debugging problems.
! 341:
! 342: Sshd sends debugging output to the system log. Check your system
! 343: log (and syslogd configuration) to see why it dies. One possible
! 344: reason is that your system does not have a proper host key in
! 345: /etc/ssh_host_key. You can either generate a key with ssh-keygen
! 346: (it is automatically generated by "make install"), or specify an
! 347: alternative key with the -h option to the server. Another reason
! 348: could be that the port which the server tries to listen is already
! 349: reserved by some other program.
! 350:
! 351: Rhosts authentication does not work
! 352:
! 353: By default, the server does not accept normal .rhosts or /etc/hosts.equiv
! 354: authentication, because they are fundamentally insecure and can be spoofed
! 355: by anyone with access to the local network. Rhosts authentication can be
! 356: enabled at compile time by giving the --with-rhosts option to configure.
! 357:
! 358: The preferred alternative is to collect the public host keys of the entire
! 359: site to a file, and copy this to /etc/ssh_known_hosts on every machine in
! 360: the organization running sshd. This will prevent all IP spoofing attacks
! 361: and provides improved security (provided rshd, rlogind, and rexecd are
! 362: disabled).
! 363:
! 364: Opening connections is too slow
! 365:
! 366: On very slow machines, encrypting and decrypting the session key may
! 367: be too slow. For example, on a heavily loaded sun3 it took
! 368: several minutes to log in with the default key sizes. When we changed it
! 369: to use shorter host key (512 bits) and server key (384 bits),
! 370: login time dropped to about a second. A symptom of this problem is
! 371: that "ssh -v hostname" waits for a long time after printing "Sent
! 372: encrypted session key".
! 373:
! 374: Shorter host keys can be generated with "ssh-keygen -b 512", giving
! 375: /etc/ssh_host_key as the file in which to save the key (with empty
! 376: passphrase). The server key size can be specified with the -b
! 377: option on sshd command line (typically, in /etc/rc.local). The
! 378: server must be restarted for changes to take effect.
! 379:
! 380: The program complains "Could not set controlling tty" or something similar
! 381:
! 382: There are many different styles of pseudo ttys. Ssh currently
! 383: supports about five different styles (plus variations of them). It
! 384: is quite possible that there are more variations, some of which are
! 385: not supported by existing code. Fixing the problem may require
! 386: adding new code in pty.c and configure.in. You are encouraged to
! 387: write the needed code and send a patch to the author, or at least
! 388: report the problem.
! 389:
! 390: General problem solving
! 391:
! 392: The client has -v option, which sends verbose output to stdout. It
! 393: is very helpful in solving problems.
! 394:
! 395: The server has -d option, which causes it to send verbose debugging
! 396: output to system log and stderr. This option also causes the server
! 397: to only serve a single connection and not fork, which helps debugging.
! 398:
! 399:
! 400: REPORTING PROBLEMS AND OTHER CONTACTS
! 401:
! 402: Please report any bugs, problems, and enhancements to
! 403: ossh-bugs@sics.se.
! 404:
! 405: There is a mailing list for ossh. It is ossh@sics.se. If you would
! 406: like to join, send a message to majordomo@sics.se with "subscribe
! 407: ossh" in body.
! 408:
! 409: Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland.
![[BACK]](/icons/back.gif){kind=icon}
Return to INSTALL CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh