3 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5 .\" All rights reserved
7 .\" As far as I am concerned, the code I have written for this software
8 .\" can be used freely for any purpose. Any derived versions of this
9 .\" software must be clearly marked as such, and if the derived work is
10 .\" incompatible with the protocol description in the RFC file, it must be
11 .\" called by a name other than "ssh" or "Secure Shell".
13 .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
14 .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
15 .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
17 .\" Redistribution and use in source and binary forms, with or without
18 .\" modification, are permitted provided that the following conditions
20 .\" 1. Redistributions of source code must retain the above copyright
21 .\" notice, this list of conditions and the following disclaimer.
22 .\" 2. Redistributions in binary form must reproduce the above copyright
23 .\" notice, this list of conditions and the following disclaimer in the
24 .\" documentation and/or other materials provided with the distribution.
26 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
27 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
29 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
30 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
31 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
35 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37 .\" $OpenBSD: sshd.8,v 1.215 2006/02/01 09:11:41 jmc Exp $
39 .Dd September 25, 1999
44 .Nd OpenSSH SSH daemon
50 .Op Fl f Ar config_file
51 .Op Fl g Ar login_grace_time
52 .Op Fl h Ar host_key_file
53 .Op Fl k Ar key_gen_time
60 (OpenSSH Daemon) is the daemon program for
62 Together these programs replace rlogin and rsh, and
63 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.
99 Specifies the number of bits in the ephemeral protocol version 1
100 server key (default 768).
102 When this option is specified,
104 will not detach and does not become a daemon.
105 This allows easy monitoring of
109 The server sends verbose debug output to the system
110 log, and does not put itself in the background.
111 The server also will not fork and will only process one connection.
112 This option is only intended for debugging for the server.
115 options increase the debugging level.
118 When this option is specified,
120 will send the output to the standard error instead of the system log.
121 .It Fl f Ar configuration_file
122 Specifies the name of the configuration file.
124 .Pa /etc/ssh/sshd_config .
126 refuses to start if there is no configuration file.
127 .It Fl g Ar login_grace_time
128 Gives the grace time for clients to authenticate themselves (default
130 If the client fails to authenticate the user within
131 this many seconds, the server disconnects and exits.
132 A value of zero indicates no limit.
133 .It Fl h Ar host_key_file
134 Specifies a file from which a host key is read.
135 This option must be given if
137 is not run as root (as the normal
138 host key files are normally not readable by anyone but root).
140 .Pa /etc/ssh/ssh_host_key
141 for protocol version 1, and
142 .Pa /etc/ssh/ssh_host_dsa_key
143 for protocol version 2.
144 It is possible to have multiple host key files for
145 the different protocol versions and host key algorithms.
153 from inetd because it needs to generate the server key before it can
154 respond to the client, and this may take tens of seconds.
155 Clients would have to wait too long if the key was regenerated every time.
156 However, with small key sizes (e.g., 512) using
160 .It Fl k Ar key_gen_time
161 Specifies how often the ephemeral protocol version 1 server key is
162 regenerated (default 3600 seconds, or one hour).
163 The motivation for regenerating the key fairly
164 often is that the key is not stored anywhere, and after about an hour
165 it becomes impossible to recover the key for decrypting intercepted
166 communications even if the machine is cracked into or physically
168 A value of zero indicates that the key will never be regenerated.
170 Can be used to give options in the format used in the configuration file.
171 This is useful for specifying options for which there is no separate
173 For full details of the options, and their values, see
176 Specifies the port on which the server listens for connections
178 Multiple port options are permitted.
179 Ports specified in the configuration file with the
181 option are ignored when a command-line port is specified.
182 Ports specified using the
184 option override command-line ports.
187 Nothing is sent to the system log.
188 Normally the beginning,
189 authentication, and termination of each connection is logged.
192 Only check the validity of the configuration file and sanity of the keys.
193 This is useful for updating
195 reliably as configuration options may change.
197 This option is used to specify the size of the field
200 structure that holds the remote host name.
201 If the resolved host name is longer than
203 the dotted decimal value will be used instead.
204 This allows hosts with very long host names that
205 overflow this field to still be uniquely identified.
208 indicates that only dotted decimal addresses
209 should be put into the
213 may also be used to prevent
215 from making DNS requests unless the authentication
216 mechanism or configuration requires it.
217 Authentication mechanisms that may require DNS include
218 .Cm RhostsRSAAuthentication ,
219 .Cm HostbasedAuthentication ,
221 .Cm from="pattern-list"
222 option in a key file.
223 Configuration options that require DNS include using a
230 The OpenSSH SSH daemon supports SSH protocols 1 and 2.
231 Both protocols are supported by default,
232 though this can be changed via the
236 Protocol 2 supports both RSA and DSA keys;
237 protocol 1 only supports RSA keys.
239 each host has a host-specific key,
241 used to identify the host.
243 Forward security for protocol 1 is provided through
244 an additional server key,
246 generated when the server starts.
247 This key is normally regenerated every hour if it has been used, and
248 is never stored on disk.
249 Whenever a client connects, the daemon responds with its public
250 host and server keys.
251 The client compares the
252 RSA host key against its own database to verify that it has not changed.
253 The client then generates a 256-bit random number.
255 random number using both the host key and the server key, and sends
256 the encrypted number to the server.
257 Both sides then use this
258 random number as a session key which is used to encrypt all further
259 communications in the session.
260 The rest of the session is encrypted
261 using a conventional cipher, currently Blowfish or 3DES, with 3DES
262 being used by default.
263 The client selects the encryption algorithm
264 to use from those offered by the server.
267 forward security is provided through a Diffie-Hellman key agreement.
268 This key agreement results in a shared session key.
269 The rest of the session is encrypted using a symmetric cipher, currently
270 128-bit AES, Blowfish, 3DES, CAST128, Arcfour, 192-bit AES, or 256-bit AES.
271 The client selects the encryption algorithm
272 to use from those offered by the server.
273 Additionally, session integrity is provided
274 through a cryptographic message authentication code
275 (hmac-sha1 or hmac-md5).
277 Finally, the server and the client enter an authentication dialog.
278 The client tries to authenticate itself using
279 host-based authentication,
280 public key authentication,
281 challenge-response authentication,
282 or password authentication.
284 Regardless of the authentication type, the account is checked to
285 ensure that it is accessible. An account is not accessible if it is
288 or its group is listed in
290 \&. The definition of a locked account is system dependant. Some platforms
291 have their own account database (eg AIX) and some modify the passwd field (
293 on Solaris and UnixWare,
300 on FreeBSD and a leading
302 on Linux). If there is a requirement to disable password authentication
303 for the account while allowing still public-key, then the passwd field
304 should be set to something other than these values (eg
310 System security is not improved unless
315 are disabled (thus completely disabling
320 .Sh COMMAND EXECUTION AND DATA FORWARDING
321 If the client successfully authenticates itself, a dialog for
322 preparing the session is entered.
323 At this time the client may request
324 things like allocating a pseudo-tty, forwarding X11 connections,
325 forwarding TCP connections, or forwarding the authentication agent
326 connection over the secure channel.
328 Finally, the client either requests a shell or execution of a command.
329 The sides then enter session mode.
330 In this mode, either side may send
331 data at any time, and such data is forwarded to/from the shell or
332 command on the server side, and the user terminal in the client side.
334 When the user program terminates and all forwarded X11 and other
335 connections have been closed, the server sends command exit status to
336 the client, and both sides exit.
338 When a user successfully logs in,
341 .Bl -enum -offset indent
343 If the login is on a tty, and no command has been specified,
344 prints last login time and
346 (unless prevented in the configuration file or by
352 If the login is on a tty, records login time.
356 .Pa /var/run/nologin ;
357 if one exists, it prints the contents and quits
360 Changes to run with normal user privileges.
362 Sets up basic environment.
365 .Pa ~/.ssh/environment ,
366 if it exists, and users are allowed to change their environment.
368 .Cm PermitUserEnvironment
372 Changes to user's home directory.
376 exists, runs it; else if
383 files are given the X11
384 authentication protocol and cookie (if applicable) in standard input.
386 Runs user's shell or command.
388 .Sh AUTHORIZED_KEYS FILE FORMAT
389 .Pa ~/.ssh/authorized_keys
390 is the default file that lists the public keys that are
391 permitted for RSA authentication in protocol version 1
392 and for public key authentication (PubkeyAuthentication)
393 in protocol version 2.
394 .Cm AuthorizedKeysFile
395 may be used to specify an alternative file.
397 Each line of the file contains one
398 key (empty lines and lines starting with a
402 Each RSA public key consists of the following fields, separated by
403 spaces: options, bits, exponent, modulus, comment.
404 Each protocol version 2 public key consists of:
405 options, keytype, base64 encoded key, comment.
407 is optional; its presence is determined by whether the line starts
408 with a number or not (the options field never starts with a number).
409 The bits, exponent, modulus and comment fields give the RSA key for
410 protocol version 1; the
411 comment field is not used for anything (but may be convenient for the
412 user to identify the key).
413 For protocol version 2 the keytype is
418 Note that lines in this file are usually several hundred bytes long
419 (because of the size of the public key encoding) up to a limit of
420 8 kilobytes, which permits DSA keys up to 8 kilobits and RSA
421 keys up to 16 kilobits.
422 You don't want to type them in; instead, copy the
430 enforces a minimum RSA key modulus size for protocol 1
431 and protocol 2 keys of 768 bits.
433 The options (if present) consist of comma-separated option
435 No spaces are permitted, except within double quotes.
436 The following option specifications are supported (note
437 that option keywords are case-insensitive):
439 .It Cm from="pattern-list"
440 Specifies that in addition to public key authentication, the canonical name
441 of the remote host must be present in the comma-separated list of
447 The list may also contain
448 patterns negated by prefixing them with
450 if the canonical host name matches a negated pattern, the key is not accepted.
452 of this option is to optionally increase security: public key authentication
453 by itself does not trust the network or name servers or anything (but
454 the key); however, if somebody somehow steals the key, the key
455 permits an intruder to log in from anywhere in the world.
456 This additional option makes using a stolen key more difficult (name
457 servers and/or routers would have to be compromised in addition to
459 .It Cm command="command"
460 Specifies that the command is executed whenever this key is used for
462 The command supplied by the user (if any) is ignored.
463 The command is run on a pty if the client requests a pty;
464 otherwise it is run without a tty.
465 If an 8-bit clean channel is required,
466 one must not request a pty or should specify
468 A quote may be included in the command by quoting it with a backslash.
469 This option might be useful
470 to restrict certain public keys to perform just a specific operation.
471 An example might be a key that permits remote backups but nothing else.
472 Note that the client may specify TCP and/or X11
473 forwarding unless they are explicitly prohibited.
474 Note that this option applies to shell, command or subsystem execution.
475 .It Cm environment="NAME=value"
476 Specifies that the string is to be added to the environment when
477 logging in using this key.
478 Environment variables set this way
479 override other default environment values.
480 Multiple options of this type are permitted.
481 Environment processing is disabled by default and is
483 .Cm PermitUserEnvironment
485 This option is automatically disabled if
488 .It Cm no-port-forwarding
489 Forbids TCP forwarding when this key is used for authentication.
490 Any port forward requests by the client will return an error.
491 This might be used, e.g., in connection with the
494 .It Cm no-X11-forwarding
495 Forbids X11 forwarding when this key is used for authentication.
496 Any X11 forward requests by the client will return an error.
497 .It Cm no-agent-forwarding
498 Forbids authentication agent forwarding when this key is used for
501 Prevents tty allocation (a request to allocate a pty will fail).
502 .It Cm permitopen="host:port"
505 port forwarding such that it may only connect to the specified host and
507 IPv6 addresses can be specified with an alternative syntax:
508 .Ar host Ns / Ns Ar port .
511 options may be applied separated by commas.
512 No pattern matching is performed on the specified hostnames,
513 they must be literal domains or addresses.
517 device on the server.
518 Without this option, the next available device will be used if
519 the client requests a tunnel.
522 1024 33 12121...312314325 ylo@foo.bar
524 from="*.niksula.hut.fi,!pc.niksula.hut.fi" 1024 35 23...2334 ylo@niksula
526 command="dump /home",no-pty,no-port-forwarding 1024 33 23...2323 backup.hut.fi
528 permitopen="10.2.1.55:80",permitopen="10.2.1.56:25" 1024 33 23...2323
530 tunnel="0",command="sh /etc/netstart tun0" ssh-rsa AAAA...== reyk@openbsd.org
531 .Sh SSH_KNOWN_HOSTS FILE FORMAT
533 .Pa /etc/ssh/ssh_known_hosts
535 .Pa ~/.ssh/known_hosts
536 files contain host public keys for all known hosts.
537 The global file should
538 be prepared by the administrator (optional), and the per-user file is
539 maintained automatically: whenever the user connects from an unknown host
540 its key is added to the per-user file.
542 Each line in these files contains the following fields: hostnames,
543 bits, exponent, modulus, comment.
544 The fields are separated by spaces.
546 Hostnames is a comma-separated list of patterns
551 wildcards); each pattern in turn is matched against the canonical host
552 name (when authenticating a client) or against the user-supplied
553 name (when authenticating a server).
554 A pattern may also be preceded by
556 to indicate negation: if the host name matches a negated
557 pattern, it is not accepted (by that line) even if it matched another
560 Alternately, hostnames may be stored in a hashed form which hides host names
561 and addresses should the file's contents be disclosed.
562 Hashed hostnames start with a
565 Only one hashed hostname may appear on a single line and none of the above
566 negation or wildcard operators may be applied.
568 Bits, exponent, and modulus are taken directly from the RSA host key; they
569 can be obtained, e.g., from
570 .Pa /etc/ssh/ssh_host_key.pub .
571 The optional comment field continues to the end of the line, and is not used.
575 and empty lines are ignored as comments.
577 When performing host authentication, authentication is accepted if any
578 matching line has the proper key.
579 It is thus permissible (but not
580 recommended) to have several lines or different host keys for the same
582 This will inevitably happen when short forms of host names
583 from different domains are put in the file.
585 that the files contain conflicting information; authentication is
586 accepted if valid information can be found from either file.
588 Note that the lines in these files are typically hundreds of characters
589 long, and you definitely don't want to type in the host keys by hand.
590 Rather, generate them by a script
592 .Pa /etc/ssh/ssh_host_key.pub
593 and adding the host names at the front.
596 closenet,...,130.233.208.41 1024 37 159...93 closenet.hut.fi
597 cvs.openbsd.org,199.185.137.3 ssh-rsa AAAA1234.....=
601 |1|JfKTdBh7rNbXkVAQCRp4OQoPfmI=|USECr3SWf1JUPsms5AqfD5QfxkM= ssh-rsa
606 .It Pa /etc/ssh/sshd_config
607 Contains configuration data for
609 The file format and configuration options are described in
611 .It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key
612 These two files contain the private parts of the host keys.
613 These files should only be owned by root, readable only by root, and not
614 accessible to others.
617 does not start if this file is group/world-accessible.
618 .It Pa /etc/ssh/ssh_host_key.pub, /etc/ssh/ssh_host_dsa_key.pub
619 These two files contain the public parts of the host keys.
620 These files should be world-readable but writable only by
622 Their contents should match the respective private parts.
624 really used for anything; they are provided for the convenience of
625 the user so their contents can be copied to known hosts files.
626 These files are created using
628 .It Pa /etc/ssh/moduli
629 Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange".
630 The file format is described in
636 during privilege separation in the pre-authentication phase.
637 The directory should not contain any files and must be owned by root
638 and not group or world-writable.
639 .It Pa /var/run/sshd.pid
640 Contains the process ID of the
642 listening for connections (if there are several daemons running
643 concurrently for different ports, this contains the process ID of the one
645 The content of this file is not sensitive; it can be world-readable.
646 .It Pa ~/.ssh/authorized_keys
647 Lists the public keys (RSA or DSA) that can be used to log into the user's account.
648 This file must be readable by root (which may on some machines imply
649 it being world-readable if the user's home directory resides on an NFS
651 It is recommended that it not be accessible by others.
652 The format of this file is described above.
653 Users will place the contents of their
658 files into this file, as described in
660 .It Pa "/etc/ssh/ssh_known_hosts", "~/.ssh/known_hosts"
661 These files are consulted when using rhosts with RSA host
662 authentication or protocol version 2 hostbased authentication
663 to check the public key of the host.
664 The key must be listed in one of these files to be accepted.
665 The client uses the same files
666 to verify that it is connecting to the correct remote host.
667 These files should be writable only by root/the owner.
668 .Pa /etc/ssh/ssh_known_hosts
669 should be world-readable, and
670 .Pa ~/.ssh/known_hosts
671 can, but need not be, world-readable.
676 This file is used to suppress printing the last login time and
684 It does not suppress printing of the banner specified by
689 refuses to let anyone except root log in.
690 The contents of the file
691 are displayed to anyone trying to log in, and non-root connections are
693 The file should be world-readable.
694 .It Pa /etc/hosts.allow, /etc/hosts.deny
695 Access controls that should be enforced by tcp-wrappers are defined here.
696 Further details are described in
699 This file is used during
700 .Cm RhostsRSAAuthentication
702 .Cm HostbasedAuthentication
703 and contains host-username pairs, separated by a space, one per
705 The given user on the corresponding host is permitted to log in
707 The same file is used by rlogind and rshd.
709 be writable only by the user; it is recommended that it not be
710 accessible by others.
712 It is also possible to use netgroups in the file.
714 name may be of the form +@groupname to specify all hosts or all users
718 this file is exactly the same as for
720 However, this file is
721 not used by rlogin and rshd, so using this permits access using SSH only.
722 .It Pa /etc/hosts.equiv
723 This file is used during
724 .Cm RhostsRSAAuthentication
726 .Cm HostbasedAuthentication
728 In the simplest form, this file contains host names, one per line.
730 those hosts are permitted to log in without a password, provided they
731 have the same user name on both machines.
732 The host name may also be
733 followed by a user name; such users are permitted to log in as
735 user on this machine (except root).
736 Additionally, the syntax
738 can be used to specify netgroups.
739 Negated entries start with
742 If the client host/user is successfully matched in this file, login is
743 automatically permitted provided the client and server user names are the
745 Additionally, successful client host key authentication is required.
746 This file must be writable only by root; it is recommended
747 that it be world-readable.
749 .Sy "Warning: It is almost never a good idea to use user names in"
751 Beware that it really means that the named user(s) can log in as
753 which includes bin, daemon, adm, and other accounts that own critical
754 binaries and directories.
755 Using a user name practically grants the user root access.
756 The only valid use for user names that I can think
757 of is in negative entries.
759 Note that this warning also applies to rsh/rlogin.
760 .It Pa /etc/ssh/shosts.equiv
761 This is processed exactly as
762 .Pa /etc/hosts.equiv .
763 However, this file may be useful in environments that want to run both
765 .It Pa ~/.ssh/environment
766 This file is read into the environment at login (if it exists).
767 It can only contain empty lines, comment lines (that start with
769 and assignment lines of the form name=value.
770 The file should be writable
771 only by the user; it need not be readable by anyone else.
772 Environment processing is disabled by default and is
774 .Cm PermitUserEnvironment
777 If this file exists, it is run with
780 environment files but before starting the user's shell or command.
781 It must not produce any output on stdout; stderr must be used
783 If X11 forwarding is in use, it will receive the "proto cookie" pair in
784 its standard input (and
791 will not run xauth automatically to add X11 cookies.
793 The primary purpose of this file is to run any initialization routines
794 which may be needed before the user's home directory becomes
795 accessible; AFS is a particular example of such an environment.
797 This file will probably contain some initialization code followed by
798 something similar to:
800 if read proto cookie && [ -n "$DISPLAY" ]; then
801 if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then
802 # X11UseLocalhost=yes
803 echo add unix:`echo $DISPLAY |
804 cut -c11-` $proto $cookie
807 echo add $DISPLAY $proto $cookie
812 If this file does not exist,
815 does not exist either, xauth is used to add the cookie.
817 This file should be writable only by the user, and need not be
818 readable by anyone else.
819 .It Pa /etc/ssh/sshrc
822 This can be used to specify
823 machine-specific login-time initializations globally.
824 This file should be writable only by root, and should be world-readable.
846 .%T "SSH Protocol Architecture"
847 .%N draft-ietf-secsh-architecture-12.txt
849 .%O work in progress material
855 .%T "Diffie-Hellman Group Exchange for the SSH Transport Layer Protocol"
856 .%N draft-ietf-secsh-dh-group-exchange-02.txt
858 .%O work in progress material
861 OpenSSH is a derivative of the original and free
862 ssh 1.2.12 release by Tatu Ylonen.
863 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
864 Theo de Raadt and Dug Song
865 removed many bugs, re-added newer features and
867 Markus Friedl contributed the support for SSH
868 protocol versions 1.5 and 2.0.
869 Niels Provos and Markus Friedl contributed support
870 for privilege separation.