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