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