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