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