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