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