blob: dae1bb159cb363819288371a65483f1c84f9c35c [file] [log] [blame]
Damien Millerb5f89271999-11-12 14:35:58 +110011. Prerequisites
2----------------
3
4You will need working installations of Zlib and OpenSSL.
5
Darren Tucker42d30822003-09-22 13:28:36 +10006Zlib 1.1.4 or greater:
Damien Millera8e06ce2003-11-21 23:48:55 +11007http://www.gzip.org/zlib/
Damien Millerb5f89271999-11-12 14:35:58 +11008
Ben Lindstromdc163542002-03-07 17:49:39 +00009OpenSSL 0.9.6 or greater:
Damien Millerb5f89271999-11-12 14:35:58 +110010http://www.openssl.org/
11
Damien Millera8e06ce2003-11-21 23:48:55 +110012(OpenSSL 0.9.5a is partially supported, but some ciphers (SSH protocol 1
Damien Miller6d8d7882002-07-25 14:36:24 +100013Blowfish) do not work correctly.)
Damien Millere71eb912000-04-13 12:19:32 +100014
Damien Millerb5f89271999-11-12 14:35:58 +110015OpenSSH can utilise Pluggable Authentication Modules (PAM) if your system
Kevin Stevesdf4a7ae2000-11-07 14:47:51 +000016supports it. PAM is standard on Redhat and Debian Linux, Solaris and
17HP-UX 11.
Damien Millerb5f89271999-11-12 14:35:58 +110018
Damien Millera8e06ce2003-11-21 23:48:55 +110019NB. If you operating system supports /dev/random, you should configure
20OpenSSL to use it. OpenSSH relies on OpenSSL's direct support of
21/dev/random. If you don't you will have to rely on ssh-rand-helper, which
Damien Millerbd638742002-04-17 12:22:58 +100022is inferior to a good kernel-based solution.
23
Damien Millerb5f89271999-11-12 14:35:58 +110024PAM:
25http://www.kernel.org/pub/linux/libs/pam/
26
Damien Miller780b3761999-12-26 13:36:11 +110027If you wish to build the GNOME passphrase requester, you will need the GNOME
Damien Millerb5f89271999-11-12 14:35:58 +110028libraries and headers.
29
30GNOME:
31http://www.gnome.org/
32
Darren Tucker0ffe6382004-05-27 09:59:31 +100033Alternatively, Jim Knoble <jmknoble@pobox.com> has written an excellent X11
Damien Miller7d7c60d2000-01-26 14:37:48 +110034passphrase requester. This is maintained separately at:
Damien Miller780b3761999-12-26 13:36:11 +110035
Damien Miller80409392003-09-19 17:05:24 +100036http://www.jmknoble.net/software/x11-ssh-askpass/
Damien Miller780b3761999-12-26 13:36:11 +110037
Damien Miller0736c4d2001-01-25 10:51:46 +110038PRNGD:
39
Damien Millera8e06ce2003-11-21 23:48:55 +110040If your system lacks Kernel based random collection, the use of Lutz
Damien Miller0736c4d2001-01-25 10:51:46 +110041Jaenicke's PRNGd is recommended.
42
43http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html
44
45EGD:
46
Damien Miller54057c22000-05-09 15:03:37 +100047The Entropy Gathering Daemon (EGD) is supported if you have a system which
48lacks /dev/random and don't want to use OpenSSH's internal entropy collection.
Damien Millerb5f89271999-11-12 14:35:58 +110049
Damien Millerb5f89271999-11-12 14:35:58 +110050http://www.lothar.com/tech/crypto/
51
Ben Lindstrom305fb002000-11-10 02:41:30 +000052S/Key Libraries:
53http://www.sparc.spb.su/solaris/skey/
54
55If you wish to use --with-skey then you will need the above library
56installed. No other current S/Key library is currently known to be
Damien Millera8e06ce2003-11-21 23:48:55 +110057supported.
Ben Lindstromca1c2a02000-10-14 21:33:19 +000058
Damien Millerb5f89271999-11-12 14:35:58 +1100592. Building / Installation
60--------------------------
61
62To install OpenSSH with default options:
63
64./configure
65make
66make install
67
68This will install the OpenSSH binaries in /usr/local/bin, configuration files
69in /usr/local/etc, the server in /usr/local/sbin, etc. To specify a different
70installation prefix, use the --prefix option to configure:
71
72./configure --prefix=/opt
73make
74make install
75
Damien Millera8e06ce2003-11-21 23:48:55 +110076Will install OpenSSH in /opt/{bin,etc,lib,sbin}. You can also override
Damien Millerb5f89271999-11-12 14:35:58 +110077specific paths, for example:
78
79./configure --prefix=/opt --sysconfdir=/etc/ssh
80make
81make install
82
83This will install the binaries in /opt/{bin,lib,sbin}, but will place the
84configuration files in /etc/ssh.
85
Kevin Steves32c97c32001-04-20 20:56:21 +000086If you are using PAM, you may need to manually install a PAM control
87file as "/etc/pam.d/sshd" (or wherever your system prefers to keep
88them). Note that the service name used to start PAM is __progname,
89which is the basename of the path of your sshd (e.g., the service name
90for /usr/sbin/osshd will be osshd). If you have renamed your sshd
91executable, your PAM configuration may need to be modified.
92
93A generic PAM configuration is included as "contrib/sshd.pam.generic",
94you may need to edit it before using it on your system. If you are
95using a recent version of Red Hat Linux, the config file in
96contrib/redhat/sshd.pam should be more useful. Failure to install a
97valid PAM file may result in an inability to use password
98authentication. On HP-UX 11 and Solaris, the standard /etc/pam.conf
99configuration will work with sshd (sshd will match the other service
Kevin Stevesdf4a7ae2000-11-07 14:47:51 +0000100name).
Damien Miller755c90c1999-11-22 16:12:31 +1100101
Damien Millerb5f89271999-11-12 14:35:58 +1100102There are a few other options to the configure script:
103
Damien Miller5c3a5582003-09-23 22:12:38 +1000104--with-pam enables PAM support. If PAM support is compiled in, it must
105also be enabled in sshd_config (refer to the UsePAM directive).
Damien Millerb5f89271999-11-12 14:35:58 +1100106
Damien Millera8e06ce2003-11-21 23:48:55 +1100107--with-prngd-socket=/some/file allows you to enable EGD or PRNGD
108support and to specify a PRNGd socket. Use this if your Unix lacks
109/dev/random and you don't want to use OpenSSH's builtin entropy
Damien Millerd0ccb982001-03-04 00:29:20 +1100110collection support.
111
Damien Millera8e06ce2003-11-21 23:48:55 +1100112--with-prngd-port=portnum allows you to enable EGD or PRNGD support
113and to specify a EGD localhost TCP port. Use this if your Unix lacks
114/dev/random and you don't want to use OpenSSH's builtin entropy
Damien Miller0736c4d2001-01-25 10:51:46 +1100115collection support.
Damien Millerb5f89271999-11-12 14:35:58 +1100116
Damien Millera8e06ce2003-11-21 23:48:55 +1100117--with-lastlog=FILE will specify the location of the lastlog file.
Damien Miller8bdeee21999-12-30 15:50:54 +1100118./configure searches a few locations for lastlog, but may not find
119it if lastlog is installed in a different place.
120
121--without-lastlog will disable lastlog support entirely.
122
Damien Millera8e06ce2003-11-21 23:48:55 +1100123--with-osfsia, --without-osfsia will enable or disable OSF1's Security
Ben Lindstrom72af2ef2001-05-08 20:42:28 +0000124Integration Architecture. The default for OSF1 machines is enable.
125
Damien Millera8e06ce2003-11-21 23:48:55 +1100126--with-skey=PATH will enable S/Key one time password support. You will
Ben Lindstrom305fb002000-11-10 02:41:30 +0000127need the S/Key libraries and header files installed for this to work.
Damien Millerc0967271999-11-19 15:53:50 +1100128
129--with-tcp-wrappers will enable TCP Wrappers (/etc/hosts.allow|deny)
130support. You will need libwrap.a and tcpd.h installed.
131
132--with-md5-passwords will enable the use of MD5 passwords. Enable this
Darren Tucker0d37b5c2003-10-21 12:41:14 +1000133if your operating system uses MD5 passwords and the system crypt() does
134not support them directly (see the crypt(3/3c) man page). If enabled, the
135resulting binary will support both MD5 and traditional crypt passwords.
Damien Miller3d1b22c1999-11-12 15:46:08 +1100136
Damien Millera8e06ce2003-11-21 23:48:55 +1100137--with-utmpx enables utmpx support. utmpx support is automatic for
Damien Miller8bdeee21999-12-30 15:50:54 +1100138some platforms.
139
140--without-shadow disables shadow password support.
141
Damien Millera8e06ce2003-11-21 23:48:55 +1100142--with-ipaddr-display forces the use of a numeric IP address in the
Damien Miller8bdeee21999-12-30 15:50:54 +1100143$DISPLAY environment variable. Some broken systems need this.
144
145--with-default-path=PATH allows you to specify a default $PATH for sessions
Damien Miller29ea30d2000-03-17 10:54:15 +1100146started by sshd. This replaces the standard path entirely.
Damien Miller8bdeee21999-12-30 15:50:54 +1100147
Damien Miller5eed6a22000-01-16 12:05:18 +1100148--with-pid-dir=PATH specifies the directory in which the ssh.pid file is
149created.
150
151--with-xauth=PATH specifies the location of the xauth binary
152
Damien Miller0c0e4bf2000-02-03 13:58:51 +1100153--with-ssl-dir=DIR allows you to specify where your OpenSSL libraries
154are installed.
155
Damien Millerfd263682000-03-16 11:51:09 +1100156--with-4in6 Check for IPv4 in IPv6 mapped addresses and convert them to
157real (AF_INET) IPv4 addresses. Works around some quirks on Linux.
158
Ben Lindstroma42694f2002-04-05 16:11:45 +0000159--with-opensc=DIR
160--with-sectok=DIR allows for OpenSC or sectok smartcard libraries to
161be used with OpenSSH. See 'README.smartcard' for more details.
162
Damien Millerbeb4ba51999-12-28 15:09:35 +1100163If you need to pass special options to the compiler or linker, you
Damien Miller615f9392000-05-17 22:53:33 +1000164can specify these as environment variables before running ./configure.
Damien Millerbeb4ba51999-12-28 15:09:35 +1100165For example:
166
Damien Millerb5c42d92000-08-31 11:13:10 +1100167CFLAGS="-O -m486" LDFLAGS="-s" LIBS="-lrubbish" LD="/usr/foo/ld" ./configure
Damien Millerb5f89271999-11-12 14:35:58 +1100168
1693. Configuration
170----------------
171
Damien Millera8e06ce2003-11-21 23:48:55 +1100172The runtime configuration files are installed by in ${prefix}/etc or
Damien Millerb5f89271999-11-12 14:35:58 +1100173whatever you specified as your --sysconfdir (/usr/local/etc by default).
174
Damien Millera8e06ce2003-11-21 23:48:55 +1100175The default configuration should be instantly usable, though you should
Damien Millerb5f89271999-11-12 14:35:58 +1100176review it to ensure that it matches your security requirements.
177
Damien Miller4095f892000-03-03 22:13:52 +1100178To generate a host key, run "make host-key". Alternately you can do so
Damien Millera8e06ce2003-11-21 23:48:55 +1100179manually using the following commands:
Damien Miller2a9d9f61999-11-15 23:34:11 +1100180
Damien Miller86093322001-02-18 12:58:24 +1100181 ssh-keygen -t rsa1 -f /etc/ssh/ssh_host_key -N ""
182 ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key -N ""
183 ssh-keygen -t dsa -f /etc/ssh/ssh_host_dsa_key -N ""
Damien Miller2a9d9f61999-11-15 23:34:11 +1100184
Damien Miller6ae00d61999-12-14 15:43:03 +1100185Replacing /etc/ssh with the correct path to the configuration directory.
Damien Millera8e06ce2003-11-21 23:48:55 +1100186(${prefix}/etc or whatever you specified with --sysconfdir during
Damien Miller6ae00d61999-12-14 15:43:03 +1100187configuration)
188
Damien Millerab8a4da1999-12-16 13:05:30 +1100189If you have configured OpenSSH with EGD support, ensure that EGD is
190running and has collected some Entropy.
191
Damien Millera8e06ce2003-11-21 23:48:55 +1100192For more information on configuration, please refer to the manual pages
Damien Millerb5f89271999-11-12 14:35:58 +1100193for sshd, ssh and ssh-agent.
194
Damien Miller6ae00d61999-12-14 15:43:03 +11001954. Problems?
196------------
197
Damien Millera8e06ce2003-11-21 23:48:55 +1100198If you experience problems compiling, installing or running OpenSSH.
Damien Miller6ae00d61999-12-14 15:43:03 +1100199Please refer to the "reporting bugs" section of the webpage at
Damien Miller615f9392000-05-17 22:53:33 +1000200http://www.openssh.com/
Damien Miller6ae00d61999-12-14 15:43:03 +1100201
Damien Millere9cf3572001-02-09 12:55:35 +1100202
Darren Tucker0ffe6382004-05-27 09:59:31 +1000203$Id: INSTALL,v 1.64 2004/05/26 23:59:31 dtucker Exp $