summaryrefslogtreecommitdiff
path: root/ssh.0
diff options
context:
space:
mode:
Diffstat (limited to 'ssh.0')
-rw-r--r--ssh.0831
1 files changed, 447 insertions, 384 deletions
diff --git a/ssh.0 b/ssh.0
index 274fab8b5..83c4b94eb 100644
--- a/ssh.0
+++ b/ssh.0
@@ -5,208 +5,26 @@ NAME
5 5
6SYNOPSIS 6SYNOPSIS
7 ssh [-1246AaCfgkMNnqsTtVvXxY] [-b bind_address] [-c cipher_spec] 7 ssh [-1246AaCfgkMNnqsTtVvXxY] [-b bind_address] [-c cipher_spec]
8 [-D port] [-e escape_char] [-F configfile] [-i identity_file] 8 [-D [bind_address:]port] [-e escape_char] [-F configfile]
9 [-L [bind_address:]port:host:hostport] [-l login_name] [-m mac_spec] 9 [-i identity_file] [-L [bind_address:]port:host:hostport]
10 [-O ctl_cmd] [-o option] [-p port] 10 [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port]
11 [-R [bind_address:]port:host:hostport] [-S ctl_path] [user@]hostname 11 [-R [bind_address:]port:host:hostport] [-S ctl_path]
12 [command] 12 [-w tunnel:tunnel] [user@]hostname [command]
13 13
14DESCRIPTION 14DESCRIPTION
15 ssh (SSH client) is a program for logging into a remote machine and for 15 ssh (SSH client) is a program for logging into a remote machine and for
16 executing commands on a remote machine. It is intended to replace rlogin 16 executing commands on a remote machine. It is intended to replace rlogin
17 and rsh, and provide secure encrypted communications between two untrust- 17 and rsh, and provide secure encrypted communications between two untrust-
18 ed hosts over an insecure network. X11 connections and arbitrary TCP/IP 18 ed hosts over an insecure network. X11 connections and arbitrary TCP
19 ports can also be forwarded over the secure channel. 19 ports can also be forwarded over the secure channel.
20 20
21 ssh connects and logs into the specified hostname (with optional user 21 ssh connects and logs into the specified hostname (with optional user
22 name). The user must prove his/her identity to the remote machine using 22 name). The user must prove his/her identity to the remote machine using
23 one of several methods depending on the protocol version used. 23 one of several methods depending on the protocol version used (see be-
24 low).
24 25
25 If command is specified, command is executed on the remote host instead 26 If command is specified, it is executed on the remote host instead of a
26 of a login shell. 27 login shell.
27
28 SSH protocol version 1
29 The first authentication method is the rhosts or hosts.equiv method com-
30 bined with RSA-based host authentication. If the machine the user logs
31 in from is listed in /etc/hosts.equiv or /etc/shosts.equiv on the remote
32 machine, and the user names are the same on both sides, or if the files
33 ~/.rhosts or ~/.shosts exist in the user's home directory on the remote
34 machine and contain a line containing the name of the client machine and
35 the name of the user on that machine, the user is considered for log in.
36 Additionally, if the server can verify the client's host key (see
37 /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts in the FILES section),
38 only then is login permitted. This authentication method closes security
39 holes due to IP spoofing, DNS spoofing and routing spoofing. [Note to
40 the administrator: /etc/hosts.equiv, ~/.rhosts, and the rlogin/rsh proto-
41 col in general, are inherently insecure and should be disabled if securi-
42 ty is desired.]
43
44 As a second authentication method, ssh supports RSA based authentication.
45 The scheme is based on public-key cryptography: there are cryptosystems
46 where encryption and decryption are done using separate keys, and it is
47 not possible to derive the decryption key from the encryption key. RSA
48 is one such system. The idea is that each user creates a public/private
49 key pair for authentication purposes. The server knows the public key,
50 and only the user knows the private key.
51
52 The file ~/.ssh/authorized_keys lists the public keys that are permitted
53 for logging in. When the user logs in, the ssh program tells the server
54 which key pair it would like to use for authentication. The server
55 checks if this key is permitted, and if so, sends the user (actually the
56 ssh program running on behalf of the user) a challenge, a random number,
57 encrypted by the user's public key. The challenge can only be decrypted
58 using the proper private key. The user's client then decrypts the chal-
59 lenge using the private key, proving that he/she knows the private key
60 but without disclosing it to the server.
61
62 ssh implements the RSA authentication protocol automatically. The user
63 creates his/her RSA key pair by running ssh-keygen(1). This stores the
64 private key in ~/.ssh/identity and stores the public key in
65 ~/.ssh/identity.pub in the user's home directory. The user should then
66 copy the identity.pub to ~/.ssh/authorized_keys in his/her home directory
67 on the remote machine (the authorized_keys file corresponds to the con-
68 ventional ~/.rhosts file, and has one key per line, though the lines can
69 be very long). After this, the user can log in without giving the pass-
70 word.
71
72 The most convenient way to use RSA authentication may be with an authen-
73 tication agent. See ssh-agent(1) for more information.
74
75 If other authentication methods fail, ssh prompts the user for a pass-
76 word. The password is sent to the remote host for checking; however,
77 since all communications are encrypted, the password cannot be seen by
78 someone listening on the network.
79
80 SSH protocol version 2
81 When a user connects using protocol version 2, similar authentication
82 methods are available. Using the default values for
83 PreferredAuthentications, the client will try to authenticate first using
84 the hostbased method; if this method fails, public key authentication is
85 attempted, and finally if this method fails, keyboard-interactive and
86 password authentication are tried.
87
88 The public key method is similar to RSA authentication described in the
89 previous section and allows the RSA or DSA algorithm to be used: The
90 client uses his private key, ~/.ssh/id_dsa or ~/.ssh/id_rsa, to sign the
91 session identifier and sends the result to the server. The server checks
92 whether the matching public key is listed in ~/.ssh/authorized_keys and
93 grants access if both the key is found and the signature is correct. The
94 session identifier is derived from a shared Diffie-Hellman value and is
95 only known to the client and the server.
96
97 If public key authentication fails or is not available, a password can be
98 sent encrypted to the remote host to prove the user's identity.
99
100 Additionally, ssh supports hostbased or challenge response authentica-
101 tion.
102
103 Protocol 2 provides additional mechanisms for confidentiality (the traf-
104 fic is encrypted using AES, 3DES, Blowfish, CAST128 or Arcfour) and in-
105 tegrity (hmac-md5, hmac-sha1, hmac-ripemd160). Note that protocol 1
106 lacks a strong mechanism for ensuring the integrity of the connection.
107
108 Login session and remote execution
109 When the user's identity has been accepted by the server, the server ei-
110 ther executes the given command, or logs into the machine and gives the
111 user a normal shell on the remote machine. All communication with the
112 remote command or shell will be automatically encrypted.
113
114 If a pseudo-terminal has been allocated (normal login session), the user
115 may use the escape characters noted below.
116
117 If no pseudo-tty has been allocated, the session is transparent and can
118 be used to reliably transfer binary data. On most systems, setting the
119 escape character to ``none'' will also make the session transparent even
120 if a tty is used.
121
122 The session terminates when the command or shell on the remote machine
123 exits and all X11 and TCP/IP connections have been closed. The exit sta-
124 tus of the remote program is returned as the exit status of ssh.
125
126 Escape Characters
127 When a pseudo-terminal has been requested, ssh supports a number of func-
128 tions through the use of an escape character.
129
130 A single tilde character can be sent as ~~ or by following the tilde by a
131 character other than those described below. The escape character must
132 always follow a newline to be interpreted as special. The escape charac-
133 ter can be changed in configuration files using the EscapeChar configura-
134 tion directive or on the command line by the -e option.
135
136 The supported escapes (assuming the default `~') are:
137
138 ~. Disconnect.
139
140 ~^Z Background ssh.
141
142 ~# List forwarded connections.
143
144 ~& Background ssh at logout when waiting for forwarded connection /
145 X11 sessions to terminate.
146
147 ~? Display a list of escape characters.
148
149 ~B Send a BREAK to the remote system (only useful for SSH protocol
150 version 2 and if the peer supports it).
151
152 ~C Open command line. Currently this allows the addition of port
153 forwardings using the -L and -R options (see below). It also al-
154 lows the cancellation of existing remote port-forwardings using
155 -KR hostport. Basic help is available, using the -h option.
156
157 ~R Request rekeying of the connection (only useful for SSH protocol
158 version 2 and if the peer supports it).
159
160 X11 and TCP forwarding
161 If the ForwardX11 variable is set to ``yes'' (or see the description of
162 the -X and -x options described later) and the user is using X11 (the
163 DISPLAY environment variable is set), the connection to the X11 display
164 is automatically forwarded to the remote side in such a way that any X11
165 programs started from the shell (or command) will go through the encrypt-
166 ed channel, and the connection to the real X server will be made from the
167 local machine. The user should not manually set DISPLAY. Forwarding of
168 X11 connections can be configured on the command line or in configuration
169 files.
170
171 The DISPLAY value set by ssh will point to the server machine, but with a
172 display number greater than zero. This is normal, and happens because
173 ssh creates a ``proxy'' X server on the server machine for forwarding the
174 connections over the encrypted channel.
175
176 ssh will also automatically set up Xauthority data on the server machine.
177 For this purpose, it will generate a random authorization cookie, store
178 it in Xauthority on the server, and verify that any forwarded connections
179 carry this cookie and replace it by the real cookie when the connection
180 is opened. The real authentication cookie is never sent to the server
181 machine (and no cookies are sent in the plain).
182
183 If the ForwardAgent variable is set to ``yes'' (or see the description of
184 the -A and -a options described later) and the user is using an authenti-
185 cation agent, the connection to the agent is automatically forwarded to
186 the remote side.
187
188 Forwarding of arbitrary TCP/IP connections over the secure channel can be
189 specified either on the command line or in a configuration file. One
190 possible application of TCP/IP forwarding is a secure connection to an
191 electronic purse; another is going through firewalls.
192
193 Server authentication
194 ssh automatically maintains and checks a database containing identifica-
195 tions for all hosts it has ever been used with. Host keys are stored in
196 ~/.ssh/known_hosts in the user's home directory. Additionally, the file
197 /etc/ssh/ssh_known_hosts is automatically checked for known hosts. Any
198 new hosts are automatically added to the user's file. If a host's iden-
199 tification ever changes, ssh warns about this and disables password au-
200 thentication to prevent a trojan horse from getting the user's password.
201 Another purpose of this mechanism is to prevent man-in-the-middle attacks
202 which could otherwise be used to circumvent the encryption. The
203 StrictHostKeyChecking option can be used to prevent logins to machines
204 whose host key is not known or has changed.
205
206 ssh can be configured to verify host identification using fingerprint re-
207 source records (SSHFP) published in DNS. The VerifyHostKeyDNS option can
208 be used to control how DNS lookups are performed. SSHFP resource records
209 can be generated using ssh-keygen(1).
210 28
211 The options are as follows: 29 The options are as follows:
212 30
@@ -238,7 +56,7 @@ DESCRIPTION
238 dress. 56 dress.
239 57
240 -C Requests compression of all data (including stdin, stdout, 58 -C Requests compression of all data (including stdin, stdout,
241 stderr, and data for forwarded X11 and TCP/IP connections). The 59 stderr, and data for forwarded X11 and TCP connections). The
242 compression algorithm is the same used by gzip(1), and the 60 compression algorithm is the same used by gzip(1), and the
243 ``level'' can be controlled by the CompressionLevel option for 61 ``level'' can be controlled by the CompressionLevel option for
244 protocol version 1. Compression is desirable on modem lines and 62 protocol version 1. Compression is desirable on modem lines and
@@ -250,7 +68,7 @@ DESCRIPTION
250 Selects the cipher specification for encrypting the session. 68 Selects the cipher specification for encrypting the session.
251 69
252 Protocol version 1 allows specification of a single cipher. The 70 Protocol version 1 allows specification of a single cipher. The
253 suported values are ``3des'', ``blowfish'' and ``des''. 3des 71 supported values are ``3des'', ``blowfish'', and ``des''. 3des
254 (triple-des) is an encrypt-decrypt-encrypt triple with three dif- 72 (triple-des) is an encrypt-decrypt-encrypt triple with three dif-
255 ferent keys. It is believed to be secure. blowfish is a fast 73 ferent keys. It is believed to be secure. blowfish is a fast
256 block cipher; it appears very secure and is much faster than 74 block cipher; it appears very secure and is much faster than
@@ -259,29 +77,39 @@ DESCRIPTION
259 the 3des cipher. Its use is strongly discouraged due to crypto- 77 the 3des cipher. Its use is strongly discouraged due to crypto-
260 graphic weaknesses. The default is ``3des''. 78 graphic weaknesses. The default is ``3des''.
261 79
262 For protocol version 2 cipher_spec is a comma-separated list of 80 For protocol version 2, cipher_spec is a comma-separated list of
263 ciphers listed in order of preference. The supported ciphers are 81 ciphers listed in order of preference. The supported ciphers
264 ``3des-cbc'', ``aes128-cbc'', ``aes192-cbc'', ``aes256-cbc'', 82 are: 3des-cbc, aes128-cbc, aes192-cbc, aes256-cbc, aes128-ctr,
265 ``aes128-ctr'', ``aes192-ctr'', ``aes256-ctr'', ``arcfour128'', 83 aes192-ctr, aes256-ctr, arcfour128, arcfour256, arcfour, blow-
266 ``arcfour256'', ``arcfour'', ``blowfish-cbc'', and 84 fish-cbc, and cast128-cbc. The default is:
267 ``cast128-cbc''. The default is
268 85
269 ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128, 86 aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128,
270 arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr, 87 arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr,
271 aes192-ctr,aes256-ctr'' 88 aes192-ctr,aes256-ctr
272 89
273 -D port 90 -D [bind_address:]port
274 Specifies a local ``dynamic'' application-level port forwarding. 91 Specifies a local ``dynamic'' application-level port forwarding.
275 This works by allocating a socket to listen to port on the local 92 This works by allocating a socket to listen to port on the local
276 side, and whenever a connection is made to this port, the connec- 93 side, optionally bound to the specified bind_address. Whenever a
277 tion is forwarded over the secure channel, and the application 94 connection is made to this port, the connection is forwarded over
278 protocol is then used to determine where to connect to from the 95 the secure channel, and the application protocol is then used to
279 remote machine. Currently the SOCKS4 and SOCKS5 protocols are 96 determine where to connect to from the remote machine. Currently
280 supported, and ssh will act as a SOCKS server. Only root can 97 the SOCKS4 and SOCKS5 protocols are supported, and ssh will act
281 forward privileged ports. Dynamic port forwardings can also be 98 as a SOCKS server. Only root can forward privileged ports. Dy-
282 specified in the configuration file. 99 namic port forwardings can also be specified in the configuration
283 100 file.
284 -e ch | ^ch | none 101
102 IPv6 addresses can be specified with an alternative syntax:
103 [bind_address/]port or by enclosing the address in square brack-
104 ets. Only the superuser can forward privileged ports. By de-
105 fault, the local port is bound in accordance with the
106 GatewayPorts setting. However, an explicit bind_address may be
107 used to bind the connection to a specific address. The
108 bind_address of ``localhost'' indicates that the listening port
109 be bound for local use only, while an empty address or `*' indi-
110 cates that the port should be available from all interfaces.
111
112 -e escape_char
285 Sets the escape character for sessions with a pty (default: `~'). 113 Sets the escape character for sessions with a pty (default: `~').
286 The escape character is only recognized at the beginning of a 114 The escape character is only recognized at the beginning of a
287 line. The escape character followed by a dot (`.') closes the 115 line. The escape character followed by a dot (`.') closes the
@@ -305,9 +133,10 @@ DESCRIPTION
305 -g Allows remote hosts to connect to local forwarded ports. 133 -g Allows remote hosts to connect to local forwarded ports.
306 134
307 -I smartcard_device 135 -I smartcard_device
308 Specifies which smartcard device to use. The argument is the de- 136 Specify the device ssh should use to communicate with a smartcard
309 vice ssh should use to communicate with a smartcard used for 137 used for storing the user's private RSA key. This option is only
310 storing the user's private RSA key. 138 available if support for smartcard devices is compiled in (de-
139 fault is no support).
311 140
312 -i identity_file 141 -i identity_file
313 Selects a file from which the identity (private key) for RSA or 142 Selects a file from which the identity (private key) for RSA or
@@ -345,8 +174,10 @@ DESCRIPTION
345 may be specified on a per-host basis in the configuration file. 174 may be specified on a per-host basis in the configuration file.
346 175
347 -M Places the ssh client into ``master'' mode for connection shar- 176 -M Places the ssh client into ``master'' mode for connection shar-
348 ing. Refer to the description of ControlMaster in ssh_config(5) 177 ing. Multiple -M options places ssh into ``master'' mode with
349 for details. 178 confirmation required before slave connections are accepted. Re-
179 fer to the description of ControlMaster in ssh_config(5) for de-
180 tails.
350 181
351 -m mac_spec 182 -m mac_spec
352 Additionally, for protocol version 2 a comma-separated list of 183 Additionally, for protocol version 2 a comma-separated list of
@@ -410,17 +241,20 @@ DESCRIPTION
410 IdentityFile 241 IdentityFile
411 IdentitiesOnly 242 IdentitiesOnly
412 KbdInteractiveDevices 243 KbdInteractiveDevices
244 LocalCommand
413 LocalForward 245 LocalForward
414 LogLevel 246 LogLevel
415 MACs 247 MACs
416 NoHostAuthenticationForLocalhost 248 NoHostAuthenticationForLocalhost
417 NumberOfPasswordPrompts 249 NumberOfPasswordPrompts
418 PasswordAuthentication 250 PasswordAuthentication
251 PermitLocalCommand
419 Port 252 Port
420 PreferredAuthentications 253 PreferredAuthentications
421 Protocol 254 Protocol
422 ProxyCommand 255 ProxyCommand
423 PubkeyAuthentication 256 PubkeyAuthentication
257 RekeyLimit
424 RemoteForward 258 RemoteForward
425 RhostsRSAAuthentication 259 RhostsRSAAuthentication
426 RSAAuthentication 260 RSAAuthentication
@@ -430,6 +264,8 @@ DESCRIPTION
430 SmartcardDevice 264 SmartcardDevice
431 StrictHostKeyChecking 265 StrictHostKeyChecking
432 TCPKeepAlive 266 TCPKeepAlive
267 Tunnel
268 TunnelDevice
433 UsePrivilegedPort 269 UsePrivilegedPort
434 User 270 User
435 UserKnownHostsFile 271 UserKnownHostsFile
@@ -489,6 +325,12 @@ DESCRIPTION
489 tion, and configuration problems. Multiple -v options increase 325 tion, and configuration problems. Multiple -v options increase
490 the verbosity. The maximum is 3. 326 the verbosity. The maximum is 3.
491 327
328 -w tunnel:tunnel
329 Requests a tun(4) device on the client (first tunnel arg) and
330 server (second tunnel arg). The devices may be specified by nu-
331 merical ID or the keyword ``any'', which uses the next available
332 tunnel device. See also the Tunnel directive in ssh_config(5).
333
492 -X Enables X11 forwarding. This can also be specified on a per-host 334 -X Enables X11 forwarding. This can also be specified on a per-host
493 basis in a configuration file. 335 basis in a configuration file.
494 336
@@ -508,100 +350,358 @@ DESCRIPTION
508 -Y Enables trusted X11 forwarding. Trusted X11 forwardings are not 350 -Y Enables trusted X11 forwarding. Trusted X11 forwardings are not
509 subjected to the X11 SECURITY extension controls. 351 subjected to the X11 SECURITY extension controls.
510 352
511CONFIGURATION FILES
512 ssh may additionally obtain configuration data from a per-user configura- 353 ssh may additionally obtain configuration data from a per-user configura-
513 tion file and a system-wide configuration file. The file format and con- 354 tion file and a system-wide configuration file. The file format and con-
514 figuration options are described in ssh_config(5). 355 figuration options are described in ssh_config(5).
515 356
516ENVIRONMENT 357 ssh exits with the exit status of the remote command or with 255 if an
517 ssh will normally set the following environment variables: 358 error occurred.
359
360AUTHENTICATION
361 The OpenSSH SSH client supports SSH protocols 1 and 2. Protocol 2 is the
362 default, with ssh falling back to protocol 1 if it detects protocol 2 is
363 unsupported. These settings may be altered using the Protocol option in
364 ssh_config(5), or enforced using the -1 and -2 options (see above). Both
365 protocols support similar authentication methods, but protocol 2 is pre-
366 ferred since it provides additional mechanisms for confidentiality (the
367 traffic is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour) and
368 integrity (hmac-md5, hmac-sha1, hmac-ripemd160). Protocol 1 lacks a
369 strong mechanism for ensuring the integrity of the connection.
370
371 The methods available for authentication are: host-based authentication,
372 public key authentication, challenge-response authentication, and pass-
373 word authentication. Authentication methods are tried in the order spec-
374 ified above, though protocol 2 has a configuration option to change the
375 default order: PreferredAuthentications.
376
377 Host-based authentication works as follows: If the machine the user logs
378 in from is listed in /etc/hosts.equiv or /etc/shosts.equiv on the remote
379 machine, and the user names are the same on both sides, or if the files
380 ~/.rhosts or ~/.shosts exist in the user's home directory on the remote
381 machine and contain a line containing the name of the client machine and
382 the name of the user on that machine, the user is considered for login.
383 Additionally, the server must be able to verify the client's host key
384 (see the description of /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts,
385 below) for login to be permitted. This authentication method closes se-
386 curity holes due to IP spoofing, DNS spoofing, and routing spoofing.
387 [Note to the administrator: /etc/hosts.equiv, ~/.rhosts, and the
388 rlogin/rsh protocol in general, are inherently insecure and should be
389 disabled if security is desired.]
390
391 Public key authentication works as follows: The scheme is based on pub-
392 lic-key cryptography, using cryptosystems where encryption and decryption
393 are done using separate keys, and it is unfeasible to derive the decryp-
394 tion key from the encryption key. The idea is that each user creates a
395 public/private key pair for authentication purposes. The server knows
396 the public key, and only the user knows the private key. ssh implements
397 public key authentication protocol automatically, using either the RSA or
398 DSA algorithms. Protocol 1 is restricted to using only RSA keys, but
399 protocol 2 may use either. The HISTORY section of ssl(8) contains a
400 brief discussion of the two algorithms.
401
402 The file ~/.ssh/authorized_keys lists the public keys that are permitted
403 for logging in. When the user logs in, the ssh program tells the server
404 which key pair it would like to use for authentication. The client
405 proves that it has access to the private key and the server checks that
406 the corresponding public key is authorized to accept the account.
407
408 The user creates his/her key pair by running ssh-keygen(1). This stores
409 the private key in ~/.ssh/identity (protocol 1), ~/.ssh/id_dsa (protocol
410 2 DSA), or ~/.ssh/id_rsa (protocol 2 RSA) and stores the public key in
411 ~/.ssh/identity.pub (protocol 1), ~/.ssh/id_dsa.pub (protocol 2 DSA), or
412 ~/.ssh/id_rsa.pub (protocol 2 RSA) in the user's home directory. The us-
413 er should then copy the public key to ~/.ssh/authorized_keys in his/her
414 home directory on the remote machine. The authorized_keys file corre-
415 sponds to the conventional ~/.rhosts file, and has one key per line,
416 though the lines can be very long. After this, the user can log in with-
417 out giving the password.
418
419 The most convenient way to use public key authentication may be with an
420 authentication agent. See ssh-agent(1) for more information.
421
422 Challenge-response authentication works as follows: The server sends an
423 arbitrary "challenge" text, and prompts for a response. Protocol 2 al-
424 lows multiple challenges and responses; protocol 1 is restricted to just
425 one challenge/response. Examples of challenge-response authentication
426 include BSD Authentication (see login.conf(5)) and PAM (some non-OpenBSD
427 systems).
428
429 Finally, if other authentication methods fail, ssh prompts the user for a
430 password. The password is sent to the remote host for checking; however,
431 since all communications are encrypted, the password cannot be seen by
432 someone listening on the network.
433
434 ssh automatically maintains and checks a database containing identifica-
435 tion for all hosts it has ever been used with. Host keys are stored in
436 ~/.ssh/known_hosts in the user's home directory. Additionally, the file
437 /etc/ssh/ssh_known_hosts is automatically checked for known hosts. Any
438 new hosts are automatically added to the user's file. If a host's iden-
439 tification ever changes, ssh warns about this and disables password au-
440 thentication to prevent server spoofing or man-in-the-middle attacks,
441 which could otherwise be used to circumvent the encryption. The
442 StrictHostKeyChecking option can be used to control logins to machines
443 whose host key is not known or has changed.
444
445 When the user's identity has been accepted by the server, the server ei-
446 ther executes the given command, or logs into the machine and gives the
447 user a normal shell on the remote machine. All communication with the
448 remote command or shell will be automatically encrypted.
449
450 If a pseudo-terminal has been allocated (normal login session), the user
451 may use the escape characters noted below.
452
453 If no pseudo-tty has been allocated, the session is transparent and can
454 be used to reliably transfer binary data. On most systems, setting the
455 escape character to ``none'' will also make the session transparent even
456 if a tty is used.
457
458 The session terminates when the command or shell on the remote machine
459 exits and all X11 and TCP connections have been closed.
460
461ESCAPE CHARACTERS
462 When a pseudo-terminal has been requested, ssh supports a number of func-
463 tions through the use of an escape character.
464
465 A single tilde character can be sent as ~~ or by following the tilde by a
466 character other than those described below. The escape character must
467 always follow a newline to be interpreted as special. The escape charac-
468 ter can be changed in configuration files using the EscapeChar configura-
469 tion directive or on the command line by the -e option.
470
471 The supported escapes (assuming the default `~') are:
472
473 ~. Disconnect.
474
475 ~^Z Background ssh.
476
477 ~# List forwarded connections.
478
479 ~& Background ssh at logout when waiting for forwarded connection /
480 X11 sessions to terminate.
481
482 ~? Display a list of escape characters.
483
484 ~B Send a BREAK to the remote system (only useful for SSH protocol
485 version 2 and if the peer supports it).
486
487 ~C Open command line. Currently this allows the addition of port
488 forwardings using the -L and -R options (see above). It also al-
489 lows the cancellation of existing remote port-forwardings using
490 -KR hostport. !command allows the user to execute a local com-
491 mand if the PermitLocalCommand option is enabled in
492 ssh_config(5). Basic help is available, using the -h option.
493
494 ~R Request rekeying of the connection (only useful for SSH protocol
495 version 2 and if the peer supports it).
496
497TCP FORWARDING
498 Forwarding of arbitrary TCP connections over the secure channel can be
499 specified either on the command line or in a configuration file. One
500 possible application of TCP forwarding is a secure connection to a mail
501 server; another is going through firewalls.
502
503 In the example below, we look at encrypting communication between an IRC
504 client and server, even though the IRC server does not directly support
505 encrypted communications. This works as follows: the user connects to
506 the remote host using ssh, specifying a port to be used to forward con-
507 nections to the remote server. After that it is possible to start the
508 service which is to be encrypted on the client machine, connecting to the
509 same local port, and ssh will encrypt and forward the connection.
510
511 The following example tunnels an IRC session from client machine
512 ``127.0.0.1'' (localhost) to remote server ``server.example.com'':
513
514 $ ssh -f -L 1234:localhost:6667 server.example.com sleep 10
515 $ irc -c '#users' -p 1234 pinky 127.0.0.1
516
517 This tunnels a connection to IRC server ``server.example.com'', joining
518 channel ``#users'', nickname ``pinky'', using port 1234. It doesn't mat-
519 ter which port is used, as long as it's greater than 1023 (remember, only
520 root can open sockets on privileged ports) and doesn't conflict with any
521 ports already in use. The connection is forwarded to port 6667 on the
522 remote server, since that's the standard port for IRC services.
523
524 The -f option backgrounds ssh and the remote command ``sleep 10'' is
525 specified to allow an amount of time (10 seconds, in the example) to
526 start the service which is to be tunnelled. If no connections are made
527 within the time specified, ssh will exit.
528
529X11 FORWARDING
530 If the ForwardX11 variable is set to ``yes'' (or see the description of
531 the -X, -x, and -Y options above) and the user is using X11 (the DISPLAY
532 environment variable is set), the connection to the X11 display is auto-
533 matically forwarded to the remote side in such a way that any X11 pro-
534 grams started from the shell (or command) will go through the encrypted
535 channel, and the connection to the real X server will be made from the
536 local machine. The user should not manually set DISPLAY. Forwarding of
537 X11 connections can be configured on the command line or in configuration
538 files.
539
540 The DISPLAY value set by ssh will point to the server machine, but with a
541 display number greater than zero. This is normal, and happens because
542 ssh creates a ``proxy'' X server on the server machine for forwarding the
543 connections over the encrypted channel.
544
545 ssh will also automatically set up Xauthority data on the server machine.
546 For this purpose, it will generate a random authorization cookie, store
547 it in Xauthority on the server, and verify that any forwarded connections
548 carry this cookie and replace it by the real cookie when the connection
549 is opened. The real authentication cookie is never sent to the server
550 machine (and no cookies are sent in the plain).
551
552 If the ForwardAgent variable is set to ``yes'' (or see the description of
553 the -A and -a options above) and the user is using an authentication
554 agent, the connection to the agent is automatically forwarded to the re-
555 mote side.
556
557VERIFYING HOST KEYS
558 When connecting to a server for the first time, a fingerprint of the
559 server's public key is presented to the user (unless the option
560 StrictHostKeyChecking has been disabled). Fingerprints can be determined
561 using ssh-keygen(1):
562
563 $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key
564
565 If the fingerprint is already known, it can be matched and verified, and
566 the key can be accepted. If the fingerprint is unknown, an alternative
567 method of verification is available: SSH fingerprints verified by DNS.
568 An additional resource record (RR), SSHFP, is added to a zonefile and the
569 connecting client is able to match the fingerprint with that of the key
570 presented.
571
572 In this example, we are connecting a client to a server,
573 ``host.example.com''. The SSHFP resource records should first be added
574 to the zonefile for host.example.com:
518 575
519 DISPLAY The DISPLAY variable indicates the location of the X11 server. 576 $ ssh-keygen -f /etc/ssh/ssh_host_rsa_key.pub -r host.example.com.
520 It is automatically set by ssh to point to a value of the form 577 $ ssh-keygen -f /etc/ssh/ssh_host_dsa_key.pub -r host.example.com.
521 ``hostname:n'' where hostname indicates the host where the shell
522 runs, and n is an integer >= 1. ssh uses this special value to
523 forward X11 connections over the secure channel. The user
524 should normally not set DISPLAY explicitly, as that will render
525 the X11 connection insecure (and will require the user to manu-
526 ally copy any required authorization cookies).
527 578
528 HOME Set to the path of the user's home directory. 579 The output lines will have to be added to the zonefile. To check that
580 the zone is answering fingerprint queries:
529 581
530 LOGNAME Synonym for USER; set for compatibility with systems that use 582 $ dig -t SSHFP host.example.com
531 this variable.
532 583
533 MAIL Set to the path of the user's mailbox. 584 Finally the client connects:
534 585
535 PATH Set to the default PATH, as specified when compiling ssh. 586 $ ssh -o "VerifyHostKeyDNS ask" host.example.com
587 [...]
588 Matching host key fingerprint found in DNS.
589 Are you sure you want to continue connecting (yes/no)?
536 590
537 SSH_ASKPASS 591 See the VerifyHostKeyDNS option in ssh_config(5) for more information.
538 If ssh needs a passphrase, it will read the passphrase from the
539 current terminal if it was run from a terminal. If ssh does not
540 have a terminal associated with it but DISPLAY and SSH_ASKPASS
541 are set, it will execute the program specified by SSH_ASKPASS
542 and open an X11 window to read the passphrase. This is particu-
543 larly useful when calling ssh from a .xsession or related
544 script. (Note that on some machines it may be necessary to
545 redirect the input from /dev/null to make this work.)
546 592
547 SSH_AUTH_SOCK 593SSH-BASED VIRTUAL PRIVATE NETWORKS
548 Identifies the path of a unix-domain socket used to communicate 594 ssh contains support for Virtual Private Network (VPN) tunnelling using
549 with the agent. 595 the tun(4) network pseudo-device, allowing two networks to be joined se-
596 curely. The sshd_config(5) configuration option PermitTunnel controls
597 whether the server supports this, and at what level (layer 2 or 3 traf-
598 fic).
550 599
551 SSH_CONNECTION 600 The following example would connect client network 10.0.50.0/24 with re-
552 Identifies the client and server ends of the connection. The 601 mote network 10.0.99.0/24, provided that the SSH server running on the
553 variable contains four space-separated values: client ip-ad- 602 gateway to the remote network, at 192.168.1.15, allows it:
554 dress, client port number, server ip-address and server port
555 number.
556 603
557 SSH_ORIGINAL_COMMAND 604 # ssh -f -w 0:1 192.168.1.15 true
558 The variable contains the original command line if a forced com- 605 # ifconfig tun0 10.0.50.1 10.0.99.1 netmask 255.255.255.252
559 mand is executed. It can be used to extract the original argu-
560 ments.
561 606
562 SSH_TTY This is set to the name of the tty (path to the device) associ- 607 Client access may be more finely tuned via the /root/.ssh/authorized_keys
563 ated with the current shell or command. If the current session 608 file (see below) and the PermitRootLogin server option. The following
564 has no tty, this variable is not set. 609 entry would permit connections on the first tun(4) device from user
610 ``jane'' and on the second device from user ``john'', if PermitRootLogin
611 is set to ``forced-commands-only'':
565 612
566 TZ The timezone variable is set to indicate the present timezone if 613 tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane
567 it was set when the daemon was started (i.e., the daemon passes 614 tunnel="2",command="sh /etc/netstart tun1" ssh-rsa ... john
568 the value on to new connections).
569 615
570 USER Set to the name of the user logging in. 616 Since a SSH-based setup entails a fair amount of overhead, it may be more
617 suited to temporary setups, such as for wireless VPNs. More permanent
618 VPNs are better provided by tools such as ipsecctl(8) and isakmpd(8).
619
620ENVIRONMENT
621 ssh will normally set the following environment variables:
622
623 DISPLAY The DISPLAY variable indicates the location of the
624 X11 server. It is automatically set by ssh to
625 point to a value of the form ``hostname:n'', where
626 ``hostname'' indicates the host where the shell
627 runs, and `n' is an integer >= 1. ssh uses this
628 special value to forward X11 connections over the
629 secure channel. The user should normally not set
630 DISPLAY explicitly, as that will render the X11
631 connection insecure (and will require the user to
632 manually copy any required authorization cookies).
633
634 HOME Set to the path of the user's home directory.
635
636 LOGNAME Synonym for USER; set for compatibility with sys-
637 tems that use this variable.
638
639 MAIL Set to the path of the user's mailbox.
640
641 PATH Set to the default PATH, as specified when compil-
642 ing ssh.
643
644 SSH_ASKPASS If ssh needs a passphrase, it will read the
645 passphrase from the current terminal if it was run
646 from a terminal. If ssh does not have a terminal
647 associated with it but DISPLAY and SSH_ASKPASS are
648 set, it will execute the program specified by
649 SSH_ASKPASS and open an X11 window to read the
650 passphrase. This is particularly useful when call-
651 ing ssh from a .xsession or related script. (Note
652 that on some machines it may be necessary to redi-
653 rect the input from /dev/null to make this work.)
654
655 SSH_AUTH_SOCK Identifies the path of a UNIX-domain socket used to
656 communicate with the agent.
657
658 SSH_CONNECTION Identifies the client and server ends of the con-
659 nection. The variable contains four space-separat-
660 ed values: client IP address, client port number,
661 server IP address, and server port number.
662
663 SSH_ORIGINAL_COMMAND This variable contains the original command line if
664 a forced command is executed. It can be used to
665 extract the original arguments.
666
667 SSH_TTY This is set to the name of the tty (path to the de-
668 vice) associated with the current shell or command.
669 If the current session has no tty, this variable is
670 not set.
671
672 TZ This variable is set to indicate the present time
673 zone if it was set when the daemon was started
674 (i.e., the daemon passes the value on to new con-
675 nections).
676
677 USER Set to the name of the user logging in.
571 678
572 Additionally, ssh reads ~/.ssh/environment, and adds lines of the format 679 Additionally, ssh reads ~/.ssh/environment, and adds lines of the format
573 ``VARNAME=value'' to the environment if the file exists and if users are 680 ``VARNAME=value'' to the environment if the file exists and users are al-
574 allowed to change their environment. For more information, see the 681 lowed to change their environment. For more information, see the
575 PermitUserEnvironment option in sshd_config(5). 682 PermitUserEnvironment option in sshd_config(5).
576 683
577FILES 684FILES
578 ~/.ssh/known_hosts 685 ~/.rhosts
579 Records host keys for all hosts the user has logged into that are 686 This file is used for host-based authentication (see above). On
580 not in /etc/ssh/ssh_known_hosts. See sshd(8). 687 some machines this file may need to be world-readable if the us-
581 688 er's home directory is on an NFS partition, because sshd(8) reads
582 ~/.ssh/identity, ~/.ssh/id_dsa, ~/.ssh/id_rsa 689 it as root. Additionally, this file must be owned by the user,
583 Contains the authentication identity of the user. They are for 690 and must not have write permissions for anyone else. The recom-
584 protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively. 691 mended permission for most machines is read/write for the user,
585 These files contain sensitive data and should be readable by the 692 and not accessible by others.
586 user but not accessible by others (read/write/execute). Note 693
587 that ssh ignores a private key file if it is accessible by oth- 694 ~/.shosts
588 ers. It is possible to specify a passphrase when generating the 695 This file is used in exactly the same way as .rhosts, but allows
589 key; the passphrase will be used to encrypt the sensitive part of 696 host-based authentication without permitting login with
590 this file using 3DES. 697 rlogin/rsh.
591 698
592 ~/.ssh/identity.pub, ~/.ssh/id_dsa.pub, ~/.ssh/id_rsa.pub 699 ~/.ssh/authorized_keys
593 Contains the public key for authentication (public part of the 700 Lists the public keys (RSA/DSA) that can be used for logging in
594 identity file in human-readable form). The contents of the 701 as this user. The format of this file is described in the
595 ~/.ssh/identity.pub file should be added to the file 702 sshd(8) manual page. This file is not highly sensitive, but the
596 ~/.ssh/authorized_keys on all machines where the user wishes to 703 recommended permissions are read/write for the user, and not ac-
597 log in using protocol version 1 RSA authentication. The contents 704 cessible by others.
598 of the ~/.ssh/id_dsa.pub and ~/.ssh/id_rsa.pub file should be
599 added to ~/.ssh/authorized_keys on all machines where the user
600 wishes to log in using protocol version 2 DSA/RSA authentication.
601 These files are not sensitive and can (but need not) be readable
602 by anyone. These files are never used automatically and are not
603 necessary; they are only provided for the convenience of the us-
604 er.
605 705
606 ~/.ssh/config 706 ~/.ssh/config
607 This is the per-user configuration file. The file format and 707 This is the per-user configuration file. The file format and
@@ -609,112 +709,75 @@ FILES
609 the potential for abuse, this file must have strict permissions: 709 the potential for abuse, this file must have strict permissions:
610 read/write for the user, and not accessible by others. 710 read/write for the user, and not accessible by others.
611 711
612 ~/.ssh/authorized_keys 712 ~/.ssh/environment
613 Lists the public keys (RSA/DSA) that can be used for logging in 713 Contains additional definitions for environment variables; see
614 as this user. The format of this file is described in the 714 ENVIRONMENT, above.
615 sshd(8) manual page. In the simplest form the format is the same 715
616 as the .pub identity files. This file is not highly sensitive, 716 ~/.ssh/identity
617 but the recommended permissions are read/write for the user, and 717 ~/.ssh/id_dsa
618 not accessible by others. 718 ~/.ssh/id_rsa
719 Contains the private key for authentication. These files contain
720 sensitive data and should be readable by the user but not acces-
721 sible by others (read/write/execute). ssh will simply ignore a
722 private key file if it is accessible by others. It is possible
723 to specify a passphrase when generating the key which will be
724 used to encrypt the sensitive part of this file using 3DES.
725
726 ~/.ssh/identity.pub
727 ~/.ssh/id_dsa.pub
728 ~/.ssh/id_rsa.pub
729 Contains the public key for authentication. These files are not
730 sensitive and can (but need not) be readable by anyone.
619 731
620 /etc/ssh/ssh_known_hosts 732 ~/.ssh/known_hosts
621 Systemwide list of known host keys. This file should be prepared 733 Contains a list of host keys for all hosts the user has logged
622 by the system administrator to contain the public host keys of 734 into that are not already in the systemwide list of known host
623 all machines in the organization. This file should be world- 735 keys. See sshd(8) for further details of the format of this
624 readable. This file contains public keys, one per line, in the 736 file.
625 following format (fields separated by spaces): system name, pub- 737
626 lic key and optional comment field. When different names are 738 ~/.ssh/rc
627 used for the same machine, all such names should be listed, sepa- 739 Commands in this file are executed by ssh when the user logs in,
628 rated by commas. The format is described in the sshd(8) manual 740 just before the user's shell (or command) is started. See the
629 page. 741 sshd(8) manual page for more information.
630 742
631 The canonical system name (as returned by name servers) is used 743 /etc/hosts.equiv
632 by sshd(8) to verify the client host when logging in; other names 744 This file is for host-based authentication (see above). It
633 are needed because ssh does not convert the user-supplied name to 745 should only be writable by root.
634 a canonical name before checking the key, because someone with 746
635 access to the name servers would then be able to fool host au- 747 /etc/shosts.equiv
636 thentication. 748 This file is used in exactly the same way as hosts.equiv, but al-
749 lows host-based authentication without permitting login with
750 rlogin/rsh.
637 751
638 /etc/ssh/ssh_config 752 /etc/ssh/ssh_config
639 Systemwide configuration file. The file format and configuration 753 Systemwide configuration file. The file format and configuration
640 options are described in ssh_config(5). 754 options are described in ssh_config(5).
641 755
642 /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, 756 /etc/ssh/ssh_host_key
643 /etc/ssh/ssh_host_rsa_key 757 /etc/ssh/ssh_host_dsa_key
758 /etc/ssh/ssh_host_rsa_key
644 These three files contain the private parts of the host keys and 759 These three files contain the private parts of the host keys and
645 are used for RhostsRSAAuthentication and HostbasedAuthentication. 760 are used for host-based authentication. If protocol version 1 is
646 If the protocol version 1 RhostsRSAAuthentication method is used, 761 used, ssh must be setuid root, since the host key is readable on-
647 ssh must be setuid root, since the host key is readable only by 762 ly by root. For protocol version 2, ssh uses ssh-keysign(8) to
648 root. For protocol version 2, ssh uses ssh-keysign(8) to access 763 access the host keys, eliminating the requirement that ssh be se-
649 the host keys for HostbasedAuthentication. This eliminates the 764 tuid root when host-based authentication is used. By default ssh
650 requirement that ssh be setuid root when that authentication 765 is not setuid root.
651 method is used. By default ssh is not setuid root.
652 766
653 ~/.rhosts 767 /etc/ssh/ssh_known_hosts
654 This file is used in RhostsRSAAuthentication and 768 Systemwide list of known host keys. This file should be prepared
655 HostbasedAuthentication authentication to list the host/user 769 by the system administrator to contain the public host keys of
656 pairs that are permitted to log in. (Note that this file is also 770 all machines in the organization. It should be world-readable.
657 used by rlogin and rsh, which makes using this file insecure.) 771 See sshd(8) for further details of the format of this file.
658 Each line of the file contains a host name (in the canonical form
659 returned by name servers), and then a user name on that host,
660 separated by a space. On some machines this file may need to be
661 world-readable if the user's home directory is on a NFS parti-
662 tion, because sshd(8) reads it as root. Additionally, this file
663 must be owned by the user, and must not have write permissions
664 for anyone else. The recommended permission for most machines is
665 read/write for the user, and not accessible by others.
666
667 Note that sshd(8) allows authentication only in combination with
668 client host key authentication before permitting log in. If the
669 server machine does not have the client's host key in
670 /etc/ssh/ssh_known_hosts, it can be stored in ~/.ssh/known_hosts.
671 The easiest way to do this is to connect back to the client from
672 the server machine using ssh; this will automatically add the
673 host key to ~/.ssh/known_hosts.
674
675 ~/.shosts
676 This file is used exactly the same way as .rhosts. The purpose
677 for having this file is to be able to use RhostsRSAAuthentication
678 and HostbasedAuthentication authentication without permitting lo-
679 gin with rlogin or rsh(1).
680
681 /etc/hosts.equiv
682 This file is used during RhostsRSAAuthentication and
683 HostbasedAuthentication authentication. It contains canonical
684 hosts names, one per line (the full format is described in the
685 sshd(8) manual page). If the client host is found in this file,
686 login is automatically permitted provided client and server user
687 names are the same. Additionally, successful client host key au-
688 thentication is required. This file should only be writable by
689 root.
690
691 /etc/shosts.equiv
692 This file is processed exactly as /etc/hosts.equiv. This file
693 may be useful to permit logins using ssh but not using
694 rsh/rlogin.
695 772
696 /etc/ssh/sshrc 773 /etc/ssh/sshrc
697 Commands in this file are executed by ssh when the user logs in 774 Commands in this file are executed by ssh when the user logs in,
698 just before the user's shell (or command) is started. See the
699 sshd(8) manual page for more information.
700
701 ~/.ssh/rc
702 Commands in this file are executed by ssh when the user logs in
703 just before the user's shell (or command) is started. See the 775 just before the user's shell (or command) is started. See the
704 sshd(8) manual page for more information. 776 sshd(8) manual page for more information.
705 777
706 ~/.ssh/environment
707 Contains additional definitions for environment variables, see
708 section ENVIRONMENT above.
709
710DIAGNOSTICS
711 ssh exits with the exit status of the remote command or with 255 if an
712 error occurred.
713
714SEE ALSO 778SEE ALSO
715 gzip(1), rsh(1), scp(1), sftp(1), ssh-add(1), ssh-agent(1), 779 scp(1), sftp(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), ssh-keyscan(1),
716 ssh-keygen(1), telnet(1), hosts.equiv(5), ssh_config(5), ssh-keysign(8), 780 tun(4), hosts.equiv(5), ssh_config(5), ssh-keysign(8), sshd(8)
717 sshd(8)
718 781
719 T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne, and S. Lehtinen, SSH 782 T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne, and S. Lehtinen, SSH
720 Protocol Architecture, draft-ietf-secsh-architecture-12.txt, January 783 Protocol Architecture, draft-ietf-secsh-architecture-12.txt, January
@@ -727,4 +790,4 @@ AUTHORS
727 created OpenSSH. Markus Friedl contributed the support for SSH protocol 790 created OpenSSH. Markus Friedl contributed the support for SSH protocol
728 versions 1.5 and 2.0. 791 versions 1.5 and 2.0.
729 792
730OpenBSD 3.8 September 25, 1999 12 793OpenBSD 3.9 September 25, 1999 12
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-02 17:04:18 +0000