]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - crypto/openssh/ssh.1
This commit was generated by cvs2svn to compensate for changes in r123331,
[FreeBSD/FreeBSD.git] / crypto / openssh / ssh.1
1 .\"  -*- nroff -*-
2 .\"
3 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5 .\"                    All rights reserved
6 .\"
7 .\" As far as I am concerned, the code I have written for this software
8 .\" can be used freely for any purpose.  Any derived versions of this
9 .\" software must be clearly marked as such, and if the derived work is
10 .\" incompatible with the protocol description in the RFC file, it must be
11 .\" called by a name other than "ssh" or "Secure Shell".
12 .\"
13 .\" Copyright (c) 1999,2000 Markus Friedl.  All rights reserved.
14 .\" Copyright (c) 1999 Aaron Campbell.  All rights reserved.
15 .\" Copyright (c) 1999 Theo de Raadt.  All rights reserved.
16 .\"
17 .\" Redistribution and use in source and binary forms, with or without
18 .\" modification, are permitted provided that the following conditions
19 .\" are met:
20 .\" 1. Redistributions of source code must retain the above copyright
21 .\"    notice, this list of conditions and the following disclaimer.
22 .\" 2. Redistributions in binary form must reproduce the above copyright
23 .\"    notice, this list of conditions and the following disclaimer in the
24 .\"    documentation and/or other materials provided with the distribution.
25 .\"
26 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
27 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
29 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
30 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
31 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
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.
36 .\"
37 .\" $OpenBSD: ssh.1,v 1.168 2003/03/28 10:11:43 jmc Exp $
38 .\" $FreeBSD$
39 .Dd September 25, 1999
40 .Dt SSH 1
41 .Os
42 .Sh NAME
43 .Nm ssh
44 .Nd OpenSSH SSH client (remote login program)
45 .Sh SYNOPSIS
46 .Nm ssh
47 .Op Fl l Ar login_name
48 .Ar hostname | user@hostname
49 .Op Ar command
50 .Pp
51 .Nm ssh
52 .Bk -words
53 .Op Fl afgknqstvxACNTX1246
54 .Op Fl b Ar bind_address
55 .Op Fl c Ar cipher_spec
56 .Op Fl e Ar escape_char
57 .Op Fl i Ar identity_file
58 .Op Fl l Ar login_name
59 .Op Fl m Ar mac_spec
60 .Op Fl o Ar option
61 .Op Fl p Ar port
62 .Op Fl F Ar configfile
63 .Oo Fl L Xo
64 .Sm off
65 .Ar port :
66 .Ar host :
67 .Ar hostport
68 .Sm on
69 .Xc
70 .Oc
71 .Ek
72 .Bk -words
73 .Oo Fl R Xo
74 .Sm off
75 .Ar port :
76 .Ar host :
77 .Ar hostport
78 .Sm on
79 .Xc
80 .Oc
81 .Op Fl D Ar port
82 .Ar hostname | user@hostname
83 .Op Ar command
84 .Ek
85 .Sh DESCRIPTION
86 .Nm
87 (SSH client) is a program for logging into a remote machine and for
88 executing commands on a remote machine.
89 It is intended to replace
90 rlogin and rsh, and provide secure encrypted communications between
91 two untrusted hosts over an insecure network.
92 X11 connections and
93 arbitrary TCP/IP ports can also be forwarded over the secure channel.
94 .Pp
95 .Nm
96 connects and logs into the specified
97 .Ar hostname .
98 The user must prove
99 his/her identity to the remote machine using one of several methods
100 depending on the protocol version used:
101 .Pp
102 .Ss SSH protocol version 1
103 .Pp
104 First, if the machine the user logs in from is listed in
105 .Pa /etc/hosts.equiv
106 or
107 .Pa /etc/ssh/shosts.equiv
108 on the remote machine, and the user names are
109 the same on both sides, the user is immediately permitted to log in.
110 Second, if
111 .Pa \&.rhosts
112 or
113 .Pa \&.shosts
114 exists in the user's home directory on the
115 remote machine and contains a line containing the name of the client
116 machine and the name of the user on that machine, the user is
117 permitted to log in.
118 This form of authentication alone is normally not
119 allowed by the server because it is not secure.
120 .Pp
121 The second authentication method is the
122 .Pa rhosts
123 or
124 .Pa hosts.equiv
125 method combined with RSA-based host authentication.
126 It means that if the login would be permitted by
127 .Pa $HOME/.rhosts ,
128 .Pa $HOME/.shosts ,
129 .Pa /etc/hosts.equiv ,
130 or
131 .Pa /etc/ssh/shosts.equiv ,
132 and if additionally the server can verify the client's
133 host key (see
134 .Pa /etc/ssh/ssh_known_hosts
135 and
136 .Pa $HOME/.ssh/known_hosts
137 in the
138 .Sx FILES
139 section), only then login is permitted.
140 This authentication method closes security holes due to IP
141 spoofing, DNS spoofing and routing spoofing.
142 [Note to the administrator:
143 .Pa /etc/hosts.equiv ,
144 .Pa $HOME/.rhosts ,
145 and the rlogin/rsh protocol in general, are inherently insecure and should be
146 disabled if security is desired.]
147 .Pp
148 As a third authentication method,
149 .Nm
150 supports RSA based authentication.
151 The scheme is based on public-key cryptography: there are cryptosystems
152 where encryption and decryption are done using separate keys, and it
153 is not possible to derive the decryption key from the encryption key.
154 RSA is one such system.
155 The idea is that each user creates a public/private
156 key pair for authentication purposes.
157 The server knows the public key, and only the user knows the private key.
158 The file
159 .Pa $HOME/.ssh/authorized_keys
160 lists the public keys that are permitted for logging
161 in.
162 When the user logs in, the
163 .Nm
164 program tells the server which key pair it would like to use for
165 authentication.
166 The server checks if this key is permitted, and if
167 so, sends the user (actually the
168 .Nm
169 program running on behalf of the user) a challenge, a random number,
170 encrypted by the user's public key.
171 The challenge can only be
172 decrypted using the proper private key.
173 The user's client then decrypts the
174 challenge using the private key, proving that he/she knows the private
175 key but without disclosing it to the server.
176 .Pp
177 .Nm
178 implements the RSA authentication protocol automatically.
179 The user creates his/her RSA key pair by running
180 .Xr ssh-keygen 1 .
181 This stores the private key in
182 .Pa $HOME/.ssh/identity
183 and the public key in
184 .Pa $HOME/.ssh/identity.pub
185 in the user's home directory.
186 The user should then copy the
187 .Pa identity.pub
188 to
189 .Pa $HOME/.ssh/authorized_keys
190 in his/her home directory on the remote machine (the
191 .Pa authorized_keys
192 file corresponds to the conventional
193 .Pa $HOME/.rhosts
194 file, and has one key
195 per line, though the lines can be very long).
196 After this, the user can log in without giving the password.
197 RSA authentication is much
198 more secure than rhosts authentication.
199 .Pp
200 The most convenient way to use RSA authentication may be with an
201 authentication agent.
202 See
203 .Xr ssh-agent 1
204 for more information.
205 .Pp
206 If other authentication methods fail,
207 .Nm
208 prompts the user for a password.
209 The password is sent to the remote
210 host for checking; however, since all communications are encrypted,
211 the password cannot be seen by someone listening on the network.
212 .Pp
213 .Ss SSH protocol version 2
214 .Pp
215 When a user connects using protocol version 2
216 similar authentication methods are available.
217 Using the default values for
218 .Cm PreferredAuthentications ,
219 the client will try to authenticate first using the hostbased method;
220 if this method fails public key authentication is attempted,
221 and finally if this method fails keyboard-interactive and
222 password authentication are tried.
223 .Pp
224 The public key method is similar to RSA authentication described
225 in the previous section and allows the RSA or DSA algorithm to be used:
226 The client uses his private key,
227 .Pa $HOME/.ssh/id_dsa
228 or
229 .Pa $HOME/.ssh/id_rsa ,
230 to sign the session identifier and sends the result to the server.
231 The server checks whether the matching public key is listed in
232 .Pa $HOME/.ssh/authorized_keys
233 and grants access if both the key is found and the signature is correct.
234 The session identifier is derived from a shared Diffie-Hellman value
235 and is only known to the client and the server.
236 .Pp
237 If public key authentication fails or is not available a password
238 can be sent encrypted to the remote host for proving the user's identity.
239 .Pp
240 Additionally,
241 .Nm
242 supports hostbased or challenge response authentication.
243 .Pp
244 Protocol 2 provides additional mechanisms for confidentiality
245 (the traffic is encrypted using 3DES, Blowfish, CAST128 or Arcfour)
246 and integrity (hmac-md5, hmac-sha1).
247 Note that protocol 1 lacks a strong mechanism for ensuring the
248 integrity of the connection.
249 .Pp
250 .Ss Login session and remote execution
251 .Pp
252 When the user's identity has been accepted by the server, the server
253 either executes the given command, or logs into the machine and gives
254 the user a normal shell on the remote machine.
255 All communication with
256 the remote command or shell will be automatically encrypted.
257 .Pp
258 If a pseudo-terminal has been allocated (normal login session), the
259 user may use the escape characters noted below.
260 .Pp
261 If no pseudo tty has been allocated, the
262 session is transparent and can be used to reliably transfer binary
263 data.
264 On most systems, setting the escape character to
265 .Dq none
266 will also make the session transparent even if a tty is used.
267 .Pp
268 The session terminates when the command or shell on the remote
269 machine exits and all X11 and TCP/IP connections have been closed.
270 The exit status of the remote program is returned as the exit status
271 of
272 .Nm ssh .
273 .Pp
274 .Ss Escape Characters
275 .Pp
276 When a pseudo terminal has been requested, ssh supports a number of functions
277 through the use of an escape character.
278 .Pp
279 A single tilde character can be sent as
280 .Ic ~~
281 or by following the tilde by a character other than those described below.
282 The escape character must always follow a newline to be interpreted as
283 special.
284 The escape character can be changed in configuration files using the
285 .Cm EscapeChar
286 configuration directive or on the command line by the
287 .Fl e
288 option.
289 .Pp
290 The supported escapes (assuming the default
291 .Ql ~ )
292 are:
293 .Bl -tag -width Ds
294 .It Cm ~.
295 Disconnect
296 .It Cm ~^Z
297 Background ssh
298 .It Cm ~#
299 List forwarded connections
300 .It Cm ~&
301 Background ssh at logout when waiting for forwarded connection / X11 sessions
302 to terminate
303 .It Cm ~?
304 Display a list of escape characters
305 .It Cm ~C
306 Open command line (only useful for adding port forwardings using the
307 .Fl L
308 and
309 .Fl R
310 options)
311 .It Cm ~R
312 Request rekeying of the connection (only useful for SSH protocol version 2
313 and if the peer supports it)
314 .El
315 .Pp
316 .Ss X11 and TCP forwarding
317 .Pp
318 If the
319 .Cm ForwardX11
320 variable is set to
321 .Dq yes
322 (or, see the description of the
323 .Fl X
324 and
325 .Fl x
326 options described later)
327 and the user is using X11 (the
328 .Ev DISPLAY
329 environment variable is set), the connection to the X11 display is
330 automatically forwarded to the remote side in such a way that any X11
331 programs started from the shell (or command) will go through the
332 encrypted channel, and the connection to the real X server will be made
333 from the local machine.
334 The user should not manually set
335 .Ev DISPLAY .
336 Forwarding of X11 connections can be
337 configured on the command line or in configuration files.
338 Take note that X11 forwarding can represent a security hazard.
339 .Pp
340 The
341 .Ev DISPLAY
342 value set by
343 .Nm
344 will point to the server machine, but with a display number greater
345 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 .Pp
379 .Ss Server authentication
380 .Pp
381 .Nm
382 automatically maintains and checks a database containing
383 identifications for all hosts it has ever been used with.
384 Host keys are stored in
385 .Pa $HOME/.ssh/known_hosts
386 in the user's home directory.
387 Additionally, the file
388 .Pa /etc/ssh/ssh_known_hosts
389 is automatically checked for known hosts.
390 Any new hosts are automatically added to the user's file.
391 If a host's identification
392 ever changes,
393 .Nm
394 warns about this and disables password authentication to prevent a
395 trojan horse from getting the user's password.
396 Another purpose of
397 this mechanism is to prevent man-in-the-middle attacks which could
398 otherwise be used to circumvent the encryption.
399 The
400 .Cm StrictHostKeyChecking
401 option can be used to prevent logins to machines whose
402 host key is not known or has changed.
403 .Pp
404 The options are as follows:
405 .Bl -tag -width Ds
406 .It Fl a
407 Disables forwarding of the authentication agent connection.
408 .It Fl A
409 Enables forwarding of the authentication agent connection.
410 This can also be specified on a per-host basis in a configuration file.
411 .Pp
412 Agent forwarding should be enabled with caution.
413 Users with the ability to bypass file permissions on the remote host
414 (for the agent's Unix-domain socket)
415 can access the local agent through the forwarded connection.
416 An attacker cannot obtain key material from the agent,
417 however they can perform operations on the keys that enable them to
418 authenticate using the identities loaded into the agent.
419 .It Fl b Ar bind_address
420 Specify the interface to transmit from on machines with multiple
421 interfaces or aliased addresses.
422 .It Fl c Ar blowfish|3des|des
423 Selects the cipher to use for encrypting the session.
424 .Ar 3des
425 is used by default.
426 It is believed to be secure.
427 .Ar 3des
428 (triple-des) is an encrypt-decrypt-encrypt triple with three different keys.
429 .Ar blowfish
430 is a fast block cipher, it appears very secure and is much faster than
431 .Ar 3des .
432 .Ar des
433 is only supported in the
434 .Nm
435 client for interoperability with legacy protocol 1 implementations
436 that do not support the
437 .Ar 3des
438 cipher.
439 Its use is strongly discouraged due to cryptographic weaknesses.
440 .It Fl c Ar cipher_spec
441 Additionally, for protocol version 2 a comma-separated list of ciphers can
442 be specified in order of preference.
443 See
444 .Cm Ciphers
445 for more information.
446 .It Fl e Ar ch|^ch|none
447 Sets the escape character for sessions with a pty (default:
448 .Ql ~ ) .
449 The escape character is only recognized at the beginning of a line.
450 The escape character followed by a dot
451 .Pq Ql \&.
452 closes the connection, followed
453 by control-Z suspends the connection, and followed by itself sends the
454 escape character once.
455 Setting the character to
456 .Dq none
457 disables any escapes and makes the session fully transparent.
458 .It Fl f
459 Requests
460 .Nm
461 to go to background just before command execution.
462 This is useful if
463 .Nm
464 is going to ask for passwords or passphrases, but the user
465 wants it in the background.
466 This implies
467 .Fl n .
468 The recommended way to start X11 programs at a remote site is with
469 something like
470 .Ic ssh -f host xterm .
471 .It Fl g
472 Allows remote hosts to connect to local forwarded ports.
473 .It Fl i Ar identity_file
474 Selects a file from which the identity (private key) for
475 RSA or DSA authentication is read.
476 The default is
477 .Pa $HOME/.ssh/identity
478 for protocol version 1, and
479 .Pa $HOME/.ssh/id_rsa
480 and
481 .Pa $HOME/.ssh/id_dsa
482 for protocol version 2.
483 Identity files may also be specified on
484 a per-host basis in the configuration file.
485 It is possible to have multiple
486 .Fl i
487 options (and multiple identities specified in
488 configuration files).
489 .It Fl I Ar smartcard_device
490 Specifies which smartcard device to use. The argument is
491 the device
492 .Nm
493 should use to communicate with a smartcard used for storing the user's
494 private RSA key.
495 .It Fl k
496 Disables forwarding of Kerberos tickets and AFS tokens.
497 This may also be specified on a per-host basis in the configuration file.
498 .It Fl l Ar login_name
499 Specifies the user to log in as on the remote machine.
500 This also may be specified on a per-host basis in the configuration file.
501 .It Fl m Ar mac_spec
502 Additionally, for protocol version 2 a comma-separated list of MAC
503 (message authentication code) algorithms can
504 be specified in order of preference.
505 See the
506 .Cm MACs
507 keyword for more information.
508 .It Fl n
509 Redirects stdin from
510 .Pa /dev/null
511 (actually, prevents reading from stdin).
512 This must be used when
513 .Nm
514 is run in the background.
515 A common trick is to use this to run X11 programs on a remote machine.
516 For example,
517 .Ic ssh -n shadows.cs.hut.fi emacs &
518 will start an emacs on shadows.cs.hut.fi, and the X11
519 connection will be automatically forwarded over an encrypted channel.
520 The
521 .Nm
522 program will be put in the background.
523 (This does not work if
524 .Nm
525 needs to ask for a password or passphrase; see also the
526 .Fl f
527 option.)
528 .It Fl N
529 Do not execute a remote command.
530 This is useful for just forwarding ports
531 (protocol version 2 only).
532 .It Fl o Ar option
533 Can be used to give options in the format used in the configuration file.
534 This is useful for specifying options for which there is no separate
535 command-line flag.
536 .It Fl p Ar port
537 Port to connect to on the remote host.
538 This can be specified on a
539 per-host basis in the configuration file.
540 .It Fl q
541 Quiet mode.
542 Causes all warning and diagnostic messages to be suppressed.
543 .It Fl s
544 May be used to request invocation of a subsystem on the remote system. Subsystems are a feature of the SSH2 protocol which facilitate the use
545 of SSH as a secure transport for other applications (eg. sftp). The
546 subsystem is specified as the remote command.
547 .It Fl t
548 Force pseudo-tty allocation.
549 This can be used to execute arbitrary
550 screen-based programs on a remote machine, which can be very useful,
551 e.g., when implementing menu services.
552 Multiple
553 .Fl t
554 options force tty allocation, even if
555 .Nm
556 has no local tty.
557 .It Fl T
558 Disable pseudo-tty allocation.
559 .It Fl v
560 Verbose mode.
561 Causes
562 .Nm
563 to print debugging messages about its progress.
564 This is helpful in
565 debugging connection, authentication, and configuration problems.
566 Multiple
567 .Fl v
568 options increases the verbosity.
569 Maximum is 3.
570 .It Fl x
571 Disables X11 forwarding.
572 .It Fl X
573 Enables X11 forwarding.
574 This can also be specified on a per-host basis in a configuration file.
575 .Pp
576 X11 forwarding should be enabled with caution.
577 Users with the ability to bypass file permissions on the remote host
578 (for the user's X authorization database)
579 can access the local X11 display through the forwarded connection.
580 An attacker may then be able to perform activities such as keystroke monitoring.
581 .It Fl C
582 Requests compression of all data (including stdin, stdout, stderr, and
583 data for forwarded X11 and TCP/IP connections).
584 The compression algorithm is the same used by
585 .Xr gzip 1 ,
586 and the
587 .Dq level
588 can be controlled by the
589 .Cm CompressionLevel
590 option for protocol version 1.
591 Compression is desirable on modem lines and other
592 slow connections, but will only slow down things on fast networks.
593 The default value can be set on a host-by-host basis in the
594 configuration files; see the
595 .Cm Compression
596 option.
597 .It Fl F Ar configfile
598 Specifies an alternative per-user configuration file.
599 If a configuration file is given on the command line,
600 the system-wide configuration file
601 .Pq Pa /etc/ssh/ssh_config
602 will be ignored.
603 The default for the per-user configuration file is
604 .Pa $HOME/.ssh/config .
605 .It Fl L Ar port:host:hostport
606 Specifies that the given port on the local (client) host is to be
607 forwarded to the given host and port on the remote side.
608 This works by allocating a socket to listen to
609 .Ar port
610 on the local side, and whenever a connection is made to this port, the
611 connection is forwarded over the secure channel, and a connection is
612 made to
613 .Ar host
614 port
615 .Ar hostport
616 from the remote machine.
617 Port forwardings can also be specified in the configuration file.
618 Only root can forward privileged ports.
619 IPv6 addresses can be specified with an alternative syntax:
620 .Ar port/host/hostport
621 .It Fl R Ar port:host:hostport
622 Specifies that the given port on the remote (server) host is to be
623 forwarded to the given host and port on the local side.
624 This works by allocating a socket to listen to
625 .Ar port
626 on the remote side, and whenever a connection is made to this port, the
627 connection is forwarded over the secure channel, and a connection is
628 made to
629 .Ar host
630 port
631 .Ar hostport
632 from the local machine.
633 Port forwardings can also be specified in the configuration file.
634 Privileged ports can be forwarded only when
635 logging in as root on the remote machine.
636 IPv6 addresses can be specified with an alternative syntax:
637 .Ar port/host/hostport
638 .It Fl D Ar port
639 Specifies a local
640 .Dq dynamic
641 application-level port forwarding.
642 This works by allocating a socket to listen to
643 .Ar port
644 on the local side, and whenever a connection is made to this port, the
645 connection is forwarded over the secure channel, and the application
646 protocol is then used to determine where to connect to from the
647 remote machine.
648 Currently the SOCKS4 protocol is supported, and
649 .Nm
650 will act as a SOCKS4 server.
651 Only root can forward privileged ports.
652 Dynamic port forwardings can also be specified in the configuration file.
653 .It Fl 1
654 Forces
655 .Nm
656 to try protocol version 1 only.
657 .It Fl 2
658 Forces
659 .Nm
660 to try protocol version 2 only.
661 .It Fl 4
662 Forces
663 .Nm
664 to use IPv4 addresses only.
665 .It Fl 6
666 Forces
667 .Nm
668 to use IPv6 addresses only.
669 .El
670 .Sh CONFIGURATION FILES
671 .Nm
672 may additionally obtain configuration data from
673 a per-user configuration file and a system-wide configuration file.
674 The file format and configuration options are described in
675 .Xr ssh_config 5 .
676 .Sh ENVIRONMENT
677 .Nm
678 will normally set the following environment variables:
679 .Bl -tag -width Ds
680 .It Ev DISPLAY
681 The
682 .Ev DISPLAY
683 variable indicates the location of the X11 server.
684 It is automatically set by
685 .Nm
686 to point to a value of the form
687 .Dq hostname:n
688 where hostname indicates
689 the host where the shell runs, and n is an integer \*(>= 1.
690 .Nm
691 uses this special value to forward X11 connections over the secure
692 channel.
693 The user should normally not set
694 .Ev DISPLAY
695 explicitly, as that
696 will render the X11 connection insecure (and will require the user to
697 manually copy any required authorization cookies).
698 .It Ev HOME
699 Set to the path of the user's home directory.
700 .It Ev LOGNAME
701 Synonym for
702 .Ev USER ;
703 set for compatibility with systems that use this variable.
704 .It Ev MAIL
705 Set to the path of the user's mailbox.
706 .It Ev PATH
707 Set to the default
708 .Ev PATH ,
709 as specified when compiling
710 .Nm ssh .
711 .It Ev SSH_ASKPASS
712 If
713 .Nm
714 needs a passphrase, it will read the passphrase from the current
715 terminal if it was run from a terminal.
716 If
717 .Nm
718 does not have a terminal associated with it but
719 .Ev DISPLAY
720 and
721 .Ev SSH_ASKPASS
722 are set, it will execute the program specified by
723 .Ev SSH_ASKPASS
724 and open an X11 window to read the passphrase.
725 This is particularly useful when calling
726 .Nm
727 from a
728 .Pa .Xsession
729 or related script.
730 (Note that on some machines it
731 may be necessary to redirect the input from
732 .Pa /dev/null
733 to make this work.)
734 .It Ev SSH_AUTH_SOCK
735 Identifies the path of a unix-domain socket used to communicate with the
736 agent.
737 .It Ev SSH_CONNECTION
738 Identifies the client and server ends of the connection.
739 The variable contains
740 four space-separated values: client ip-address, client port number,
741 server ip-address and server port number.
742 .It Ev SSH_ORIGINAL_COMMAND
743 The variable contains the original command line if a forced command
744 is executed.
745 It can be used to extract the original arguments.
746 .It Ev SSH_TTY
747 This is set to the name of the tty (path to the device) associated
748 with the current shell or command.
749 If the current session has no tty,
750 this variable is not set.
751 .It Ev TZ
752 The timezone variable is set to indicate the present timezone if it
753 was set when the daemon was started (i.e., the daemon passes the value
754 on to new connections).
755 .It Ev USER
756 Set to the name of the user logging in.
757 .El
758 .Pp
759 Additionally,
760 .Nm
761 reads
762 .Pa $HOME/.ssh/environment ,
763 and adds lines of the format
764 .Dq VARNAME=value
765 to the environment if the file exists and if users are allowed to
766 change their environment.
767 See the
768 .Cm PermitUserEnvironment
769 option in
770 .Xr sshd_config 5 .
771 .Sh FILES
772 .Bl -tag -width Ds
773 .It Pa $HOME/.ssh/known_hosts
774 Records host keys for all hosts the user has logged into that are not
775 in
776 .Pa /etc/ssh/ssh_known_hosts .
777 See
778 .Xr sshd 8 .
779 .It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa
780 Contains the authentication identity of the user.
781 They are for protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively.
782 These files
783 contain sensitive data and should be readable by the user but not
784 accessible by others (read/write/execute).
785 Note that
786 .Nm
787 ignores a private key file if it is accessible by others.
788 It is possible to specify a passphrase when
789 generating the key; the passphrase will be used to encrypt the
790 sensitive part of this file using 3DES.
791 .It Pa $HOME/.ssh/identity.pub, $HOME/.ssh/id_dsa.pub, $HOME/.ssh/id_rsa.pub
792 Contains the public key for authentication (public part of the
793 identity file in human-readable form).
794 The contents of the
795 .Pa $HOME/.ssh/identity.pub
796 file should be added to
797 .Pa $HOME/.ssh/authorized_keys
798 on all machines
799 where the user wishes to log in using protocol version 1 RSA authentication.
800 The contents of the
801 .Pa $HOME/.ssh/id_dsa.pub
802 and
803 .Pa $HOME/.ssh/id_rsa.pub
804 file should be added to
805 .Pa $HOME/.ssh/authorized_keys
806 on all machines
807 where the user wishes to log in using protocol version 2 DSA/RSA authentication.
808 These files are not
809 sensitive and can (but need not) be readable by anyone.
810 These files are
811 never used automatically and are not necessary; they are only provided for
812 the convenience of the user.
813 .It Pa $HOME/.ssh/config
814 This is the per-user configuration file.
815 The file format and configuration options are described in
816 .Xr ssh_config 5 .
817 .It Pa $HOME/.ssh/authorized_keys
818 Lists the public keys (RSA/DSA) that can be used for logging in as this user.
819 The format of this file is described in the
820 .Xr sshd 8
821 manual page.
822 In the simplest form the format is the same as the .pub
823 identity files.
824 This file is not highly sensitive, but the recommended
825 permissions are read/write for the user, and not accessible by others.
826 .It Pa /etc/ssh/ssh_known_hosts
827 Systemwide list of known host keys.
828 This file should be prepared by the
829 system administrator to contain the public host keys of all machines in the
830 organization.
831 This file should be world-readable.
832 This file contains
833 public keys, one per line, in the following format (fields separated
834 by spaces): system name, public key and optional comment field.
835 When different names are used
836 for the same machine, all such names should be listed, separated by
837 commas.
838 The format is described on the
839 .Xr sshd 8
840 manual page.
841 .Pp
842 The canonical system name (as returned by name servers) is used by
843 .Xr sshd 8
844 to verify the client host when logging in; other names are needed because
845 .Nm
846 does not convert the user-supplied name to a canonical name before
847 checking the key, because someone with access to the name servers
848 would then be able to fool host authentication.
849 .It Pa /etc/ssh/ssh_config
850 Systemwide configuration file.
851 The file format and configuration options are described in
852 .Xr ssh_config 5 .
853 .It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key
854 These three files contain the private parts of the host keys
855 and are used for
856 .Cm RhostsRSAAuthentication
857 and
858 .Cm HostbasedAuthentication .
859 If the protocol version 1
860 .Cm RhostsRSAAuthentication
861 method is used,
862 .Nm
863 must be setuid root, since the host key is readable only by root.
864 For protocol version 2,
865 .Nm
866 uses
867 .Xr ssh-keysign 8
868 to access the host keys for
869 .Cm HostbasedAuthentication .
870 This eliminates the requirement that
871 .Nm
872 be setuid root when that authentication method is used.
873 By default
874 .Nm
875 is not setuid root.
876 .It Pa $HOME/.rhosts
877 This file is used in
878 .Pa \&.rhosts
879 authentication to list the
880 host/user pairs that are permitted to log in.
881 (Note that this file is
882 also used by rlogin and rsh, which makes using this file insecure.)
883 Each line of the file contains a host name (in the canonical form
884 returned by name servers), and then a user name on that host,
885 separated by a space.
886 On some machines this file may need to be
887 world-readable if the user's home directory is on a NFS partition,
888 because
889 .Xr sshd 8
890 reads it as root.
891 Additionally, this file must be owned by the user,
892 and must not have write permissions for anyone else.
893 The recommended
894 permission for most machines is read/write for the user, and not
895 accessible by others.
896 .Pp
897 Note that by default
898 .Xr sshd 8
899 will be installed so that it requires successful RSA host
900 authentication before permitting \s+2.\s0rhosts authentication.
901 If the server machine does not have the client's host key in
902 .Pa /etc/ssh/ssh_known_hosts ,
903 it can be stored in
904 .Pa $HOME/.ssh/known_hosts .
905 The easiest way to do this is to
906 connect back to the client from the server machine using ssh; this
907 will automatically add the host key to
908 .Pa $HOME/.ssh/known_hosts .
909 .It Pa $HOME/.shosts
910 This file is used exactly the same way as
911 .Pa \&.rhosts .
912 The purpose for
913 having this file is to be able to use rhosts authentication with
914 .Nm
915 without permitting login with
916 .Nm rlogin
917 or
918 .Xr rsh 1 .
919 .It Pa /etc/hosts.equiv
920 This file is used during
921 .Pa \&.rhosts
922 authentication.
923 It contains
924 canonical hosts names, one per line (the full format is described on
925 the
926 .Xr sshd 8
927 manual page).
928 If the client host is found in this file, login is
929 automatically permitted provided client and server user names are the
930 same.
931 Additionally, successful RSA host authentication is normally
932 required.
933 This file should only be writable by root.
934 .It Pa /etc/ssh/shosts.equiv
935 This file is processed exactly as
936 .Pa /etc/hosts.equiv .
937 This file may be useful to permit logins using
938 .Nm
939 but not using rsh/rlogin.
940 .It Pa /etc/ssh/sshrc
941 Commands in this file are executed by
942 .Nm
943 when the user logs in just before the user's shell (or command) is started.
944 See the
945 .Xr sshd 8
946 manual page for more information.
947 .It Pa $HOME/.ssh/rc
948 Commands in this file are executed by
949 .Nm
950 when the user logs in just before the user's shell (or command) is
951 started.
952 See the
953 .Xr sshd 8
954 manual page for more information.
955 .It Pa $HOME/.ssh/environment
956 Contains additional definitions for environment variables, see section
957 .Sx ENVIRONMENT
958 above.
959 .El
960 .Sh DIAGNOSTICS
961 .Nm
962 exits with the exit status of the remote command or with 255
963 if an error occurred.
964 .Sh AUTHORS
965 OpenSSH is a derivative of the original and free
966 ssh 1.2.12 release by Tatu Ylonen.
967 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
968 Theo de Raadt and Dug Song
969 removed many bugs, re-added newer features and
970 created OpenSSH.
971 Markus Friedl contributed the support for SSH
972 protocol versions 1.5 and 2.0.
973 .Sh SEE ALSO
974 .Xr rsh 1 ,
975 .Xr scp 1 ,
976 .Xr sftp 1 ,
977 .Xr ssh-add 1 ,
978 .Xr ssh-agent 1 ,
979 .Xr ssh-keygen 1 ,
980 .Xr telnet 1 ,
981 .Xr ssh_config 5 ,
982 .Xr ssh-keysign 8 ,
983 .Xr sshd 8
984 .Rs
985 .%A T. Ylonen
986 .%A T. Kivinen
987 .%A M. Saarinen
988 .%A T. Rinne
989 .%A S. Lehtinen
990 .%T "SSH Protocol Architecture"
991 .%N draft-ietf-secsh-architecture-12.txt
992 .%D January 2002
993 .%O work in progress material
994 .Re