INSTALL

   1 1. Prerequisites
   2 ----------------
   3
   4 You will need working installations of Zlib and OpenSSL.
   5
   6 Zlib 1.1.4 or 1.2.1.2 or greater (ealier 1.2.x versions have problems):
   7 http://www.gzip.org/zlib/
   8
   9 OpenSSL 0.9.6 or greater:
  10 http://www.openssl.org/
  11
  12 (OpenSSL 0.9.5a is partially supported, but some ciphers (SSH protocol 1
  13 Blowfish) do not work correctly.)
  14
  15 The remaining items are optional.
  16
  17 OpenSSH can utilise Pluggable Authentication Modules (PAM) if your
  18 system supports it. PAM is standard most Linux distributions, Solaris,
  19 HP-UX 11 and AIX >= 5.2.
  20
  21 NB. If you operating system supports /dev/random, you should configure
  22 OpenSSL to use it. OpenSSH relies on OpenSSL's direct support of
  23 /dev/random. If you don't you will have to rely on ssh-rand-helper, which
  24 is inferior to a good kernel-based solution.
  25
  26 Linux PAM:
  27 http://www.kernel.org/pub/linux/libs/pam/
  28
  29 OpenPAM:
  30 http://www.openpam.org/
  31
  32 If you wish to build the GNOME passphrase requester, you will need the GNOME
  33 libraries and headers.
  34
  35 GNOME:
  36 http://www.gnome.org/
  37
  38 Alternatively, Jim Knoble <jmknoble@pobox.com> has written an excellent X11
  39 passphrase requester. This is maintained separately at:
  40
  41 http://www.jmknoble.net/software/x11-ssh-askpass/
  42
  43 PRNGD:
  44
  45 If your system lacks Kernel based random collection, the use of Lutz
  46 Jaenicke's PRNGd is recommended.
  47
  48 http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html
  49
  50 EGD:
  51
  52 The Entropy Gathering Daemon (EGD) is supported if you have a system which
  53 lacks /dev/random and don't want to use OpenSSH's internal entropy collection.
  54
  55 http://www.lothar.com/tech/crypto/
  56
  57 S/Key Libraries:
  58
  59 If you wish to use --with-skey then you will need the library below
  60 installed.  No other S/Key library is currently known to be supported.
  61
  62 http://www.sparc.spb.su/solaris/skey/
  63
  64 LibEdit:
  65
  66 sftp supports command-line editing via NetBSD's libedit.  If your platform
  67 has it available natively you can use that, alternatively you might try
  68 these multi-platform ports:
  69
  70 http://www.thrysoee.dk/editline/
  71 http://sourceforge.net/projects/libedit/
  72
  73 Autoconf:
  74
  75 If you modify configure.ac or configure doesn't exist (eg if you checked
  76 the code out of CVS yourself) then you will need autoconf-2.61 to rebuild
  77 the automatically generated files by running "autoreconf".  Earlier
  78 version may also work but this is not guaranteed.
  79
  80 http://www.gnu.org/software/autoconf/
  81
  82 Basic Security Module (BSM):
  83
  84 Native BSM support is know to exist in Solaris from at least 2.5.1,
  85 FreeBSD 6.1 and OS X.  Alternatively, you may use the OpenBSM
  86 implementation (http://www.openbsm.org).
  87
  88
  89 2. Building / Installation
  90 --------------------------
  91
  92 To install OpenSSH with default options:
  93
  94 ./configure
  95 make
  96 make install
  97
  98 This will install the OpenSSH binaries in /usr/local/bin, configuration files
  99 in /usr/local/etc, the server in /usr/local/sbin, etc. To specify a different
 100 installation prefix, use the --prefix option to configure:
 101
 102 ./configure --prefix=/opt
 103 make
 104 make install
 105
 106 Will install OpenSSH in /opt/{bin,etc,lib,sbin}. You can also override
 107 specific paths, for example:
 108
 109 ./configure --prefix=/opt --sysconfdir=/etc/ssh
 110 make
 111 make install
 112
 113 This will install the binaries in /opt/{bin,lib,sbin}, but will place the
 114 configuration files in /etc/ssh.
 115
 116 If you are using Privilege Separation (which is enabled by default)
 117 then you will also need to create the user, group and directory used by
 118 sshd for privilege separation.  See README.privsep for details.
 119
 120 If you are using PAM, you may need to manually install a PAM control
 121 file as "/etc/pam.d/sshd" (or wherever your system prefers to keep
 122 them).  Note that the service name used to start PAM is __progname,
 123 which is the basename of the path of your sshd (e.g., the service name
 124 for /usr/sbin/osshd will be osshd).  If you have renamed your sshd
 125 executable, your PAM configuration may need to be modified.
 126
 127 A generic PAM configuration is included as "contrib/sshd.pam.generic",
 128 you may need to edit it before using it on your system. If you are
 129 using a recent version of Red Hat Linux, the config file in
 130 contrib/redhat/sshd.pam should be more useful.  Failure to install a
 131 valid PAM file may result in an inability to use password
 132 authentication.  On HP-UX 11 and Solaris, the standard /etc/pam.conf
 133 configuration will work with sshd (sshd will match the other service
 134 name).
 135
 136 There are a few other options to the configure script:
 137
 138 --with-audit=[module] enable additional auditing via the specified module.
 139 Currently, drivers for "debug" (additional info via syslog) and "bsm"
 140 (Sun's Basic Security Module) are supported.
 141
 142 --with-pam enables PAM support. If PAM support is compiled in, it must
 143 also be enabled in sshd_config (refer to the UsePAM directive).
 144
 145 --with-prngd-socket=/some/file allows you to enable EGD or PRNGD
 146 support and to specify a PRNGd socket. Use this if your Unix lacks
 147 /dev/random and you don't want to use OpenSSH's builtin entropy
 148 collection support.
 149
 150 --with-prngd-port=portnum allows you to enable EGD or PRNGD support
 151 and to specify a EGD localhost TCP port. Use this if your Unix lacks
 152 /dev/random and you don't want to use OpenSSH's builtin entropy
 153 collection support.
 154
 155 --with-lastlog=FILE will specify the location of the lastlog file.
 156 ./configure searches a few locations for lastlog, but may not find
 157 it if lastlog is installed in a different place.
 158
 159 --without-lastlog will disable lastlog support entirely.
 160
 161 --with-osfsia, --without-osfsia will enable or disable OSF1's Security
 162 Integration Architecture.  The default for OSF1 machines is enable.
 163
 164 --with-skey=PATH will enable S/Key one time password support. You will
 165 need the S/Key libraries and header files installed for this to work.
 166
 167 --with-tcp-wrappers will enable TCP Wrappers (/etc/hosts.allow|deny)
 168 support. You will need libwrap.a and tcpd.h installed.
 169
 170 --with-md5-passwords will enable the use of MD5 passwords. Enable this
 171 if your operating system uses MD5 passwords and the system crypt() does
 172 not support them directly (see the crypt(3/3c) man page). If enabled, the
 173 resulting binary will support both MD5 and traditional crypt passwords.
 174
 175 --with-utmpx enables utmpx support. utmpx support is automatic for
 176 some platforms.
 177
 178 --without-shadow disables shadow password support.
 179
 180 --with-ipaddr-display forces the use of a numeric IP address in the
 181 $DISPLAY environment variable. Some broken systems need this.
 182
 183 --with-default-path=PATH allows you to specify a default $PATH for sessions
 184 started by sshd. This replaces the standard path entirely.
 185
 186 --with-pid-dir=PATH specifies the directory in which the ssh.pid file is
 187 created.
 188
 189 --with-xauth=PATH specifies the location of the xauth binary
 190
 191 --with-ssl-dir=DIR allows you to specify where your OpenSSL libraries
 192 are installed.
 193
 194 --with-ssl-engine enables OpenSSL's (hardware) ENGINE support
 195
 196 --with-4in6 Check for IPv4 in IPv6 mapped addresses and convert them to
 197 real (AF_INET) IPv4 addresses. Works around some quirks on Linux.
 198
 199 --with-opensc=DIR
 200 --with-sectok=DIR allows for OpenSC or sectok smartcard libraries to
 201 be used with OpenSSH.  See 'README.smartcard' for more details.
 202
 203 If you need to pass special options to the compiler or linker, you
 204 can specify these as environment variables before running ./configure.
 205 For example:
 206
 207 CFLAGS="-O -m486" LDFLAGS="-s" LIBS="-lrubbish" LD="/usr/foo/ld" ./configure
 208
 209 3. Configuration
 210 ----------------
 211
 212 The runtime configuration files are installed by in ${prefix}/etc or
 213 whatever you specified as your --sysconfdir (/usr/local/etc by default).
 214
 215 The default configuration should be instantly usable, though you should
 216 review it to ensure that it matches your security requirements.
 217
 218 To generate a host key, run "make host-key". Alternately you can do so
 219 manually using the following commands:
 220
 221     ssh-keygen -t rsa1 -f /etc/ssh/ssh_host_key -N ""
 222     ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key -N ""
 223     ssh-keygen -t dsa -f /etc/ssh/ssh_host_dsa_key -N ""
 224
 225 Replacing /etc/ssh with the correct path to the configuration directory.
 226 (${prefix}/etc or whatever you specified with --sysconfdir during
 227 configuration)
 228
 229 If you have configured OpenSSH with EGD support, ensure that EGD is
 230 running and has collected some Entropy.
 231
 232 For more information on configuration, please refer to the manual pages
 233 for sshd, ssh and ssh-agent.
 234
 235 4. (Optional) Send survey
 236 -------------------------
 237
 238 $ make survey
 239 [check the contents of the file "survey" to ensure there's no information
 240 that you consider sensitive]
 241 $ make send-survey
 242
 243 This will send configuration information for the currently configured
 244 host to a survey address.  This will help determine which configurations
 245 are actually in use, and what valid combinations of configure options
 246 exist.  The raw data is available only to the OpenSSH developers, however
 247 summary data may be published.
 248
 249 5. Problems?
 250 ------------
 251
 252 If you experience problems compiling, installing or running OpenSSH.
 253 Please refer to the "reporting bugs" section of the webpage at
 254 http://www.openssh.com/
 255
 256
 257 $Id$