diff options
author | Darren Tucker <dtucker@zip.com.au> | 2005-12-20 16:09:36 +1100 |
---|---|---|
committer | Darren Tucker <dtucker@zip.com.au> | 2005-12-20 16:09:36 +1100 |
commit | d3877b995ac0e1245c70e520cc986aac99c901be (patch) | |
tree | 37ec5f7966bb3f28282c9246884a956e1ff84028 | |
parent | 0d0e8f0173bd10a8a2325fbb3ef83e04a91abdcc (diff) |
- jmc@cvs.openbsd.org 2005/12/16 18:07:08
[ssh.1]
move the option descriptions up the page: start of a restructure;
ok markus deraadt
-rw-r--r-- | ChangeLog | 6 | ||||
-rw-r--r-- | ssh.1 | 600 |
2 files changed, 305 insertions, 301 deletions
@@ -3,6 +3,10 @@ | |||
3 | - reyk@cvs.openbsd.org 2005/12/13 15:03:02 | 3 | - reyk@cvs.openbsd.org 2005/12/13 15:03:02 |
4 | [serverloop.c] | 4 | [serverloop.c] |
5 | if forced_tun_device is not set, it is -1 and not SSH_TUNID_ANY | 5 | if forced_tun_device is not set, it is -1 and not SSH_TUNID_ANY |
6 | - jmc@cvs.openbsd.org 2005/12/16 18:07:08 | ||
7 | [ssh.1] | ||
8 | move the option descriptions up the page: start of a restructure; | ||
9 | ok markus deraadt | ||
6 | 10 | ||
7 | 20051219 | 11 | 20051219 |
8 | - (dtucker) [cipher-aes.c cipher-ctr.c cipher.c configure.ac | 12 | - (dtucker) [cipher-aes.c cipher-ctr.c cipher.c configure.ac |
@@ -3477,4 +3481,4 @@ | |||
3477 | - (djm) Trim deprecated options from INSTALL. Mention UsePAM | 3481 | - (djm) Trim deprecated options from INSTALL. Mention UsePAM |
3478 | - (djm) Fix quote handling in sftp; Patch from admorten AT umich.edu | 3482 | - (djm) Fix quote handling in sftp; Patch from admorten AT umich.edu |
3479 | 3483 | ||
3480 | $Id: ChangeLog,v 1.4032 2005/12/20 05:08:42 dtucker Exp $ | 3484 | $Id: ChangeLog,v 1.4033 2005/12/20 05:09:36 dtucker Exp $ |
@@ -34,7 +34,7 @@ | |||
34 | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | 34 | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
35 | .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | 35 | .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
36 | .\" | 36 | .\" |
37 | .\" $OpenBSD: ssh.1,v 1.217 2005/12/08 14:59:44 jmc Exp $ | 37 | .\" $OpenBSD: ssh.1,v 1.218 2005/12/16 18:07:08 jmc Exp $ |
38 | .Dd September 25, 1999 | 38 | .Dd September 25, 1999 |
39 | .Dt SSH 1 | 39 | .Dt SSH 1 |
40 | .Os | 40 | .Os |
@@ -107,304 +107,6 @@ If | |||
107 | is specified, | 107 | is specified, |
108 | .Ar command | 108 | .Ar command |
109 | is executed on the remote host instead of a login shell. | 109 | is executed on the remote host instead of a login shell. |
110 | .Ss SSH protocol version 1 | ||
111 | The first authentication method is the | ||
112 | .Em rhosts | ||
113 | or | ||
114 | .Em hosts.equiv | ||
115 | method combined with RSA-based host authentication. | ||
116 | If the machine the user logs in from is listed in | ||
117 | .Pa /etc/hosts.equiv | ||
118 | or | ||
119 | .Pa /etc/shosts.equiv | ||
120 | on the remote machine, and the user names are | ||
121 | the same on both sides, or if the files | ||
122 | .Pa ~/.rhosts | ||
123 | or | ||
124 | .Pa ~/.shosts | ||
125 | exist in the user's home directory on the | ||
126 | remote machine and contain a line containing the name of the client | ||
127 | machine and the name of the user on that machine, the user is | ||
128 | considered for log in. | ||
129 | Additionally, if the server can verify the client's | ||
130 | host key (see | ||
131 | .Pa /etc/ssh/ssh_known_hosts | ||
132 | and | ||
133 | .Pa ~/.ssh/known_hosts | ||
134 | in the | ||
135 | .Sx FILES | ||
136 | section), only then is login permitted. | ||
137 | This authentication method closes security holes due to IP | ||
138 | spoofing, DNS spoofing and routing spoofing. | ||
139 | [Note to the administrator: | ||
140 | .Pa /etc/hosts.equiv , | ||
141 | .Pa ~/.rhosts , | ||
142 | and the rlogin/rsh protocol in general, are inherently insecure and should be | ||
143 | disabled if security is desired.] | ||
144 | .Pp | ||
145 | As a second authentication method, | ||
146 | .Nm | ||
147 | supports RSA based authentication. | ||
148 | The scheme is based on public-key cryptography: there are cryptosystems | ||
149 | where encryption and decryption are done using separate keys, and it | ||
150 | is not possible to derive the decryption key from the encryption key. | ||
151 | RSA is one such system. | ||
152 | The idea is that each user creates a public/private | ||
153 | key pair for authentication purposes. | ||
154 | The server knows the public key, and only the user knows the private key. | ||
155 | .Pp | ||
156 | The file | ||
157 | .Pa ~/.ssh/authorized_keys | ||
158 | lists the public keys that are permitted for logging in. | ||
159 | When the user logs in, the | ||
160 | .Nm | ||
161 | program tells the server which key pair it would like to use for | ||
162 | authentication. | ||
163 | The server checks if this key is permitted, and if so, | ||
164 | sends the user (actually the | ||
165 | .Nm | ||
166 | program running on behalf of the user) a challenge, a random number, | ||
167 | encrypted by the user's public key. | ||
168 | The challenge can only be decrypted using the proper private key. | ||
169 | The user's client then decrypts the challenge using the private key, | ||
170 | proving that he/she knows the private key | ||
171 | but without disclosing it to the server. | ||
172 | .Pp | ||
173 | .Nm | ||
174 | implements the RSA authentication protocol automatically. | ||
175 | The user creates his/her RSA key pair by running | ||
176 | .Xr ssh-keygen 1 . | ||
177 | This stores the private key in | ||
178 | .Pa ~/.ssh/identity | ||
179 | and stores the public key in | ||
180 | .Pa ~/.ssh/identity.pub | ||
181 | in the user's home directory. | ||
182 | The user should then copy the | ||
183 | .Pa identity.pub | ||
184 | to | ||
185 | .Pa ~/.ssh/authorized_keys | ||
186 | in his/her home directory on the remote machine (the | ||
187 | .Pa authorized_keys | ||
188 | file corresponds to the conventional | ||
189 | .Pa ~/.rhosts | ||
190 | file, and has one key | ||
191 | per line, though the lines can be very long). | ||
192 | After this, the user can log in without giving the password. | ||
193 | .Pp | ||
194 | The most convenient way to use RSA authentication may be with an | ||
195 | authentication agent. | ||
196 | See | ||
197 | .Xr ssh-agent 1 | ||
198 | for more information. | ||
199 | .Pp | ||
200 | If other authentication methods fail, | ||
201 | .Nm | ||
202 | prompts the user for a password. | ||
203 | The password is sent to the remote | ||
204 | host for checking; however, since all communications are encrypted, | ||
205 | the password cannot be seen by someone listening on the network. | ||
206 | .Ss SSH protocol version 2 | ||
207 | When a user connects using protocol version 2, | ||
208 | similar authentication methods are available. | ||
209 | Using the default values for | ||
210 | .Cm PreferredAuthentications , | ||
211 | the client will try to authenticate first using the hostbased method; | ||
212 | if this method fails, public key authentication is attempted, | ||
213 | and finally if this method fails, keyboard-interactive and | ||
214 | password authentication are tried. | ||
215 | .Pp | ||
216 | The public key method is similar to RSA authentication described | ||
217 | in the previous section and allows the RSA or DSA algorithm to be used: | ||
218 | The client uses his private key, | ||
219 | .Pa ~/.ssh/id_dsa | ||
220 | or | ||
221 | .Pa ~/.ssh/id_rsa , | ||
222 | to sign the session identifier and sends the result to the server. | ||
223 | The server checks whether the matching public key is listed in | ||
224 | .Pa ~/.ssh/authorized_keys | ||
225 | and grants access if both the key is found and the signature is correct. | ||
226 | The session identifier is derived from a shared Diffie-Hellman value | ||
227 | and is only known to the client and the server. | ||
228 | .Pp | ||
229 | If public key authentication fails or is not available, a password | ||
230 | can be sent encrypted to the remote host to prove the user's identity. | ||
231 | .Pp | ||
232 | Additionally, | ||
233 | .Nm | ||
234 | supports hostbased or challenge response authentication. | ||
235 | .Pp | ||
236 | Protocol 2 provides additional mechanisms for confidentiality | ||
237 | (the traffic is encrypted using AES, 3DES, Blowfish, CAST128 or Arcfour) | ||
238 | and integrity (hmac-md5, hmac-sha1, hmac-ripemd160). | ||
239 | Note that protocol 1 lacks a strong mechanism for ensuring the | ||
240 | integrity of the connection. | ||
241 | .Ss Login session and remote execution | ||
242 | When the user's identity has been accepted by the server, the server | ||
243 | either executes the given command, or logs into the machine and gives | ||
244 | the user a normal shell on the remote machine. | ||
245 | All communication with | ||
246 | the remote command or shell will be automatically encrypted. | ||
247 | .Pp | ||
248 | If a pseudo-terminal has been allocated (normal login session), the | ||
249 | user may use the escape characters noted below. | ||
250 | .Pp | ||
251 | If no pseudo-tty has been allocated, | ||
252 | the session is transparent and can be used to reliably transfer binary data. | ||
253 | On most systems, setting the escape character to | ||
254 | .Dq none | ||
255 | will also make the session transparent even if a tty is used. | ||
256 | .Pp | ||
257 | The session terminates when the command or shell on the remote | ||
258 | machine exits and all X11 and TCP/IP connections have been closed. | ||
259 | The exit status of the remote program is returned as the exit status of | ||
260 | .Nm ssh . | ||
261 | .Ss Escape Characters | ||
262 | When a pseudo-terminal has been requested, | ||
263 | .Nm | ||
264 | supports a number of functions through the use of an escape character. | ||
265 | .Pp | ||
266 | A single tilde character can be sent as | ||
267 | .Ic ~~ | ||
268 | or by following the tilde by a character other than those described below. | ||
269 | The escape character must always follow a newline to be interpreted as | ||
270 | special. | ||
271 | The escape character can be changed in configuration files using the | ||
272 | .Cm EscapeChar | ||
273 | configuration directive or on the command line by the | ||
274 | .Fl e | ||
275 | option. | ||
276 | .Pp | ||
277 | The supported escapes (assuming the default | ||
278 | .Ql ~ ) | ||
279 | are: | ||
280 | .Bl -tag -width Ds | ||
281 | .It Cm ~. | ||
282 | Disconnect. | ||
283 | .It Cm ~^Z | ||
284 | Background | ||
285 | .Nm ssh . | ||
286 | .It Cm ~# | ||
287 | List forwarded connections. | ||
288 | .It Cm ~& | ||
289 | Background | ||
290 | .Nm | ||
291 | at logout when waiting for forwarded connection / X11 sessions to terminate. | ||
292 | .It Cm ~? | ||
293 | Display a list of escape characters. | ||
294 | .It Cm ~B | ||
295 | Send a BREAK to the remote system | ||
296 | (only useful for SSH protocol version 2 and if the peer supports it). | ||
297 | .It Cm ~C | ||
298 | Open command line. | ||
299 | Currently this allows the addition of port forwardings using the | ||
300 | .Fl L | ||
301 | and | ||
302 | .Fl R | ||
303 | options (see below). | ||
304 | It also allows the cancellation of existing remote port-forwardings | ||
305 | using | ||
306 | .Fl KR Ar hostport . | ||
307 | .Ic !\& Ns Ar command | ||
308 | allows the user to execute a local command if the | ||
309 | .Ic PermitLocalCommand | ||
310 | option is enabled in | ||
311 | .Xr ssh_config 5 . | ||
312 | Basic help is available, using the | ||
313 | .Fl h | ||
314 | option. | ||
315 | .It Cm ~R | ||
316 | Request rekeying of the connection | ||
317 | (only useful for SSH protocol version 2 and if the peer supports it). | ||
318 | .El | ||
319 | .Ss X11 and TCP forwarding | ||
320 | If the | ||
321 | .Cm ForwardX11 | ||
322 | variable is set to | ||
323 | .Dq yes | ||
324 | (or see the description of the | ||
325 | .Fl X | ||
326 | and | ||
327 | .Fl x | ||
328 | options described later) | ||
329 | and the user is using X11 (the | ||
330 | .Ev DISPLAY | ||
331 | environment variable is set), the connection to the X11 display is | ||
332 | automatically forwarded to the remote side in such a way that any X11 | ||
333 | programs started from the shell (or command) will go through the | ||
334 | encrypted channel, and the connection to the real X server will be made | ||
335 | from the local machine. | ||
336 | The user should not manually set | ||
337 | .Ev DISPLAY . | ||
338 | Forwarding of X11 connections can be | ||
339 | configured on the command line or in configuration files. | ||
340 | .Pp | ||
341 | The | ||
342 | .Ev DISPLAY | ||
343 | value set by | ||
344 | .Nm | ||
345 | will point to the server machine, but with a display number greater than zero. | ||
346 | This is normal, and happens because | ||
347 | .Nm | ||
348 | creates a | ||
349 | .Dq proxy | ||
350 | X server on the server machine for forwarding the | ||
351 | connections over the encrypted channel. | ||
352 | .Pp | ||
353 | .Nm | ||
354 | will also automatically set up Xauthority data on the server machine. | ||
355 | For this purpose, it will generate a random authorization cookie, | ||
356 | store it in Xauthority on the server, and verify that any forwarded | ||
357 | connections carry this cookie and replace it by the real cookie when | ||
358 | the connection is opened. | ||
359 | The real authentication cookie is never | ||
360 | sent to the server machine (and no cookies are sent in the plain). | ||
361 | .Pp | ||
362 | If the | ||
363 | .Cm ForwardAgent | ||
364 | variable is set to | ||
365 | .Dq yes | ||
366 | (or see the description of the | ||
367 | .Fl A | ||
368 | and | ||
369 | .Fl a | ||
370 | options described later) and | ||
371 | the user is using an authentication agent, the connection to the agent | ||
372 | is automatically forwarded to the remote side. | ||
373 | .Pp | ||
374 | Forwarding of arbitrary TCP/IP connections over the secure channel can | ||
375 | be specified either on the command line or in a configuration file. | ||
376 | One possible application of TCP/IP forwarding is a secure connection to an | ||
377 | electronic purse; another is going through firewalls. | ||
378 | .Ss Server authentication | ||
379 | .Nm | ||
380 | automatically maintains and checks a database containing | ||
381 | identifications for all hosts it has ever been used with. | ||
382 | Host keys are stored in | ||
383 | .Pa ~/.ssh/known_hosts | ||
384 | in the user's home directory. | ||
385 | Additionally, the file | ||
386 | .Pa /etc/ssh/ssh_known_hosts | ||
387 | is automatically checked for known hosts. | ||
388 | Any new hosts are automatically added to the user's file. | ||
389 | If a host's identification ever changes, | ||
390 | .Nm | ||
391 | warns about this and disables password authentication to prevent a | ||
392 | trojan horse from getting the user's password. | ||
393 | Another purpose of this mechanism is to prevent man-in-the-middle attacks | ||
394 | which could otherwise be used to circumvent the encryption. | ||
395 | The | ||
396 | .Cm StrictHostKeyChecking | ||
397 | option can be used to prevent logins to machines whose | ||
398 | host key is not known or has changed. | ||
399 | .Pp | ||
400 | .Nm | ||
401 | can be configured to verify host identification using fingerprint resource | ||
402 | records (SSHFP) published in DNS. | ||
403 | The | ||
404 | .Cm VerifyHostKeyDNS | ||
405 | option can be used to control how DNS lookups are performed. | ||
406 | SSHFP resource records can be generated using | ||
407 | .Xr ssh-keygen 1 . | ||
408 | .Pp | 110 | .Pp |
409 | The options are as follows: | 111 | The options are as follows: |
410 | .Bl -tag -width Ds | 112 | .Bl -tag -width Ds |
@@ -912,12 +614,310 @@ Enables trusted X11 forwarding. | |||
912 | Trusted X11 forwardings are not subjected to the X11 SECURITY extension | 614 | Trusted X11 forwardings are not subjected to the X11 SECURITY extension |
913 | controls. | 615 | controls. |
914 | .El | 616 | .El |
915 | .Sh CONFIGURATION FILES | 617 | .Ss SSH protocol version 1 |
618 | The first authentication method is the | ||
619 | .Em rhosts | ||
620 | or | ||
621 | .Em hosts.equiv | ||
622 | method combined with RSA-based host authentication. | ||
623 | If the machine the user logs in from is listed in | ||
624 | .Pa /etc/hosts.equiv | ||
625 | or | ||
626 | .Pa /etc/shosts.equiv | ||
627 | on the remote machine, and the user names are | ||
628 | the same on both sides, or if the files | ||
629 | .Pa ~/.rhosts | ||
630 | or | ||
631 | .Pa ~/.shosts | ||
632 | exist in the user's home directory on the | ||
633 | remote machine and contain a line containing the name of the client | ||
634 | machine and the name of the user on that machine, the user is | ||
635 | considered for log in. | ||
636 | Additionally, if the server can verify the client's | ||
637 | host key (see | ||
638 | .Pa /etc/ssh/ssh_known_hosts | ||
639 | and | ||
640 | .Pa ~/.ssh/known_hosts | ||
641 | in the | ||
642 | .Sx FILES | ||
643 | section), only then is login permitted. | ||
644 | This authentication method closes security holes due to IP | ||
645 | spoofing, DNS spoofing and routing spoofing. | ||
646 | [Note to the administrator: | ||
647 | .Pa /etc/hosts.equiv , | ||
648 | .Pa ~/.rhosts , | ||
649 | and the rlogin/rsh protocol in general, are inherently insecure and should be | ||
650 | disabled if security is desired.] | ||
651 | .Pp | ||
652 | As a second authentication method, | ||
653 | .Nm | ||
654 | supports RSA based authentication. | ||
655 | The scheme is based on public-key cryptography: there are cryptosystems | ||
656 | where encryption and decryption are done using separate keys, and it | ||
657 | is not possible to derive the decryption key from the encryption key. | ||
658 | RSA is one such system. | ||
659 | The idea is that each user creates a public/private | ||
660 | key pair for authentication purposes. | ||
661 | The server knows the public key, and only the user knows the private key. | ||
662 | .Pp | ||
663 | The file | ||
664 | .Pa ~/.ssh/authorized_keys | ||
665 | lists the public keys that are permitted for logging in. | ||
666 | When the user logs in, the | ||
667 | .Nm | ||
668 | program tells the server which key pair it would like to use for | ||
669 | authentication. | ||
670 | The server checks if this key is permitted, and if so, | ||
671 | sends the user (actually the | ||
672 | .Nm | ||
673 | program running on behalf of the user) a challenge, a random number, | ||
674 | encrypted by the user's public key. | ||
675 | The challenge can only be decrypted using the proper private key. | ||
676 | The user's client then decrypts the challenge using the private key, | ||
677 | proving that he/she knows the private key | ||
678 | but without disclosing it to the server. | ||
679 | .Pp | ||
680 | .Nm | ||
681 | implements the RSA authentication protocol automatically. | ||
682 | The user creates his/her RSA key pair by running | ||
683 | .Xr ssh-keygen 1 . | ||
684 | This stores the private key in | ||
685 | .Pa ~/.ssh/identity | ||
686 | and stores the public key in | ||
687 | .Pa ~/.ssh/identity.pub | ||
688 | in the user's home directory. | ||
689 | The user should then copy the | ||
690 | .Pa identity.pub | ||
691 | to | ||
692 | .Pa ~/.ssh/authorized_keys | ||
693 | in his/her home directory on the remote machine (the | ||
694 | .Pa authorized_keys | ||
695 | file corresponds to the conventional | ||
696 | .Pa ~/.rhosts | ||
697 | file, and has one key | ||
698 | per line, though the lines can be very long). | ||
699 | After this, the user can log in without giving the password. | ||
700 | .Pp | ||
701 | The most convenient way to use RSA authentication may be with an | ||
702 | authentication agent. | ||
703 | See | ||
704 | .Xr ssh-agent 1 | ||
705 | for more information. | ||
706 | .Pp | ||
707 | If other authentication methods fail, | ||
708 | .Nm | ||
709 | prompts the user for a password. | ||
710 | The password is sent to the remote | ||
711 | host for checking; however, since all communications are encrypted, | ||
712 | the password cannot be seen by someone listening on the network. | ||
713 | .Ss SSH protocol version 2 | ||
714 | When a user connects using protocol version 2, | ||
715 | similar authentication methods are available. | ||
716 | Using the default values for | ||
717 | .Cm PreferredAuthentications , | ||
718 | the client will try to authenticate first using the hostbased method; | ||
719 | if this method fails, public key authentication is attempted, | ||
720 | and finally if this method fails, keyboard-interactive and | ||
721 | password authentication are tried. | ||
722 | .Pp | ||
723 | The public key method is similar to RSA authentication described | ||
724 | in the previous section and allows the RSA or DSA algorithm to be used: | ||
725 | The client uses his private key, | ||
726 | .Pa ~/.ssh/id_dsa | ||
727 | or | ||
728 | .Pa ~/.ssh/id_rsa , | ||
729 | to sign the session identifier and sends the result to the server. | ||
730 | The server checks whether the matching public key is listed in | ||
731 | .Pa ~/.ssh/authorized_keys | ||
732 | and grants access if both the key is found and the signature is correct. | ||
733 | The session identifier is derived from a shared Diffie-Hellman value | ||
734 | and is only known to the client and the server. | ||
735 | .Pp | ||
736 | If public key authentication fails or is not available, a password | ||
737 | can be sent encrypted to the remote host to prove the user's identity. | ||
738 | .Pp | ||
739 | Additionally, | ||
740 | .Nm | ||
741 | supports hostbased or challenge response authentication. | ||
742 | .Pp | ||
743 | Protocol 2 provides additional mechanisms for confidentiality | ||
744 | (the traffic is encrypted using AES, 3DES, Blowfish, CAST128 or Arcfour) | ||
745 | and integrity (hmac-md5, hmac-sha1, hmac-ripemd160). | ||
746 | Note that protocol 1 lacks a strong mechanism for ensuring the | ||
747 | integrity of the connection. | ||
748 | .Ss Login session and remote execution | ||
749 | When the user's identity has been accepted by the server, the server | ||
750 | either executes the given command, or logs into the machine and gives | ||
751 | the user a normal shell on the remote machine. | ||
752 | All communication with | ||
753 | the remote command or shell will be automatically encrypted. | ||
754 | .Pp | ||
755 | If a pseudo-terminal has been allocated (normal login session), the | ||
756 | user may use the escape characters noted below. | ||
757 | .Pp | ||
758 | If no pseudo-tty has been allocated, | ||
759 | the session is transparent and can be used to reliably transfer binary data. | ||
760 | On most systems, setting the escape character to | ||
761 | .Dq none | ||
762 | will also make the session transparent even if a tty is used. | ||
763 | .Pp | ||
764 | The session terminates when the command or shell on the remote | ||
765 | machine exits and all X11 and TCP/IP connections have been closed. | ||
766 | The exit status of the remote program is returned as the exit status of | ||
767 | .Nm ssh . | ||
768 | .Pp | ||
916 | .Nm | 769 | .Nm |
917 | may additionally obtain configuration data from | 770 | may additionally obtain configuration data from |
918 | a per-user configuration file and a system-wide configuration file. | 771 | a per-user configuration file and a system-wide configuration file. |
919 | The file format and configuration options are described in | 772 | The file format and configuration options are described in |
920 | .Xr ssh_config 5 . | 773 | .Xr ssh_config 5 . |
774 | .Ss Escape Characters | ||
775 | When a pseudo-terminal has been requested, | ||
776 | .Nm | ||
777 | supports a number of functions through the use of an escape character. | ||
778 | .Pp | ||
779 | A single tilde character can be sent as | ||
780 | .Ic ~~ | ||
781 | or by following the tilde by a character other than those described below. | ||
782 | The escape character must always follow a newline to be interpreted as | ||
783 | special. | ||
784 | The escape character can be changed in configuration files using the | ||
785 | .Cm EscapeChar | ||
786 | configuration directive or on the command line by the | ||
787 | .Fl e | ||
788 | option. | ||
789 | .Pp | ||
790 | The supported escapes (assuming the default | ||
791 | .Ql ~ ) | ||
792 | are: | ||
793 | .Bl -tag -width Ds | ||
794 | .It Cm ~. | ||
795 | Disconnect. | ||
796 | .It Cm ~^Z | ||
797 | Background | ||
798 | .Nm ssh . | ||
799 | .It Cm ~# | ||
800 | List forwarded connections. | ||
801 | .It Cm ~& | ||
802 | Background | ||
803 | .Nm | ||
804 | at logout when waiting for forwarded connection / X11 sessions to terminate. | ||
805 | .It Cm ~? | ||
806 | Display a list of escape characters. | ||
807 | .It Cm ~B | ||
808 | Send a BREAK to the remote system | ||
809 | (only useful for SSH protocol version 2 and if the peer supports it). | ||
810 | .It Cm ~C | ||
811 | Open command line. | ||
812 | Currently this allows the addition of port forwardings using the | ||
813 | .Fl L | ||
814 | and | ||
815 | .Fl R | ||
816 | options (see below). | ||
817 | It also allows the cancellation of existing remote port-forwardings | ||
818 | using | ||
819 | .Fl KR Ar hostport . | ||
820 | .Ic !\& Ns Ar command | ||
821 | allows the user to execute a local command if the | ||
822 | .Ic PermitLocalCommand | ||
823 | option is enabled in | ||
824 | .Xr ssh_config 5 . | ||
825 | Basic help is available, using the | ||
826 | .Fl h | ||
827 | option. | ||
828 | .It Cm ~R | ||
829 | Request rekeying of the connection | ||
830 | (only useful for SSH protocol version 2 and if the peer supports it). | ||
831 | .El | ||
832 | .Ss X11 and TCP forwarding | ||
833 | If the | ||
834 | .Cm ForwardX11 | ||
835 | variable is set to | ||
836 | .Dq yes | ||
837 | (or see the description of the | ||
838 | .Fl X | ||
839 | and | ||
840 | .Fl x | ||
841 | options described later) | ||
842 | and the user is using X11 (the | ||
843 | .Ev DISPLAY | ||
844 | environment variable is set), the connection to the X11 display is | ||
845 | automatically forwarded to the remote side in such a way that any X11 | ||
846 | programs started from the shell (or command) will go through the | ||
847 | encrypted channel, and the connection to the real X server will be made | ||
848 | from the local machine. | ||
849 | The user should not manually set | ||
850 | .Ev DISPLAY . | ||
851 | Forwarding of X11 connections can be | ||
852 | configured on the command line or in configuration files. | ||
853 | .Pp | ||
854 | The | ||
855 | .Ev DISPLAY | ||
856 | value set by | ||
857 | .Nm | ||
858 | will point to the server machine, but with a display number greater than zero. | ||
859 | This is normal, and happens because | ||
860 | .Nm | ||
861 | creates a | ||
862 | .Dq proxy | ||
863 | X server on the server machine for forwarding the | ||
864 | connections over the encrypted channel. | ||
865 | .Pp | ||
866 | .Nm | ||
867 | will also automatically set up Xauthority data on the server machine. | ||
868 | For this purpose, it will generate a random authorization cookie, | ||
869 | store it in Xauthority on the server, and verify that any forwarded | ||
870 | connections carry this cookie and replace it by the real cookie when | ||
871 | the connection is opened. | ||
872 | The real authentication cookie is never | ||
873 | sent to the server machine (and no cookies are sent in the plain). | ||
874 | .Pp | ||
875 | If the | ||
876 | .Cm ForwardAgent | ||
877 | variable is set to | ||
878 | .Dq yes | ||
879 | (or see the description of the | ||
880 | .Fl A | ||
881 | and | ||
882 | .Fl a | ||
883 | options described later) and | ||
884 | the user is using an authentication agent, the connection to the agent | ||
885 | is automatically forwarded to the remote side. | ||
886 | .Pp | ||
887 | Forwarding of arbitrary TCP/IP connections over the secure channel can | ||
888 | be specified either on the command line or in a configuration file. | ||
889 | One possible application of TCP/IP forwarding is a secure connection to an | ||
890 | electronic purse; another is going through firewalls. | ||
891 | .Ss Server authentication | ||
892 | .Nm | ||
893 | automatically maintains and checks a database containing | ||
894 | identifications for all hosts it has ever been used with. | ||
895 | Host keys are stored in | ||
896 | .Pa ~/.ssh/known_hosts | ||
897 | in the user's home directory. | ||
898 | Additionally, the file | ||
899 | .Pa /etc/ssh/ssh_known_hosts | ||
900 | is automatically checked for known hosts. | ||
901 | Any new hosts are automatically added to the user's file. | ||
902 | If a host's identification ever changes, | ||
903 | .Nm | ||
904 | warns about this and disables password authentication to prevent a | ||
905 | trojan horse from getting the user's password. | ||
906 | Another purpose of this mechanism is to prevent man-in-the-middle attacks | ||
907 | which could otherwise be used to circumvent the encryption. | ||
908 | The | ||
909 | .Cm StrictHostKeyChecking | ||
910 | option can be used to prevent logins to machines whose | ||
911 | host key is not known or has changed. | ||
912 | .Pp | ||
913 | .Nm | ||
914 | can be configured to verify host identification using fingerprint resource | ||
915 | records (SSHFP) published in DNS. | ||
916 | The | ||
917 | .Cm VerifyHostKeyDNS | ||
918 | option can be used to control how DNS lookups are performed. | ||
919 | SSHFP resource records can be generated using | ||
920 | .Xr ssh-keygen 1 . | ||
921 | .Sh ENVIRONMENT | 921 | .Sh ENVIRONMENT |
922 | .Nm | 922 | .Nm |
923 | will normally set the following environment variables: | 923 | will normally set the following environment variables: |