Penguin
Recent Changes
Annotated edit history of slogin(1) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 ----
2 __NAME__
3
4
5 ssh - OpenSSH SSH client (remote login program)
6 __SYNOPSIS__
7
8
9 ssh [[-l login_name] hostname | user@hostname
10 [[command]
11
12
13 ssh [[-afgknqstvxACNPTX1246] [[-b bind_address] [[-c cipher_spec] [[-e escape_char] [[-i identity_file] [[-l login_name] [[-m mac_spec] [[-o option] [[-p port] [[-F configfile] [[
14 -L
15 port:host:hostport
16 ] [[ -R
17 port:host:hostport
18 ] [[-D port] hostname | user@hostname[[command]
19 __DESCRIPTION__
20
21
22 ssh (SSH client) is a program for logging into a remote
23 machine and for executing commands on a remote machine. It
24 is intended to replace rlogin and rsh, and provide secure
25 encrypted communications between two untrusted hosts over an
26 insecure network. X11 connections and arbitrary TCP/IP ports
27 can also be forwarded over the secure channel.
28
29
30 ssh connects and logs into the specified hostname. The user must prove his/her identity to the remote machine using one of several methods depending on the protocol version used:
31
32
33 __SSH protocol version 1__
34
35
36 First, if the machine the user logs in from is listed in
37 /etc/hosts.equiv or /etc/ssh/shosts.equiv
38 on the remote machine, and the user names are the same on
39 both sides, the user is immediately permitted to log in.
40 Second, if .rhosts or .shosts exists in
41 the user's home directory on the remote machine and contains
42 a line containing the name of the client machine and the
43 name of the user on that machine, the user is permitted to
44 log in. This form of authentication alone is normally not
45 allowed by the server because it is not secure.
46
47
48 The second authentication method is the rhosts or
49 hosts.equiv method combined with RSA-based host
50 authentica- tion. It means that if the login would be
51 permitted by $HOME/.rhosts, $HOME/.shosts,
52 /etc/hosts.equiv, or
53 /etc/ssh/shosts.equiv, and if additionally the
54 server can verify the client's host key (see
55 /etc/ssh/ssh_known_hosts and
56 $HOME/.ssh/known_hosts in the __FILES__
57 section), only then login is permitted. This authentication
58 method closes secu- rity holes due to IP spoofing, DNS
59 spoofing and routing spoofing. [[Note to the administrator:
60 /etc/hosts.equiv, $HOME/.rhosts, and the
61 rlogin/rsh protocol in general, are inherently insecure and
62 should be disabled if security is desired.]
63
64
65 As a third authentication method, ssh supports RSA based
66 authentication. The scheme is based on public-key cryptog-
67 raphy: there are cryptosystems where encryption and decryp-
68 tion are done using separate keys, and it is not possible to
69 derive the decryption key from the encryption key. RSA is
70 one such system. The idea is that each user creates a pub-
71 lic/private key pair for authentication purposes. The server
72 knows the public key, and only the user knows the private
73 key. The file $HOME/.ssh/authorized_keys lists the
74 public keys that are permitted for logging in. When the user
75 logs in, the ssh program tells the server which key pair it
76 would like to use for authentication. The server checks if
77 this key is permitted, and if so, sends the user (actually
78 the ssh program running on behalf of the user) a challenge,
79 a random number, encrypted by the user's public key. The
80 challenge can only be decrypted using the proper private
81 key. The user's client then decrypts the challenge using the
82 private key, proving that he/she knows the private key but
83 without disclosing it to the server.
84
85
86 ssh implements the RSA authentication protocol automati-
87 cally. The user creates his/her RSA key pair by running
88 ssh-keygen(1). This stores the private key in
89 $HOME/.ssh/identity and the public key in
90 $HOME/.ssh/identity.pub in the user's home
91 directory. The user should then copy the
92 identity.pub to $HOME/.ssh/authorized_keys
93 in his/her home directory on the remote machine (the
94 authorized_keys file corresponds to the
95 conventional $HOME/.rhosts file, and has one key
96 per line, though the lines can be very long). After this,
97 the user can log in without giving the password. RSA
98 authentication is much more secure than rhosts
99 authentication.
100
101
102 The most convenient way to use RSA authentication may be
103 with an authentication agent. See ssh-agent(1) for
104 more information.
105
106
107 If other authentication methods fail, ssh prompts the user
108 for a password. The password is sent to the remote host for
109 checking; however, since all communications are encrypted,
110 the password cannot be seen by someone listening on the net-
111 work.
112
113
114 __SSH protocol version 2__
115
116
117 When a user connects using the protocol version 2 different
118 authentication methods are available. Using the default
2 perry 119 values for !PreferredAuthentications, the client will try to
1 perry 120 authenticate first using the hostbased method; if this
121 method fails public key authentication is attempted, and
122 finally if this method fails keyboard-interactive and pass-
123 word authentication are tried.
124
125
126 The public key method is similar to RSA authentication
127 described in the previous section and allows the RSA or DSA
128 algorithm to be used: The client uses his private key,
129 $HOME/.ssh/id_dsa or $HOME/.ssh/id_rsa, to
130 sign the session identifier and sends the result to the
131 server. The server checks whether the matching public key is
132 listed in $HOME/.ssh/authorized_keys and grants
133 access if both the key is found and the signature is
134 correct. The session identi- fier is derived from a shared
135 Diffie-Hellman value and is only known to the client and the
136 server.
137
138
139 If public key authentication fails or is not available a
140 password can be sent encrypted to the remote host for prov-
141 ing the user's identity.
142
143
144 Additionally, ssh supports hostbased or challenge response
145 authentication.
146
147
148 Protocol 2 provides additional mechanisms for confidential-
149 ity (the traffic is encrypted using 3DES, Blowfish, CAST128
150 or Arcfour) and integrity (hmac-md5, hmac-sha1). Note that
151 protocol 1 lacks a strong mechanism for ensuring the
152 integrity of the connection.
153
154
155 __Login session and remote execution__
156
157
158 When the user's identity has been accepted by the server,
159 the server either executes the given command, or logs into
160 the machine and gives the user a normal shell on the remote
161 machine. All communication with the remote command or shell
162 will be automatically encrypted.
163
164
165 If a pseudo-terminal has been allocated (normal login ses-
166 sion), the user may use the escape characters noted
167 below.
168
169
170 If no pseudo tty has been allocated, the session is trans-
171 parent and can be used to reliably transfer binary data. On
172 most systems, setting the escape character to ``none'' will
173 also make the session transparent even if a tty is
174 used.
175
176
177 The session terminates when the command or shell on the
178 remote machine exits and all X11 and TCP/IP connections have
179 been closed. The exit status of the remote program is
180 returned as the exit status of ssh.
181
182
183 __Escape Characters__
184
185
186 When a pseudo terminal has been requested, ssh supports a
187 number of functions through the use of an escape
188 character.
189
190
191 A single tilde character can be sent as ~~ or by following
192 the tilde by a character other than those described below.
193 The escape character must always follow a newline to be
194 interpreted as special. The escape character can be changed
2 perry 195 in configuration files using the !EscapeChar configuration
1 perry 196 directive or on the command line by the -e
197 option.
198
199
200 The supported escapes (assuming the default ~)
201 are:
202 ~. Disconnect
203
204
205 ~^ZBackground ssh~#List forwarded connections~X11 and TCP forwarding__If the ForwardX11 variable is set to ``yes'' (or, see thedescription of the -X and -x options described later) andthe user is using X11 (the DISPLAY environment variable is set), the connection to the X11 display is automatically forwarded to the remote side in such a way that any X11 pro- grams started from the shell (or command) will go through the encrypted channel, and the connection to the real X server will be made from the local machine. The user should not manually set DISPLAY. Forwarding of X11 connections can be configured on the command line or in configuration files.
206
207
208 The DISPLAY value set by ssh will point to the
209 server machine, but with a display number greater than zero.
210 This is normal, and happens because ssh creates a ``proxy''
211 X server on the server machine for forwarding the
212 connections over the encrypted channel.
213
214
215 ssh will also automatically set up Xauthority data on the
216 server machine. For this purpose, it will generate a random
217 authorization cookie, store it in Xauthority on the server,
218 and verify that any forwarded connections carry this cookie
219 and replace it by the real cookie when the connection is
220 opened. The real authentication cookie is never sent to the
221 server machine (and no cookies are sent in the
222 plain).
223
224
225 If the user is using an authentication agent, the connection
226 to the agent is automatically forwarded to the remote side
227 unless disabled on the command line or in a configuration
228 file.
229
230
231 Forwarding of arbitrary TCP/IP connections over the secure
232 channel can be specified either on the command line or in a
233 configuration file. One possible application of TCP/IP for-
234 warding is a secure connection to an electronic purse;
235 another is going through firewalls.
236
237
238 __Server authentication__
239
240
241 ssh automatically maintains and checks a database containing
242 identifications for all hosts it has ever been used with.
243 Host keys are stored in $HOME/.ssh/known_hosts in
244 the user's home directory. Additionally, the file
245 /etc/ssh/ssh_known_hosts is automatically checked
246 for known hosts. Any new hosts are automatically added to
247 the user's file. If a host's identification ever changes,
248 ssh warns about this and disables password authentication to
249 prevent a trojan horse from getting the user's password.
250 Another pur- pose of this mechanism is to prevent
251 man-in-the-middle attacks which could otherwise be used to
2 perry 252 circumvent the encryption. The !StrictHostKeyChecking option
1 perry 253 (see below) can be used to prevent logins to machines whose
254 host key is not known or has changed.
255
256
257 The options are as follows:
258
259
260 -a Disables forwarding of the authentication agent con-
261 nection.
262
263
264 -A
265 Enables forwarding of the authentication agent con- nection.
266 This can also be specified on a per-host basis in a
267 configuration file.
268
269
270 -b bind_address
271 Specify the interface to transmit from on machines with
272 multiple interfaces or aliased addresses.
273
274
275 -c blowfish|3des|des
276 Selects the cipher to use for encrypting the session. 3des
277 is used by default. It is believed to be secure. 3des
278 (triple-des) is an encrypt-decrypt-encrypt triple with three
279 different keys. blowfish is a fast block cipher, it appears
280 very secure and is much faster than 3des. des is only
281 supported in the ssh client for interoperability with legacy
282 protocol 1 implementations that do not support the 3des
283 cipher. Its use is strongly dis- couraged due to
284 cryptographic weaknesses.
285
286
287 -c cipher_spec
288 Additionally, for protocol version 2 a comma-sepa- rated
289 list of ciphers can be specified in order of preference. See
290 Ciphers for more information.
291
292
293 -e ch|^ch|none
294 Sets the escape character for sessions with a pty (default:
295 ~). The escape character is only recog- nized at
296 the beginning of a line. The escape charac- ter followed by
297 a dot (.) closes the connection, fol- lowed by
298 control-Z suspends the connection, and fol- lowed by itself
299 sends the escape character once. Setting the character to
300 ``none'' disables any escapes and makes the session fully
301 transparent.
302
303
304 -f
305 Requests ssh to go to background just before command
306 execution. This is useful if ssh is going to ask for
307 passwords or passphrases, but the user wants it in the
308 background. This implies -n. The recommended way to start
309 X11 programs at a remote site is with something like ssh -f
310 host xterm.
311
312
313 -g
314 Allows remote hosts to connect to local forwarded
315 ports.
316
317
318 -i identity_file
319 Selects the file from which the identity (private key) for
320 RSA or DSA authentication is read. Default is
321 $HOME/.ssh/identity in the user's home directory.
322 Identity files may also be specified on a per-host basis in
323 the configuration file. It is possible to have multiple -i
324 options (and multiple identities specified in configuration
325 files).
326
327
328 -I smartcard_device
329 Specifies which smartcard device to use. The argument is the
330 device ssh should use to communicate with a smartcard used
331 for storing the user's private RSA key.
332
333
334 -k
335 Disables forwarding of Kerberos tickets and AFS tokens. This
336 may also be specified on a per-host basis in the
337 configuration file.
338
339
340 -l login_name
341 Specifies the user to log in as on the remote machine. This
342 also may be specified on a per-host basis in the
343 configuration file.
344
345
346 -m mac_spec
347 Additionally, for protocol version 2 a comma-sepa- rated
348 list of MAC (message authentication code) algo- rithms can
349 be specified in order of preference. See the MACs keyword
350 for more information.
351
352
353 -n
354 Redirects stdin from /dev/null (actually, prevents
355 reading from stdin). This must be used when ssh is run in
356 the background. A common trick is to use this to run X11
357 programs on a remote machine. For exam- ple, ssh -n
358 shadows.cs.hut.fi emacs
359
360
361 -N
362 Do not execute a remote command. This is useful for just
363 forwarding ports (protocol version 2 only).
364
365
366 -o option
367 Can be used to give options in the format used in the
368 configuration file. This is useful for specifying options
369 for which there is no separate command-line
370 flag.
371
372
373 -p port
374 Port to connect to on the remote host. This can be specified
375 on a per-host basis in the configuration file.
376
377
378 -P
379 Use a non-privileged port for outgoing connections. This can
380 be used if a firewall does not permit con- nections from
381 privileged ports. Note that this option turns off
2 perry 382 !RhostsAuthentication and RhostsRSAAuthentication for older
1 perry 383 servers.
384
385
386 -q
387 Quiet mode. Causes all warning and diagnostic mes- sages to
388 be suppressed. Only fatal errors are dis- played. If a
389 second -q is given then even fatal errors are
390 suppressed.
391
392
393 -s
394 May be used to request invocation of a subsystem on the
395 remote system. Subsystems are a feature of the SSH2 protocol
396 which facilitate the use of SSH as a secure transport for
397 other applications (eg. sftp). The subsystem is specified as
398 the remote command.
399
400
401 -t
402 Force pseudo-tty allocation. This can be used to execute
403 arbitrary screen-based programs on a remote machine, which
404 can be very useful, e.g., when imple- menting menu services.
405 Multiple -t options force tty allocation, even if ssh has no
406 local tty.
407
408
409 -T
410 Disable pseudo-tty allocation.
411
412
413 -v
414 Verbose mode. Causes ssh to print debugging messages about
415 its progress. This is helpful in debugging connection,
416 authentication, and configuration prob- lems. Multiple -v
417 options increases the verbosity. Maximum is 3.
418
419
420 -x
421 Disables X11 forwarding.
422
423
424 -X
425 Enables X11 forwarding. This can also be specified on a
426 per-host basis in a configuration file.
427
428
429 -C
430 Requests compression of all data (including stdin, stdout,
431 stderr, and data for forwarded X11 and TCP/IP connections).
432 The compression algorithm is the same used by
433 gzip(1), and the ``level'' can be controlled by the
2 perry 434 !CompressionLevel option (see below). Compres- sion is
1 perry 435 desirable on modem lines and other slow con- nections, but
436 will only slow down things on fast net- works. The default
437 value can be set on a host-by-host basis in the
438 configuration files; see the Compression option
439 below.
440
441
442 -F configfile
443 Specifies an alternative per-user configuration file. If a
444 configuration file is given on the command line, the
445 system-wide configuration file
446 (/etc/ssh/ssh_config) will be ignored. The default
447 for the per-user configuration file is
448 $HOME/.ssh/config.
449
450
451 -L port:host:hostport
452 Specifies that the given port on the local (client) host is
453 to be forwarded to the given host and port on the remote
454 side. This works by allocating a socket to listen to port on
455 the local side, and whenever a connection is made to this
456 port, the connection is forwarded over the secure channel,
457 and a connection is made to host port hostport from the
458 remote machine. Port forwardings can also be specified in
459 the configuration file. Only root can forward privi- leged
460 ports. IPv6 addresses can be specified with an alternative
461 syntax: port/host/hostport
462
463
464 -R port:host:hostport
465 Specifies that the given port on the remote (server) host is
466 to be forwarded to the given host and port on the local
467 side. This works by allocating a socket to listen to port on
468 the remote side, and whenever a connection is made to this
469 port, the connection is forwarded over the secure channel,
470 and a connection is made to host port hostport from the
471 local machine. Port forwardings can also be specified in the
472 config- uration file. Privileged ports can be forwarded only
473 when logging in as root on the remote machine. IPv6
474 addresses can be specified with an alternative syn- tax:
475 port/host/hostport
476
477
478 -D port
479 Specifies a local ``dynamic'' application-level port
480 forwarding. This works by allocating a socket to listen to
481 port on the local side, and whenever a con- nection is made
482 to this port, the connection is for- warded over the secure
483 channel, and the application protocol is then used to
484 determine where to connect to from the remote machine.
485 Currently the SOCKS4 protocol is supported, and ssh will act
486 as a SOCKS4 server. Only root can forward privileged ports.
487 Dynamic port forwardings can also be specified in the
488 configuration file.
489
490
491 -1
492 Forces ssh to try protocol version 1 only.
493
494
495 -2
496 Forces ssh to try protocol version 2 only.
497
498
499 -4
500 Forces ssh to use IPv4 addresses only.
501
502
503 -6
504 Forces ssh to use IPv6 addresses only.
505
506
507 __CONFIGURATION FILES__
508
509
510 ssh obtains configuration data from the following sources in
511 the following order: command line options, user's configura-
512 tion file ($HOME/.ssh/config), and system-wide
513 configuration file (/etc/ssh/ssh_config). For each
514 parameter, the first obtained value will be used. The
515 configuration files con- tain sections bracketed by ``Host''
516 specifications, and that section is only applied for hosts
517 that match one of the pat- terns given in the specification.
518 The matched host name is the one given on the command
519 line.
520
521
522 Since the first obtained value for each parameter is used,
523 more host-specific declarations should be given near the
524 beginning of the file, and general defaults at the
525 end.
526
527
528 The configuration file has the following
529 format:
530
531
532 Empty lines and lines starting with # are
533 comments.
534
535
536 Otherwise a line is of the format ``keyword arguments''.
537 Configuration options may be separated by whitespace or
538 optional whitespace and exactly one =; the latter
539 format is useful to avoid the need to quote whitespace when
540 specifying configuration options using the ssh, scp and sftp
541 -o option.
542
543
544 The possible keywords and their meanings are as follows
545 (note that keywords are case-insensitive and arguments are
546 case-sensitive):
547 Host Restricts the following declarations (up to the nextHost keyword) to be only for those hosts that matchone of the patterns given after the keyword. and ?can be used as wildcards in the patterns. A singleas a pattern can be used to provide global defaultsfor all hosts. The host is the hostname argumentgiven on the command line (i.e., the name is not con-verted to a canonicalized host name before matching).
548
549
2 perry 550 AFSTokenPassingSpecifies whether to pass AFS tokens to remote host.The argument to this keyword must be ``yes'' or``no''. This option applies to protocol version 1only.!BatchModeIf set to ``yes'', passphrase/password querying willbe disabled. In addition, the !ProtocolKeepAlives andSetupTimeOut options will both be set to 300 secondsby default. This option is useful in scripts andother batch jobs where no user is present to supplythe password, and where it is desirable to detect abroken network swiftly. The argument must be ``yes''or ``no''. The default is ``no''.!BindAddressSpecify the interface to transmit from on machineswith multiple interfaces or aliased addresses. Notethat this option does not work if !UsePrivilegedPortis set to ``yes''.CheckHostIPIf this flag is set to ``yes'', ssh will additionallycheck the host IP address in the known_hosts file. This allows ssh to detect if a host key changed due to DNS spoofing. If the option is set to ``no'', the check will not be executed. The default is ``yes''.
1 perry 551
552
553 Cipher
554 Specifies the cipher to use for encrypting the ses- sion in
555 protocol version 1. Currently, ``blowfish'', ``3des'', and
556 ``des'' are supported. des is only supported in the ssh
557 client for interoperability with legacy protocol 1
558 implementations that do not support the 3des cipher. Its use
559 is strongly discouraged due to cryptographic weaknesses. The
560 default is ``3des''.
561
562
563 Ciphers
564 Specifies the ciphers allowed for protocol version 2 in
565 order of preference. Multiple ciphers must be
566 comma-separated. The default is
567
568
569 ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,
570 aes192-cbc,aes256-cbc''
2 perry 571 !ClearAllForwardings
1 perry 572
573
574 Specifies that all local, remote and dynamic port
575 forwardings specified in the configuration files or on the
576 command line be cleared. This option is pri- marily useful
577 when used from the ssh command line to clear port
578 forwardings set in configuration files, and is automatically
579 set by scp(1) and sftp(1). The argument
580 must be ``yes'' or ``no''. The default is
581 ``no''.
582
583
584 Compression
585 Specifies whether to use compression. The argument must be ``yes'' or ``no''. The default is ``no''.
586
587
2 perry 588 !CompressionLevel
1 perry 589 Specifies the compression level to use if compression is
590 enabled. The argument must be an integer from 1 (fast) to 9
591 (slow, best). The default level is 6, which is good for most
592 applications. The meaning of the values is the same as in
593 gzip(1). Note that this option applies to protocol
594 version 1 only.
595
596
2 perry 597 !ConnectionAttempts
1 perry 598 Specifies the number of tries (one per second) to make
599 before falling back to rsh or exiting. The argument must be
600 an integer. This may be useful in scripts if the connection
601 sometimes fails. The default is 1.
602
603
2 perry 604 !DynamicForward
1 perry 605 Specifies that a TCP/IP port on the local machine be
606 forwarded over the secure channel, and the applica- tion
607 protocol is then used to determine where to con- nect to
608 from the remote machine. The argument must be a port number.
609 Currently the SOCKS4 protocol is supported, and ssh will act
610 as a SOCKS4 server. Mul- tiple forwardings may be specified,
611 and additional forwardings can be given on the command line.
612 Only the superuser can forward privileged
613 ports.
614
615
2 perry 616 !EscapeChar
1 perry 617 Sets the escape character (default: ~). The escape
618 character can also be set on the command line. The argument
619 should be a single character, ^ followed by a
620 letter, or ``none'' to disable the escape character entirely
621 (making the connection transparent for binary
622 data).
623
624
2 perry 625 !FallBackToRsh
1 perry 626 Specifies that if connecting via ssh fails due to a
627 connection refused error (there is no sshd(8)
628 listen- ing on the remote host), rsh(1) should
629 automatically be used instead (after a suitable warning
630 about the session being unencrypted). The argument must be
631 ``yes'' or ``no''. The default is ``no''.
632
633
2 perry 634 !ForwardAgent
1 perry 635 Specifies whether the connection to the authentica- tion
636 agent (if any) will be forwarded to the remote machine. The
637 argument must be ``yes'' or ``no''. The default is
638 ``no''.
639
640
641 ForwardX11
642 Specifies whether X11 connections will be automati- cally
643 redirected over the secure channel and DISPLAY set.
644 The argument must be ``yes'' or ``no''. The default is
645 ``no''.
646
647
2 perry 648 !GatewayPorts
1 perry 649 Specifies whether remote hosts are allowed to connect to
650 local forwarded ports. By default, ssh binds local port
651 forwardings to the loopback addresss. This prevents other
652 remote hosts from connecting to forwarded ports.
2 perry 653 !GatewayPorts can be used to specify that ssh should bind
1 perry 654 local port forwardings to the wildcard address, thus
655 allowing remote hosts to con- nect to forwarded ports. The
656 argument must be ``yes'' or ``no''. The default is
657 ``no''.
658
659
2 perry 660 !GlobalKnownHostsFile
1 perry 661 Specifies a file to use for the global host key database
662 instead of /etc/ssh/ssh_known_hosts.
663
664
2 perry 665 !HostbasedAuthentication
1 perry 666 Specifies whether to try rhosts based authentication with
667 public key authentication. The argument must be ``yes'' or
668 ``no''. The default is ``no''. This option applies to
669 protocol version 2 only and is sim- ilar to
670 RhostsRSAAuthentication.
671
672
2 perry 673 !HostKeyAlgorithms
1 perry 674 Specifies the protocol version 2 host key algorithms that
675 the client wants to use in order of preference. The default
676 for this option is: ``ssh-rsa,ssh-dss''
677
678
2 perry 679 !HostKeyAlias
1 perry 680 Specifies an alias that should be used instead of the real
681 host name when looking up or saving the host key in the host
682 key database files. This option is use- ful for tunneling
683 ssh connections or for multiple servers running on a single
684 host.
685
686
2 perry 687 !HostName
1 perry 688 Specifies the real host name to log into. This can be used
689 to specify nicknames or abbreviations for hosts. Default is
690 the name given on the command line. Numeric IP addresses are
2 perry 691 also permitted (both on the command line and in !HostName
1 perry 692 specifications).
693
694
2 perry 695 !IdentityFile
1 perry 696 Specifies the file from which the user's RSA or DSA
697 authentication identity is read (default
698 $HOME/.ssh/identity in the user's home directory).
699 Additionally, any identities represented by the
700 authentication agent will be used for authentication. The
701 file name may use the tilde syntax to refer to a user's home
702 directory. It is possible to have multi- ple identity files
703 specified in configuration files; all these identities will
704 be tried in sequence.
705
706
2 perry 707 !KeepAlive
1 perry 708 Specifies whether the system should send keepalive messages
709 to the other side. If they are sent, death of the connection
710 or crash of one of the machines will be properly noticed.
711 This option only uses TCP keepalives (as opposed to using
712 ssh level keepalives), so takes a long time to notice when
713 the connection dies. As such, you probably want the
2 perry 714 !ProtocolKeepAlives option as well. However, this means that
1 perry 715 connections will die if the route is down temporarily, and
716 some people find it annoying.
717
718
719 The default is ``yes'' (to send keepalives), and the client
720 will notice if the network goes down or the remote host
721 dies. This is important in scripts, and many users want it
722 too.
723
724
725 To disable keepalives, the value should be set to ``no'' in
726 both the server and the client configura- tion
727 files.
728
729
2 perry 730 !KerberosAuthentication
1 perry 731 Specifies whether Kerberos authentication will be used. The
732 argument to this keyword must be ``yes'' or
733 ``no''.
734
735
2 perry 736 !KerberosTgtPassing
1 perry 737 Specifies whether a Kerberos TGT will be forwarded to the
738 server. This will only work if the Kerberos server is
739 actually an AFS kaserver. The argument to this keyword must
740 be ``yes'' or ``no''.
741
742
2 perry 743 !LocalForward
1 perry 744 Specifies that a TCP/IP port on the local machine be
745 forwarded over the secure channel to the specified host and
746 port from the remote machine. The first argument must be a
747 port number, and the second must be host:port. IPv6
748 addresses can be specified with an alternative syntax:
749 host/port. Multiple forward- ings may be specified, and
750 additional forwardings can be given on the command line.
751 Only the superuser can forward privileged
752 ports.
753
754
2 perry 755 !LogLevel
1 perry 756 Gives the verbosity level that is used when logging messages
757 from ssh. The possible values are: QUIET, FATAL, ERROR,
758 INFO, VERBOSE and DEBUG. The default is INFO.
759
760
761 MACs
762 Specifies the MAC (message authentication code) algo- rithms
763 in order of preference. The MAC algorithm is used in
764 protocol version 2 for data integrity protec- tion. Multiple
765 algorithms must be comma-separated. The default is
766 ``hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96''.
767
768
2 perry 769 !NoHostAuthenticationForLocalhost
1 perry 770 This option can be used if the home directory is shared
771 across machines. In this case localhost will refer to a
772 different machine on each of the machines and the user will
773 get many warnings about changed host keys. However, this
774 option disables host authentication for localhost. The
775 argument to this keyword must be ``yes'' or ``no''. The
776 default is to check the host key for localhost.
777
778
2 perry 779 !NumberOfPasswordPrompts
1 perry 780 Specifies the number of password prompts before giv- ing up.
781 The argument to this keyword must be an integer. Default is
782 3.
783
784
2 perry 785 !PasswordAuthentication
1 perry 786 Specifies whether to use password authentication. The
787 argument to this keyword must be ``yes'' or ``no''. The
788 default is ``yes''.
789
790
791 Port
792 Specifies the port number to connect on the remote host.
793 Default is 22.
794
795
2 perry 796 !PreferredAuthentications
1 perry 797 Specifies the order in which the client should try protocol
798 2 authentication methods. This allows a client to prefer one
799 method (e.g. keyboard-interactive) over another method (e.g.
800 password) The default for this option is:
801 ``hostbased,publickey,keyboard-interactive,password''
802
803
804 Protocol
805 Specifies the protocol versions ssh should support in order
806 of preference. The possible values are ``1'' and ``2''.
807 Multiple versions must be comma-sepa- rated. The default is
808 ``2,1''. This means that ssh tries version 2 and falls back
809 to version 1 if ver- sion 2 is not available.
810
811
2 perry 812 !ProtocolKeepAlives
1 perry 813 Specifies the interval at which IGNORE packets will be sent
814 to the server during dile periods. Use this option in
815 scripts to detect when the network fails. The argument must
816 be an integer. The default is 0 (disabled), or 300 if the
2 perry 817 !BatchMode option is set.
1 perry 818
819
2 perry 820 !ProxyCommand
1 perry 821 Specifies the command to use to connect to the server. The
822 command string extends to the end of the line, and is
823 executed with /bin/sh. In the command string,
824 %h will be substituted by the host name to connect
825 and %p by the port. The command can be basi- cally
826 anything, and should read from its standard input and write
827 to its standard output. It should eventually connect an
828 sshd(8) server running on some machine, or execute
829 sshd -i somewhere. Host key man- agement will be done using
2 perry 830 the !HostName of the host being connected (defaulting to the
1 perry 831 name typed by the user). Note that CheckHostIP is not
832 available for connects with a proxy command.
833
834
2 perry 835 !PubkeyAuthentication
1 perry 836 Specifies whether to try public key authentication. The
837 argument to this keyword must be ``yes'' or ``no''. The
838 default is ``yes''. This option applies to protocol version
839 2 only.
840
841
2 perry 842 !RemoteForward
1 perry 843 Specifies that a TCP/IP port on the remote machine be
844 forwarded over the secure channel to the specified host and
845 port from the local machine. The first argument must be a
846 port number, and the second must be host:port. IPv6
847 addresses can be specified with an alternative syntax:
848 host/port. Multiple forward- ings may be specified, and
849 additional forwardings can be given on the command line.
850 Only the superuser can forward privileged
851 ports.
852
853
2 perry 854 !RhostsAuthentication
1 perry 855 Specifies whether to try rhosts based authentication. Note
856 that this declaration only affects the client side and has
857 no effect whatsoever on security. Dis- abling rhosts
858 authentication may reduce authentica- tion time on slow
859 connections when rhosts authentica- tion is not used. Most
860 servers do not permit Rhost- sAuthentication because it is
861 not secure (see RhostsRSAAuthentication). The argument to
862 this key- word must be ``yes'' or ``no''. The default is
863 ``yes''. This option applies to protocol version 1
864 only.
865
866
867 RhostsRSAAuthentication
868 Specifies whether to try rhosts based authentication with
869 RSA host authentication. The argument must be ``yes'' or
870 ``no''. The default is ``yes''. This option applies to
871 protocol version 1 only.
872
873
874 RSAAuthentication
875 Specifies whether to try RSA authentication. The argument to
876 this keyword must be ``yes'' or ``no''. RSA authentication
877 will only be attempted if the identity file exists, or an
878 authentication agent is running. The default is ``yes''.
879 Note that this option applies to protocol version 1
880 only.
881
882
2 perry 883 !ChallengeResponseAuthentication
1 perry 884 Specifies whether to use challenge response authenti-
885 cation. The argument to this keyword must be ``yes'' or
886 ``no''. The default is ``yes''.
887
888
2 perry 889 !SetupTimeOut
1 perry 890 Normally, ssh blocks indefinitly whilst waiting to receive
891 the ssh banner and other setup protocol from the server,
892 during the session setup. This can cause ssh to hang under
893 certain circumstances. If this option is set, ssh will give
894 up if no data from the server is received for the specified
895 number of sec- onds. The argument must be an integer. The
2 perry 896 default is 0 (disabled), or 300 if !BatchMode is
1 perry 897 set.
898
899
2 perry 900 !SmartcardDevice
1 perry 901 Specifies which smartcard device to use. The argument to
902 this keyword is the device ssh should use to com- municate
903 with a smartcard used for storing the user's private RSA
904 key. By default, no device is specified and smartcard
905 support is not activated.
906
907
2 perry 908 !StrictHostKeyChecking
1 perry 909 If this flag is set to ``yes'', ssh will never auto-
910 matically add host keys to the
911 $HOME/.ssh/known_hosts file, and refuses to connect
912 to hosts whose host key has changed. This provides maximum
913 protection against trojan horse attacks, however, can be
914 annoy- ing when the /etc/ssh/ssh_known_hosts file
915 is poorly maintained, or connections to new hosts are fre-
916 quently made. This option forces the user to manu- ally add
917 all new hosts. If this flag is set to ``no'', ssh will
918 automatically add new host keys to the user known hosts
919 files. If this flag is set to ``ask'', new host keys will be
920 added to the user known host files only after the user has
921 confirmed that is what they really want to do, and ssh will
922 refuse to connect to hosts whose host key has changed. The
923 host keys of known hosts will be veri- fied automatically in
924 all cases. The argument must be ``yes'', ``no'' or ``ask''.
925 The default is ``ask''.
926
927
2 perry 928 !UsePrivilegedPort
1 perry 929 Specifies whether to use a privileged port for outgo- ing
930 connections. The argument must be ``yes'' or ``no''. The
931 default is ``no''. Note that this option must be set to
2 perry 932 ``yes'' if !RhostsAuthentication and RhostsRSAAuthentication
1 perry 933 authentications are needed with older servers.
934
935
936 User
937 Specifies the user to log in as. This can be useful when a
938 different user name is used on different machines. This
939 saves the trouble of having to remem- ber to give the user
940 name on the command line.
941
942
2 perry 943 !UserKnownHostsFile
1 perry 944 Specifies a file to use for the user host key database
945 instead of $HOME/.ssh/known_hosts.
946
947
2 perry 948 !UseRsh
1 perry 949 Specifies that rlogin/rsh should be used for this host. It
950 is possible that the host does not at all support the ssh
951 protocol. This causes ssh to immedi- ately execute
2 perry 952 rsh(1). All other options (except !HostName) are
1 perry 953 ignored if this has been specified. The argument must be
954 ``yes'' or ``no''.
955
956
957 XAuthLocation
958 Specifies the location of the xauth(1) program. The
959 default is /usr/bin/X11/xauth.
960
961
962 __ENVIRONMENT__
963
964
965 ssh will normally set the following environment
966 variables:
967 DISPLAY
968
969
970 The DISPLAY variable indicates the location of the
971 X11 server. It is automatically set by ssh to point to a
972 value of the form ``hostname:n'' where hostname indicates
973 the host where the shell runs, and n is an integer
974 DISPLAY explicitly, as that will render the X11
975 connection insecure (and will require the user to manually
976 copy any required autho- rization cookies).
977
978
979 HOME
980 Set to the path of the user's home directory.
981
982
983 LOGNAME
984 Synonym for USER; set for compatibility with
985 systems that use this variable.
986
987
988 MAIL
989 Set to the path of the user's mailbox.
990
991
992 PATH
993 Set to the default PATH, as specified when
994 compiling ssh.
995
996
997 SSH_ASKPASS
998 If ssh needs a passphrase, it will read the passphrase from
999 the current terminal if it was run from a terminal. If ssh
1000 does not have a terminal associated with it but
1001 DISPLAY and SSH_ASKPASS are set, it will
1002 execute the program specified by SSH_ASKPASS and
1003 open an X11 window to read the passphrase. This is
1004 particularly useful when calling ssh from a
1005 .Xsession or related script. (Note that on some
1006 machines it may be necessary to redirect the input from
1007 /dev/null to make this work.)
1008
1009
1010 SSH_AUTH_SOCK
1011 Identifies the path of a unix-domain socket used to
1012 communicate with the agent.
1013
1014
1015 SSH_CLIENT
1016 Identifies the client end of the connection. The variable
1017 contains three space-separated values: client ip-address,
1018 client port number, and server port number.
1019
1020
1021 SSH_ORIGINAL_COMMAND
1022 The variable contains the original command line if a forced
1023 command is executed. It can be used to extract the original
1024 arguments.
1025
1026
1027 SSH_TTY
1028 This is set to the name of the tty (path to the device)
1029 associated with the current shell or command. If the current
1030 session has no tty, this variable is not set.
1031
1032
1033 TZ
1034 The timezone variable is set to indicate the present
1035 timezone if it was set when the daemon was started (i.e.,
1036 the daemon passes the value on to new connec-
1037 tions).
1038
1039
1040 USER
1041 Set to the name of the user logging in.
1042
1043
1044 Additionally, ssh reads $HOME/.ssh/environment, and
1045 adds lines of the format ``VARNAME=value'' to the
1046 environment.
1047
1048
1049 __FILES__
1050 $HOME/.ssh/known_hosts
1051
1052
1053 Records host keys for all hosts the user has logged into
1054 that are not in /etc/ssh/ssh_known_hosts. See
1055 sshd(8).
1056
1057
1058 $HOME/.ssh/identity, $HOME/.ssh/id_dsa,
1059 $HOME/.ssh/id_rsa
1060 Contains the authentication identity of the user. They are
1061 for protocol 1 RSA, protocol 2 DSA, and pro- tocol 2 RSA,
1062 respectively. These files contain sen- sitive data and
1063 should be readable by the user but not accessible by others
1064 (read/write/execute). Note that ssh ignores a private key
1065 file if it is accessi- ble by others. It is possible to
1066 specify a passphrase when generating the key; the passphrase
1067 will be used to encrypt the sensitive part of this file
1068 using 3DES.
1069
1070
1071 $HOME/.ssh/identity.pub, $HOME/.ssh/id_dsa.pub,
1072 $HOME/.ssh/id_rsa.pub
1073 Contains the public key for authentication (public part of
1074 the identity file in human-readable form). The contents of
1075 the $HOME/.ssh/identity.pub file should be added to
1076 $HOME/.ssh/authorized_keys on all machines where
1077 the user wishes to log in using proto- col version 1 RSA
1078 authentication. The contents of the
1079 $HOME/.ssh/id_dsa.pub and
1080 $HOME/.ssh/id_rsa.pub file should be added to
1081 $HOME/.ssh/authorized_keys on all machines where
1082 the user wishes to log in using protocol version 2 DSA/RSA
1083 authentication. These files are not sensitive and can (but
1084 need not) be readable by anyone. These files are never used
1085 auto- matically and are not necessary; they are only pro-
1086 vided for the convenience of the user.
1087
1088
1089 $HOME/.ssh/config
1090 This is the per-user configuration file. The format of this
1091 file is described above. This file is used by the ssh
1092 client. This file does not usually con- tain any sensitive
1093 information, but the recommended permissions are read/write
1094 for the user, and not accessible by others.
1095
1096
1097 $HOME/.ssh/authorized_keys
1098 Lists the public keys (RSA/DSA) that can be used for logging
1099 in as this user. The format of this file is described in the
1100 sshd(8) manual page. In the sim- plest form the
1101 format is the same as the .pub iden- tity files. This file
1102 is not highly sensitive, but the recommended permissions are
1103 read/write for the user, and not accessible by
1104 others.
1105
1106
1107 /etc/ssh/ssh_known_hosts
1108 Systemwide list of known host keys. This file should be
1109 prepared by the system administrator to contain the public
1110 host keys of all machines in the organiza- tion. This file
1111 should be world-readable. This file contains public keys,
1112 one per line, in the following format (fields separated by
1113 spaces): system name, public key and optional comment field.
1114 When differ- ent names are used for the same machine, all
1115 such names should be listed, separated by commas. The format
1116 is described on the sshd(8) manual
1117 page.
1118
1119
1120 The canonical system name (as returned by name servers) is
1121 used by sshd(8) to verify the client host when
1122 logging in; other names are needed because ssh does not
1123 convert the user-supplied name to a canoni- cal name before
1124 checking the key, because someone with access to the name
1125 servers would then be able to fool host
1126 authentication.
1127
1128
1129 /etc/ssh/ssh_config
1130 Systemwide configuration file. This file provides defaults
1131 for those values that are not specified in the user's
1132 configuration file, and for those users who do not have a
1133 configuration file. This file must be
1134 world-readable.
1135
1136
1137 /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key,
1138 /etc/ssh/ssh_host_rsa_key
1139 These three files contain the private parts of the host keys
1140 and are used for RhostsRSAAuthentication and
2 perry 1141 !HostbasedAuthentication. Since they are readable only by
1 perry 1142 root ssh must be setuid root if these authen- tication
1143 methods are desired.
1144
1145
1146 $HOME/.rhosts
1147 This file is used in .rhosts authentication to list
1148 the host/user pairs that are permitted to log in. (Note that
1149 this file is also used by rlogin and rsh, which makes using
1150 this file insecure.) Each line of the file contains a host
1151 name (in the canonical form returned by name servers), and
1152 then a user name on that host, separated by a space. On some
1153 machines this file may need to be world-readable if the
1154 user's home directory is on a NFS partition, because
1155 sshd(8) reads it as root. Additionally, this file
1156 must be owned by the user, and must not have write permis-
1157 sions for anyone else. The recommended permission for most
1158 machines is read/write for the user, and not accessible by
1159 others.
1160
1161
1162 Note that by default sshd(8) will be installed so
1163 that it requires successful RSA host authentication before
1164 permitting . rhosts authentication. If the server
1165 machine does not have the client's host key in
1166 /etc/ssh/ssh_known_hosts, it can be stored in
1167 $HOME/.ssh/known_hosts. The easiest way to do this
1168 is to connect back to the client from the server machine
1169 using ssh; this will automatically add the host key to
1170 $HOME/.ssh/known_hosts.
1171
1172
1173 $HOME/.shosts
1174 This file is used exactly the same way as .rhosts.
1175 The purpose for having this file is to be able to use rhosts
1176 authentication with ssh without permitting login with
1177 rlogin(1) or rsh(1).
1178
1179
1180 /etc/hosts.equiv
1181 This file is used during .rhosts authentication. It
1182 contains canonical hosts names, one per line (the full
1183 format is described on the sshd(8) manual page). If
1184 the client host is found in this file, login is
1185 automatically permitted provided client and server user
1186 names are the same. Additionally, successful RSA host
1187 authentication is normally required. This file should only
1188 be writable by root.
1189
1190
1191 /etc/ssh/shosts.equiv
1192 This file is processed exactly as /etc/hosts.equiv.
1193 This file may be useful to permit logins using ssh but not
1194 using rsh/rlogin.
1195
1196
1197 /etc/ssh/sshrc
1198 Commands in this file are executed by ssh when the user logs
1199 in just before the user's shell (or com- mand) is started.
1200 See the sshd(8) manual page for more
1201 information.
1202
1203
1204 $HOME/.ssh/rc
1205 Commands in this file are executed by ssh when the user logs
1206 in just before the user's shell (or com- mand) is started.
1207 See the sshd(8) manual page for more
1208 information.
1209
1210
1211 $HOME/.ssh/environment
1212 Contains additional definitions for environment vari- ables,
1213 see section __ENVIRONMENT__ above.
1214
1215
1216 __AUTHORS__
1217
1218
1219 OpenSSH is a derivative of the original and free ssh 1.2.12
1220 release by Tatu Ylonen. Aaron Campbell, Bob Beck, Markus
1221 Friedl, Niels Provos, Theo de Raadt and Dug Song removed
1222 many bugs, re-added newer features and created OpenSSH.
1223 Markus Friedl contributed the support for SSH protocol ver-
1224 sions 1.5 and 2.0.
1225 __SEE ALSO__
1226
1227
1228 rlogin(1), rsh(1), scp(1),
1229 sftp(1), ssh-add(1),
1230 ssh-agent(1), ssh-keygen(1),
1231 telnet(1), sshd(8)
1232 T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne, and S. Lehtinen,'' SSH Protocol Architecture'', draft-ietf-secsh-architecture-09.txt, July 2001, work inprogress material.BSD September 25, 1999 1
1233 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.