[BACK]Return to ssh.1 CVS log [TXT][DIR] Up to [local] / src / usr.bin / ssh

Annotation of src/usr.bin/ssh/ssh.1, Revision 1.16

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