summaryrefslogtreecommitdiff
path: root/sshd.0
diff options
context:
space:
mode:
authorColin Watson <cjwatson@debian.org>2003-09-17 01:19:29 +0000
committerColin Watson <cjwatson@debian.org>2003-09-17 01:19:29 +0000
commit9221adce6959801664fd4a340c19e6b69107ad0b (patch)
treee8b7b5706043a4eb66e0e41aad2a7986cbedeb0f /sshd.0
parentade1cee573c0897cd08987dc14e23a555898cd12 (diff)
parent22f9b945efa61bba12a4778b889df07cf851838a (diff)
Import OpenSSH 3.7.1p1.
Diffstat (limited to 'sshd.0')
-rw-r--r--sshd.0556
1 files changed, 556 insertions, 0 deletions
diff --git a/sshd.0 b/sshd.0
new file mode 100644
index 000000000..60be52888
--- /dev/null
+++ b/sshd.0
@@ -0,0 +1,556 @@
1SSHD(8) OpenBSD System Manager's Manual SSHD(8)
2
3NAME
4 sshd - OpenSSH SSH daemon
5
6SYNOPSIS
7 sshd [-deiqtD46] [-b bits] [-f config_file] [-g login_grace_time]
8 [-h host_key_file] [-k key_gen_time] [-o option] [-p port] [-u len]
9
10DESCRIPTION
11 sshd (SSH Daemon) is the daemon program for ssh(1). Together these pro-
12 grams replace rlogin and rsh, and provide secure encrypted communications
13 between two untrusted hosts over an insecure network. The programs are
14 intended to be as easy to install and use as possible.
15
16 sshd is the daemon that listens for connections from clients. It is nor-
17 mally started at boot from /etc/rc. It forks a new daemon for each in-
18 coming connection. The forked daemons handle key exchange, encryption,
19 authentication, command execution, and data exchange. This implementa-
20 tion of sshd supports both SSH protocol version 1 and 2 simultaneously.
21 sshd works as follows:
22
23 SSH protocol version 1
24
25 Each host has a host-specific RSA key (normally 1024 bits) used to iden-
26 tify the host. Additionally, when the daemon starts, it generates a
27 server RSA key (normally 768 bits). This key is normally regenerated ev-
28 ery hour if it has been used, and is never stored on disk.
29
30 Whenever a client connects, the daemon responds with its public host and
31 server keys. The client compares the RSA host key against its own
32 database to verify that it has not changed. The client then generates a
33 256 bit random number. It encrypts this random number using both the
34 host key and the server key, and sends the encrypted number to the serv-
35 er. Both sides then use this random number as a session key which is
36 used to encrypt all further communications in the session. The rest of
37 the session is encrypted using a conventional cipher, currently Blowfish
38 or 3DES, with 3DES being used by default. The client selects the encryp-
39 tion algorithm to use from those offered by the server.
40
41 Next, the server and the client enter an authentication dialog. The
42 client tries to authenticate itself using .rhosts authentication, .rhosts
43 authentication combined with RSA host authentication, RSA challenge-re-
44 sponse authentication, or password based authentication.
45
46 Regardless of the authentication type, the account is checked to ensure
47 that it is accessible. An account is not accessible if it is locked,
48 listed in DenyUsers or its group is listed in DenyGroups . The defini-
49 tion of a locked account is system dependant. Some platforms have their
50 own account database (eg AIX) and some modify the passwd field ( `*LK*'
51 on Solaris, `*' on HP-UX, containing `Nologin' on Tru64 and a leading
52 `!!' on Linux). If there is a requirement to disable password authenti-
53 cation for the account while allowing still public-key, then the passwd
54 field should be set to something other than these values (eg `NP' or
55 `*NP*' ).
56
57 Rhosts authentication is normally disabled because it is fundamentally
58 insecure, but can be enabled in the server configuration file if desired.
59 System security is not improved unless rshd, rlogind, and rexecd are dis-
60 abled (thus completely disabling rlogin and rsh into the machine).
61
62 SSH protocol version 2
63
64 Version 2 works similarly: Each host has a host-specific key (RSA or DSA)
65 used to identify the host. However, when the daemon starts, it does not
66 generate a server key. Forward security is provided through a Diffie-
67 Hellman key agreement. This key agreement results in a shared session
68 key.
69
70 The rest of the session is encrypted using a symmetric cipher, currently
71 128 bit AES, Blowfish, 3DES, CAST128, Arcfour, 192 bit AES, or 256 bit
72 AES. The client selects the encryption algorithm to use from those of-
73 fered by the server. Additionally, session integrity is provided through
74 a cryptographic message authentication code (hmac-sha1 or hmac-md5).
75
76 Protocol version 2 provides a public key based user (PubkeyAuthentica-
77 tion) or client host (HostbasedAuthentication) authentication method,
78 conventional password authentication and challenge response based meth-
79 ods.
80
81 Command execution and data forwarding
82
83 If the client successfully authenticates itself, a dialog for preparing
84 the session is entered. At this time the client may request things like
85 allocating a pseudo-tty, forwarding X11 connections, forwarding TCP/IP
86 connections, or forwarding the authentication agent connection over the
87 secure channel.
88
89 Finally, the client either requests a shell or execution of a command.
90 The sides then enter session mode. In this mode, either side may send
91 data at any time, and such data is forwarded to/from the shell or command
92 on the server side, and the user terminal in the client side.
93
94 When the user program terminates and all forwarded X11 and other connec-
95 tions have been closed, the server sends command exit status to the
96 client, and both sides exit.
97
98 sshd can be configured using command-line options or a configuration
99 file. Command-line options override values specified in the configura-
100 tion file.
101
102 sshd rereads its configuration file when it receives a hangup signal,
103 SIGHUP, by executing itself with the name it was started as, i.e.,
104 /usr/sbin/sshd.
105
106 The options are as follows:
107
108 -b bits
109 Specifies the number of bits in the ephemeral protocol version 1
110 server key (default 768).
111
112 -d Debug mode. The server sends verbose debug output to the system
113 log, and does not put itself in the background. The server also
114 will not fork and will only process one connection. This option
115 is only intended for debugging for the server. Multiple -d op-
116 tions increase the debugging level. Maximum is 3.
117
118 -e When this option is specified, sshd will send the output to the
119 standard error instead of the system log.
120
121 -f configuration_file
122 Specifies the name of the configuration file. The default is
123 /etc/ssh/sshd_config. sshd refuses to start if there is no con-
124 figuration file.
125
126 -g login_grace_time
127 Gives the grace time for clients to authenticate themselves (de-
128 fault 120 seconds). If the client fails to authenticate the user
129 within this many seconds, the server disconnects and exits. A
130 value of zero indicates no limit.
131
132 -h host_key_file
133 Specifies a file from which a host key is read. This option must
134 be given if sshd is not run as root (as the normal host key files
135 are normally not readable by anyone but root). The default is
136 /etc/ssh/ssh_host_key for protocol version 1, and
137 /etc/ssh/ssh_host_rsa_key and /etc/ssh/ssh_host_dsa_key for pro-
138 tocol version 2. It is possible to have multiple host key files
139 for the different protocol versions and host key algorithms.
140
141 -i Specifies that sshd is being run from inetd(8). sshd is normally
142 not run from inetd because it needs to generate the server key
143 before it can respond to the client, and this may take tens of
144 seconds. Clients would have to wait too long if the key was re-
145 generated every time. However, with small key sizes (e.g., 512)
146 using sshd from inetd may be feasible.
147
148 -k key_gen_time
149 Specifies how often the ephemeral protocol version 1 server key
150 is regenerated (default 3600 seconds, or one hour). The motiva-
151 tion for regenerating the key fairly often is that the key is not
152 stored anywhere, and after about an hour, it becomes impossible
153 to recover the key for decrypting intercepted communications even
154 if the machine is cracked into or physically seized. A value of
155 zero indicates that the key will never be regenerated.
156
157 -o option
158 Can be used to give options in the format used in the configura-
159 tion file. This is useful for specifying options for which there
160 is no separate command-line flag.
161
162 -p port
163 Specifies the port on which the server listens for connections
164 (default 22). Multiple port options are permitted. Ports speci-
165 fied in the configuration file are ignored when a command-line
166 port is specified.
167
168 -q Quiet mode. Nothing is sent to the system log. Normally the be-
169 ginning, authentication, and termination of each connection is
170 logged.
171
172 -t Test mode. Only check the validity of the configuration file and
173 sanity of the keys. This is useful for updating sshd reliably as
174 configuration options may change.
175
176 -u len This option is used to specify the size of the field in the utmp
177 structure that holds the remote host name. If the resolved host
178 name is longer than len, the dotted decimal value will be used
179 instead. This allows hosts with very long host names that over-
180 flow this field to still be uniquely identified. Specifying -u0
181 indicates that only dotted decimal addresses should be put into
182 the utmp file. -u0 may also be used to prevent sshd from making
183 DNS requests unless the authentication mechanism or configuration
184 requires it. Authentication mechanisms that may require DNS in-
185 clude RhostsRSAAuthentication, HostbasedAuthentication and using
186 a from="pattern-list" option in a key file. Configuration op-
187 tions that require DNS include using a USER@HOST pattern in
188 AllowUsers or DenyUsers.
189
190 -D When this option is specified sshd will not detach and does not
191 become a daemon. This allows easy monitoring of sshd.
192
193 -4 Forces sshd to use IPv4 addresses only.
194
195 -6 Forces sshd to use IPv6 addresses only.
196
197CONFIGURATION FILE
198 sshd reads configuration data from /etc/ssh/sshd_config (or the file
199 specified with -f on the command line). The file format and configura-
200 tion options are described in sshd_config(5).
201
202LOGIN PROCESS
203 When a user successfully logs in, sshd does the following:
204
205 1. If the login is on a tty, and no command has been specified,
206 prints last login time and /etc/motd (unless prevented in the
207 configuration file or by $HOME/.hushlogin; see the FILES sec-
208 tion).
209
210 2. If the login is on a tty, records login time.
211
212 3. Checks /etc/nologin; if it exists, prints contents and quits
213 (unless root).
214
215 4. Changes to run with normal user privileges.
216
217 5. Sets up basic environment.
218
219 6. Reads $HOME/.ssh/environment if it exists and users are al-
220 lowed to change their environment. See the
221 PermitUserEnvironment option in sshd_config(5).
222
223 7. Changes to user's home directory.
224
225 8. If $HOME/.ssh/rc exists, runs it; else if /etc/ssh/sshrc ex-
226 ists, runs it; otherwise runs xauth. The ``rc'' files are
227 given the X11 authentication protocol and cookie in standard
228 input.
229
230 9. Runs user's shell or command.
231
232AUTHORIZED_KEYS FILE FORMAT
233 $HOME/.ssh/authorized_keys is the default file that lists the public keys
234 that are permitted for RSA authentication in protocol version 1 and for
235 public key authentication (PubkeyAuthentication) in protocol version 2.
236 AuthorizedKeysFile may be used to specify an alternative file.
237
238 Each line of the file contains one key (empty lines and lines starting
239 with a `#' are ignored as comments). Each RSA public key consists of the
240 following fields, separated by spaces: options, bits, exponent, modulus,
241 comment. Each protocol version 2 public key consists of: options, key-
242 type, base64 encoded key, comment. The options field is optional; its
243 presence is determined by whether the line starts with a number or not
244 (the options field never starts with a number). The bits, exponent, mod-
245 ulus and comment fields give the RSA key for protocol version 1; the com-
246 ment field is not used for anything (but may be convenient for the user
247 to identify the key). For protocol version 2 the keytype is ``ssh-dss''
248 or ``ssh-rsa''.
249
250 Note that lines in this file are usually several hundred bytes long (be-
251 cause of the size of the public key encoding). You don't want to type
252 them in; instead, copy the identity.pub, id_dsa.pub or the id_rsa.pub
253 file and edit it.
254
255 sshd enforces a minimum RSA key modulus size for protocol 1 and protocol
256 2 keys of 768 bits.
257
258 The options (if present) consist of comma-separated option specifica-
259 tions. No spaces are permitted, except within double quotes. The fol-
260 lowing option specifications are supported (note that option keywords are
261 case-insensitive):
262
263 from="pattern-list"
264 Specifies that in addition to public key authentication, the
265 canonical name of the remote host must be present in the comma-
266 separated list of patterns (`*' and `?' serve as wildcards). The
267 list may also contain patterns negated by prefixing them with
268 `!'; if the canonical host name matches a negated pattern, the
269 key is not accepted. The purpose of this option is to optionally
270 increase security: public key authentication by itself does not
271 trust the network or name servers or anything (but the key); how-
272 ever, if somebody somehow steals the key, the key permits an in-
273 truder to log in from anywhere in the world. This additional op-
274 tion makes using a stolen key more difficult (name servers and/or
275 routers would have to be compromised in addition to just the
276 key).
277
278 command="command"
279 Specifies that the command is executed whenever this key is used
280 for authentication. The command supplied by the user (if any) is
281 ignored. The command is run on a pty if the client requests a
282 pty; otherwise it is run without a tty. If an 8-bit clean chan-
283 nel is required, one must not request a pty or should specify no-
284 pty. A quote may be included in the command by quoting it with a
285 backslash. This option might be useful to restrict certain pub-
286 lic keys to perform just a specific operation. An example might
287 be a key that permits remote backups but nothing else. Note that
288 the client may specify TCP/IP and/or X11 forwarding unless they
289 are explicitly prohibited. Note that this option applies to
290 shell, command or subsystem execution.
291
292 environment="NAME=value"
293 Specifies that the string is to be added to the environment when
294 logging in using this key. Environment variables set this way
295 override other default environment values. Multiple options of
296 this type are permitted. Environment processing is disabled by
297 default and is controlled via the PermitUserEnvironment option.
298 This option is automatically disabled if UseLogin is enabled.
299
300 no-port-forwarding
301 Forbids TCP/IP forwarding when this key is used for authentica-
302 tion. Any port forward requests by the client will return an er-
303 ror. This might be used, e.g., in connection with the command
304 option.
305
306 no-X11-forwarding
307 Forbids X11 forwarding when this key is used for authentication.
308 Any X11 forward requests by the client will return an error.
309
310 no-agent-forwarding
311 Forbids authentication agent forwarding when this key is used for
312 authentication.
313
314 no-pty Prevents tty allocation (a request to allocate a pty will fail).
315
316 permitopen="host:port"
317 Limit local ``ssh -L'' port forwarding such that it may only con-
318 nect to the specified host and port. IPv6 addresses can be spec-
319 ified with an alternative syntax: host/port. Multiple permitopen
320 options may be applied separated by commas. No pattern matching
321 is performed on the specified hostnames, they must be literal do-
322 mains or addresses.
323
324 Examples
325 1024 33 12121...312314325 ylo@foo.bar
326
327 from="*.niksula.hut.fi,!pc.niksula.hut.fi" 1024 35 23...2334 ylo@niksula
328
329 command="dump /home",no-pty,no-port-forwarding 1024 33 23...2323 back-
330 up.hut.fi
331
332 permitopen="10.2.1.55:80",permitopen="10.2.1.56:25" 1024 33 23...2323
333
334SSH_KNOWN_HOSTS FILE FORMAT
335 The /etc/ssh/ssh_known_hosts and $HOME/.ssh/known_hosts files contain
336 host public keys for all known hosts. The global file should be prepared
337 by the administrator (optional), and the per-user file is maintained au-
338 tomatically: whenever the user connects from an unknown host its key is
339 added to the per-user file.
340
341 Each line in these files contains the following fields: hostnames, bits,
342 exponent, modulus, comment. The fields are separated by spaces.
343
344 Hostnames is a comma-separated list of patterns (`*' and `?' act as wild-
345 cards); each pattern in turn is matched against the canonical host name
346 (when authenticating a client) or against the user-supplied name (when
347 authenticating a server). A pattern may also be preceded by `!' to indi-
348 cate negation: if the host name matches a negated pattern, it is not ac-
349 cepted (by that line) even if it matched another pattern on the line.
350
351 Bits, exponent, and modulus are taken directly from the RSA host key;
352 they can be obtained, e.g., from /etc/ssh/ssh_host_key.pub. The optional
353 comment field continues to the end of the line, and is not used.
354
355 Lines starting with `#' and empty lines are ignored as comments.
356
357 When performing host authentication, authentication is accepted if any
358 matching line has the proper key. It is thus permissible (but not recom-
359 mended) to have several lines or different host keys for the same names.
360 This will inevitably happen when short forms of host names from different
361 domains are put in the file. It is possible that the files contain con-
362 flicting information; authentication is accepted if valid information can
363 be found from either file.
364
365 Note that the lines in these files are typically hundreds of characters
366 long, and you definitely don't want to type in the host keys by hand.
367 Rather, generate them by a script or by taking /etc/ssh/ssh_host_key.pub
368 and adding the host names at the front.
369
370 Examples
371
372 closenet,...,130.233.208.41 1024 37 159...93 closenet.hut.fi
373 cvs.openbsd.org,199.185.137.3 ssh-rsa AAAA1234.....=
374
375FILES
376 /etc/ssh/sshd_config
377 Contains configuration data for sshd. The file format and con-
378 figuration options are described in sshd_config(5).
379
380 /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key,
381 /etc/ssh/ssh_host_rsa_key
382 These three files contain the private parts of the host keys.
383 These files should only be owned by root, readable only by root,
384 and not accessible to others. Note that sshd does not start if
385 this file is group/world-accessible.
386
387 /etc/ssh/ssh_host_key.pub, /etc/ssh/ssh_host_dsa_key.pub,
388 /etc/ssh/ssh_host_rsa_key.pub
389 These three files contain the public parts of the host keys.
390 These files should be world-readable but writable only by root.
391 Their contents should match the respective private parts. These
392 files are not really used for anything; they are provided for the
393 convenience of the user so their contents can be copied to known
394 hosts files. These files are created using ssh-keygen(1).
395
396 /etc/moduli
397 Contains Diffie-Hellman groups used for the "Diffie-Hellman Group
398 Exchange". The file format is described in moduli(5).
399
400 /var/empty
401 chroot(2) directory used by sshd during privilege separation in
402 the pre-authentication phase. The directory should not contain
403 any files and must be owned by root and not group or world-
404 writable.
405
406 /var/run/sshd.pid
407 Contains the process ID of the sshd listening for connections (if
408 there are several daemons running concurrently for different
409 ports, this contains the process ID of the one started last).
410 The content of this file is not sensitive; it can be world-read-
411 able.
412
413 $HOME/.ssh/authorized_keys
414 Lists the public keys (RSA or DSA) that can be used to log into
415 the user's account. This file must be readable by root (which
416 may on some machines imply it being world-readable if the user's
417 home directory resides on an NFS volume). It is recommended that
418 it not be accessible by others. The format of this file is de-
419 scribed above. Users will place the contents of their
420 identity.pub, id_dsa.pub and/or id_rsa.pub files into this file,
421 as described in ssh-keygen(1).
422
423 /etc/ssh/ssh_known_hosts and $HOME/.ssh/known_hosts
424 These files are consulted when using rhosts with RSA host authen-
425 tication or protocol version 2 hostbased authentication to check
426 the public key of the host. The key must be listed in one of
427 these files to be accepted. The client uses the same files to
428 verify that it is connecting to the correct remote host. These
429 files should be writable only by root/the owner.
430 /etc/ssh/ssh_known_hosts should be world-readable, and
431 $HOME/.ssh/known_hosts can, but need not be, world-readable.
432
433 /etc/nologin
434 If this file exists, sshd refuses to let anyone except root log
435 in. The contents of the file are displayed to anyone trying to
436 log in, and non-root connections are refused. The file should be
437 world-readable.
438
439 /etc/hosts.allow, /etc/hosts.deny
440 Access controls that should be enforced by tcp-wrappers are de-
441 fined here. Further details are described in hosts_access(5).
442
443 $HOME/.rhosts
444 This file contains host-username pairs, separated by a space, one
445 per line. The given user on the corresponding host is permitted
446 to log in without a password. The same file is used by rlogind
447 and rshd. The file must be writable only by the user; it is rec-
448 ommended that it not be accessible by others.
449
450 If is also possible to use netgroups in the file. Either host or
451 user name may be of the form +@groupname to specify all hosts or
452 all users in the group.
453
454 $HOME/.shosts
455 For ssh, this file is exactly the same as for .rhosts. However,
456 this file is not used by rlogin and rshd, so using this permits
457 access using SSH only.
458
459 /etc/hosts.equiv
460 This file is used during .rhosts authentication. In the simplest
461 form, this file contains host names, one per line. Users on
462 those hosts are permitted to log in without a password, provided
463 they have the same user name on both machines. The host name may
464 also be followed by a user name; such users are permitted to log
465 in as any user on this machine (except root). Additionally, the
466 syntax ``+@group'' can be used to specify netgroups. Negated en-
467 tries start with `-'.
468
469 If the client host/user is successfully matched in this file, lo-
470 gin is automatically permitted provided the client and server us-
471 er names are the same. Additionally, successful RSA host authen-
472 tication is normally required. This file must be writable only
473 by root; it is recommended that it be world-readable.
474
475 Warning: It is almost never a good idea to use user names in
476 hosts.equiv. Beware that it really means that the named user(s)
477 can log in as anybody, which includes bin, daemon, adm, and other
478 accounts that own critical binaries and directories. Using a us-
479 er name practically grants the user root access. The only valid
480 use for user names that I can think of is in negative entries.
481
482 Note that this warning also applies to rsh/rlogin.
483
484 /etc/shosts.equiv
485 This is processed exactly as /etc/hosts.equiv. However, this
486 file may be useful in environments that want to run both
487 rsh/rlogin and ssh.
488
489 $HOME/.ssh/environment
490 This file is read into the environment at login (if it exists).
491 It can only contain empty lines, comment lines (that start with
492 `#'), and assignment lines of the form name=value. The file
493 should be writable only by the user; it need not be readable by
494 anyone else. Environment processing is disabled by default and
495 is controlled via the PermitUserEnvironment option.
496
497 $HOME/.ssh/rc
498 If this file exists, it is run with /bin/sh after reading the en-
499 vironment files but before starting the user's shell or command.
500 It must not produce any output on stdout; stderr must be used in-
501 stead. If X11 forwarding is in use, it will receive the "proto
502 cookie" pair in its standard input (and DISPLAY in its environ-
503 ment). The script must call xauth(1) because sshd will not run
504 xauth automatically to add X11 cookies.
505
506 The primary purpose of this file is to run any initialization
507 routines which may be needed before the user's home directory be-
508 comes accessible; AFS is a particular example of such an environ-
509 ment.
510
511 This file will probably contain some initialization code followed
512 by something similar to:
513
514 if read proto cookie && [ -n "$DISPLAY" ]; then
515 if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then
516 # X11UseLocalhost=yes
517 echo add unix:`echo $DISPLAY |
518 cut -c11-` $proto $cookie
519 else
520 # X11UseLocalhost=no
521 echo add $DISPLAY $proto $cookie
522 fi | xauth -q -
523 fi
524
525 If this file does not exist, /etc/ssh/sshrc is run, and if that
526 does not exist either, xauth is used to add the cookie.
527
528 This file should be writable only by the user, and need not be
529 readable by anyone else.
530
531 /etc/ssh/sshrc
532 Like $HOME/.ssh/rc. This can be used to specify machine-specific
533 login-time initializations globally. This file should be
534 writable only by root, and should be world-readable.
535
536SEE ALSO
537 scp(1), sftp(1), ssh(1), ssh-add(1), ssh-agent(1), ssh-keygen(1),
538 login.conf(5), moduli(5), sshd_config(5), sftp-server(8)
539
540 T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne, and S. Lehtinen, SSH
541 Protocol Architecture, draft-ietf-secsh-architecture-12.txt, January
542 2002, work in progress material.
543
544 M. Friedl, N. Provos, and W. A. Simpson, Diffie-Hellman Group Exchange
545 for the SSH Transport Layer Protocol, draft-ietf-secsh-dh-group-
546 exchange-02.txt, January 2002, work in progress material.
547
548AUTHORS
549 OpenSSH is a derivative of the original and free ssh 1.2.12 release by
550 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
551 de Raadt and Dug Song removed many bugs, re-added newer features and
552 created OpenSSH. Markus Friedl contributed the support for SSH protocol
553 versions 1.5 and 2.0. Niels Provos and Markus Friedl contributed support
554 for privilege separation.
555
556OpenBSD 3.4 September 25, 1999 9