]> andersk Git - openssh.git/blob - ssh.1
be1290f249f9a1cf2fd818cd99c0d5bf569a3e6e
[openssh.git] / ssh.1
1 .\"  -*- nroff -*-
2 .\"
3 .\" ssh.1.in
4 .\"
5 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
6 .\"
7 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
8 .\"                    All rights reserved
9 .\"
10 .\" Created: Sat Apr 22 21:55:14 1995 ylo
11 .\"
12 .\" $Id$
13 .\"
14 .Dd September 25, 1999
15 .Dt SSH 1
16 .Os
17 .Sh NAME
18 .Nm ssh
19 .Nd OpenSSH secure shell client (remote login program)
20 .Sh SYNOPSIS
21 .Nm ssh
22 .Op Fl l Ar login_name
23 .Op Ar hostname | user@hostname
24 .Op Ar command
25 .Pp
26 .Nm ssh
27 .Op Fl afgknqtvxCPX
28 .Op Fl c Ar blowfish | 3des
29 .Op Fl e Ar escape_char
30 .Op Fl i Ar identity_file
31 .Op Fl l Ar login_name
32 .Op Fl o Ar option
33 .Op Fl p Ar port
34 .Oo Fl L Xo
35 .Sm off
36 .Ar host :
37 .Ar port :
38 .Ar hostport
39 .Sm on
40 .Xc
41 .Oc
42 .Oo Fl R Xo
43 .Sm off
44 .Ar host :
45 .Ar port :
46 .Ar hostport
47 .Sm on
48 .Xc
49 .Oc
50 .Op Ar hostname | user@hostname
51 .Op Ar command
52 .Sh DESCRIPTION 
53 .Nm
54 (Secure Shell) is a program for logging into a remote machine and for
55 executing commands on a remote machine.  It is intended to replace
56 rlogin and rsh, and provide secure encrypted communications between
57 two untrusted hosts over an insecure network.  X11 connections and
58 arbitrary TCP/IP ports can also be forwarded over the secure channel.
59 .Pp
60 .Nm
61 connects and logs into the specified 
62 .Ar hostname .
63 The user must prove
64 his/her identity to the remote machine using one of several methods.
65 .Pp
66 First, if the machine the user logs in from is listed in
67 .Pa /etc/hosts.equiv
68 or
69 .Pa /etc/ssh/shosts.equiv
70 on the remote machine, and the user names are
71 the same on both sides, the user is immediately permitted to log in.
72 Second, if 
73 .Pa \&.rhosts
74 or
75 .Pa \&.shosts
76 exists in the user's home directory on the
77 remote machine and contains a line containing the name of the client
78 machine and the name of the user on that machine, the user is
79 permitted to log in.  This form of authentication alone is normally not
80 allowed by the server because it is not secure.
81 .Pp
82 The second (and primary) authentication method is the
83 .Pa rhosts
84 or
85 .Pa hosts.equiv
86 method combined with RSA-based host authentication.  It
87 means that if the login would be permitted by
88 .Pa \&.rhosts ,
89 .Pa \&.shosts ,
90 .Pa /etc/hosts.equiv ,
91 or
92 .Pa /etc/ssh/shosts.equiv ,
93 and if additionally the server can verify the client's
94 host key (see 
95 .Pa /etc/ssh/ssh_known_hosts
96 and
97 .Pa $HOME/.ssh/known_hosts
98 in the
99 .Sx FILES
100 section), only then login is
101 permitted.  This authentication method closes security holes due to IP
102 spoofing, DNS spoofing and routing spoofing.  [Note to the
103 administrator:
104 .Pa /etc/hosts.equiv ,
105 .Pa \&.rhosts ,
106 and the rlogin/rsh protocol in general, are inherently insecure and should be
107 disabled if security is desired.]
108 .Pp
109 As a third authentication method, 
110 .Nm
111 supports RSA based authentication.
112 The scheme is based on public-key cryptography: there are cryptosystems
113 where encryption and decryption are done using separate keys, and it
114 is not possible to derive the decryption key from the encryption key.
115 RSA is one such system.  The idea is that each user creates a public/private 
116 key pair for authentication purposes.  The
117 server knows the public key, and only the user knows the private key.
118 The file 
119 .Pa $HOME/.ssh/authorized_keys
120 lists the public keys that are permitted for logging
121 in.  When the user logs in, the
122 .Nm
123 program tells the server which key pair it would like to use for
124 authentication.  The server checks if this key is permitted, and if
125 so, sends the user (actually the
126 .Nm
127 program running on behalf of the user) a challenge, a random number,
128 encrypted by the user's public key.  The challenge can only be
129 decrypted using the proper private key.  The user's client then decrypts the
130 challenge using the private key, proving that he/she knows the private
131 key but without disclosing it to the server.
132 .Pp
133 .Nm
134 implements the RSA authentication protocol automatically.  The user
135 creates his/her RSA key pair by running
136 .Xr ssh-keygen 1 .
137 This stores the private key in 
138 .Pa \&.ssh/identity
139 and the public key in
140 .Pa \&.ssh/identity.pub
141 in the user's home directory.  The user should then
142 copy the 
143 .Pa identity.pub
144 to 
145 .Pa \&.ssh/authorized_keys
146 in his/her home directory on the remote machine (the 
147 .Pa authorized_keys
148 file corresponds to the conventional 
149 .Pa \&.rhosts
150 file, and has one key
151 per line, though the lines can be very long).  After this, the user
152 can log in without giving the password.  RSA authentication is much
153 more secure than rhosts authentication.
154 .Pp
155 The most convenient way to use RSA authentication may be with an
156 authentication agent.  See
157 .Xr ssh-agent 1
158 for more information.
159 .Pp
160 If other authentication methods fail, 
161 .Nm
162 prompts the user for a password.  The password is sent to the remote
163 host for checking; however, since all communications are encrypted,
164 the password cannot be seen by someone listening on the network.
165 .Pp
166 When the user's identity has been accepted by the server, the server
167 either executes the given command, or logs into the machine and gives
168 the user a normal shell on the remote machine.  All communication with
169 the remote command or shell will be automatically encrypted.
170 .Pp
171 If a pseudo-terminal has been allocated (normal login session), the
172 user can disconnect with
173 .Ic ~. ,
174 and suspend
175 .Nm
176 with
177 .Ic ~^Z .
178 All forwarded connections can be listed with
179 .Ic ~# 
180 and if
181 the session blocks waiting for forwarded X11 or TCP/IP
182 connections to terminate, it can be backgrounded with
183 .Ic ~&
184 (this should not be used while the user shell is active, as it can cause the
185 shell to hang).  All available escapes can be listed with
186 .Ic ~? .
187 .Pp
188 A single tilde character can be sent as
189 .Ic ~~
190 (or by following the tilde by a character other than those described above).
191 The escape character must always follow a newline to be interpreted as
192 special.  The escape character can be changed in configuration files
193 or on the command line.  
194 .Pp
195 If no pseudo tty has been allocated, the
196 session is transparent and can be used to reliably transfer binary
197 data.  On most systems, setting the escape character to
198 .Dq none
199 will also make the session transparent even if a tty is used.
200 .Pp
201 The session terminates when the command or shell in on the remote
202 machine exists and all X11 and TCP/IP connections have been closed.
203 The exit status of the remote program is returned as the exit status
204 of
205 .Nm ssh .
206 .Pp
207 If the user is using X11 (the
208 .Ev DISPLAY
209 environment variable is set), the connection to the X11 display is
210 automatically forwarded to the remote side in such a way that any X11
211 programs started from the shell (or command) will go through the
212 encrypted channel, and the connection to the real X server will be made
213 from the local machine.  The user should not manually set
214 .Ev DISPLAY .
215 Forwarding of X11 connections can be
216 configured on the command line or in configuration files.
217 .Pp
218 The
219 .Ev DISPLAY 
220 value set by
221 .Nm
222 will point to the server machine, but with a display number greater
223 than zero.  This is normal, and happens because
224 .Nm
225 creates a
226 .Dq proxy
227 X server on the server machine for forwarding the
228 connections over the encrypted channel.
229 .Pp
230 .Nm
231 will also automatically set up Xauthority data on the server machine.
232 For this purpose, it will generate a random authorization cookie,
233 store it in Xauthority on the server, and verify that any forwarded
234 connections carry this cookie and replace it by the real cookie when
235 the connection is opened.  The real authentication cookie is never
236 sent to the server machine (and no cookies are sent in the plain).
237 .Pp
238 If the user is using an authentication agent, the connection to the agent
239 is automatically forwarded to the remote side unless disabled on
240 command line or in a configuration file.
241 .Pp
242 Forwarding of arbitrary TCP/IP connections over the secure channel can
243 be specified either on command line or in a configuration file.  One
244 possible application of TCP/IP forwarding is a secure connection to an
245 electronic purse; another is going trough firewalls.
246 .Pp
247 .Nm
248 automatically maintains and checks a database containing RSA-based
249 identifications for all hosts it has ever been used with.  The
250 database is stored in 
251 .Pa \&.ssh/known_hosts
252 in the user's home directory.  Additionally, the file 
253 .Pa /etc/ssh/ssh_known_hosts
254 is automatically checked for known hosts.  Any new hosts are
255 automatically added to the user's file.  If a host's identification
256 ever changes,
257 .Nm
258 warns about this and disables password authentication to prevent a
259 trojan horse from getting the user's password.  Another purpose of
260 this mechanism is to prevent man-in-the-middle attacks which could
261 otherwise be used to circumvent the encryption.  The
262 .Cm StrictHostKeyChecking
263 option (see below) can be used to prevent logins to machines whose
264 host key is not known or has changed.
265 .Sh OPTIONS
266 .Bl -tag -width Ds
267 .It Fl a
268 Disables forwarding of the authentication agent connection. This may
269 also be specified on a per-host basis in the configuration file.
270 .It Fl c Ar blowfish|3des
271 Selects the cipher to use for encrypting the session. 
272 .Ar 3des
273 is used by default.  It is believed to be secure. 
274 .Ar 3des
275 (triple-des) is an encrypt-decrypt-encrypt triple with three different keys.
276 It is presumably more secure than the
277 .Ar des
278 cipher which is no longer supported in ssh.
279 .Ar blowfish
280 is a fast block cipher, it appears very secure and is much faster than
281 .Ar 3des .  
282 .It Fl e Ar ch|^ch|none
283 Sets the escape character for sessions with a pty (default:
284 .Ql ~ ) .
285 The escape character is only recognized at the beginning of a line.  The
286 escape character followed by a dot
287 .Pq Ql \&.
288 closes the connection, followed
289 by control-Z suspends the connection, and followed by itself sends the
290 escape character once.  Setting the character to
291 .Dq none
292 disables any escapes and makes the session fully transparent.
293 .It Fl f
294 Requests
295 .Nm
296 to go to background after authentication.  This is useful
297 if
298 .Nm
299 is going to ask for passwords or passphrases, but the user
300 wants it in the background.  This implies 
301 .Fl n .
302 The recommended way to start X11 programs at a remote site is with
303 something like
304 .Ic ssh -f host xterm .
305 .It Fl i Ar identity_file
306 Selects the file from which the identity (private key) for 
307 RSA authentication is read.  Default is 
308 .Pa \&.ssh/identity
309 in the user's home directory.  Identity files may also be specified on
310 a per-host basis in the configuration file.  It is possible to have
311 multiple
312 .Fl i
313 options (and multiple identities specified in
314 configuration files).
315 .It Fl g
316 Allows remote hosts to connect to local forwarded ports.
317 .It Fl k
318 Disables forwarding of Kerberos tickets and AFS tokens. This may
319 also be specified on a per-host basis in the configuration file.
320 .It Fl l Ar login_name
321 Specifies the user to log in as on the remote machine.  This may also
322 be specified on a per-host basis in the configuration file.
323 .It Fl n
324 Redirects stdin from
325 .Pa /dev/null
326 (actually, prevents reading from stdin).
327 This must be used when
328 .Nm
329 is run in the background.  A common trick is to use this to run X11
330 programs in a remote machine.  For example,
331 .Ic ssh -n shadows.cs.hut.fi emacs &
332 will start an emacs on shadows.cs.hut.fi, and the X11
333 connection will be automatically forwarded over an encrypted channel.
334 The
335 .Nm
336 program will be put in the background.
337 (This does not work if
338 .Nm
339 needs to ask for a password or passphrase; see also the
340 .Fl f
341 option.)
342 .It Fl o Ar option
343 Can be used to give options in the format used in the config file.
344 This is useful for specifying options for which there is no separate
345 command-line flag.  The option has the same format as a line in the
346 configuration file.
347 .It Fl p Ar port
348 Port to connect to on the remote host.  This can be specified on a
349 per-host basis in the configuration file.
350 .It Fl P
351 Use a non-privileged port for outgoing connections.
352 This can be used if your firewall does
353 not permit connections from privileged ports.
354 Note that this option turns of
355 .Cm RhostsAuthentication
356 and
357 .Cm RhostsRSAAuthentication .
358 .It Fl q
359 Quiet mode.  Causes all warning and diagnostic messages to be
360 suppressed.  Only fatal errors are displayed.
361 .It Fl t
362 Force pseudo-tty allocation.  This can be used to execute arbitary
363 screen-based programs on a remote machine, which can be very useful
364 e.g. when implementing menu services.
365 .It Fl v
366 Verbose mode.  Causes
367 .Nm
368 to print debugging messages about its progress.  This is helpful in
369 debugging connection, authentication, and configuration problems.
370 The verbose mode is also used to display
371 .Xr skey 1
372 challenges, if the user entered "s/key" as password.
373 .It Fl x
374 Disables X11 forwarding.  This can also be specified on a per-host
375 basis in a configuration file.
376 .It Fl X
377 Enables X11 forwarding.
378 .It Fl C
379 Requests compression of all data (including stdin, stdout, stderr, and
380 data for forwarded X11 and TCP/IP connections).  The compression
381 algorithm is the same used by gzip, and the
382 .Dq level
383 can be controlled by the
384 .Cm CompressionLevel
385 option (see below).  Compression is desirable on modem lines and other
386 slow connections, but will only slow down things on fast networks.
387 The default value can be set on a host-by-host basis in the
388 configuration files; see the
389 .Cm Compress
390 option below.
391 .It Fl L Ar port:host:hostport
392 Specifies that the given port on the local (client) host is to be
393 forwarded to the given host and port on the remote side.  This works
394 by allocating a socket to listen to
395 .Ar port
396 on the local side, and whenever a connection is made to this port, the
397 connection is forwarded over the secure channel, and a connection is
398 made to
399 .Ar host:hostport
400 from the remote machine.  Port forwardings can also be specified in the
401 configuration file.  Only root can forward privileged ports.
402 .It Fl R Ar port:host:hostport
403 Specifies that the given port on the remote (server) host is to be
404 forwarded to the given host and port on the local side.  This works
405 by allocating a socket to listen to
406 .Ar port
407 on the remote side, and whenever a connection is made to this port, the
408 connection is forwarded over the secure channel, and a connection is
409 made to
410 .Ar host:hostport
411 from the local machine.  Port forwardings can also be specified in the
412 configuration file.  Privileged ports can be forwarded only when
413 logging in as root on the remote machine.
414 .El
415 .Sh CONFIGURATION FILES
416 .Nm
417 obtains configuration data from the following sources (in this order):
418 command line options, user's configuration file
419 .Pq Pa $HOME/.ssh/config ,
420 and system-wide configuration file
421 .Pq Pa /etc/ssh/ssh_config .
422 For each parameter, the first obtained value
423 will be used.  The configuration files contain sections bracketed by
424 "Host" specifications, and that section is only applied for hosts that
425 match one of the patterns given in the specification.  The matched
426 host name is the one given on the command line.
427 .Pp
428 Since the first obtained value for each parameter is used, more
429 host-specific declarations should be given near the beginning of the
430 file, and general defaults at the end.
431 .Pp
432 The configuration file has the following format:
433 .Pp
434 Empty lines and lines starting with
435 .Ql #
436 are comments.
437 .Pp
438 Otherwise a line is of the format
439 .Dq keyword arguments .
440 The possible
441 keywords and their meanings are as follows (note that the
442 configuration files are case-sensitive):
443 .Bl -tag -width Ds
444 .It Cm Host
445 Restricts the following declarations (up to the next
446 .Cm Host
447 keyword) to be only for those hosts that match one of the patterns
448 given after the keyword.
449 .Ql \&*
450 and
451 .Ql ?
452 can be used as wildcards in the
453 patterns.  A single
454 .Ql \&*
455 as a pattern can be used to provide global
456 defaults for all hosts.  The host is the
457 .Ar hostname
458 argument given on the command line (i.e., the name is not converted to
459 a canonicalized host name before matching).
460 .It Cm AFSTokenPassing
461 Specifies whether to pass AFS tokens to remote host. The argument to 
462 this keyword must be
463 .Dq yes
464 or
465 .Dq no .
466 .It Cm BatchMode
467 If set to
468 .Dq yes ,
469 passphrase/password querying will be disabled.  This
470 option is useful in scripts and other batch jobs where you have no
471 user to supply the password.  The argument must be
472 .Dq yes
473 or
474 .Dq no .
475 .It Cm Cipher
476 Specifies the cipher to use for encrypting the session.  Currently,
477 .Dq blowfish ,
478 and
479 .Dq 3des
480 are supported.  The default is
481 .Dq 3des .
482 .It Cm Compression
483 Specifies whether to use compression.  The argument must be
484 .Dq yes
485 or
486 .Dq no .
487 .It Cm CompressionLevel
488 Specifies the compression level to use if compression is enable.  The
489 argument must be an integer from 1 (fast) to 9 (slow, best).  The
490 default level is 6, which is good for most applications.  The meaning
491 of the values is the same as in GNU GZIP.
492 .It Cm ConnectionAttempts
493 Specifies the number of tries (one per second) to make before falling
494 back to rsh or exiting.  The argument must be an integer.  This may be
495 useful in scripts if the connection sometimes fails.
496 .It Cm EscapeChar
497 Sets the escape character (default:
498 .Ql ~ ) .
499 The escape character can also
500 be set on the command line.  The argument should be a single
501 character,
502 .Ql ^
503 followed by a letter, or
504 .Dq none
505 to disable the escape
506 character entirely (making the connection transparent for binary
507 data).
508 .It Cm FallBackToRsh 
509 Specifies that if connecting via
510 .Nm
511 fails due to a connection refused error (there is no
512 .Xr sshd 8
513 listening on the remote host), 
514 .Xr rsh 1
515 should automatically be used instead (after a suitable warning about
516 the session being unencrypted).  The argument must be
517 .Dq yes
518 or
519 .Dq no .
520 .It Cm ForwardAgent
521 Specifies whether the connection to the authentication agent (if any)
522 will be forwarded to the remote machine.  The argument must be
523 .Dq yes
524 or
525 .Dq no .
526 .It Cm ForwardX11
527 Specifies whether X11 connections will be automatically redirected
528 over the secure channel and 
529 .Ev DISPLAY
530 set.  The argument must be 
531 .Dq yes
532 or
533 .Dq no .
534 .It Cm GatewayPorts
535 Specifies whether remote hosts are allowed to connect to local
536 forwarded ports.
537 The argument must be
538 .Dq yes
539 or
540 .Dq no .
541 The default is
542 .Dq no .
543 .It Cm GlobalKnownHostsFile
544 Specifies a file to use instead of 
545 .Pa /etc/ssh/ssh_known_hosts .
546 .It Cm HostName
547 Specifies the real host name to log into.  This can be used to specify
548 nicnames or abbreviations for hosts.  Default is the name given on the
549 command line.  Numeric IP addresses are also permitted (both on the
550 command line and in
551 .Cm HostName
552 specifications).
553 .It Cm IdentityFile
554 Specifies the file from which the user's RSA authentication identity
555 is read (default
556 .Pa .ssh/identity
557 in the user's home directory).
558 Additionally, any identities represented by the authentication agent
559 will be used for authentication.  The file name may use the tilde
560 syntax to refer to a user's home directory.  It is possible to have
561 multiple identity files specified in configuration files; all these
562 identities will be tried in sequence.
563 .It Cm KeepAlive
564 Specifies whether the system should send keepalive messages to the
565 other side.  If they are sent, death of the connection or crash of one
566 of the machines will be properly noticed.  However, this means that
567 connections will die if the route is down temporarily, and some people
568 find it annoying.  
569 .Pp
570 The default is
571 .Dq yes
572 (to send keepalives), and the client will notice
573 if the network goes down or the remote host dies.  This is important
574 in scripts, and many users want it too.
575 .Pp
576 To disable keepalives, the value should be set to
577 .Dq no
578 in both the server and the client configuration files.
579 .It Cm KerberosAuthentication
580 Specifies whether Kerberos authentication will be used. The argument to 
581 this keyword must be
582 .Dq yes
583 or
584 .Dq no .
585 .It Cm KerberosTgtPassing
586 Specifies whether a Kerberos TGT will be forwarded to the server. This
587 will only work if the Kerberos server is actually an AFS kaserver. The
588 argument to this keyword must be
589 .Dq yes
590 or
591 .Dq no .
592 .It Cm LocalForward
593 Specifies that a TCP/IP port on the local machine be forwarded over
594 the secure channel to given host:port from the remote machine.  The
595 first argument must be a port number, and the second must be
596 host:port.  Multiple forwardings may be specified, and additional
597 forwardings can be given on the command line.  Only the root can
598 forward privileged ports.
599 .It Cm PasswordAuthentication
600 Specifies whether to use password authentication.  The argument to
601 this keyword must be
602 .Dq yes
603 or
604 .Dq no .
605 .It Cm LogLevel
606 Gives the verbosity level that is used when logging messages from
607 .Nm ssh .
608 The possible values are:
609 QUIET, FATAL, ERROR, INFO, CHAT and DEBUG.
610 The default is INFO.
611 .It Cm NumberOfPasswordPrompts
612 Specifies the number of password prompts before giving up. The
613 argument to this keyword must be an integer. Default is 3.
614 .It Cm Port
615 Specifies the port number to connect on the remote host.  Default is
616 22.
617 .It Cm ProxyCommand
618 Specifies the command to use to connect to the server.  The command
619 string extends to the end of the line, and is executed with /bin/sh.
620 In the command string, %h will be substituted by the host name to
621 connect and %p by the port.  The command can be basically anything,
622 and should read from its stdin and write to its stdout.  It should
623 eventually connect an
624 .Xr sshd 8
625 server running on some machine, or execute
626 .Ic sshd -i
627 somewhere.  Host key management will be done using the
628 HostName of the host being connected (defaulting to the name typed by
629 the user).
630 .Pp
631 .It Cm RemoteForward
632 Specifies that a TCP/IP port on the remote machine be forwarded over
633 the secure channel to given host:port from the local machine.  The
634 first argument must be a port number, and the second must be
635 host:port.  Multiple forwardings may be specified, and additional
636 forwardings can be given on the command line.  Only the root can
637 forward privileged ports.
638 .It Cm RhostsAuthentication
639 Specifies whether to try rhosts based authentication.  Note that this
640 declaration only affects the client side and has no effect whatsoever
641 on security.  Disabling rhosts authentication may reduce
642 authentication time on slow connections when rhosts authentication is
643 not used.  Most servers do not permit RhostsAuthentication because it
644 is not secure (see RhostsRSAAuthentication).  The argument to this
645 keyword must be
646 .Dq yes
647 or
648 .Dq no .
649 .It Cm RhostsRSAAuthentication
650 Specifies whether to try rhosts based authentication with RSA host
651 authentication.  This is the primary authentication method for most
652 sites.  The argument must be
653 .Dq yes
654 or
655 .Dq no .
656 .It Cm RSAAuthentication
657 Specifies whether to try RSA authentication.  The argument to this
658 keyword must be
659 .Dq yes
660 or
661 .Dq no .
662 RSA authentication will only be
663 attempted if the identity file exists, or an authentication agent is
664 running.
665 .It Cm CheckHostIP
666 If this flag is set to
667 .Dq yes ,
668 ssh will additionally check the host ip address in the
669 .Pa known_hosts
670 file. This allows ssh to detect if a host key changed due to DNS spoofing.
671 If the option is set to
672 .Dq no ,
673 the check will not be executed.
674 .It Cm StrictHostKeyChecking
675 If this flag is set to
676 .Dq yes , 
677 .Nm
678 ssh will never automatically add host keys to the
679 .Pa $HOME/.ssh/known_hosts
680 file, and refuses to connect hosts whose host key has changed.  This
681 provides maximum protection against trojan horse attacks.  However, it
682 can be somewhat annoying if you don't have good
683 .Pa /etc/ssh/ssh_known_hosts
684 files installed and frequently
685 connect new hosts.  Basically this option forces the user to manually
686 add any new hosts.  Normally this option is disabled, and new hosts
687 will automatically be added to the known host files.  The host keys of
688 known hosts will be verified automatically in either case.  The
689 argument must be
690 .Dq yes
691 or
692 .Dq no .
693 .It Cm User
694 Specifies the user to log in as.  This can be useful if you have a
695 different user name in different machines.  This saves the trouble of
696 having to remember to give the user name on the command line.
697 .It Cm UserKnownHostsFile
698 Specifies a file to use instead of
699 .Pa $HOME/.ssh/known_hosts .
700 .It Cm UsePrivilegedPort
701 Specifies whether to use a privileged port for outgoing connections.
702 The argument must be
703 .Dq yes
704 or
705 .Dq no .
706 The default is
707 .Dq yes .
708 Note that setting this option to
709 .Dq no
710 turns of
711 .Cm RhostsAuthentication
712 and
713 .Cm RhostsRSAAuthentication .
714 .It Cm UseRsh
715 Specifies that rlogin/rsh should be used for this host.  It is
716 possible that the host does not at all support the
717 .Nm
718 protocol.  This causes
719 .Nm
720 to immediately exec 
721 .Xr rsh 1 .
722 All other options (except
723 .Cm HostName )
724 are ignored if this has been specified.  The argument must be
725 .Dq yes
726 or
727 .Dq no .
728 .Sh ENVIRONMENT
729 .Nm
730 will normally set the following environment variables:
731 .Bl -tag -width Ds
732 .It Ev DISPLAY
733 The
734 .Ev DISPLAY
735 variable indicates the location of the X11 server.  It is
736 automatically set by 
737 .Nm
738 to point to a value of the form
739 .Dq hostname:n
740 where hostname indicates
741 the host where the shell runs, and n is an integer >= 1.  Ssh uses
742 this special value to forward X11 connections over the secure
743 channel.  The user should normally not set DISPLAY explicitly, as that
744 will render the X11 connection insecure (and will require the user to
745 manually copy any required authorization cookies).
746 .It Ev HOME
747 Set to the path of the user's home directory.
748 .It Ev LOGNAME
749 Synonym for
750 .Ev USER ;
751 set for compatibility with systems that use this variable.
752 .It Ev MAIL
753 Set to point the user's mailbox.
754 .It Ev  PATH
755 Set to the default
756 .Ev PATH ,
757 as specified when compiling
758 .Nm ssh .
759 .It Ev SSH_AUTH_SOCK
760 indicates the path of a unix-domain socket used to communicate with the
761 agent.
762 .It Ev SSH_CLIENT
763 Identifies the client end of the connection.  The variable contains
764 three space-separated values: client ip-address, client port number,
765 and server port number.
766 .It Ev SSH_TTY
767 This is set to the name of the tty (path to the device) associated
768 with the current shell or command.  If the current session has no tty,
769 this variable is not set.
770 .It Ev TZ
771 The timezone variable is set to indicate the present timezone if it
772 was set when the daemon was started (e.i., the daemon passes the value
773 on to new connections).
774 .It Ev USER
775 Set to the name of the user logging in.
776 .El
777 .Pp
778 Additionally, 
779 .Nm
780 reads 
781 .Pa $HOME/.ssh/environment , 
782 and adds lines of the format
783 .Dq VARNAME=value
784 to the environment.
785 .Sh FILES
786 .Bl -tag -width $HOME/.ssh/known_hosts
787 .It Pa $HOME/.ssh/known_hosts
788 Records host keys for all hosts the user has logged into (that are not
789 in
790 .Pa /etc/ssh/ssh_known_hosts ) .
791 See
792 .Xr sshd 8 .
793 .It Pa $HOME/.ssh/random_seed
794 Used for seeding the random number generator.  This file contains
795 sensitive data and should read/write for the user and not accessible
796 for others.  This file is created the first time the program is run
797 and updated automatically.  The user should never need to read or
798 modify this file.
799 .It Pa $HOME/.ssh/identity
800 Contains the RSA authentication identity of the user.  This file
801 contains sensitive data and should be readable by the user but not
802 accessible by others (read/write/execute).
803 Note that
804 .Nm
805 ignores this file if it is accessible by others.
806 It is possible to specify a passphrase when
807 generating the key; the passphrase will be used to encrypt the
808 sensitive part of this file using 3DES.
809 .It Pa $HOME/.ssh/identity.pub 
810 Contains the public key for authentication (public part of the
811 identity file in human-readable form).  The contents of this file
812 should be added to
813 .Pa $HOME/.ssh/authorized_keys
814 on all machines
815 where you wish to log in using RSA authentication.  This file is not
816 sensitive and can (but need not) be readable by anyone.  This file is
817 never used automatically and is not necessary; it is only provided for
818 the convenience of the user.
819 .It Pa $HOME/.ssh/config
820 This is the per-user configuration file.  The format of this file is
821 described above.  This file is used by the
822 .Nm
823 client.  This file does not usually contain any sensitive information,
824 but the recommended permissions are read/write for the user, and not
825 accessible by others.
826 .It Pa $HOME/.ssh/authorized_keys
827 Lists the RSA keys that can be used for logging in as this user.  The
828 format of this file is described in the
829 .Xr sshd 8
830 manual page.  In the simplest form the format is the same as the .pub
831 identity files (that is, each line contains the number of bits in
832 modulus, public exponent, modulus, and comment fields, separated by
833 spaces).  This file is not highly sensitive, but the recommended
834 permissions are read/write for the user, and not accessible by others.
835 .It Pa /etc/ssh/ssh_known_hosts
836 Systemwide list of known host keys.  This file should be prepared by the
837 system administrator to contain the public host keys of all machines in the
838 organization.  This file should be world-readable.  This file contains
839 public keys, one per line, in the following format (fields separated
840 by spaces): system name, number of bits in modulus, public exponent,
841 modulus, and optional comment field.  When different names are used
842 for the same machine, all such names should be listed, separated by
843 commas.  The format is described on the
844 .Xr sshd 8
845 manual page.
846 .Pp
847 The canonical system name (as returned by name servers) is used by
848 .Xr sshd 8
849 to verify the client host when logging in; other names are needed because
850 .Nm
851 does not convert the user-supplied name to a canonical name before
852 checking the key, because someone with access to the name servers
853 would then be able to fool host authentication.
854 .It Pa /etc/ssh/ssh_config
855 Systemwide configuration file.  This file provides defaults for those
856 values that are not specified in the user's configuration file, and
857 for those users who do not have a configuration file.  This file must
858 be world-readable.
859 .It Pa $HOME/.rhosts
860 This file is used in
861 .Pa \&.rhosts
862 authentication to list the
863 host/user pairs that are permitted to log in.  (Note that this file is
864 also used by rlogin and rsh, which makes using this file insecure.)
865 Each line of the file contains a host name (in the canonical form
866 returned by name servers), and then a user name on that host,
867 separated by a space.  One some machines this file may need to be
868 world-readable if the user's home directory is on a NFS partition,
869 because
870 .Xr sshd 8
871 reads it as root.  Additionally, this file must be owned by the user,
872 and must not have write permissions for anyone else.  The recommended
873 permission for most machines is read/write for the user, and not
874 accessible by others.
875 .Pp
876 Note that by default
877 .Xr sshd 8
878 will be installed so that it requires successful RSA host
879 authentication before permitting \s+2.\s0rhosts authentication.  If your
880 server machine does not have the client's host key in
881 .Pa /etc/ssh/ssh_known_hosts ,
882 you can store it in
883 .Pa $HOME/.ssh/known_hosts .
884 The easiest way to do this is to
885 connect back to the client from the server machine using ssh; this
886 will automatically add the host key inxi
887 .Pa $HOME/.ssh/known_hosts .
888 .It Pa $HOME/.shosts
889 This file is used exactly the same way as
890 .Pa \&.rhosts .
891 The purpose for
892 having this file is to be able to use rhosts authentication with
893 .Nm
894 without permitting login with
895 .Xr rlogin 1
896 or
897 .Xr rsh 1 .
898 .It Pa /etc/hosts.equiv
899 This file is used during
900 .Pa \&.rhosts authentication.  It contains
901 canonical hosts names, one per line (the full format is described on
902 the
903 .Xr sshd 8
904 manual page).  If the client host is found in this file, login is
905 automatically permitted provided client and server user names are the
906 same.  Additionally, successful RSA host authentication is normally
907 required.  This file should only be writable by root.
908 .It Pa /etc/ssh/shosts.equiv
909 This file is processed exactly as 
910 .Pa /etc/hosts.equiv .
911 This file may be useful to permit logins using
912 .Nm
913 but not using rsh/rlogin.
914 .It Pa /etc/ssh/sshrc
915 Commands in this file are executed by
916 .Nm
917 when the user logs in just before the user's shell (or command) is started.
918 See the
919 .Xr sshd 8
920 manual page for more information.
921 .It Pa $HOME/.ssh/rc
922 Commands in this file are executed by
923 .Nm
924 when the user logs in just before the user's shell (or command) is
925 started.
926 See the 
927 .Xr sshd 8
928 manual page for more information.
929 .It Pa libcrypto.so.X.1
930 A version of this library which includes support for the RSA algorithm
931 is required for proper operation.
932 .Sh AUTHOR
933 Tatu Ylonen <ylo@cs.hut.fi>
934 .Pp
935 Issues can be found from the SSH WWW home page:
936 .Pp
937 .Dl http://www.cs.hut.fi/ssh
938 .Pp
939 OpenSSH
940 is a derivative of the original (free) ssh 1.2.12 release, but with bugs
941 removed and newer features re-added.   Rapidly after the 1.2.12 release,
942 newer versions bore successively more restrictive licenses.  This version
943 of OpenSSH
944 .Bl -bullet
945 .It
946 has all components of a restrictive nature (ie. patents, see
947 .Xr ssl 8 )
948 directly removed from the source code; any licensed or patented components
949 are chosen from
950 external libraries.
951 .It
952 has been updated to support ssh protocol 1.5.
953 .It
954 contains added support for 
955 .Xr kerberos 8
956 authentication and ticket passing.
957 .It
958 supports one-time password authentication with
959 .Xr skey 1 .
960 .El
961 .Pp
962 The libraries described in
963 .Xr ssl 8
964 are required for proper operation.
965 .Pp
966 OpenSSH has been created by Aaron Cambell, Bob Beck, Markus Friedl,
967 Niels Provos, Theo de Raadt, and Dug Song.
968 .Sh SEE ALSO
969 .Xr rlogin 1 ,
970 .Xr rsh 1 ,
971 .Xr scp 1 ,
972 .Xr ssh-add 1 ,
973 .Xr ssh-agent 1 ,
974 .Xr ssh-keygen 1 ,
975 .Xr telnet 1 ,
976 .Xr sshd 8 ,
977 .Xr ssl 8
This page took 0.10821 seconds and 3 git commands to generate.