Context Navigation

sshd.0 @ 18759

Visit:

Revision 18759, 27.8 KB checked in by zacheiss, 22 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r18758, which included commits to RCS files with non-trunk default branches.

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

Note: See TracBrowser for help on using the repository browser.

Download in other formats:

Original Format