diff options
Diffstat (limited to 'ssh.0')
-rw-r--r-- | ssh.0 | 946 |
1 files changed, 946 insertions, 0 deletions
@@ -0,0 +1,946 @@ | |||
1 | SSH(1) OpenBSD Reference Manual SSH(1) | ||
2 | |||
3 | NAME | ||
4 | ssh - OpenSSH SSH client (remote login program) | ||
5 | |||
6 | SYNOPSIS | ||
7 | ssh [-1246AaCfgKkMNnqsTtVvXxYy] [-b bind_address] [-c cipher_spec] | ||
8 | [-D [bind_address:]port] [-E log_file] [-e escape_char] | ||
9 | [-F configfile] [-I pkcs11] [-i identity_file] | ||
10 | [-L [bind_address:]port:host:hostport] [-l login_name] [-m mac_spec] | ||
11 | [-O ctl_cmd] [-o option] [-p port] | ||
12 | [-Q cipher | cipher-auth | mac | kex | key] | ||
13 | [-R [bind_address:]port:host:hostport] [-S ctl_path] [-W host:port] | ||
14 | [-w local_tun[:remote_tun]] [user@]hostname [command] | ||
15 | |||
16 | DESCRIPTION | ||
17 | ssh (SSH client) is a program for logging into a remote machine and for | ||
18 | executing commands on a remote machine. It is intended to replace rlogin | ||
19 | and rsh, and provide secure encrypted communications between two | ||
20 | untrusted hosts over an insecure network. X11 connections and arbitrary | ||
21 | TCP ports can also be forwarded over the secure channel. | ||
22 | |||
23 | ssh connects and logs into the specified hostname (with optional user | ||
24 | name). The user must prove his/her identity to the remote machine using | ||
25 | one of several methods depending on the protocol version used (see | ||
26 | below). | ||
27 | |||
28 | If command is specified, it is executed on the remote host instead of a | ||
29 | login shell. | ||
30 | |||
31 | The options are as follows: | ||
32 | |||
33 | -1 Forces ssh to try protocol version 1 only. | ||
34 | |||
35 | -2 Forces ssh to try protocol version 2 only. | ||
36 | |||
37 | -4 Forces ssh to use IPv4 addresses only. | ||
38 | |||
39 | -6 Forces ssh to use IPv6 addresses only. | ||
40 | |||
41 | -A Enables forwarding of the authentication agent connection. This | ||
42 | can also be specified on a per-host basis in a configuration | ||
43 | file. | ||
44 | |||
45 | Agent forwarding should be enabled with caution. Users with the | ||
46 | ability to bypass file permissions on the remote host (for the | ||
47 | agent's UNIX-domain socket) can access the local agent through | ||
48 | the forwarded connection. An attacker cannot obtain key material | ||
49 | from the agent, however they can perform operations on the keys | ||
50 | that enable them to authenticate using the identities loaded into | ||
51 | the agent. | ||
52 | |||
53 | -a Disables forwarding of the authentication agent connection. | ||
54 | |||
55 | -b bind_address | ||
56 | Use bind_address on the local machine as the source address of | ||
57 | the connection. Only useful on systems with more than one | ||
58 | address. | ||
59 | |||
60 | -C Requests compression of all data (including stdin, stdout, | ||
61 | stderr, and data for forwarded X11 and TCP connections). The | ||
62 | compression algorithm is the same used by gzip(1), and the | ||
63 | ``level'' can be controlled by the CompressionLevel option for | ||
64 | protocol version 1. Compression is desirable on modem lines and | ||
65 | other slow connections, but will only slow down things on fast | ||
66 | networks. The default value can be set on a host-by-host basis | ||
67 | in the configuration files; see the Compression option. | ||
68 | |||
69 | -c cipher_spec | ||
70 | Selects the cipher specification for encrypting the session. | ||
71 | |||
72 | Protocol version 1 allows specification of a single cipher. The | ||
73 | supported values are ``3des'', ``blowfish'', and ``des''. 3des | ||
74 | (triple-des) is an encrypt-decrypt-encrypt triple with three | ||
75 | different keys. It is believed to be secure. blowfish is a fast | ||
76 | block cipher; it appears very secure and is much faster than | ||
77 | 3des. des is only supported in the ssh client for | ||
78 | interoperability with legacy protocol 1 implementations that do | ||
79 | not support the 3des cipher. Its use is strongly discouraged due | ||
80 | to cryptographic weaknesses. The default is ``3des''. | ||
81 | |||
82 | For protocol version 2, cipher_spec is a comma-separated list of | ||
83 | ciphers listed in order of preference. See the Ciphers keyword | ||
84 | in ssh_config(5) for more information. | ||
85 | |||
86 | -D [bind_address:]port | ||
87 | Specifies a local ``dynamic'' application-level port forwarding. | ||
88 | This works by allocating a socket to listen to port on the local | ||
89 | side, optionally bound to the specified bind_address. Whenever a | ||
90 | connection is made to this port, the connection is forwarded over | ||
91 | the secure channel, and the application protocol is then used to | ||
92 | determine where to connect to from the remote machine. Currently | ||
93 | the SOCKS4 and SOCKS5 protocols are supported, and ssh will act | ||
94 | as a SOCKS server. Only root can forward privileged ports. | ||
95 | Dynamic port forwardings can also be specified in the | ||
96 | configuration file. | ||
97 | |||
98 | IPv6 addresses can be specified by enclosing the address in | ||
99 | square brackets. Only the superuser can forward privileged | ||
100 | ports. By default, the local port is bound in accordance with | ||
101 | the GatewayPorts setting. However, an explicit bind_address may | ||
102 | be used to bind the connection to a specific address. The | ||
103 | bind_address of ``localhost'' indicates that the listening port | ||
104 | be bound for local use only, while an empty address or `*' | ||
105 | indicates that the port should be available from all interfaces. | ||
106 | |||
107 | -E log_file | ||
108 | Append debug logs to log_file instead of standard error. | ||
109 | |||
110 | -e escape_char | ||
111 | Sets the escape character for sessions with a pty (default: `~'). | ||
112 | The escape character is only recognized at the beginning of a | ||
113 | line. The escape character followed by a dot (`.') closes the | ||
114 | connection; followed by control-Z suspends the connection; and | ||
115 | followed by itself sends the escape character once. Setting the | ||
116 | character to ``none'' disables any escapes and makes the session | ||
117 | fully transparent. | ||
118 | |||
119 | -F configfile | ||
120 | Specifies an alternative per-user configuration file. If a | ||
121 | configuration file is given on the command line, the system-wide | ||
122 | configuration file (/etc/ssh/ssh_config) will be ignored. The | ||
123 | default for the per-user configuration file is ~/.ssh/config. | ||
124 | |||
125 | -f Requests ssh to go to background just before command execution. | ||
126 | This is useful if ssh is going to ask for passwords or | ||
127 | passphrases, but the user wants it in the background. This | ||
128 | implies -n. The recommended way to start X11 programs at a | ||
129 | remote site is with something like ssh -f host xterm. | ||
130 | |||
131 | If the ExitOnForwardFailure configuration option is set to | ||
132 | ``yes'', then a client started with -f will wait for all remote | ||
133 | port forwards to be successfully established before placing | ||
134 | itself in the background. | ||
135 | |||
136 | -g Allows remote hosts to connect to local forwarded ports. | ||
137 | |||
138 | -I pkcs11 | ||
139 | Specify the PKCS#11 shared library ssh should use to communicate | ||
140 | with a PKCS#11 token providing the user's private RSA key. | ||
141 | |||
142 | -i identity_file | ||
143 | Selects a file from which the identity (private key) for public | ||
144 | key authentication is read. The default is ~/.ssh/identity for | ||
145 | protocol version 1, and ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, | ||
146 | ~/.ssh/id_ed25519 and ~/.ssh/id_rsa for protocol version 2. | ||
147 | Identity files may also be specified on a per-host basis in the | ||
148 | configuration file. It is possible to have multiple -i options | ||
149 | (and multiple identities specified in configuration files). ssh | ||
150 | will also try to load certificate information from the filename | ||
151 | obtained by appending -cert.pub to identity filenames. | ||
152 | |||
153 | -K Enables GSSAPI-based authentication and forwarding (delegation) | ||
154 | of GSSAPI credentials to the server. | ||
155 | |||
156 | -k Disables forwarding (delegation) of GSSAPI credentials to the | ||
157 | server. | ||
158 | |||
159 | -L [bind_address:]port:host:hostport | ||
160 | Specifies that the given port on the local (client) host is to be | ||
161 | forwarded to the given host and port on the remote side. This | ||
162 | works by allocating a socket to listen to port on the local side, | ||
163 | optionally bound to the specified bind_address. Whenever a | ||
164 | connection is made to this port, the connection is forwarded over | ||
165 | the secure channel, and a connection is made to host port | ||
166 | hostport from the remote machine. Port forwardings can also be | ||
167 | specified in the configuration file. IPv6 addresses can be | ||
168 | specified by enclosing the address in square brackets. Only the | ||
169 | superuser can forward privileged ports. By default, the local | ||
170 | port is bound in accordance with the GatewayPorts setting. | ||
171 | However, an explicit bind_address may be used to bind the | ||
172 | connection to a specific address. The bind_address of | ||
173 | ``localhost'' indicates that the listening port be bound for | ||
174 | local use only, while an empty address or `*' indicates that the | ||
175 | port should be available from all interfaces. | ||
176 | |||
177 | -l login_name | ||
178 | Specifies the user to log in as on the remote machine. This also | ||
179 | may be specified on a per-host basis in the configuration file. | ||
180 | |||
181 | -M Places the ssh client into ``master'' mode for connection | ||
182 | sharing. Multiple -M options places ssh into ``master'' mode | ||
183 | with confirmation required before slave connections are accepted. | ||
184 | Refer to the description of ControlMaster in ssh_config(5) for | ||
185 | details. | ||
186 | |||
187 | -m mac_spec | ||
188 | Additionally, for protocol version 2 a comma-separated list of | ||
189 | MAC (message authentication code) algorithms can be specified in | ||
190 | order of preference. See the MACs keyword for more information. | ||
191 | |||
192 | -N Do not execute a remote command. This is useful for just | ||
193 | forwarding ports (protocol version 2 only). | ||
194 | |||
195 | -n Redirects stdin from /dev/null (actually, prevents reading from | ||
196 | stdin). This must be used when ssh is run in the background. A | ||
197 | common trick is to use this to run X11 programs on a remote | ||
198 | machine. For example, ssh -n shadows.cs.hut.fi emacs & will | ||
199 | start an emacs on shadows.cs.hut.fi, and the X11 connection will | ||
200 | be automatically forwarded over an encrypted channel. The ssh | ||
201 | program will be put in the background. (This does not work if | ||
202 | ssh needs to ask for a password or passphrase; see also the -f | ||
203 | option.) | ||
204 | |||
205 | -O ctl_cmd | ||
206 | Control an active connection multiplexing master process. When | ||
207 | the -O option is specified, the ctl_cmd argument is interpreted | ||
208 | and passed to the master process. Valid commands are: ``check'' | ||
209 | (check that the master process is running), ``forward'' (request | ||
210 | forwardings without command execution), ``cancel'' (cancel | ||
211 | forwardings), ``exit'' (request the master to exit), and ``stop'' | ||
212 | (request the master to stop accepting further multiplexing | ||
213 | requests). | ||
214 | |||
215 | -o option | ||
216 | Can be used to give options in the format used in the | ||
217 | configuration file. This is useful for specifying options for | ||
218 | which there is no separate command-line flag. For full details | ||
219 | of the options listed below, and their possible values, see | ||
220 | ssh_config(5). | ||
221 | |||
222 | AddressFamily | ||
223 | BatchMode | ||
224 | BindAddress | ||
225 | CanonicalDomains | ||
226 | CanonicalizeFallbackLocal | ||
227 | CanonicalizeHostname | ||
228 | CanonicalizeMaxDots | ||
229 | CanonicalizePermittedCNAMEs | ||
230 | ChallengeResponseAuthentication | ||
231 | CheckHostIP | ||
232 | Cipher | ||
233 | Ciphers | ||
234 | ClearAllForwardings | ||
235 | Compression | ||
236 | CompressionLevel | ||
237 | ConnectionAttempts | ||
238 | ConnectTimeout | ||
239 | ControlMaster | ||
240 | ControlPath | ||
241 | ControlPersist | ||
242 | DynamicForward | ||
243 | EscapeChar | ||
244 | ExitOnForwardFailure | ||
245 | ForwardAgent | ||
246 | ForwardX11 | ||
247 | ForwardX11Timeout | ||
248 | ForwardX11Trusted | ||
249 | GatewayPorts | ||
250 | GlobalKnownHostsFile | ||
251 | GSSAPIAuthentication | ||
252 | GSSAPIDelegateCredentials | ||
253 | HashKnownHosts | ||
254 | Host | ||
255 | HostbasedAuthentication | ||
256 | HostKeyAlgorithms | ||
257 | HostKeyAlias | ||
258 | HostName | ||
259 | IdentityFile | ||
260 | IdentitiesOnly | ||
261 | IPQoS | ||
262 | KbdInteractiveAuthentication | ||
263 | KbdInteractiveDevices | ||
264 | KexAlgorithms | ||
265 | LocalCommand | ||
266 | LocalForward | ||
267 | LogLevel | ||
268 | MACs | ||
269 | Match | ||
270 | NoHostAuthenticationForLocalhost | ||
271 | NumberOfPasswordPrompts | ||
272 | PasswordAuthentication | ||
273 | PermitLocalCommand | ||
274 | PKCS11Provider | ||
275 | Port | ||
276 | PreferredAuthentications | ||
277 | Protocol | ||
278 | ProxyCommand | ||
279 | ProxyUseFdpass | ||
280 | PubkeyAuthentication | ||
281 | RekeyLimit | ||
282 | RemoteForward | ||
283 | RequestTTY | ||
284 | RhostsRSAAuthentication | ||
285 | RSAAuthentication | ||
286 | SendEnv | ||
287 | ServerAliveInterval | ||
288 | ServerAliveCountMax | ||
289 | StrictHostKeyChecking | ||
290 | TCPKeepAlive | ||
291 | Tunnel | ||
292 | TunnelDevice | ||
293 | UsePrivilegedPort | ||
294 | User | ||
295 | UserKnownHostsFile | ||
296 | VerifyHostKeyDNS | ||
297 | VisualHostKey | ||
298 | XAuthLocation | ||
299 | |||
300 | -p port | ||
301 | Port to connect to on the remote host. This can be specified on | ||
302 | a per-host basis in the configuration file. | ||
303 | |||
304 | -Q cipher | cipher-auth | mac | kex | key | ||
305 | Queries ssh for the algorithms supported for the specified | ||
306 | version 2. The available features are: cipher (supported | ||
307 | symmetric ciphers), cipher-auth (supported symmetric ciphers that | ||
308 | support authenticated encryption), mac (supported message | ||
309 | integrity codes), kex (key exchange algorithms), key (key types). | ||
310 | |||
311 | -q Quiet mode. Causes most warning and diagnostic messages to be | ||
312 | suppressed. | ||
313 | |||
314 | -R [bind_address:]port:host:hostport | ||
315 | Specifies that the given port on the remote (server) host is to | ||
316 | be forwarded to the given host and port on the local side. This | ||
317 | works by allocating a socket to listen to port on the remote | ||
318 | side, and whenever a connection is made to this port, the | ||
319 | connection is forwarded over the secure channel, and a connection | ||
320 | is made to host port hostport from the local machine. | ||
321 | |||
322 | Port forwardings can also be specified in the configuration file. | ||
323 | Privileged ports can be forwarded only when logging in as root on | ||
324 | the remote machine. IPv6 addresses can be specified by enclosing | ||
325 | the address in square brackets. | ||
326 | |||
327 | By default, the listening socket on the server will be bound to | ||
328 | the loopback interface only. This may be overridden by | ||
329 | specifying a bind_address. An empty bind_address, or the address | ||
330 | `*', indicates that the remote socket should listen on all | ||
331 | interfaces. Specifying a remote bind_address will only succeed | ||
332 | if the server's GatewayPorts option is enabled (see | ||
333 | sshd_config(5)). | ||
334 | |||
335 | If the port argument is `0', the listen port will be dynamically | ||
336 | allocated on the server and reported to the client at run time. | ||
337 | When used together with -O forward the allocated port will be | ||
338 | printed to the standard output. | ||
339 | |||
340 | -S ctl_path | ||
341 | Specifies the location of a control socket for connection | ||
342 | sharing, or the string ``none'' to disable connection sharing. | ||
343 | Refer to the description of ControlPath and ControlMaster in | ||
344 | ssh_config(5) for details. | ||
345 | |||
346 | -s May be used to request invocation of a subsystem on the remote | ||
347 | system. Subsystems are a feature of the SSH2 protocol which | ||
348 | facilitate the use of SSH as a secure transport for other | ||
349 | applications (eg. sftp(1)). The subsystem is specified as the | ||
350 | remote command. | ||
351 | |||
352 | -T Disable pseudo-tty allocation. | ||
353 | |||
354 | -t Force pseudo-tty allocation. This can be used to execute | ||
355 | arbitrary screen-based programs on a remote machine, which can be | ||
356 | very useful, e.g. when implementing menu services. Multiple -t | ||
357 | options force tty allocation, even if ssh has no local tty. | ||
358 | |||
359 | -V Display the version number and exit. | ||
360 | |||
361 | -v Verbose mode. Causes ssh to print debugging messages about its | ||
362 | progress. This is helpful in debugging connection, | ||
363 | authentication, and configuration problems. Multiple -v options | ||
364 | increase the verbosity. The maximum is 3. | ||
365 | |||
366 | -W host:port | ||
367 | Requests that standard input and output on the client be | ||
368 | forwarded to host on port over the secure channel. Implies -N, | ||
369 | -T, ExitOnForwardFailure and ClearAllForwardings. Works with | ||
370 | Protocol version 2 only. | ||
371 | |||
372 | -w local_tun[:remote_tun] | ||
373 | Requests tunnel device forwarding with the specified tun(4) | ||
374 | devices between the client (local_tun) and the server | ||
375 | (remote_tun). | ||
376 | |||
377 | The devices may be specified by numerical ID or the keyword | ||
378 | ``any'', which uses the next available tunnel device. If | ||
379 | remote_tun is not specified, it defaults to ``any''. See also | ||
380 | the Tunnel and TunnelDevice directives in ssh_config(5). If the | ||
381 | Tunnel directive is unset, it is set to the default tunnel mode, | ||
382 | which is ``point-to-point''. | ||
383 | |||
384 | -X Enables X11 forwarding. This can also be specified on a per-host | ||
385 | basis in a configuration file. | ||
386 | |||
387 | X11 forwarding should be enabled with caution. Users with the | ||
388 | ability to bypass file permissions on the remote host (for the | ||
389 | user's X authorization database) can access the local X11 display | ||
390 | through the forwarded connection. An attacker may then be able | ||
391 | to perform activities such as keystroke monitoring. | ||
392 | |||
393 | For this reason, X11 forwarding is subjected to X11 SECURITY | ||
394 | extension restrictions by default. Please refer to the ssh -Y | ||
395 | option and the ForwardX11Trusted directive in ssh_config(5) for | ||
396 | more information. | ||
397 | |||
398 | -x Disables X11 forwarding. | ||
399 | |||
400 | -Y Enables trusted X11 forwarding. Trusted X11 forwardings are not | ||
401 | subjected to the X11 SECURITY extension controls. | ||
402 | |||
403 | -y Send log information using the syslog(3) system module. By | ||
404 | default this information is sent to stderr. | ||
405 | |||
406 | ssh may additionally obtain configuration data from a per-user | ||
407 | configuration file and a system-wide configuration file. The file format | ||
408 | and configuration options are described in ssh_config(5). | ||
409 | |||
410 | AUTHENTICATION | ||
411 | The OpenSSH SSH client supports SSH protocols 1 and 2. The default is to | ||
412 | use protocol 2 only, though this can be changed via the Protocol option | ||
413 | in ssh_config(5) or the -1 and -2 options (see above). Both protocols | ||
414 | support similar authentication methods, but protocol 2 is the default | ||
415 | since it provides additional mechanisms for confidentiality (the traffic | ||
416 | is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour) and | ||
417 | integrity (hmac-md5, hmac-sha1, hmac-sha2-256, hmac-sha2-512, umac-64, | ||
418 | umac-128, hmac-ripemd160). Protocol 1 lacks a strong mechanism for | ||
419 | ensuring the integrity of the connection. | ||
420 | |||
421 | The methods available for authentication are: GSSAPI-based | ||
422 | authentication, host-based authentication, public key authentication, | ||
423 | challenge-response authentication, and password authentication. | ||
424 | Authentication methods are tried in the order specified above, though | ||
425 | protocol 2 has a configuration option to change the default order: | ||
426 | PreferredAuthentications. | ||
427 | |||
428 | Host-based authentication works as follows: If the machine the user logs | ||
429 | in from is listed in /etc/hosts.equiv or /etc/shosts.equiv on the remote | ||
430 | machine, and the user names are the same on both sides, or if the files | ||
431 | ~/.rhosts or ~/.shosts exist in the user's home directory on the remote | ||
432 | machine and contain a line containing the name of the client machine and | ||
433 | the name of the user on that machine, the user is considered for login. | ||
434 | Additionally, the server must be able to verify the client's host key | ||
435 | (see the description of /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts, | ||
436 | below) for login to be permitted. This authentication method closes | ||
437 | security holes due to IP spoofing, DNS spoofing, and routing spoofing. | ||
438 | [Note to the administrator: /etc/hosts.equiv, ~/.rhosts, and the | ||
439 | rlogin/rsh protocol in general, are inherently insecure and should be | ||
440 | disabled if security is desired.] | ||
441 | |||
442 | Public key authentication works as follows: The scheme is based on | ||
443 | public-key cryptography, using cryptosystems where encryption and | ||
444 | decryption are done using separate keys, and it is unfeasible to derive | ||
445 | the decryption key from the encryption key. The idea is that each user | ||
446 | creates a public/private key pair for authentication purposes. The | ||
447 | server knows the public key, and only the user knows the private key. | ||
448 | ssh implements public key authentication protocol automatically, using | ||
449 | one of the DSA, ECDSA, ED25519 or RSA algorithms. Protocol 1 is | ||
450 | restricted to using only RSA keys, but protocol 2 may use any. The | ||
451 | HISTORY section of ssl(8) contains a brief discussion of the DSA and RSA | ||
452 | algorithms. | ||
453 | |||
454 | The file ~/.ssh/authorized_keys lists the public keys that are permitted | ||
455 | for logging in. When the user logs in, the ssh program tells the server | ||
456 | which key pair it would like to use for authentication. The client | ||
457 | proves that it has access to the private key and the server checks that | ||
458 | the corresponding public key is authorized to accept the account. | ||
459 | |||
460 | The user creates his/her key pair by running ssh-keygen(1). This stores | ||
461 | the private key in ~/.ssh/identity (protocol 1), ~/.ssh/id_dsa (protocol | ||
462 | 2 DSA), ~/.ssh/id_ecdsa (protocol 2 ECDSA), ~/.ssh/id_ed25519 (protocol 2 | ||
463 | ED25519), or ~/.ssh/id_rsa (protocol 2 RSA) and stores the public key in | ||
464 | ~/.ssh/identity.pub (protocol 1), ~/.ssh/id_dsa.pub (protocol 2 DSA), | ||
465 | ~/.ssh/id_ecdsa.pub (protocol 2 ECDSA), ~/.ssh/id_ed25519.pub (protocol 2 | ||
466 | ED25519), or ~/.ssh/id_rsa.pub (protocol 2 RSA) in the user's home | ||
467 | directory. The user should then copy the public key to | ||
468 | ~/.ssh/authorized_keys in his/her home directory on the remote machine. | ||
469 | The authorized_keys file corresponds to the conventional ~/.rhosts file, | ||
470 | and has one key per line, though the lines can be very long. After this, | ||
471 | the user can log in without giving the password. | ||
472 | |||
473 | A variation on public key authentication is available in the form of | ||
474 | certificate authentication: instead of a set of public/private keys, | ||
475 | signed certificates are used. This has the advantage that a single | ||
476 | trusted certification authority can be used in place of many | ||
477 | public/private keys. See the CERTIFICATES section of ssh-keygen(1) for | ||
478 | more information. | ||
479 | |||
480 | The most convenient way to use public key or certificate authentication | ||
481 | may be with an authentication agent. See ssh-agent(1) for more | ||
482 | information. | ||
483 | |||
484 | Challenge-response authentication works as follows: The server sends an | ||
485 | arbitrary "challenge" text, and prompts for a response. Protocol 2 | ||
486 | allows multiple challenges and responses; protocol 1 is restricted to | ||
487 | just one challenge/response. Examples of challenge-response | ||
488 | authentication include BSD Authentication (see login.conf(5)) and PAM | ||
489 | (some non-OpenBSD systems). | ||
490 | |||
491 | Finally, if other authentication methods fail, ssh prompts the user for a | ||
492 | password. The password is sent to the remote host for checking; however, | ||
493 | since all communications are encrypted, the password cannot be seen by | ||
494 | someone listening on the network. | ||
495 | |||
496 | ssh automatically maintains and checks a database containing | ||
497 | identification for all hosts it has ever been used with. Host keys are | ||
498 | stored in ~/.ssh/known_hosts in the user's home directory. Additionally, | ||
499 | the file /etc/ssh/ssh_known_hosts is automatically checked for known | ||
500 | hosts. Any new hosts are automatically added to the user's file. If a | ||
501 | host's identification ever changes, ssh warns about this and disables | ||
502 | password authentication to prevent server spoofing or man-in-the-middle | ||
503 | attacks, which could otherwise be used to circumvent the encryption. The | ||
504 | StrictHostKeyChecking option can be used to control logins to machines | ||
505 | whose host key is not known or has changed. | ||
506 | |||
507 | When the user's identity has been accepted by the server, the server | ||
508 | either executes the given command, or logs into the machine and gives the | ||
509 | user a normal shell on the remote machine. All communication with the | ||
510 | remote command or shell will be automatically encrypted. | ||
511 | |||
512 | If a pseudo-terminal has been allocated (normal login session), the user | ||
513 | may use the escape characters noted below. | ||
514 | |||
515 | If no pseudo-tty has been allocated, the session is transparent and can | ||
516 | be used to reliably transfer binary data. On most systems, setting the | ||
517 | escape character to ``none'' will also make the session transparent even | ||
518 | if a tty is used. | ||
519 | |||
520 | The session terminates when the command or shell on the remote machine | ||
521 | exits and all X11 and TCP connections have been closed. | ||
522 | |||
523 | ESCAPE CHARACTERS | ||
524 | When a pseudo-terminal has been requested, ssh supports a number of | ||
525 | functions through the use of an escape character. | ||
526 | |||
527 | A single tilde character can be sent as ~~ or by following the tilde by a | ||
528 | character other than those described below. The escape character must | ||
529 | always follow a newline to be interpreted as special. The escape | ||
530 | character can be changed in configuration files using the EscapeChar | ||
531 | configuration directive or on the command line by the -e option. | ||
532 | |||
533 | The supported escapes (assuming the default `~') are: | ||
534 | |||
535 | ~. Disconnect. | ||
536 | |||
537 | ~^Z Background ssh. | ||
538 | |||
539 | ~# List forwarded connections. | ||
540 | |||
541 | ~& Background ssh at logout when waiting for forwarded connection / | ||
542 | X11 sessions to terminate. | ||
543 | |||
544 | ~? Display a list of escape characters. | ||
545 | |||
546 | ~B Send a BREAK to the remote system (only useful for SSH protocol | ||
547 | version 2 and if the peer supports it). | ||
548 | |||
549 | ~C Open command line. Currently this allows the addition of port | ||
550 | forwardings using the -L, -R and -D options (see above). It also | ||
551 | allows the cancellation of existing port-forwardings with | ||
552 | -KL[bind_address:]port for local, -KR[bind_address:]port for | ||
553 | remote and -KD[bind_address:]port for dynamic port-forwardings. | ||
554 | !command allows the user to execute a local command if the | ||
555 | PermitLocalCommand option is enabled in ssh_config(5). Basic | ||
556 | help is available, using the -h option. | ||
557 | |||
558 | ~R Request rekeying of the connection (only useful for SSH protocol | ||
559 | version 2 and if the peer supports it). | ||
560 | |||
561 | ~V Decrease the verbosity (LogLevel) when errors are being written | ||
562 | to stderr. | ||
563 | |||
564 | ~v Increase the verbosity (LogLevel) when errors are being written | ||
565 | to stderr. | ||
566 | |||
567 | TCP FORWARDING | ||
568 | Forwarding of arbitrary TCP connections over the secure channel can be | ||
569 | specified either on the command line or in a configuration file. One | ||
570 | possible application of TCP forwarding is a secure connection to a mail | ||
571 | server; another is going through firewalls. | ||
572 | |||
573 | In the example below, we look at encrypting communication between an IRC | ||
574 | client and server, even though the IRC server does not directly support | ||
575 | encrypted communications. This works as follows: the user connects to | ||
576 | the remote host using ssh, specifying a port to be used to forward | ||
577 | connections to the remote server. After that it is possible to start the | ||
578 | service which is to be encrypted on the client machine, connecting to the | ||
579 | same local port, and ssh will encrypt and forward the connection. | ||
580 | |||
581 | The following example tunnels an IRC session from client machine | ||
582 | ``127.0.0.1'' (localhost) to remote server ``server.example.com'': | ||
583 | |||
584 | $ ssh -f -L 1234:localhost:6667 server.example.com sleep 10 | ||
585 | $ irc -c '#users' -p 1234 pinky 127.0.0.1 | ||
586 | |||
587 | This tunnels a connection to IRC server ``server.example.com'', joining | ||
588 | channel ``#users'', nickname ``pinky'', using port 1234. It doesn't | ||
589 | matter which port is used, as long as it's greater than 1023 (remember, | ||
590 | only root can open sockets on privileged ports) and doesn't conflict with | ||
591 | any ports already in use. The connection is forwarded to port 6667 on | ||
592 | the remote server, since that's the standard port for IRC services. | ||
593 | |||
594 | The -f option backgrounds ssh and the remote command ``sleep 10'' is | ||
595 | specified to allow an amount of time (10 seconds, in the example) to | ||
596 | start the service which is to be tunnelled. If no connections are made | ||
597 | within the time specified, ssh will exit. | ||
598 | |||
599 | X11 FORWARDING | ||
600 | If the ForwardX11 variable is set to ``yes'' (or see the description of | ||
601 | the -X, -x, and -Y options above) and the user is using X11 (the DISPLAY | ||
602 | environment variable is set), the connection to the X11 display is | ||
603 | automatically forwarded to the remote side in such a way that any X11 | ||
604 | programs started from the shell (or command) will go through the | ||
605 | encrypted channel, and the connection to the real X server will be made | ||
606 | from the local machine. The user should not manually set DISPLAY. | ||
607 | Forwarding of X11 connections can be configured on the command line or in | ||
608 | configuration files. | ||
609 | |||
610 | The DISPLAY value set by ssh will point to the server machine, but with a | ||
611 | display number greater than zero. This is normal, and happens because | ||
612 | ssh creates a ``proxy'' X server on the server machine for forwarding the | ||
613 | connections over the encrypted channel. | ||
614 | |||
615 | ssh will also automatically set up Xauthority data on the server machine. | ||
616 | For this purpose, it will generate a random authorization cookie, store | ||
617 | it in Xauthority on the server, and verify that any forwarded connections | ||
618 | carry this cookie and replace it by the real cookie when the connection | ||
619 | is opened. The real authentication cookie is never sent to the server | ||
620 | machine (and no cookies are sent in the plain). | ||
621 | |||
622 | If the ForwardAgent variable is set to ``yes'' (or see the description of | ||
623 | the -A and -a options above) and the user is using an authentication | ||
624 | agent, the connection to the agent is automatically forwarded to the | ||
625 | remote side. | ||
626 | |||
627 | VERIFYING HOST KEYS | ||
628 | When connecting to a server for the first time, a fingerprint of the | ||
629 | server's public key is presented to the user (unless the option | ||
630 | StrictHostKeyChecking has been disabled). Fingerprints can be determined | ||
631 | using ssh-keygen(1): | ||
632 | |||
633 | $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key | ||
634 | |||
635 | If the fingerprint is already known, it can be matched and the key can be | ||
636 | accepted or rejected. Because of the difficulty of comparing host keys | ||
637 | just by looking at hex strings, there is also support to compare host | ||
638 | keys visually, using random art. By setting the VisualHostKey option to | ||
639 | ``yes'', a small ASCII graphic gets displayed on every login to a server, | ||
640 | no matter if the session itself is interactive or not. By learning the | ||
641 | pattern a known server produces, a user can easily find out that the host | ||
642 | key has changed when a completely different pattern is displayed. | ||
643 | Because these patterns are not unambiguous however, a pattern that looks | ||
644 | similar to the pattern remembered only gives a good probability that the | ||
645 | host key is the same, not guaranteed proof. | ||
646 | |||
647 | To get a listing of the fingerprints along with their random art for all | ||
648 | known hosts, the following command line can be used: | ||
649 | |||
650 | $ ssh-keygen -lv -f ~/.ssh/known_hosts | ||
651 | |||
652 | If the fingerprint is unknown, an alternative method of verification is | ||
653 | available: SSH fingerprints verified by DNS. An additional resource | ||
654 | record (RR), SSHFP, is added to a zonefile and the connecting client is | ||
655 | able to match the fingerprint with that of the key presented. | ||
656 | |||
657 | In this example, we are connecting a client to a server, | ||
658 | ``host.example.com''. The SSHFP resource records should first be added | ||
659 | to the zonefile for host.example.com: | ||
660 | |||
661 | $ ssh-keygen -r host.example.com. | ||
662 | |||
663 | The output lines will have to be added to the zonefile. To check that | ||
664 | the zone is answering fingerprint queries: | ||
665 | |||
666 | $ dig -t SSHFP host.example.com | ||
667 | |||
668 | Finally the client connects: | ||
669 | |||
670 | $ ssh -o "VerifyHostKeyDNS ask" host.example.com | ||
671 | [...] | ||
672 | Matching host key fingerprint found in DNS. | ||
673 | Are you sure you want to continue connecting (yes/no)? | ||
674 | |||
675 | See the VerifyHostKeyDNS option in ssh_config(5) for more information. | ||
676 | |||
677 | SSH-BASED VIRTUAL PRIVATE NETWORKS | ||
678 | ssh contains support for Virtual Private Network (VPN) tunnelling using | ||
679 | the tun(4) network pseudo-device, allowing two networks to be joined | ||
680 | securely. The sshd_config(5) configuration option PermitTunnel controls | ||
681 | whether the server supports this, and at what level (layer 2 or 3 | ||
682 | traffic). | ||
683 | |||
684 | The following example would connect client network 10.0.50.0/24 with | ||
685 | remote network 10.0.99.0/24 using a point-to-point connection from | ||
686 | 10.1.1.1 to 10.1.1.2, provided that the SSH server running on the gateway | ||
687 | to the remote network, at 192.168.1.15, allows it. | ||
688 | |||
689 | On the client: | ||
690 | |||
691 | # ssh -f -w 0:1 192.168.1.15 true | ||
692 | # ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252 | ||
693 | # route add 10.0.99.0/24 10.1.1.2 | ||
694 | |||
695 | On the server: | ||
696 | |||
697 | # ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252 | ||
698 | # route add 10.0.50.0/24 10.1.1.1 | ||
699 | |||
700 | Client access may be more finely tuned via the /root/.ssh/authorized_keys | ||
701 | file (see below) and the PermitRootLogin server option. The following | ||
702 | entry would permit connections on tun(4) device 1 from user ``jane'' and | ||
703 | on tun device 2 from user ``john'', if PermitRootLogin is set to | ||
704 | ``forced-commands-only'': | ||
705 | |||
706 | tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane | ||
707 | tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john | ||
708 | |||
709 | Since an SSH-based setup entails a fair amount of overhead, it may be | ||
710 | more suited to temporary setups, such as for wireless VPNs. More | ||
711 | permanent VPNs are better provided by tools such as ipsecctl(8) and | ||
712 | isakmpd(8). | ||
713 | |||
714 | ENVIRONMENT | ||
715 | ssh will normally set the following environment variables: | ||
716 | |||
717 | DISPLAY The DISPLAY variable indicates the location of the | ||
718 | X11 server. It is automatically set by ssh to | ||
719 | point to a value of the form ``hostname:n'', where | ||
720 | ``hostname'' indicates the host where the shell | ||
721 | runs, and `n' is an integer >= 1. ssh uses this | ||
722 | special value to forward X11 connections over the | ||
723 | secure channel. The user should normally not set | ||
724 | DISPLAY explicitly, as that will render the X11 | ||
725 | connection insecure (and will require the user to | ||
726 | manually copy any required authorization cookies). | ||
727 | |||
728 | HOME Set to the path of the user's home directory. | ||
729 | |||
730 | LOGNAME Synonym for USER; set for compatibility with | ||
731 | systems that use this variable. | ||
732 | |||
733 | MAIL Set to the path of the user's mailbox. | ||
734 | |||
735 | PATH Set to the default PATH, as specified when | ||
736 | compiling ssh. | ||
737 | |||
738 | SSH_ASKPASS If ssh needs a passphrase, it will read the | ||
739 | passphrase from the current terminal if it was run | ||
740 | from a terminal. If ssh does not have a terminal | ||
741 | associated with it but DISPLAY and SSH_ASKPASS are | ||
742 | set, it will execute the program specified by | ||
743 | SSH_ASKPASS and open an X11 window to read the | ||
744 | passphrase. This is particularly useful when | ||
745 | calling ssh from a .xsession or related script. | ||
746 | (Note that on some machines it may be necessary to | ||
747 | redirect the input from /dev/null to make this | ||
748 | work.) | ||
749 | |||
750 | SSH_AUTH_SOCK Identifies the path of a UNIX-domain socket used to | ||
751 | communicate with the agent. | ||
752 | |||
753 | SSH_CONNECTION Identifies the client and server ends of the | ||
754 | connection. The variable contains four space- | ||
755 | separated values: client IP address, client port | ||
756 | number, server IP address, and server port number. | ||
757 | |||
758 | SSH_ORIGINAL_COMMAND This variable contains the original command line if | ||
759 | a forced command is executed. It can be used to | ||
760 | extract the original arguments. | ||
761 | |||
762 | SSH_TTY This is set to the name of the tty (path to the | ||
763 | device) associated with the current shell or | ||
764 | command. If the current session has no tty, this | ||
765 | variable is not set. | ||
766 | |||
767 | TZ This variable is set to indicate the present time | ||
768 | zone if it was set when the daemon was started | ||
769 | (i.e. the daemon passes the value on to new | ||
770 | connections). | ||
771 | |||
772 | USER Set to the name of the user logging in. | ||
773 | |||
774 | Additionally, ssh reads ~/.ssh/environment, and adds lines of the format | ||
775 | ``VARNAME=value'' to the environment if the file exists and users are | ||
776 | allowed to change their environment. For more information, see the | ||
777 | PermitUserEnvironment option in sshd_config(5). | ||
778 | |||
779 | FILES | ||
780 | ~/.rhosts | ||
781 | This file is used for host-based authentication (see above). On | ||
782 | some machines this file may need to be world-readable if the | ||
783 | user's home directory is on an NFS partition, because sshd(8) | ||
784 | reads it as root. Additionally, this file must be owned by the | ||
785 | user, and must not have write permissions for anyone else. The | ||
786 | recommended permission for most machines is read/write for the | ||
787 | user, and not accessible by others. | ||
788 | |||
789 | ~/.shosts | ||
790 | This file is used in exactly the same way as .rhosts, but allows | ||
791 | host-based authentication without permitting login with | ||
792 | rlogin/rsh. | ||
793 | |||
794 | ~/.ssh/ | ||
795 | This directory is the default location for all user-specific | ||
796 | configuration and authentication information. There is no | ||
797 | general requirement to keep the entire contents of this directory | ||
798 | secret, but the recommended permissions are read/write/execute | ||
799 | for the user, and not accessible by others. | ||
800 | |||
801 | ~/.ssh/authorized_keys | ||
802 | Lists the public keys (DSA, ECDSA, ED25519, RSA) that can be used | ||
803 | for logging in as this user. The format of this file is | ||
804 | described in the sshd(8) manual page. This file is not highly | ||
805 | sensitive, but the recommended permissions are read/write for the | ||
806 | user, and not accessible by others. | ||
807 | |||
808 | ~/.ssh/config | ||
809 | This is the per-user configuration file. The file format and | ||
810 | configuration options are described in ssh_config(5). Because of | ||
811 | the potential for abuse, this file must have strict permissions: | ||
812 | read/write for the user, and not writable by others. | ||
813 | |||
814 | ~/.ssh/environment | ||
815 | Contains additional definitions for environment variables; see | ||
816 | ENVIRONMENT, above. | ||
817 | |||
818 | ~/.ssh/identity | ||
819 | ~/.ssh/id_dsa | ||
820 | ~/.ssh/id_ecdsa | ||
821 | ~/.ssh/id_ed25519 | ||
822 | ~/.ssh/id_rsa | ||
823 | Contains the private key for authentication. These files contain | ||
824 | sensitive data and should be readable by the user but not | ||
825 | accessible by others (read/write/execute). ssh will simply | ||
826 | ignore a private key file if it is accessible by others. It is | ||
827 | possible to specify a passphrase when generating the key which | ||
828 | will be used to encrypt the sensitive part of this file using | ||
829 | 3DES. | ||
830 | |||
831 | ~/.ssh/identity.pub | ||
832 | ~/.ssh/id_dsa.pub | ||
833 | ~/.ssh/id_ecdsa.pub | ||
834 | ~/.ssh/id_ed25519.pub | ||
835 | ~/.ssh/id_rsa.pub | ||
836 | Contains the public key for authentication. These files are not | ||
837 | sensitive and can (but need not) be readable by anyone. | ||
838 | |||
839 | ~/.ssh/known_hosts | ||
840 | Contains a list of host keys for all hosts the user has logged | ||
841 | into that are not already in the systemwide list of known host | ||
842 | keys. See sshd(8) for further details of the format of this | ||
843 | file. | ||
844 | |||
845 | ~/.ssh/rc | ||
846 | Commands in this file are executed by ssh when the user logs in, | ||
847 | just before the user's shell (or command) is started. See the | ||
848 | sshd(8) manual page for more information. | ||
849 | |||
850 | /etc/hosts.equiv | ||
851 | This file is for host-based authentication (see above). It | ||
852 | should only be writable by root. | ||
853 | |||
854 | /etc/shosts.equiv | ||
855 | This file is used in exactly the same way as hosts.equiv, but | ||
856 | allows host-based authentication without permitting login with | ||
857 | rlogin/rsh. | ||
858 | |||
859 | /etc/ssh/ssh_config | ||
860 | Systemwide configuration file. The file format and configuration | ||
861 | options are described in ssh_config(5). | ||
862 | |||
863 | /etc/ssh/ssh_host_key | ||
864 | /etc/ssh/ssh_host_dsa_key | ||
865 | /etc/ssh/ssh_host_ecdsa_key | ||
866 | /etc/ssh/ssh_host_ed25519_key | ||
867 | /etc/ssh/ssh_host_rsa_key | ||
868 | These files contain the private parts of the host keys and are | ||
869 | used for host-based authentication. If protocol version 1 is | ||
870 | used, ssh must be setuid root, since the host key is readable | ||
871 | only by root. For protocol version 2, ssh uses ssh-keysign(8) to | ||
872 | access the host keys, eliminating the requirement that ssh be | ||
873 | setuid root when host-based authentication is used. By default | ||
874 | ssh is not setuid root. | ||
875 | |||
876 | /etc/ssh/ssh_known_hosts | ||
877 | Systemwide list of known host keys. This file should be prepared | ||
878 | by the system administrator to contain the public host keys of | ||
879 | all machines in the organization. It should be world-readable. | ||
880 | See sshd(8) for further details of the format of this file. | ||
881 | |||
882 | /etc/ssh/sshrc | ||
883 | Commands in this file are executed by ssh when the user logs in, | ||
884 | just before the user's shell (or command) is started. See the | ||
885 | sshd(8) manual page for more information. | ||
886 | |||
887 | EXIT STATUS | ||
888 | ssh exits with the exit status of the remote command or with 255 if an | ||
889 | error occurred. | ||
890 | |||
891 | SEE ALSO | ||
892 | scp(1), sftp(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), ssh-keyscan(1), | ||
893 | tun(4), hosts.equiv(5), ssh_config(5), ssh-keysign(8), sshd(8) | ||
894 | |||
895 | STANDARDS | ||
896 | S. Lehtinen and C. Lonvick, The Secure Shell (SSH) Protocol Assigned | ||
897 | Numbers, RFC 4250, January 2006. | ||
898 | |||
899 | T. Ylonen and C. Lonvick, The Secure Shell (SSH) Protocol Architecture, | ||
900 | RFC 4251, January 2006. | ||
901 | |||
902 | T. Ylonen and C. Lonvick, The Secure Shell (SSH) Authentication Protocol, | ||
903 | RFC 4252, January 2006. | ||
904 | |||
905 | T. Ylonen and C. Lonvick, The Secure Shell (SSH) Transport Layer | ||
906 | Protocol, RFC 4253, January 2006. | ||
907 | |||
908 | T. Ylonen and C. Lonvick, The Secure Shell (SSH) Connection Protocol, RFC | ||
909 | 4254, January 2006. | ||
910 | |||
911 | J. Schlyter and W. Griffin, Using DNS to Securely Publish Secure Shell | ||
912 | (SSH) Key Fingerprints, RFC 4255, January 2006. | ||
913 | |||
914 | F. Cusack and M. Forssen, Generic Message Exchange Authentication for the | ||
915 | Secure Shell Protocol (SSH), RFC 4256, January 2006. | ||
916 | |||
917 | J. Galbraith and P. Remaker, The Secure Shell (SSH) Session Channel Break | ||
918 | Extension, RFC 4335, January 2006. | ||
919 | |||
920 | M. Bellare, T. Kohno, and C. Namprempre, The Secure Shell (SSH) Transport | ||
921 | Layer Encryption Modes, RFC 4344, January 2006. | ||
922 | |||
923 | B. Harris, Improved Arcfour Modes for the Secure Shell (SSH) Transport | ||
924 | Layer Protocol, RFC 4345, January 2006. | ||
925 | |||
926 | M. Friedl, N. Provos, and W. Simpson, Diffie-Hellman Group Exchange for | ||
927 | the Secure Shell (SSH) Transport Layer Protocol, RFC 4419, March 2006. | ||
928 | |||
929 | J. Galbraith and R. Thayer, The Secure Shell (SSH) Public Key File | ||
930 | Format, RFC 4716, November 2006. | ||
931 | |||
932 | D. Stebila and J. Green, Elliptic Curve Algorithm Integration in the | ||
933 | Secure Shell Transport Layer, RFC 5656, December 2009. | ||
934 | |||
935 | A. Perrig and D. Song, Hash Visualization: a New Technique to improve | ||
936 | Real-World Security, 1999, International Workshop on Cryptographic | ||
937 | Techniques and E-Commerce (CrypTEC '99). | ||
938 | |||
939 | AUTHORS | ||
940 | OpenSSH is a derivative of the original and free ssh 1.2.12 release by | ||
941 | Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo | ||
942 | de Raadt and Dug Song removed many bugs, re-added newer features and | ||
943 | created OpenSSH. Markus Friedl contributed the support for SSH protocol | ||
944 | versions 1.5 and 2.0. | ||
945 | |||
946 | OpenBSD 5.5 December 7, 2013 OpenBSD 5.5 | ||