2 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
3 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
4 .\" All rights reserved
6 .\" As far as I am concerned, the code I have written for this software
7 .\" can be used freely for any purpose. Any derived versions of this
8 .\" software must be clearly marked as such, and if the derived work is
9 .\" incompatible with the protocol description in the RFC file, it must be
10 .\" called by a name other than "ssh" or "Secure Shell".
12 .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
13 .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
14 .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
16 .\" Redistribution and use in source and binary forms, with or without
17 .\" modification, are permitted provided that the following conditions
19 .\" 1. Redistributions of source code must retain the above copyright
20 .\" notice, this list of conditions and the following disclaimer.
21 .\" 2. Redistributions in binary form must reproduce the above copyright
22 .\" notice, this list of conditions and the following disclaimer in the
23 .\" documentation and/or other materials provided with the distribution.
25 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
27 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
28 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
29 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
30 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
31 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
32 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
34 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 .\" $OpenBSD: sshd.8,v 1.288 2017/01/30 23:27:39 dtucker Exp $
38 .Dd $Mdocdate: January 30 2017 $
43 .Nd OpenSSH SSH daemon
48 .Op Fl C Ar connection_spec
49 .Op Fl c Ar host_certificate_file
51 .Op Fl f Ar config_file
52 .Op Fl g Ar login_grace_time
53 .Op Fl h Ar host_key_file
60 (OpenSSH Daemon) is the daemon program for
62 Together these programs replace rlogin and rsh,
63 and provide secure encrypted communications between two untrusted hosts
64 over an insecure network.
67 listens for connections from clients.
68 It is normally started at boot from
71 daemon for each incoming connection.
72 The forked daemons handle
73 key exchange, encryption, authentication, command execution,
77 can be configured using command-line options or a configuration file
80 command-line options override values specified in the
83 rereads its configuration file when it receives a hangup signal,
85 by executing itself with the name and options it was started with, e.g.\&
88 The options are as follows:
93 to use IPv4 addresses only.
97 to use IPv6 addresses only.
98 .It Fl C Ar connection_spec
99 Specify the connection parameters to use for the
104 directives in the configuration file
105 that would apply to the specified user, host, and address will be set before
106 the configuration is written to standard output.
107 The connection parameters are supplied as keyword=value pairs.
115 All are required and may be supplied in any order, either with multiple
117 options or as a comma-separated list.
118 .It Fl c Ar host_certificate_file
119 Specifies a path to a certificate file to identify
122 The certificate file must match a host key file specified using the
126 configuration directive.
128 When this option is specified,
130 will not detach and does not become a daemon.
131 This allows easy monitoring of
135 The server sends verbose debug output to standard error,
136 and does not put itself in the background.
137 The server also will not fork and will only process one connection.
138 This option is only intended for debugging for the server.
141 options increase the debugging level.
146 instead of the system log.
148 Write debug logs to standard error instead of the system log.
149 .It Fl f Ar config_file
150 Specifies the name of the configuration file.
152 .Pa /etc/ssh/sshd_config .
154 refuses to start if there is no configuration file.
155 .It Fl g Ar login_grace_time
156 Gives the grace time for clients to authenticate themselves (default
158 If the client fails to authenticate the user within
159 this many seconds, the server disconnects and exits.
160 A value of zero indicates no limit.
161 .It Fl h Ar host_key_file
162 Specifies a file from which a host key is read.
163 This option must be given if
165 is not run as root (as the normal
166 host key files are normally not readable by anyone but root).
168 .Pa /etc/ssh/ssh_host_dsa_key ,
169 .Pa /etc/ssh/ssh_host_ecdsa_key ,
170 .Pa /etc/ssh/ssh_host_ed25519_key
172 .Pa /etc/ssh/ssh_host_rsa_key .
173 It is possible to have multiple host key files for
174 the different host key algorithms.
181 Can be used to give options in the format used in the configuration file.
182 This is useful for specifying options for which there is no separate
184 For full details of the options, and their values, see
187 Specifies the port on which the server listens for connections
189 Multiple port options are permitted.
190 Ports specified in the configuration file with the
192 option are ignored when a command-line port is specified.
193 Ports specified using the
195 option override command-line ports.
198 Nothing is sent to the system log.
199 Normally the beginning,
200 authentication, and termination of each connection is logged.
203 Check the validity of the configuration file, output the effective configuration
204 to stdout and then exit.
207 rules may be applied by specifying the connection parameters using one or more
212 Only check the validity of the configuration file and sanity of the keys.
213 This is useful for updating
215 reliably as configuration options may change.
217 This option is used to specify the size of the field
220 structure that holds the remote host name.
221 If the resolved host name is longer than
223 the dotted decimal value will be used instead.
224 This allows hosts with very long host names that
225 overflow this field to still be uniquely identified.
228 indicates that only dotted decimal addresses
229 should be put into the
233 may also be used to prevent
235 from making DNS requests unless the authentication
236 mechanism or configuration requires it.
237 Authentication mechanisms that may require DNS include
238 .Cm HostbasedAuthentication
240 .Cm from="pattern-list"
241 option in a key file.
242 Configuration options that require DNS include using a
249 The OpenSSH SSH daemon supports SSH protocol 2 only.
250 Each host has a host-specific key,
251 used to identify the host.
252 Whenever a client connects, the daemon responds with its public
254 The client compares the
255 host key against its own database to verify that it has not changed.
256 Forward security is provided through a Diffie-Hellman key agreement.
257 This key agreement results in a shared session key.
258 The rest of the session is encrypted using a symmetric cipher, currently
259 128-bit AES, Blowfish, 3DES, CAST128, Arcfour, 192-bit AES, or 256-bit AES.
260 The client selects the encryption algorithm
261 to use from those offered by the server.
262 Additionally, session integrity is provided
263 through a cryptographic message authentication code
264 (hmac-md5, hmac-sha1, umac-64, umac-128, hmac-ripemd160,
265 hmac-sha2-256 or hmac-sha2-512).
267 Finally, the server and the client enter an authentication dialog.
268 The client tries to authenticate itself using
269 host-based authentication,
270 public key authentication,
271 challenge-response authentication,
272 or password authentication.
274 Regardless of the authentication type, the account is checked to
275 ensure that it is accessible. An account is not accessible if it is
278 or its group is listed in
280 \&. The definition of a locked account is system dependant. Some platforms
281 have their own account database (eg AIX) and some modify the passwd field (
283 on Solaris and UnixWare,
290 on FreeBSD and a leading
293 If there is a requirement to disable password authentication
294 for the account while allowing still public-key, then the passwd field
295 should be set to something other than these values (eg
301 If the client successfully authenticates itself, a dialog for
302 preparing the session is entered.
303 At this time the client may request
304 things like allocating a pseudo-tty, forwarding X11 connections,
305 forwarding TCP connections, or forwarding the authentication agent
306 connection over the secure channel.
308 After this, the client either requests a shell or execution of a command.
309 The sides then enter session mode.
310 In this mode, either side may send
311 data at any time, and such data is forwarded to/from the shell or
312 command on the server side, and the user terminal in the client side.
314 When the user program terminates and all forwarded X11 and other
315 connections have been closed, the server sends command exit status to
316 the client, and both sides exit.
318 When a user successfully logs in,
321 .Bl -enum -offset indent
323 If the login is on a tty, and no command has been specified,
324 prints last login time and
326 (unless prevented in the configuration file or by
332 If the login is on a tty, records login time.
336 .Pa /var/run/nologin ;
337 if one exists, it prints the contents and quits
340 Changes to run with normal user privileges.
342 Sets up basic environment.
345 .Pa ~/.ssh/environment ,
346 if it exists, and users are allowed to change their environment.
348 .Cm PermitUserEnvironment
352 Changes to user's home directory.
359 option is set, runs it; else if
366 files are given the X11
367 authentication protocol and cookie in standard input.
372 Runs user's shell or command.
373 All commands are run under the user's login shell as specified in the
374 system password database.
381 runs it after reading the
382 environment files but before starting the user's shell or command.
383 It must not produce any output on stdout; stderr must be used
385 If X11 forwarding is in use, it will receive the "proto cookie" pair in
386 its standard input (and
393 will not run xauth automatically to add X11 cookies.
395 The primary purpose of this file is to run any initialization routines
396 which may be needed before the user's home directory becomes
397 accessible; AFS is a particular example of such an environment.
399 This file will probably contain some initialization code followed by
400 something similar to:
401 .Bd -literal -offset 3n
402 if read proto cookie && [ -n "$DISPLAY" ]; then
403 if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then
404 # X11UseLocalhost=yes
405 echo add unix:`echo $DISPLAY |
406 cut -c11-` $proto $cookie
409 echo add $DISPLAY $proto $cookie
414 If this file does not exist,
417 does not exist either, xauth is used to add the cookie.
418 .Sh AUTHORIZED_KEYS FILE FORMAT
419 .Cm AuthorizedKeysFile
420 specifies the files containing public keys for
421 public key authentication;
422 if this option is not specified, the default is
423 .Pa ~/.ssh/authorized_keys
425 .Pa ~/.ssh/authorized_keys2 .
426 Each line of the file contains one
427 key (empty lines and lines starting with a
431 Public keys consist of the following space-separated fields:
432 options, keytype, base64-encoded key, comment.
433 The options field is optional.
435 .Dq ecdsa-sha2-nistp256 ,
436 .Dq ecdsa-sha2-nistp384 ,
437 .Dq ecdsa-sha2-nistp521 ,
442 the comment field is not used for anything (but may be convenient for the
443 user to identify the key).
445 Note that lines in this file can be several hundred bytes long
446 (because of the size of the public key encoding) up to a limit of
447 8 kilobytes, which permits DSA keys up to 8 kilobits and RSA
448 keys up to 16 kilobits.
449 You don't want to type them in; instead, copy the
458 enforces a minimum RSA key modulus size of 768 bits.
460 The options (if present) consist of comma-separated option
462 No spaces are permitted, except within double quotes.
463 The following option specifications are supported (note
464 that option keywords are case-insensitive):
466 .It Cm agent-forwarding
467 Enable authentication agent forwarding previously disabled by the
470 .It Cm cert-authority
471 Specifies that the listed key is a certification authority (CA) that is
472 trusted to validate signed certificates for user authentication.
474 Certificates may encode access restrictions similar to these key options.
475 If both certificate restrictions and key options are present, the most
476 restrictive union of the two is applied.
477 .It Cm command="command"
478 Specifies that the command is executed whenever this key is used for
480 The command supplied by the user (if any) is ignored.
481 The command is run on a pty if the client requests a pty;
482 otherwise it is run without a tty.
483 If an 8-bit clean channel is required,
484 one must not request a pty or should specify
486 A quote may be included in the command by quoting it with a backslash.
488 This option might be useful
489 to restrict certain public keys to perform just a specific operation.
490 An example might be a key that permits remote backups but nothing else.
491 Note that the client may specify TCP and/or X11
492 forwarding unless they are explicitly prohibited, e.g. using the
496 The command originally supplied by the client is available in the
497 .Ev SSH_ORIGINAL_COMMAND
498 environment variable.
499 Note that this option applies to shell, command or subsystem execution.
500 Also note that this command may be superseded by a
505 If a command is specified and a forced-command is embedded in a certificate
506 used for authentication, then the certificate will be accepted only if the
507 two commands are identical.
508 .It Cm environment="NAME=value"
509 Specifies that the string is to be added to the environment when
510 logging in using this key.
511 Environment variables set this way
512 override other default environment values.
513 Multiple options of this type are permitted.
514 Environment processing is disabled by default and is
516 .Cm PermitUserEnvironment
518 .It Cm from="pattern-list"
519 Specifies that in addition to public key authentication, either the canonical
520 name of the remote host or its IP address must be present in the
521 comma-separated list of patterns.
524 for more information on patterns.
526 In addition to the wildcard matching that may be applied to hostnames or
529 stanza may match IP addresses using CIDR address/masklen notation.
531 The purpose of this option is to optionally increase security: public key
532 authentication by itself does not trust the network or name servers or
533 anything (but the key); however, if somebody somehow steals the key, the key
534 permits an intruder to log in from anywhere in the world.
535 This additional option makes using a stolen key more difficult (name
536 servers and/or routers would have to be compromised in addition to
538 .It Cm no-agent-forwarding
539 Forbids authentication agent forwarding when this key is used for
541 .It Cm no-port-forwarding
542 Forbids TCP forwarding when this key is used for authentication.
543 Any port forward requests by the client will return an error.
544 This might be used, e.g. in connection with the
548 Prevents tty allocation (a request to allocate a pty will fail).
550 Disables execution of
552 .It Cm no-X11-forwarding
553 Forbids X11 forwarding when this key is used for authentication.
554 Any X11 forward requests by the client will return an error.
555 .It Cm permitopen="host:port"
556 Limit local port forwarding with
559 such that it may only connect to the specified host and port.
560 IPv6 addresses can be specified by enclosing the address in square brackets.
563 options may be applied separated by commas.
564 No pattern matching is performed on the specified hostnames,
565 they must be literal domains or addresses.
566 A port specification of
569 .It Cm port-forwarding
570 Enable port forwarding previously disabled by the
572 .It Cm principals="principals"
575 line, specifies allowed principals for certificate authentication as a
576 comma-separated list.
577 At least one name from the list must appear in the certificate's
578 list of principals for the certificate to be accepted.
579 This option is ignored for keys that are not marked as trusted certificate
584 Permits tty allocation previously disabled by the
588 Enable all restrictions, i.e. disable port, agent and X11 forwarding,
589 as well as disabling PTY allocation
592 If any future restriction capabilities are added to authorized_keys files
593 they will be included in this set.
597 device on the server.
598 Without this option, the next available device will be used if
599 the client requests a tunnel.
603 previously disabled by the
606 .It Cm X11-forwarding
607 Permits X11 forwarding previously disabled by the
612 An example authorized_keys file:
613 .Bd -literal -offset 3n
614 # Comments allowed at start of line
615 ssh-rsa AAAAB3Nza...LiPk== user@example.net
616 from="*.sales.example.net,!pc.sales.example.net" ssh-rsa
617 AAAAB2...19Q== john@example.net
618 command="dump /home",no-pty,no-port-forwarding ssh-dss
619 AAAAC3...51R== example.net
620 permitopen="192.0.2.1:80",permitopen="192.0.2.2:25" ssh-dss
622 tunnel="0",command="sh /etc/netstart tun0" ssh-rsa AAAA...==
624 restrict,command="uptime" ssh-rsa AAAA1C8...32Tv==
626 restrict,pty,command="nethack" ssh-rsa AAAA1f8...IrrC5==
629 .Sh SSH_KNOWN_HOSTS FILE FORMAT
631 .Pa /etc/ssh/ssh_known_hosts
633 .Pa ~/.ssh/known_hosts
634 files contain host public keys for all known hosts.
635 The global file should
636 be prepared by the administrator (optional), and the per-user file is
637 maintained automatically: whenever the user connects to an unknown host,
638 its key is added to the per-user file.
640 Each line in these files contains the following fields: markers (optional),
641 hostnames, keytype, base64-encoded key, comment.
642 The fields are separated by spaces.
644 The marker is optional, but if it is present then it must be one of
645 .Dq @cert-authority ,
646 to indicate that the line contains a certification authority (CA) key,
649 to indicate that the key contained on the line is revoked and must not ever
651 Only one marker should be used on a key line.
653 Hostnames is a comma-separated list of patterns
658 wildcards); each pattern in turn is matched against the canonical host
659 name (when authenticating a client) or against the user-supplied
660 name (when authenticating a server).
661 A pattern may also be preceded by
663 to indicate negation: if the host name matches a negated
664 pattern, it is not accepted (by that line) even if it matched another
666 A hostname or address may optionally be enclosed within
670 brackets then followed by
672 and a non-standard port number.
674 Alternately, hostnames may be stored in a hashed form which hides host names
675 and addresses should the file's contents be disclosed.
676 Hashed hostnames start with a
679 Only one hashed hostname may appear on a single line and none of the above
680 negation or wildcard operators may be applied.
682 The keytype and base64-encoded key are taken directly from the host key; they
683 can be obtained, for example, from
684 .Pa /etc/ssh/ssh_host_rsa_key.pub .
685 The optional comment field continues to the end of the line, and is not used.
689 and empty lines are ignored as comments.
691 When performing host authentication, authentication is accepted if any
692 matching line has the proper key; either one that matches exactly or,
693 if the server has presented a certificate for authentication, the key
694 of the certification authority that signed the certificate.
695 For a key to be trusted as a certification authority, it must use the
697 marker described above.
699 The known hosts file also provides a facility to mark keys as revoked,
700 for example when it is known that the associated private key has been
702 Revoked keys are specified by including the
704 marker at the beginning of the key line, and are never accepted for
705 authentication or as certification authorities, but instead will
706 produce a warning from
708 when they are encountered.
710 It is permissible (but not
711 recommended) to have several lines or different host keys for the same
713 This will inevitably happen when short forms of host names
714 from different domains are put in the file.
716 that the files contain conflicting information; authentication is
717 accepted if valid information can be found from either file.
719 Note that the lines in these files are typically hundreds of characters
720 long, and you definitely don't want to type in the host keys by hand.
721 Rather, generate them by a script,
723 or by taking, for example,
724 .Pa /etc/ssh/ssh_host_rsa_key.pub
725 and adding the host names at the front.
727 also offers some basic automated editing for
728 .Pa ~/.ssh/known_hosts
729 including removing hosts matching a host name and converting all host
730 names to their hashed representations.
732 An example ssh_known_hosts file:
733 .Bd -literal -offset 3n
734 # Comments allowed at start of line
735 closenet,...,192.0.2.53 1024 37 159...93 closenet.example.net
736 cvs.example.net,192.0.2.10 ssh-rsa AAAA1234.....=
738 |1|JfKTdBh7rNbXkVAQCRp4OQoPfmI=|USECr3SWf1JUPsms5AqfD5QfxkM= ssh-rsa
741 @revoked * ssh-rsa AAAAB5W...
742 # A CA key, accepted for any host in *.mydomain.com or *.mydomain.org
743 @cert-authority *.mydomain.org,*.mydomain.com ssh-rsa AAAAB5W...
746 .Bl -tag -width Ds -compact
748 This file is used to suppress printing the last login time and
756 It does not suppress printing of the banner specified by
760 This file is used for host-based authentication (see
762 for more information).
763 On some machines this file may need to be
764 world-readable if the user's home directory is on an NFS partition,
768 Additionally, this file must be owned by the user,
769 and must not have write permissions for anyone else.
771 permission for most machines is read/write for the user, and not
772 accessible by others.
775 This file is used in exactly the same way as
777 but allows host-based authentication without permitting login with
781 This directory is the default location for all user-specific configuration
782 and authentication information.
783 There is no general requirement to keep the entire contents of this directory
784 secret, but the recommended permissions are read/write/execute for the user,
785 and not accessible by others.
787 .It Pa ~/.ssh/authorized_keys
788 Lists the public keys (DSA, ECDSA, Ed25519, RSA)
789 that can be used for logging in as this user.
790 The format of this file is described above.
791 The content of the file is not highly sensitive, but the recommended
792 permissions are read/write for the user, and not accessible by others.
796 directory, or the user's home directory are writable
797 by other users, then the file could be modified or replaced by unauthorized
801 will not allow it to be used unless the
803 option has been set to
806 .It Pa ~/.ssh/environment
807 This file is read into the environment at login (if it exists).
808 It can only contain empty lines, comment lines (that start with
810 and assignment lines of the form name=value.
811 The file should be writable
812 only by the user; it need not be readable by anyone else.
813 Environment processing is disabled by default and is
815 .Cm PermitUserEnvironment
818 .It Pa ~/.ssh/known_hosts
819 Contains a list of host keys for all hosts the user has logged into
820 that are not already in the systemwide list of known host keys.
821 The format of this file is described above.
822 This file should be writable only by root/the owner and
823 can, but need not be, world-readable.
826 Contains initialization routines to be run before
827 the user's home directory becomes accessible.
828 This file should be writable only by the user, and need not be
829 readable by anyone else.
831 .It Pa /etc/hosts.allow
832 .It Pa /etc/hosts.deny
833 Access controls that should be enforced by tcp-wrappers are defined here.
834 Further details are described in
837 .It Pa /etc/hosts.equiv
838 This file is for host-based authentication (see
840 It should only be writable by root.
843 Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange"
845 The file format is described in
847 If no usable groups are found in this file then fixed internal groups will
857 refuses to let anyone except root log in.
858 The contents of the file
859 are displayed to anyone trying to log in, and non-root connections are
861 The file should be world-readable.
863 .It Pa /etc/shosts.equiv
864 This file is used in exactly the same way as
866 but allows host-based authentication without permitting login with
869 .It Pa /etc/ssh/ssh_host_dsa_key
870 .It Pa /etc/ssh/ssh_host_ecdsa_key
871 .It Pa /etc/ssh/ssh_host_ed25519_key
872 .It Pa /etc/ssh/ssh_host_rsa_key
873 These files contain the private parts of the host keys.
874 These files should only be owned by root, readable only by root, and not
875 accessible to others.
878 does not start if these files are group/world-accessible.
880 .It Pa /etc/ssh/ssh_host_dsa_key.pub
881 .It Pa /etc/ssh/ssh_host_ecdsa_key.pub
882 .It Pa /etc/ssh/ssh_host_ed25519_key.pub
883 .It Pa /etc/ssh/ssh_host_rsa_key.pub
884 These files contain the public parts of the host keys.
885 These files should be world-readable but writable only by
887 Their contents should match the respective private parts.
889 really used for anything; they are provided for the convenience of
890 the user so their contents can be copied to known hosts files.
891 These files are created using
894 .It Pa /etc/ssh/ssh_known_hosts
895 Systemwide list of known host keys.
896 This file should be prepared by the
897 system administrator to contain the public host keys of all machines in the
899 The format of this file is described above.
900 This file should be writable only by root/the owner and
901 should be world-readable.
903 .It Pa /etc/ssh/sshd_config
904 Contains configuration data for
906 The file format and configuration options are described in
909 .It Pa /etc/ssh/sshrc
912 it can be used to specify
913 machine-specific login-time initializations globally.
914 This file should be writable only by root, and should be world-readable.
920 during privilege separation in the pre-authentication phase.
921 The directory should not contain any files and must be owned by root
922 and not group or world-writable.
924 .It Pa /var/run/sshd.pid
925 Contains the process ID of the
927 listening for connections (if there are several daemons running
928 concurrently for different ports, this contains the process ID of the one
930 The content of this file is not sensitive; it can be world-readable.
948 OpenSSH is a derivative of the original and free
949 ssh 1.2.12 release by Tatu Ylonen.
950 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
951 Theo de Raadt and Dug Song
952 removed many bugs, re-added newer features and
954 Markus Friedl contributed the support for SSH
955 protocol versions 1.5 and 2.0.
956 Niels Provos and Markus Friedl contributed support
957 for privilege separation.