1 | .\" -*- nroff -*- |
---|
2 | .\" |
---|
3 | .\" Author: Tatu Ylonen <ylo@cs.hut.fi> |
---|
4 | .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland |
---|
5 | .\" All rights reserved |
---|
6 | .\" |
---|
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". |
---|
12 | .\" |
---|
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. |
---|
16 | .\" |
---|
17 | .\" Redistribution and use in source and binary forms, with or without |
---|
18 | .\" modification, are permitted provided that the following conditions |
---|
19 | .\" are met: |
---|
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. |
---|
25 | .\" |
---|
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. |
---|
36 | .\" |
---|
37 | .\" $OpenBSD: sshd.8,v 1.193 2002/09/24 20:59:44 todd Exp $ |
---|
38 | .Dd September 25, 1999 |
---|
39 | .Dt SSHD 8 |
---|
40 | .Os |
---|
41 | .Sh NAME |
---|
42 | .Nm sshd |
---|
43 | .Nd OpenSSH SSH daemon |
---|
44 | .Sh SYNOPSIS |
---|
45 | .Nm sshd |
---|
46 | .Op Fl deiqtD46 |
---|
47 | .Op Fl s | S |
---|
48 | .Op Fl b Ar bits |
---|
49 | .Op Fl f Ar config_file |
---|
50 | .Op Fl g Ar login_grace_time |
---|
51 | .Op Fl h Ar host_key_file |
---|
52 | .Op Fl k Ar key_gen_time |
---|
53 | .Op Fl o Ar option |
---|
54 | .Op Fl p Ar port |
---|
55 | .Op Fl u Ar len |
---|
56 | .Sh DESCRIPTION |
---|
57 | .Nm |
---|
58 | (SSH Daemon) is the daemon program for |
---|
59 | .Xr ssh 1 . |
---|
60 | Together these programs replace rlogin and rsh, and |
---|
61 | provide secure encrypted communications between two untrusted hosts |
---|
62 | over an insecure network. |
---|
63 | The programs are intended to be as easy to |
---|
64 | install and use as possible. |
---|
65 | .Pp |
---|
66 | .Nm |
---|
67 | is the daemon that listens for connections from clients. |
---|
68 | It is normally started at boot from |
---|
69 | .Pa /etc/rc . |
---|
70 | It forks a new |
---|
71 | daemon for each incoming connection. |
---|
72 | The forked daemons handle |
---|
73 | key exchange, encryption, authentication, command execution, |
---|
74 | and data exchange. |
---|
75 | This implementation of |
---|
76 | .Nm |
---|
77 | supports both SSH protocol version 1 and 2 simultaneously. |
---|
78 | .Nm |
---|
79 | works as follows. |
---|
80 | .Pp |
---|
81 | .Ss SSH protocol version 1 |
---|
82 | .Pp |
---|
83 | Each host has a host-specific RSA key |
---|
84 | (normally 1024 bits) used to identify the host. |
---|
85 | Additionally, when |
---|
86 | the daemon starts, it generates a server RSA key (normally 768 bits). |
---|
87 | This key is normally regenerated every hour if it has been used, and |
---|
88 | is never stored on disk. |
---|
89 | .Pp |
---|
90 | Whenever a client connects the daemon responds with its public |
---|
91 | host and server keys. |
---|
92 | The client compares the |
---|
93 | RSA host key against its own database to verify that it has not changed. |
---|
94 | The client then generates a 256 bit random number. |
---|
95 | It encrypts this |
---|
96 | random number using both the host key and the server key, and sends |
---|
97 | the encrypted number to the server. |
---|
98 | Both sides then use this |
---|
99 | random number as a session key which is used to encrypt all further |
---|
100 | communications in the session. |
---|
101 | The rest of the session is encrypted |
---|
102 | using a conventional cipher, currently Blowfish or 3DES, with 3DES |
---|
103 | being used by default. |
---|
104 | The client selects the encryption algorithm |
---|
105 | to use from those offered by the server. |
---|
106 | .Pp |
---|
107 | Next, the server and the client enter an authentication dialog. |
---|
108 | The client tries to authenticate itself using |
---|
109 | .Pa .rhosts |
---|
110 | authentication, |
---|
111 | .Pa .rhosts |
---|
112 | authentication combined with RSA host |
---|
113 | authentication, RSA challenge-response authentication, or password |
---|
114 | based authentication. |
---|
115 | .Pp |
---|
116 | Rhosts authentication is normally disabled |
---|
117 | because it is fundamentally insecure, but can be enabled in the server |
---|
118 | configuration file if desired. |
---|
119 | System security is not improved unless |
---|
120 | .Nm rshd , |
---|
121 | .Nm rlogind , |
---|
122 | and |
---|
123 | .Xr rexecd |
---|
124 | are disabled (thus completely disabling |
---|
125 | .Xr rlogin |
---|
126 | and |
---|
127 | .Xr rsh |
---|
128 | into the machine). |
---|
129 | .Pp |
---|
130 | .Ss SSH protocol version 2 |
---|
131 | .Pp |
---|
132 | Version 2 works similarly: |
---|
133 | Each host has a host-specific key (RSA or DSA) used to identify the host. |
---|
134 | However, when the daemon starts, it does not generate a server key. |
---|
135 | Forward security is provided through a Diffie-Hellman key agreement. |
---|
136 | This key agreement results in a shared session key. |
---|
137 | .Pp |
---|
138 | The rest of the session is encrypted using a symmetric cipher, currently |
---|
139 | 128 bit AES, Blowfish, 3DES, CAST128, Arcfour, 192 bit AES, or 256 bit AES. |
---|
140 | The client selects the encryption algorithm |
---|
141 | to use from those offered by the server. |
---|
142 | Additionally, session integrity is provided |
---|
143 | through a cryptographic message authentication code |
---|
144 | (hmac-sha1 or hmac-md5). |
---|
145 | .Pp |
---|
146 | Protocol version 2 provides a public key based |
---|
147 | user (PubkeyAuthentication) or |
---|
148 | client host (HostbasedAuthentication) authentication method, |
---|
149 | conventional password authentication and challenge response based methods. |
---|
150 | .Pp |
---|
151 | .Ss Command execution and data forwarding |
---|
152 | .Pp |
---|
153 | If the client successfully authenticates itself, a dialog for |
---|
154 | preparing the session is entered. |
---|
155 | At this time the client may request |
---|
156 | things like allocating a pseudo-tty, forwarding X11 connections, |
---|
157 | forwarding TCP/IP connections, or forwarding the authentication agent |
---|
158 | connection over the secure channel. |
---|
159 | .Pp |
---|
160 | Finally, the client either requests a shell or execution of a command. |
---|
161 | The sides then enter session mode. |
---|
162 | In this mode, either side may send |
---|
163 | data at any time, and such data is forwarded to/from the shell or |
---|
164 | command on the server side, and the user terminal in the client side. |
---|
165 | .Pp |
---|
166 | When the user program terminates and all forwarded X11 and other |
---|
167 | connections have been closed, the server sends command exit status to |
---|
168 | the client, and both sides exit. |
---|
169 | .Pp |
---|
170 | .Nm |
---|
171 | can be configured using command-line options or a configuration |
---|
172 | file. |
---|
173 | Command-line options override values specified in the |
---|
174 | configuration file. |
---|
175 | .Pp |
---|
176 | .Nm |
---|
177 | rereads its configuration file when it receives a hangup signal, |
---|
178 | .Dv SIGHUP , |
---|
179 | by executing itself with the name it was started as, i.e., |
---|
180 | .Pa /usr/sbin/sshd . |
---|
181 | .Pp |
---|
182 | The options are as follows: |
---|
183 | .Bl -tag -width Ds |
---|
184 | .It Fl b Ar bits |
---|
185 | Specifies the number of bits in the ephemeral protocol version 1 |
---|
186 | server key (default 768). |
---|
187 | .It Fl d |
---|
188 | Debug mode. |
---|
189 | The server sends verbose debug output to the system |
---|
190 | log, and does not put itself in the background. |
---|
191 | The server also will not fork and will only process one connection. |
---|
192 | This option is only intended for debugging for the server. |
---|
193 | Multiple -d options increase the debugging level. |
---|
194 | Maximum is 3. |
---|
195 | .It Fl e |
---|
196 | When this option is specified, |
---|
197 | .Nm |
---|
198 | will send the output to the standard error instead of the system log. |
---|
199 | .It Fl f Ar configuration_file |
---|
200 | Specifies the name of the configuration file. |
---|
201 | The default is |
---|
202 | .Pa /etc/ssh/sshd_config . |
---|
203 | .Nm |
---|
204 | refuses to start if there is no configuration file. |
---|
205 | .It Fl g Ar login_grace_time |
---|
206 | Gives the grace time for clients to authenticate themselves (default |
---|
207 | 120 seconds). |
---|
208 | If the client fails to authenticate the user within |
---|
209 | this many seconds, the server disconnects and exits. |
---|
210 | A value of zero indicates no limit. |
---|
211 | .It Fl h Ar host_key_file |
---|
212 | Specifies a file from which a host key is read. |
---|
213 | This option must be given if |
---|
214 | .Nm |
---|
215 | is not run as root (as the normal |
---|
216 | host key files are normally not readable by anyone but root). |
---|
217 | The default is |
---|
218 | .Pa /etc/ssh/ssh_host_key |
---|
219 | for protocol version 1, and |
---|
220 | .Pa /etc/ssh/ssh_host_rsa_key |
---|
221 | and |
---|
222 | .Pa /etc/ssh/ssh_host_dsa_key |
---|
223 | for protocol version 2. |
---|
224 | It is possible to have multiple host key files for |
---|
225 | the different protocol versions and host key algorithms. |
---|
226 | .It Fl i |
---|
227 | Specifies that |
---|
228 | .Nm |
---|
229 | is being run from inetd. |
---|
230 | .Nm |
---|
231 | is normally not run |
---|
232 | from inetd because it needs to generate the server key before it can |
---|
233 | respond to the client, and this may take tens of seconds. |
---|
234 | Clients would have to wait too long if the key was regenerated every time. |
---|
235 | However, with small key sizes (e.g., 512) using |
---|
236 | .Nm |
---|
237 | from inetd may |
---|
238 | be feasible. |
---|
239 | .It Fl k Ar key_gen_time |
---|
240 | Specifies how often the ephemeral protocol version 1 server key is |
---|
241 | regenerated (default 3600 seconds, or one hour). |
---|
242 | The motivation for regenerating the key fairly |
---|
243 | often is that the key is not stored anywhere, and after about an hour, |
---|
244 | it becomes impossible to recover the key for decrypting intercepted |
---|
245 | communications even if the machine is cracked into or physically |
---|
246 | seized. |
---|
247 | A value of zero indicates that the key will never be regenerated. |
---|
248 | .It Fl o Ar option |
---|
249 | Can be used to give options in the format used in the configuration file. |
---|
250 | This is useful for specifying options for which there is no separate |
---|
251 | command-line flag. |
---|
252 | .It Fl p Ar port |
---|
253 | Specifies the port on which the server listens for connections |
---|
254 | (default 22). |
---|
255 | Multiple port options are permitted. |
---|
256 | Ports specified in the configuration file are ignored when a |
---|
257 | command-line port is specified. |
---|
258 | .It Fl q |
---|
259 | Quiet mode. |
---|
260 | Nothing is sent to the system log. |
---|
261 | Normally the beginning, |
---|
262 | authentication, and termination of each connection is logged. |
---|
263 | .It Fl s |
---|
264 | Allows |
---|
265 | .Nm access_on/access_off |
---|
266 | to control whether sshd accepts connections. It assumes that access |
---|
267 | is set to on when |
---|
268 | .Nm sshd |
---|
269 | is started and accepts connections immediately. |
---|
270 | .It Fl t |
---|
271 | Test mode. |
---|
272 | Only check the validity of the configuration file and sanity of the keys. |
---|
273 | This is useful for updating |
---|
274 | .Nm |
---|
275 | reliably as configuration options may change. |
---|
276 | .It Fl u Ar len |
---|
277 | This option is used to specify the size of the field |
---|
278 | in the |
---|
279 | .Li utmp |
---|
280 | structure that holds the remote host name. |
---|
281 | If the resolved host name is longer than |
---|
282 | .Ar len , |
---|
283 | the dotted decimal value will be used instead. |
---|
284 | This allows hosts with very long host names that |
---|
285 | overflow this field to still be uniquely identified. |
---|
286 | Specifying |
---|
287 | .Fl u0 |
---|
288 | indicates that only dotted decimal addresses |
---|
289 | should be put into the |
---|
290 | .Pa utmp |
---|
291 | file. |
---|
292 | .Fl u0 |
---|
293 | is also be used to prevent |
---|
294 | .Nm |
---|
295 | from making DNS requests unless the authentication |
---|
296 | mechanism or configuration requires it. |
---|
297 | Authentication mechanisms that may require DNS include |
---|
298 | .Cm RhostsAuthentication , |
---|
299 | .Cm RhostsRSAAuthentication , |
---|
300 | .Cm HostbasedAuthentication |
---|
301 | and using a |
---|
302 | .Cm from="pattern-list" |
---|
303 | option in a key file. |
---|
304 | Configuration options that require DNS include using a |
---|
305 | USER@HOST pattern in |
---|
306 | .Cm AllowUsers |
---|
307 | or |
---|
308 | .Cm DenyUsers . |
---|
309 | .It Fl D |
---|
310 | When this option is specified |
---|
311 | .Nm |
---|
312 | will not detach and does not become a daemon. |
---|
313 | This allows easy monitoring of |
---|
314 | .Nm sshd . |
---|
315 | .It Fl S |
---|
316 | This option is the same as |
---|
317 | .Fl s |
---|
318 | except it assumes access is set to off when |
---|
319 | .Nm sshd |
---|
320 | starts, and does not accept connections until |
---|
321 | .Nm access_on |
---|
322 | is run. |
---|
323 | .It Fl 4 |
---|
324 | Forces |
---|
325 | .Nm |
---|
326 | to use IPv4 addresses only. |
---|
327 | .It Fl 6 |
---|
328 | Forces |
---|
329 | .Nm |
---|
330 | to use IPv6 addresses only. |
---|
331 | .El |
---|
332 | .Sh CONFIGURATION FILE |
---|
333 | .Nm |
---|
334 | reads configuration data from |
---|
335 | .Pa /etc/ssh/sshd_config |
---|
336 | (or the file specified with |
---|
337 | .Fl f |
---|
338 | on the command line). |
---|
339 | The file format and configuration options are described in |
---|
340 | .Xr sshd_config 5 . |
---|
341 | .Sh LOGIN PROCESS |
---|
342 | When a user successfully logs in, |
---|
343 | .Nm |
---|
344 | does the following: |
---|
345 | .Bl -enum -offset indent |
---|
346 | .It |
---|
347 | If the login is on a tty, and no command has been specified, |
---|
348 | prints last login time and |
---|
349 | .Pa /etc/motd |
---|
350 | (unless prevented in the configuration file or by |
---|
351 | .Pa $HOME/.hushlogin ; |
---|
352 | see the |
---|
353 | .Sx FILES |
---|
354 | section). |
---|
355 | .It |
---|
356 | If the login is on a tty, records login time. |
---|
357 | .It |
---|
358 | Checks |
---|
359 | .Pa /etc/nologin ; |
---|
360 | if it exists, prints contents and quits |
---|
361 | (unless root). |
---|
362 | .It |
---|
363 | Changes to run with normal user privileges. |
---|
364 | .It |
---|
365 | Sets up basic environment. |
---|
366 | .It |
---|
367 | Reads |
---|
368 | .Pa $HOME/.ssh/environment |
---|
369 | if it exists and users are allowed to change their environment. |
---|
370 | See the |
---|
371 | .Cm PermitUserEnvironment |
---|
372 | option in |
---|
373 | .Xr sshd_config 5 . |
---|
374 | .It |
---|
375 | Changes to user's home directory. |
---|
376 | .It |
---|
377 | If |
---|
378 | .Pa $HOME/.ssh/rc |
---|
379 | exists, runs it; else if |
---|
380 | .Pa /etc/ssh/sshrc |
---|
381 | exists, runs |
---|
382 | it; otherwise runs xauth. |
---|
383 | The |
---|
384 | .Dq rc |
---|
385 | files are given the X11 |
---|
386 | authentication protocol and cookie in standard input. |
---|
387 | .It |
---|
388 | Runs user's shell or command. |
---|
389 | .El |
---|
390 | .Sh AUTHORIZED_KEYS FILE FORMAT |
---|
391 | .Pa $HOME/.ssh/authorized_keys |
---|
392 | is the default file that lists the public keys that are |
---|
393 | permitted for RSA authentication in protocol version 1 |
---|
394 | and for public key authentication (PubkeyAuthentication) |
---|
395 | in protocol version 2. |
---|
396 | .Cm AuthorizedKeysFile |
---|
397 | may be used to specify an alternative file. |
---|
398 | .Pp |
---|
399 | Each line of the file contains one |
---|
400 | key (empty lines and lines starting with a |
---|
401 | .Ql # |
---|
402 | are ignored as |
---|
403 | comments). |
---|
404 | Each RSA public key consists of the following fields, separated by |
---|
405 | spaces: options, bits, exponent, modulus, comment. |
---|
406 | Each protocol version 2 public key consists of: |
---|
407 | options, keytype, base64 encoded key, comment. |
---|
408 | The options field |
---|
409 | is optional; its presence is determined by whether the line starts |
---|
410 | with a number or not (the options field never starts with a number). |
---|
411 | The bits, exponent, modulus and comment fields give the RSA key for |
---|
412 | protocol version 1; the |
---|
413 | comment field is not used for anything (but may be convenient for the |
---|
414 | user to identify the key). |
---|
415 | For protocol version 2 the keytype is |
---|
416 | .Dq ssh-dss |
---|
417 | or |
---|
418 | .Dq ssh-rsa . |
---|
419 | .Pp |
---|
420 | Note that lines in this file are usually several hundred bytes long |
---|
421 | (because of the size of the public key encoding). |
---|
422 | You don't want to type them in; instead, copy the |
---|
423 | .Pa identity.pub , |
---|
424 | .Pa id_dsa.pub |
---|
425 | or the |
---|
426 | .Pa id_rsa.pub |
---|
427 | file and edit it. |
---|
428 | .Pp |
---|
429 | .Nm |
---|
430 | enforces a minimum RSA key modulus size for protocol 1 |
---|
431 | and protocol 2 keys of 768 bits. |
---|
432 | .Pp |
---|
433 | The options (if present) consist of comma-separated option |
---|
434 | specifications. |
---|
435 | No spaces are permitted, except within double quotes. |
---|
436 | The following option specifications are supported (note |
---|
437 | that option keywords are case-insensitive): |
---|
438 | .Bl -tag -width Ds |
---|
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 |
---|
442 | patterns |
---|
443 | .Pf ( Ql * |
---|
444 | and |
---|
445 | .Ql ? |
---|
446 | serve as wildcards). |
---|
447 | The list may also contain |
---|
448 | patterns negated by prefixing them with |
---|
449 | .Ql ! ; |
---|
450 | if the canonical host name matches a negated pattern, the key is not accepted. |
---|
451 | The purpose |
---|
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 |
---|
458 | just the key). |
---|
459 | .It Cm command="command" |
---|
460 | Specifies that the command is executed whenever this key is used for |
---|
461 | authentication. |
---|
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 a 8-bit clean channel is required, |
---|
466 | one must not request a pty or should specify |
---|
467 | .Cm no-pty . |
---|
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/IP 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 |
---|
482 | controlled via the |
---|
483 | .Cm PermitUserEnvironment |
---|
484 | option. |
---|
485 | This option is automatically disabled if |
---|
486 | .Cm UseLogin |
---|
487 | is enabled. |
---|
488 | .It Cm no-port-forwarding |
---|
489 | Forbids TCP/IP 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 |
---|
492 | .Cm command |
---|
493 | option. |
---|
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 |
---|
499 | authentication. |
---|
500 | .It Cm no-pty |
---|
501 | Prevents tty allocation (a request to allocate a pty will fail). |
---|
502 | .It Cm permitopen="host:port" |
---|
503 | Limit local |
---|
504 | .Li ``ssh -L'' |
---|
505 | port forwarding such that it may only connect to the specified host and |
---|
506 | port. |
---|
507 | IPv6 addresses can be specified with an alternative syntax: |
---|
508 | .Ar host/port . |
---|
509 | Multiple |
---|
510 | .Cm permitopen |
---|
511 | options may be applied separated by commas. No pattern matching is |
---|
512 | performed on the specified hostnames, they must be literal domains or |
---|
513 | addresses. |
---|
514 | .El |
---|
515 | .Ss Examples |
---|
516 | 1024 33 12121.\|.\|.\|312314325 ylo@foo.bar |
---|
517 | .Pp |
---|
518 | from="*.niksula.hut.fi,!pc.niksula.hut.fi" 1024 35 23.\|.\|.\|2334 ylo@niksula |
---|
519 | .Pp |
---|
520 | command="dump /home",no-pty,no-port-forwarding 1024 33 23.\|.\|.\|2323 backup.hut.fi |
---|
521 | .Pp |
---|
522 | permitopen="10.2.1.55:80",permitopen="10.2.1.56:25" 1024 33 23.\|.\|.\|2323 |
---|
523 | .Sh SSH_KNOWN_HOSTS FILE FORMAT |
---|
524 | The |
---|
525 | .Pa /etc/ssh/ssh_known_hosts , |
---|
526 | and |
---|
527 | .Pa $HOME/.ssh/known_hosts |
---|
528 | files contain host public keys for all known hosts. |
---|
529 | The global file should |
---|
530 | be prepared by the administrator (optional), and the per-user file is |
---|
531 | maintained automatically: whenever the user connects from an unknown host |
---|
532 | its key is added to the per-user file. |
---|
533 | .Pp |
---|
534 | Each line in these files contains the following fields: hostnames, |
---|
535 | bits, exponent, modulus, comment. |
---|
536 | The fields are separated by spaces. |
---|
537 | .Pp |
---|
538 | Hostnames is a comma-separated list of patterns ('*' and '?' act as |
---|
539 | wildcards); each pattern in turn is matched against the canonical host |
---|
540 | name (when authenticating a client) or against the user-supplied |
---|
541 | name (when authenticating a server). |
---|
542 | A pattern may also be preceded by |
---|
543 | .Ql ! |
---|
544 | to indicate negation: if the host name matches a negated |
---|
545 | pattern, it is not accepted (by that line) even if it matched another |
---|
546 | pattern on the line. |
---|
547 | .Pp |
---|
548 | Bits, exponent, and modulus are taken directly from the RSA host key; they |
---|
549 | can be obtained, e.g., from |
---|
550 | .Pa /etc/ssh/ssh_host_key.pub . |
---|
551 | The optional comment field continues to the end of the line, and is not used. |
---|
552 | .Pp |
---|
553 | Lines starting with |
---|
554 | .Ql # |
---|
555 | and empty lines are ignored as comments. |
---|
556 | .Pp |
---|
557 | When performing host authentication, authentication is accepted if any |
---|
558 | matching line has the proper key. |
---|
559 | It is thus permissible (but not |
---|
560 | recommended) to have several lines or different host keys for the same |
---|
561 | names. |
---|
562 | This will inevitably happen when short forms of host names |
---|
563 | from different domains are put in the file. |
---|
564 | It is possible |
---|
565 | that the files contain conflicting information; authentication is |
---|
566 | accepted if valid information can be found from either file. |
---|
567 | .Pp |
---|
568 | Note that the lines in these files are typically hundreds of characters |
---|
569 | long, and you definitely don't want to type in the host keys by hand. |
---|
570 | Rather, generate them by a script |
---|
571 | or by taking |
---|
572 | .Pa /etc/ssh/ssh_host_key.pub |
---|
573 | and adding the host names at the front. |
---|
574 | .Ss Examples |
---|
575 | .Bd -literal |
---|
576 | closenet,.\|.\|.\|,130.233.208.41 1024 37 159.\|.\|.93 closenet.hut.fi |
---|
577 | cvs.openbsd.org,199.185.137.3 ssh-rsa AAAA1234.....= |
---|
578 | .Ed |
---|
579 | .Sh FILES |
---|
580 | .Bl -tag -width Ds |
---|
581 | .It Pa /etc/ssh/sshd_config |
---|
582 | Contains configuration data for |
---|
583 | .Nm sshd . |
---|
584 | The file format and configuration options are described in |
---|
585 | .Xr sshd_config 5 . |
---|
586 | .It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key |
---|
587 | These three files contain the private parts of the host keys. |
---|
588 | These files should only be owned by root, readable only by root, and not |
---|
589 | accessible to others. |
---|
590 | Note that |
---|
591 | .Nm |
---|
592 | does not start if this file is group/world-accessible. |
---|
593 | .It Pa /etc/ssh/ssh_host_key.pub, /etc/ssh/ssh_host_dsa_key.pub, /etc/ssh/ssh_host_rsa_key.pub |
---|
594 | These three files contain the public parts of the host keys. |
---|
595 | These files should be world-readable but writable only by |
---|
596 | root. |
---|
597 | Their contents should match the respective private parts. |
---|
598 | These files are not |
---|
599 | really used for anything; they are provided for the convenience of |
---|
600 | the user so their contents can be copied to known hosts files. |
---|
601 | These files are created using |
---|
602 | .Xr ssh-keygen 1 . |
---|
603 | .It Pa /etc/moduli |
---|
604 | Contains Diffie-Hellman groups used for the "Diffie-Hellman Group Exchange". |
---|
605 | The file format is described in |
---|
606 | .Xr moduli 5 . |
---|
607 | .It Pa /var/empty |
---|
608 | .Xr chroot 2 |
---|
609 | directory used by |
---|
610 | .Nm |
---|
611 | during privilege separation in the pre-authentication phase. |
---|
612 | The directory should not contain any files and must be owned by root |
---|
613 | and not group or world-writable. |
---|
614 | .It Pa /var/run/sshd.pid |
---|
615 | Contains the process ID of the |
---|
616 | .Nm |
---|
617 | listening for connections (if there are several daemons running |
---|
618 | concurrently for different ports, this contains the process ID of the one |
---|
619 | started last). |
---|
620 | The content of this file is not sensitive; it can be world-readable. |
---|
621 | .It Pa $HOME/.ssh/authorized_keys |
---|
622 | Lists the public keys (RSA or DSA) that can be used to log into the user's account. |
---|
623 | This file must be readable by root (which may on some machines imply |
---|
624 | it being world-readable if the user's home directory resides on an NFS |
---|
625 | volume). |
---|
626 | It is recommended that it not be accessible by others. |
---|
627 | The format of this file is described above. |
---|
628 | Users will place the contents of their |
---|
629 | .Pa identity.pub , |
---|
630 | .Pa id_dsa.pub |
---|
631 | and/or |
---|
632 | .Pa id_rsa.pub |
---|
633 | files into this file, as described in |
---|
634 | .Xr ssh-keygen 1 . |
---|
635 | .It Pa "/etc/ssh/ssh_known_hosts" and "$HOME/.ssh/known_hosts" |
---|
636 | These files are consulted when using rhosts with RSA host |
---|
637 | authentication or protocol version 2 hostbased authentication |
---|
638 | to check the public key of the host. |
---|
639 | The key must be listed in one of these files to be accepted. |
---|
640 | The client uses the same files |
---|
641 | to verify that it is connecting to the correct remote host. |
---|
642 | These files should be writable only by root/the owner. |
---|
643 | .Pa /etc/ssh/ssh_known_hosts |
---|
644 | should be world-readable, and |
---|
645 | .Pa $HOME/.ssh/known_hosts |
---|
646 | can but need not be world-readable. |
---|
647 | .It Pa /etc/nologin |
---|
648 | If this file exists, |
---|
649 | .Nm |
---|
650 | refuses to let anyone except root log in. |
---|
651 | The contents of the file |
---|
652 | are displayed to anyone trying to log in, and non-root connections are |
---|
653 | refused. |
---|
654 | The file should be world-readable. |
---|
655 | .It Pa /etc/hosts.allow, /etc/hosts.deny |
---|
656 | Access controls that should be enforced by tcp-wrappers are defined here. |
---|
657 | Further details are described in |
---|
658 | .Xr hosts_access 5 . |
---|
659 | .It Pa $HOME/.rhosts |
---|
660 | This file contains host-username pairs, separated by a space, one per |
---|
661 | line. |
---|
662 | The given user on the corresponding host is permitted to log in |
---|
663 | without password. |
---|
664 | The same file is used by rlogind and rshd. |
---|
665 | The file must |
---|
666 | be writable only by the user; it is recommended that it not be |
---|
667 | accessible by others. |
---|
668 | .Pp |
---|
669 | If is also possible to use netgroups in the file. |
---|
670 | Either host or user |
---|
671 | name may be of the form +@groupname to specify all hosts or all users |
---|
672 | in the group. |
---|
673 | .It Pa $HOME/.shosts |
---|
674 | For ssh, |
---|
675 | this file is exactly the same as for |
---|
676 | .Pa .rhosts . |
---|
677 | However, this file is |
---|
678 | not used by rlogin and rshd, so using this permits access using SSH only. |
---|
679 | .It Pa /etc/hosts.equiv |
---|
680 | This file is used during |
---|
681 | .Pa .rhosts |
---|
682 | authentication. |
---|
683 | In the simplest form, this file contains host names, one per line. |
---|
684 | Users on |
---|
685 | those hosts are permitted to log in without a password, provided they |
---|
686 | have the same user name on both machines. |
---|
687 | The host name may also be |
---|
688 | followed by a user name; such users are permitted to log in as |
---|
689 | .Em any |
---|
690 | user on this machine (except root). |
---|
691 | Additionally, the syntax |
---|
692 | .Dq +@group |
---|
693 | can be used to specify netgroups. |
---|
694 | Negated entries start with |
---|
695 | .Ql \&- . |
---|
696 | .Pp |
---|
697 | If the client host/user is successfully matched in this file, login is |
---|
698 | automatically permitted provided the client and server user names are the |
---|
699 | same. |
---|
700 | Additionally, successful RSA host authentication is normally required. |
---|
701 | This file must be writable only by root; it is recommended |
---|
702 | that it be world-readable. |
---|
703 | .Pp |
---|
704 | .Sy "Warning: It is almost never a good idea to use user names in" |
---|
705 | .Pa hosts.equiv . |
---|
706 | Beware that it really means that the named user(s) can log in as |
---|
707 | .Em anybody , |
---|
708 | which includes bin, daemon, adm, and other accounts that own critical |
---|
709 | binaries and directories. |
---|
710 | Using a user name practically grants the user root access. |
---|
711 | The only valid use for user names that I can think |
---|
712 | of is in negative entries. |
---|
713 | .Pp |
---|
714 | Note that this warning also applies to rsh/rlogin. |
---|
715 | .It Pa /etc/shosts.equiv |
---|
716 | This is processed exactly as |
---|
717 | .Pa /etc/hosts.equiv . |
---|
718 | However, this file may be useful in environments that want to run both |
---|
719 | rsh/rlogin and ssh. |
---|
720 | .It Pa $HOME/.ssh/environment |
---|
721 | This file is read into the environment at login (if it exists). |
---|
722 | It can only contain empty lines, comment lines (that start with |
---|
723 | .Ql # ) , |
---|
724 | and assignment lines of the form name=value. |
---|
725 | The file should be writable |
---|
726 | only by the user; it need not be readable by anyone else. |
---|
727 | Environment processing is disabled by default and is |
---|
728 | controlled via the |
---|
729 | .Cm PermitUserEnvironment |
---|
730 | option. |
---|
731 | .It Pa $HOME/.ssh/rc |
---|
732 | If this file exists, it is run with /bin/sh after reading the |
---|
733 | environment files but before starting the user's shell or command. |
---|
734 | It must not produce any output on stdout; stderr must be used |
---|
735 | instead. |
---|
736 | If X11 forwarding is in use, it will receive the "proto cookie" pair in |
---|
737 | its standard input (and |
---|
738 | .Ev DISPLAY |
---|
739 | in its environment). |
---|
740 | The script must call |
---|
741 | .Xr xauth 1 |
---|
742 | because |
---|
743 | .Nm |
---|
744 | will not run xauth automatically to add X11 cookies. |
---|
745 | .Pp |
---|
746 | The primary purpose of this file is to run any initialization routines |
---|
747 | which may be needed before the user's home directory becomes |
---|
748 | accessible; AFS is a particular example of such an environment. |
---|
749 | .Pp |
---|
750 | This file will probably contain some initialization code followed by |
---|
751 | something similar to: |
---|
752 | .Bd -literal |
---|
753 | if read proto cookie && [ -n "$DISPLAY" ]; then |
---|
754 | if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then |
---|
755 | # X11UseLocalhost=yes |
---|
756 | echo add unix:`echo $DISPLAY | |
---|
757 | cut -c11-` $proto $cookie |
---|
758 | else |
---|
759 | # X11UseLocalhost=no |
---|
760 | echo add $DISPLAY $proto $cookie |
---|
761 | fi | xauth -q - |
---|
762 | fi |
---|
763 | .Ed |
---|
764 | .Pp |
---|
765 | If this file does not exist, |
---|
766 | .Pa /etc/ssh/sshrc |
---|
767 | is run, and if that |
---|
768 | does not exist either, xauth is used to add the cookie. |
---|
769 | .Pp |
---|
770 | This file should be writable only by the user, and need not be |
---|
771 | readable by anyone else. |
---|
772 | .It Pa /etc/ssh/sshrc |
---|
773 | Like |
---|
774 | .Pa $HOME/.ssh/rc . |
---|
775 | This can be used to specify |
---|
776 | machine-specific login-time initializations globally. |
---|
777 | This file should be writable only by root, and should be world-readable. |
---|
778 | .El |
---|
779 | .Sh AUTHORS |
---|
780 | OpenSSH is a derivative of the original and free |
---|
781 | ssh 1.2.12 release by Tatu Ylonen. |
---|
782 | Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, |
---|
783 | Theo de Raadt and Dug Song |
---|
784 | removed many bugs, re-added newer features and |
---|
785 | created OpenSSH. |
---|
786 | Markus Friedl contributed the support for SSH |
---|
787 | protocol versions 1.5 and 2.0. |
---|
788 | Niels Provos and Markus Friedl contributed support |
---|
789 | for privilege separation. |
---|
790 | .Sh SEE ALSO |
---|
791 | .Xr access_on 1 , |
---|
792 | .Xr access_off 1 , |
---|
793 | .Xr scp 1 , |
---|
794 | .Xr sftp 1 , |
---|
795 | .Xr ssh 1 , |
---|
796 | .Xr ssh-add 1 , |
---|
797 | .Xr ssh-agent 1 , |
---|
798 | .Xr ssh-keygen 1 , |
---|
799 | .Xr login.conf 5 , |
---|
800 | .Xr moduli 5 , |
---|
801 | .Xr sshd_config 5 , |
---|
802 | .Xr sftp-server 8 |
---|
803 | .Rs |
---|
804 | .%A T. Ylonen |
---|
805 | .%A T. Kivinen |
---|
806 | .%A M. Saarinen |
---|
807 | .%A T. Rinne |
---|
808 | .%A S. Lehtinen |
---|
809 | .%T "SSH Protocol Architecture" |
---|
810 | .%N draft-ietf-secsh-architecture-12.txt |
---|
811 | .%D January 2002 |
---|
812 | .%O work in progress material |
---|
813 | .Re |
---|
814 | .Rs |
---|
815 | .%A M. Friedl |
---|
816 | .%A N. Provos |
---|
817 | .%A W. A. Simpson |
---|
818 | .%T "Diffie-Hellman Group Exchange for the SSH Transport Layer Protocol" |
---|
819 | .%N draft-ietf-secsh-dh-group-exchange-02.txt |
---|
820 | .%D January 2002 |
---|
821 | .%O work in progress material |
---|
822 | .Re |
---|