X-Git-Url: http://andersk.mit.edu/gitweb/openssh.git/blobdiff_plain/2cad6cef799b4674da368da1f2efdfbd4f53f6d5..87f4111f950926281d982aa6a69f1e487b7190d6:/ssh.1 diff --git a/ssh.1 b/ssh.1 index 4757a12d..fa25d564 100644 --- a/ssh.1 +++ b/ssh.1 @@ -34,7 +34,7 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $OpenBSD: ssh.1,v 1.106 2001/04/22 13:32:27 markus Exp $ +.\" $OpenBSD: ssh.1,v 1.164 2002/08/29 16:02:54 stevesk Exp $ .Dd September 25, 1999 .Dt SSH 1 .Os @@ -44,11 +44,12 @@ .Sh SYNOPSIS .Nm ssh .Op Fl l Ar login_name -.Op Ar hostname | user@hostname +.Ar hostname | user@hostname .Op Ar command .Pp .Nm ssh -.Op Fl afgknqstvxACNPTX1246 +.Op Fl afgknqstvxACNTX1246 +.Op Fl b Ar bind_address .Op Fl c Ar cipher_spec .Op Fl e Ar escape_char .Op Fl i Ar identity_file @@ -56,6 +57,7 @@ .Op Fl m Ar mac_spec .Op Fl o Ar option .Op Fl p Ar port +.Op Fl F Ar configfile .Oo Fl L Xo .Sm off .Ar port : @@ -72,7 +74,8 @@ .Sm on .Xc .Oc -.Op Ar hostname | user@hostname +.Op Fl D Ar port +.Ar hostname | user@hostname .Op Ar command .Sh DESCRIPTION .Nm @@ -110,7 +113,7 @@ permitted to log in. This form of authentication alone is normally not allowed by the server because it is not secure. .Pp -The second (and primary) authentication method is the +The second authentication method is the .Pa rhosts or .Pa hosts.equiv @@ -123,7 +126,7 @@ or .Pa /etc/shosts.equiv , and if additionally the server can verify the client's host key (see -.Pa /etc/ssh_known_hosts +.Pa /etc/ssh/ssh_known_hosts and .Pa $HOME/.ssh/known_hosts in the @@ -204,29 +207,34 @@ the password cannot be seen by someone listening on the network. .Pp .Ss SSH protocol version 2 .Pp -When a user connects using the protocol version 2 -different authentication methods are available: -At first, the client attempts to authenticate using the public key method. -If this method fails password authentication is tried. +When a user connects using protocol version 2 +similar authentication methods are available. +Using the default values for +.Cm PreferredAuthentications , +the client will try to authenticate first using the hostbased method; +if this method fails public key authentication is attempted, +and finally if this method fails keyboard-interactive and +password authentication are tried. .Pp The public key method is similar to RSA authentication described -in the previous section except that the DSA or RSA algorithm is used -instead. +in the previous section and allows the RSA or DSA algorithm to be used: The client uses his private key, .Pa $HOME/.ssh/id_dsa or .Pa $HOME/.ssh/id_rsa , to sign the session identifier and sends the result to the server. The server checks whether the matching public key is listed in -.Pa $HOME/.ssh/authorized_keys2 +.Pa $HOME/.ssh/authorized_keys and grants access if both the key is found and the signature is correct. The session identifier is derived from a shared Diffie-Hellman value and is only known to the client and the server. .Pp If public key authentication fails or is not available a password can be sent encrypted to the remote host for proving the user's identity. -This protocol 2 implementation does not yet support Kerberos or -S/Key authentication. +.Pp +Additionally, +.Nm +supports hostbased or challenge response authentication. .Pp Protocol 2 provides additional mechanisms for confidentiality (the traffic is encrypted using 3DES, Blowfish, CAST128 or Arcfour) @@ -261,16 +269,16 @@ of .Ss Escape Characters .Pp When a pseudo terminal has been requested, ssh supports a number of functions -through the use of an escape character. +through the use of an escape character. .Pp A single tilde character can be sent as .Ic ~~ -(or by following the tilde by a character other than those described above). +or by following the tilde by a character other than those described below. The escape character must always follow a newline to be interpreted as special. The escape character can be changed in configuration files using the .Cm EscapeChar -configuration directive or on the command line by the +configuration directive or on the command line by the .Fl e option. .Pp @@ -286,9 +294,15 @@ Background ssh List forwarded connections .It Cm ~& Background ssh at logout when waiting for forwarded connection / X11 sessions -to terminate (this does not currently work for SSH protocol version 2) +to terminate .It Cm ~? Display a list of escape characters +.It Cm ~C +Open command line (only useful for adding port forwardings using the +.Fl L +and +.Fl R +options) .It Cm ~R Request rekeying of the connection (only useful for SSH protocol version 2 and if the peer supports it) @@ -296,7 +310,16 @@ and if the peer supports it) .Pp .Ss X11 and TCP forwarding .Pp -If the user is using X11 (the +If the +.Cm ForwardX11 +variable is set to +.Dq yes +(or, see the description of the +.Fl X +and +.Fl x +options described later) +and the user is using X11 (the .Ev DISPLAY environment variable is set), the connection to the X11 display is automatically forwarded to the remote side in such a way that any X11 @@ -330,12 +353,20 @@ the connection is opened. The real authentication cookie is never sent to the server machine (and no cookies are sent in the plain). .Pp -If the user is using an authentication agent, the connection to the agent -is automatically forwarded to the remote side unless disabled on -command line or in a configuration file. +If the +.Cm ForwardAgent +variable is set to +.Dq yes +(or, see the description of the +.Fl A +and +.Fl a +options described later) and +the user is using an authentication agent, the connection to the agent +is automatically forwarded to the remote side. .Pp Forwarding of arbitrary TCP/IP connections over the secure channel can -be specified either on command line or in a configuration file. +be specified either on the command line or in a configuration file. One possible application of TCP/IP forwarding is a secure connection to an electronic purse; another is going through firewalls. .Pp @@ -344,17 +375,12 @@ electronic purse; another is going through firewalls. .Nm automatically maintains and checks a database containing identifications for all hosts it has ever been used with. -RSA host keys are stored in +Host keys are stored in .Pa $HOME/.ssh/known_hosts -and -host keys used in the protocol version 2 are stored in -.Pa $HOME/.ssh/known_hosts2 in the user's home directory. -Additionally, the files -.Pa /etc/ssh_known_hosts -and -.Pa /etc/ssh_known_hosts2 -are automatically checked for known hosts. +Additionally, the file +.Pa /etc/ssh/ssh_known_hosts +is automatically checked for known hosts. Any new hosts are automatically added to the user's file. If a host's identification ever changes, @@ -366,7 +392,7 @@ this mechanism is to prevent man-in-the-middle attacks which could otherwise be used to circumvent the encryption. The .Cm StrictHostKeyChecking -option (see below) can be used to prevent logins to machines whose +option can be used to prevent logins to machines whose host key is not known or has changed. .Pp The options are as follows: @@ -376,20 +402,27 @@ Disables forwarding of the authentication agent connection. .It Fl A Enables forwarding of the authentication agent connection. This can also be specified on a per-host basis in a configuration file. -.It Fl c Ar blowfish|3des +.It Fl b Ar bind_address +Specify the interface to transmit from on machines with multiple +interfaces or aliased addresses. +.It Fl c Ar blowfish|3des|des Selects the cipher to use for encrypting the session. .Ar 3des is used by default. It is believed to be secure. .Ar 3des (triple-des) is an encrypt-decrypt-encrypt triple with three different keys. -It is presumably more secure than the -.Ar des -cipher which is no longer fully supported in -.Nm ssh . .Ar blowfish is a fast block cipher, it appears very secure and is much faster than .Ar 3des . +.Ar des +is only supported in the +.Nm +client for interoperability with legacy protocol 1 implementations +that do not support the +.Ar 3des +cipher. Its use is strongly discouraged due to cryptographic +weaknesses. .It Fl c Ar cipher_spec Additionally, for protocol version 2 a comma-separated list of ciphers can be specified in order of preference. @@ -424,17 +457,27 @@ something like .It Fl g Allows remote hosts to connect to local forwarded ports. .It Fl i Ar identity_file -Selects the file from which the identity (private key) for +Selects a file from which the identity (private key) for RSA or DSA authentication is read. -Default is +The default is .Pa $HOME/.ssh/identity -in the user's home directory. +for protocol version 1, and +.Pa $HOME/.ssh/id_rsa +and +.Pa $HOME/.ssh/id_dsa +for protocol version 2. Identity files may also be specified on a per-host basis in the configuration file. It is possible to have multiple .Fl i options (and multiple identities specified in configuration files). +.It Fl I Ar smartcard_device +Specifies which smartcard device to use. The argument is +the device +.Nm +should use to communicate with a smartcard used for storing the user's +private RSA key. .It Fl k Disables forwarding of Kerberos tickets and AFS tokens. This may also be specified on a per-host basis in the configuration file. @@ -470,33 +513,22 @@ needs to ask for a password or passphrase; see also the option.) .It Fl N Do not execute a remote command. -This is useful if you just want to forward ports +This is useful for just forwarding ports (protocol version 2 only). .It Fl o Ar option -Can be used to give options in the format used in the config file. +Can be used to give options in the format used in the configuration file. This is useful for specifying options for which there is no separate command-line flag. -The option has the same format as a line in the configuration file. .It Fl p Ar port Port to connect to on the remote host. This can be specified on a per-host basis in the configuration file. -.It Fl P -Use a non-privileged port for outgoing connections. -This can be used if your firewall does -not permit connections from privileged ports. -Note that this option turns off -.Cm RhostsAuthentication -and -.Cm RhostsRSAAuthentication -for older servers. .It Fl q Quiet mode. Causes all warning and diagnostic messages to be suppressed. -Only fatal errors are displayed. .It Fl s -May be used to request invocation of a subsystem on the remote system. Subsystems are a feature of the SSH2 protocol which facilitate the use -of SSH as a secure transport for other application (eg. sftp). The +May be used to request invocation of a subsystem on the remote system. Subsystems are a feature of the SSH2 protocol which facilitate the use +of SSH as a secure transport for other applications (eg. sftp). The subsystem is specified as the remote command. .It Fl t Force pseudo-tty allocation. @@ -535,13 +567,21 @@ and the .Dq level can be controlled by the .Cm CompressionLevel -option (see below). +option. Compression is desirable on modem lines and other slow connections, but will only slow down things on fast networks. The default value can be set on a host-by-host basis in the configuration files; see the -.Cm Compress -option below. +.Cm Compression +option. +.It Fl F Ar configfile +Specifies an alternative per-user configuration file. +If a configuration file is given on the command line, +the system-wide configuration file +.Pq Pa /etc/ssh/ssh_config +will be ignored. +The default for the per-user configuration file is +.Pa $HOME/.ssh/config . .It Fl L Ar port:host:hostport Specifies that the given port on the local (client) host is to be forwarded to the given host and port on the remote side. @@ -573,6 +613,22 @@ from the local machine. Port forwardings can also be specified in the configuration file. Privileged ports can be forwarded only when logging in as root on the remote machine. +IPv6 addresses can be specified with an alternative syntax: +.Ar port/host/hostport +.It Fl D Ar port +Specifies a local +.Dq dynamic +application-level port forwarding. +This works by allocating a socket to listen to +.Ar port +on the local side, and whenever a connection is made to this port, the +connection is forwarded over the secure channel, and the application +protocol is then used to determine where to connect to from the +remote machine. Currently the SOCKS4 protocol is supported, and +.Nm +will act as a SOCKS4 server. +Only root can forward privileged ports. +Dynamic port forwardings can also be specified in the configuration file. .It Fl 1 Forces .Nm @@ -592,494 +648,10 @@ to use IPv6 addresses only. .El .Sh CONFIGURATION FILES .Nm -obtains configuration data from the following sources (in this order): -command line options, user's configuration file -.Pq Pa $HOME/.ssh/config , -and system-wide configuration file -.Pq Pa /etc/ssh_config . -For each parameter, the first obtained value -will be used. -The configuration files contain sections bracketed by -.Dq Host -specifications, and that section is only applied for hosts that -match one of the patterns given in the specification. -The matched host name is the one given on the command line. -.Pp -Since the first obtained value for each parameter is used, more -host-specific declarations should be given near the beginning of the -file, and general defaults at the end. -.Pp -The configuration file has the following format: -.Pp -Empty lines and lines starting with -.Ql # -are comments. -.Pp -Otherwise a line is of the format -.Dq keyword arguments . -The possible -keywords and their meanings are as follows (note that the -configuration files are case-sensitive): -.Bl -tag -width Ds -.It Cm Host -Restricts the following declarations (up to the next -.Cm Host -keyword) to be only for those hosts that match one of the patterns -given after the keyword. -.Ql \&* -and -.Ql ? -can be used as wildcards in the -patterns. -A single -.Ql \&* -as a pattern can be used to provide global -defaults for all hosts. -The host is the -.Ar hostname -argument given on the command line (i.e., the name is not converted to -a canonicalized host name before matching). -.It Cm AFSTokenPassing -Specifies whether to pass AFS tokens to remote host. -The argument to this keyword must be -.Dq yes -or -.Dq no . -.It Cm BatchMode -If set to -.Dq yes , -passphrase/password querying will be disabled. -This option is useful in scripts and other batch jobs where you have no -user to supply the password. -The argument must be -.Dq yes -or -.Dq no . -The default is -.Dq no . -.It Cm CheckHostIP -If this flag is set to -.Dq yes , -ssh will additionally check the host IP address in the -.Pa known_hosts -file. -This allows ssh to detect if a host key changed due to DNS spoofing. -If the option is set to -.Dq no , -the check will not be executed. -The default is -.Dq yes . -.It Cm Cipher -Specifies the cipher to use for encrypting the session -in protocol version 1. -Currently, -.Dq blowfish -and -.Dq 3des -are supported. -The default is -.Dq 3des . -.It Cm Ciphers -Specifies the ciphers allowed for protocol version 2 -in order of preference. -Multiple ciphers must be comma-separated. -The default is -.Pp -.Bd -literal - ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour, - aes192-cbc,aes256-cbc,rijndael128-cbc,rijndael192-cbc, - rijndael256-cbc,rijndael-cbc@lysator.liu.se'' -.Ed -.It Cm Compression -Specifies whether to use compression. -The argument must be -.Dq yes -or -.Dq no . -The default is -.Dq no . -.It Cm CompressionLevel -Specifies the compression level to use if compression is enabled. -The argument must be an integer from 1 (fast) to 9 (slow, best). -The default level is 6, which is good for most applications. -The meaning of the values is the same as in -.Xr gzip 1 . -.It Cm ConnectionAttempts -Specifies the number of tries (one per second) to make before falling -back to rsh or exiting. -The argument must be an integer. -This may be useful in scripts if the connection sometimes fails. -The default is 4. -.It Cm PubkeyAuthentication -Specifies whether to try public key authentication. -The argument to this keyword must be -.Dq yes -or -.Dq no . -The default is -.Dq yes . -Note that this option applies to protocol version 2 only. -.It Cm EscapeChar -Sets the escape character (default: -.Ql ~ ) . -The escape character can also -be set on the command line. -The argument should be a single character, -.Ql ^ -followed by a letter, or -.Dq none -to disable the escape -character entirely (making the connection transparent for binary -data). -.It Cm FallBackToRsh -Specifies that if connecting via -.Nm -fails due to a connection refused error (there is no -.Xr sshd 8 -listening on the remote host), -.Xr rsh 1 -should automatically be used instead (after a suitable warning about -the session being unencrypted). -The argument must be -.Dq yes -or -.Dq no . -The default is -.Dq no . -.It Cm ForwardAgent -Specifies whether the connection to the authentication agent (if any) -will be forwarded to the remote machine. -The argument must be -.Dq yes -or -.Dq no . -The default is -.Dq no . -.It Cm ForwardX11 -Specifies whether X11 connections will be automatically redirected -over the secure channel and -.Ev DISPLAY -set. -The argument must be -.Dq yes -or -.Dq no . -The default is -.Dq no . -.It Cm GatewayPorts -Specifies whether remote hosts are allowed to connect to local -forwarded ports. -The argument must be -.Dq yes -or -.Dq no . -The default is -.Dq no . -.It Cm GlobalKnownHostsFile -Specifies a file to use for the protocol version 1 global -host key database instead of -.Pa /etc/ssh_known_hosts . -.It Cm GlobalKnownHostsFile2 -Specifies a file to use for the protocol version 2 global -host key database instead of -.Pa /etc/ssh_known_hosts2 . -.It Cm HostKeyAlias -Specifies an alias that should be used instead of the -real host name when looking up or saving the host key -in the known_hosts files. -This option is useful for tunneling ssh connections -or if you have multiple servers running on a single host. -.It Cm HostKeyAlgorithms -Specfies the protocol version 2 host key algorithms -that the client wants to use in order of preference. -The default for this option is: -.Dq ssh-rsa,ssh-dss -.It Cm HostName -Specifies the real host name to log into. -This can be used to specify nicknames or abbreviations for hosts. -Default is the name given on the command line. -Numeric IP addresses are also permitted (both on the command line and in -.Cm HostName -specifications). -.It Cm IdentityFile -Specifies the file from which the user's RSA authentication identity -is read (default -.Pa $HOME/.ssh/identity -in the user's home directory). -Additionally, any identities represented by the authentication agent -will be used for authentication. -The file name may use the tilde -syntax to refer to a user's home directory. -It is possible to have -multiple identity files specified in configuration files; all these -identities will be tried in sequence. -.It Cm KeepAlive -Specifies whether the system should send keepalive messages to the -other side. -If they are sent, death of the connection or crash of one -of the machines will be properly noticed. -However, this means that -connections will die if the route is down temporarily, and some people -find it annoying. -.Pp -The default is -.Dq yes -(to send keepalives), and the client will notice -if the network goes down or the remote host dies. -This is important in scripts, and many users want it too. -.Pp -To disable keepalives, the value should be set to -.Dq no -in both the server and the client configuration files. -.It Cm KerberosAuthentication -Specifies whether Kerberos authentication will be used. -The argument to this keyword must be -.Dq yes -or -.Dq no . -.It Cm KerberosTgtPassing -Specifies whether a Kerberos TGT will be forwarded to the server. -This will only work if the Kerberos server is actually an AFS kaserver. -The argument to this keyword must be -.Dq yes -or -.Dq no . -.It Cm LocalForward -Specifies that a TCP/IP port on the local machine be forwarded over -the secure channel to given host:port from the remote machine. -The first argument must be a port number, and the second must be -host:port. -Multiple forwardings may be specified, and additional -forwardings can be given on the command line. -Only the superuser can forward privileged ports. -.It Cm LogLevel -Gives the verbosity level that is used when logging messages from -.Nm ssh . -The possible values are: -QUIET, FATAL, ERROR, INFO, VERBOSE and DEBUG. -The default is INFO. -.It Cm MACs -Specifies the MAC (message authentication code) algorithms -in order of preference. -The MAC algorithm is used in protocol version 2 -for data integrity protection. -Multiple algorithms must be comma-separated. -The default is -.Pp -.Bd -literal - ``hmac-md5,hmac-sha1,hmac-ripemd160,hmac-ripemd160@openssh.com, - hmac-sha1-96,hmac-md5-96'' -.Ed -.It Cm NumberOfPasswordPrompts -Specifies the number of password prompts before giving up. -The argument to this keyword must be an integer. -Default is 3. -.It Cm PasswordAuthentication -Specifies whether to use password authentication. -The argument to this keyword must be -.Dq yes -or -.Dq no . -The default is -.Dq yes . -Note that this option applies to both protocol version 1 and 2. -.It Cm Port -Specifies the port number to connect on the remote host. -Default is 22. -.It Cm PreferredAuthentications -Specifies the order in which the client should try protocol 2 -authentication methods. This allows a client to prefer one method (e.g. -.Cm keyboard-interactive ) -over another method (e.g. -.Cm password ) -The default for this option is: -.Dq publickey, password, keyboard-interactive -.It Cm Protocol -Specifies the protocol versions -.Nm -should support in order of preference. -The possible values are -.Dq 1 -and -.Dq 2 . -Multiple versions must be comma-separated. -The default is -.Dq 2,1 . -This means that -.Nm -tries version 2 and falls back to version 1 -if version 2 is not available. -.It Cm ProxyCommand -Specifies the command to use to connect to the server. -The command -string extends to the end of the line, and is executed with -.Pa /bin/sh . -In the command string, -.Ql %h -will be substituted by the host name to -connect and -.Ql %p -by the port. -The command can be basically anything, -and should read from its standard input and write to its standard output. -It should eventually connect an -.Xr sshd 8 -server running on some machine, or execute -.Ic sshd -i -somewhere. -Host key management will be done using the -HostName of the host being connected (defaulting to the name typed by -the user). -Note that -.Cm CheckHostIP -is not available for connects with a proxy command. -.Pp -.It Cm RemoteForward -Specifies that a TCP/IP port on the remote machine be forwarded over -the secure channel to given host:port from the local machine. -The first argument must be a port number, and the second must be -host:port. -Multiple forwardings may be specified, and additional -forwardings can be given on the command line. -Only the superuser can forward privileged ports. -.It Cm RhostsAuthentication -Specifies whether to try rhosts based authentication. -Note that this -declaration only affects the client side and has no effect whatsoever -on security. -Disabling rhosts authentication may reduce -authentication time on slow connections when rhosts authentication is -not used. -Most servers do not permit RhostsAuthentication because it -is not secure (see RhostsRSAAuthentication). -The argument to this keyword must be -.Dq yes -or -.Dq no . -The default is -.Dq yes . -.It Cm RhostsRSAAuthentication -Specifies whether to try rhosts based authentication with RSA host -authentication. -The argument must be -.Dq yes -or -.Dq no . -The default is -.Dq yes . -.It Cm RSAAuthentication -Specifies whether to try RSA authentication. -The argument to this keyword must be -.Dq yes -or -.Dq no . -RSA authentication will only be -attempted if the identity file exists, or an authentication agent is -running. -The default is -.Dq yes . -Note that this option applies to protocol version 1 only. -.It Cm ChallengeResponseAuthentication -Specifies whether to use challenge response authentication. -Currently there is only support for -.Xr skey 1 -authentication. -The argument to this keyword must be -.Dq yes -or -.Dq no . -The default is -.Dq no . -.It Cm StrictHostKeyChecking -If this flag is set to -.Dq yes , -.Nm -will never automatically add host keys to the -.Pa $HOME/.ssh/known_hosts -and -.Pa $HOME/.ssh/known_hosts2 -files, and refuses to connect to hosts whose host key has changed. -This provides maximum protection against trojan horse attacks. -However, it can be somewhat annoying if you don't have good -.Pa /etc/ssh_known_hosts -and -.Pa /etc/ssh_known_hosts2 -files installed and frequently -connect to new hosts. -This option forces the user to manually -add all new hosts. -If this flag is set to -.Dq no , -.Nm -will automatically add new host keys to the -user known hosts files. -If this flag is set to -.Dq ask , -new host keys -will be added to the user known host files only after the user -has confirmed that is what they really want to do, and -.Nm -will refuse to connect to hosts whose host key has changed. -The host keys of -known hosts will be verified automatically in all cases. -The argument must be -.Dq yes , -.Dq no -or -.Dq ask . -The default is -.Dq ask . -.It Cm UsePrivilegedPort -Specifies whether to use a privileged port for outgoing connections. -The argument must be -.Dq yes -or -.Dq no . -The default is -.Dq no . -Note that setting this option to -.Dq no -turns off -.Cm RhostsAuthentication -and -.Cm RhostsRSAAuthentication -for older servers. -.It Cm User -Specifies the user to log in as. -This can be useful if you have a different user name on different machines. -This saves the trouble of -having to remember to give the user name on the command line. -.It Cm UserKnownHostsFile -Specifies a file to use for the protocol version 1 user -host key database instead of -.Pa $HOME/.ssh/known_hosts . -.It Cm UserKnownHostsFile2 -Specifies a file to use for the protocol version 2 user -host key database instead of -.Pa $HOME/.ssh/known_hosts2 . -.It Cm UseRsh -Specifies that rlogin/rsh should be used for this host. -It is possible that the host does not at all support the -.Nm -protocol. -This causes -.Nm -to immediately execute -.Xr rsh 1 . -All other options (except -.Cm HostName ) -are ignored if this has been specified. -The argument must be -.Dq yes -or -.Dq no . -.It Cm XAuthLocation -Specifies the location of the -.Xr xauth 1 -program. -The default is -.Pa /usr/X11R6/bin/xauth . -.El +may additionally obtain configuration data from +a per-user configuration file and a system-wide configuration file. +The file format and configuration options are described in +.Xr ssh_config 5 . .Sh ENVIRONMENT .Nm will normally set the following environment variables: @@ -1097,7 +669,9 @@ the host where the shell runs, and n is an integer >= 1. .Nm uses this special value to forward X11 connections over the secure channel. -The user should normally not set DISPLAY explicitly, as that +The user should normally not set +.Ev DISPLAY +explicitly, as that will render the X11 connection insecure (and will require the user to manually copy any required authorization cookies). .It Ev HOME @@ -1107,14 +681,37 @@ Synonym for .Ev USER ; set for compatibility with systems that use this variable. .It Ev MAIL -Set to point the user's mailbox. +Set to the path of the user's mailbox. .It Ev PATH Set to the default .Ev PATH , as specified when compiling .Nm ssh . +.It Ev SSH_ASKPASS +If +.Nm +needs a passphrase, it will read the passphrase from the current +terminal if it was run from a terminal. +If +.Nm +does not have a terminal associated with it but +.Ev DISPLAY +and +.Ev SSH_ASKPASS +are set, it will execute the program specified by +.Ev SSH_ASKPASS +and open an X11 window to read the passphrase. +This is particularly useful when calling +.Nm +from a +.Pa .Xsession +or related script. +(Note that on some machines it +may be necessary to redirect the input from +.Pa /dev/null +to make this work.) .It Ev SSH_AUTH_SOCK -indicates the path of a unix-domain socket used to communicate with the +Identifies the path of a unix-domain socket used to communicate with the agent. .It Ev SSH_CLIENT Identifies the client end of the connection. @@ -1144,16 +741,18 @@ reads .Pa $HOME/.ssh/environment , and adds lines of the format .Dq VARNAME=value -to the environment. +to the environment if the file exists and if users are allowed to +change their environment. +See the +.Cm PermitUserEnvironment +option in +.Xr sshd_config 5 . .Sh FILES .Bl -tag -width Ds -.It Pa $HOME/.ssh/known_hosts, $HOME/.ssh/known_hosts2 -Records host keys for all hosts the user has logged into (that are not +.It Pa $HOME/.ssh/known_hosts +Records host keys for all hosts the user has logged into that are not in -.Pa /etc/ssh_known_hosts -for protocol version 1 or -.Pa /etc/ssh_known_hosts2 -for protocol version 2). +.Pa /etc/ssh/ssh_known_hosts . See .Xr sshd 8 . .It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa @@ -1176,15 +775,15 @@ The contents of the file should be added to .Pa $HOME/.ssh/authorized_keys on all machines -where you wish to log in using protocol version 1 RSA authentication. +where the user wishes to log in using protocol version 1 RSA authentication. The contents of the .Pa $HOME/.ssh/id_dsa.pub and .Pa $HOME/.ssh/id_rsa.pub file should be added to -.Pa $HOME/.ssh/authorized_keys2 +.Pa $HOME/.ssh/authorized_keys on all machines -where you wish to log in using protocol version 2 DSA/RSA authentication. +where the user wishes to log in using protocol version 2 DSA/RSA authentication. These files are not sensitive and can (but need not) be readable by anyone. These files are @@ -1192,42 +791,26 @@ never used automatically and are not necessary; they are only provided for the convenience of the user. .It Pa $HOME/.ssh/config This is the per-user configuration file. -The format of this file is described above. -This file is used by the -.Nm -client. -This file does not usually contain any sensitive information, -but the recommended permissions are read/write for the user, and not -accessible by others. +The file format and configuration options are described in +.Xr ssh_config 5 . .It Pa $HOME/.ssh/authorized_keys -Lists the RSA keys that can be used for logging in as this user. +Lists the public keys (RSA/DSA) that can be used for logging in as this user. The format of this file is described in the .Xr sshd 8 manual page. In the simplest form the format is the same as the .pub -identity files (that is, each line contains the number of bits in -modulus, public exponent, modulus, and comment fields, separated by -spaces). -This file is not highly sensitive, but the recommended -permissions are read/write for the user, and not accessible by others. -.It Pa $HOME/.ssh/authorized_keys2 -Lists the public keys (DSA/RSA) that can be used for logging in as this user. +identity files. This file is not highly sensitive, but the recommended permissions are read/write for the user, and not accessible by others. -.It Pa /etc/ssh_known_hosts, /etc/ssh_known_hosts2 +.It Pa /etc/ssh/ssh_known_hosts Systemwide list of known host keys. -.Pa /etc/ssh_known_hosts -contains RSA and -.Pa /etc/ssh_known_hosts2 -contains DSA or RSA keys for protocol version 2. -These files should be prepared by the +This file should be prepared by the system administrator to contain the public host keys of all machines in the organization. This file should be world-readable. This file contains public keys, one per line, in the following format (fields separated -by spaces): system name, number of bits in modulus, public exponent, -modulus, and optional comment field. +by spaces): system name, public key and optional comment field. When different names are used for the same machine, all such names should be listed, separated by commas. @@ -1242,12 +825,33 @@ to verify the client host when logging in; other names are needed because does not convert the user-supplied name to a canonical name before checking the key, because someone with access to the name servers would then be able to fool host authentication. -.It Pa /etc/ssh_config +.It Pa /etc/ssh/ssh_config Systemwide configuration file. -This file provides defaults for those -values that are not specified in the user's configuration file, and -for those users who do not have a configuration file. -This file must be world-readable. +The file format and configuration options are described in +.Xr ssh_config 5 . +.It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key +These three files contain the private parts of the host keys +and are used for +.Cm RhostsRSAAuthentication +and +.Cm HostbasedAuthentication . +If the protocol version 1 +.Cm RhostsRSAAuthentication +method is used, +.Nm +must be setuid root, since the host key is readable only by root. +For protocol version 2, +.Nm +uses +.Xr ssh-keysign 8 +to access the host keys for +.Cm HostbasedAuthentication . +This eliminates the requirement that +.Nm +be setuid root when that authentication method is used. +By default +.Nm +is not setuid root. .It Pa $HOME/.rhosts This file is used in .Pa \&.rhosts @@ -1273,9 +877,9 @@ Note that by default .Xr sshd 8 will be installed so that it requires successful RSA host authentication before permitting \s+2.\s0rhosts authentication. -If your server machine does not have the client's host key in -.Pa /etc/ssh_known_hosts , -you can store it in +If the server machine does not have the client's host key in +.Pa /etc/ssh/ssh_known_hosts , +it can be stored in .Pa $HOME/.ssh/known_hosts . The easiest way to do this is to connect back to the client from the server machine using ssh; this @@ -1288,7 +892,7 @@ The purpose for having this file is to be able to use rhosts authentication with .Nm without permitting login with -.Xr rlogin 1 +.Nm rlogin or .Xr rsh 1 . .It Pa /etc/hosts.equiv @@ -1311,7 +915,7 @@ This file is processed exactly as This file may be useful to permit logins using .Nm but not using rsh/rlogin. -.It Pa /etc/sshrc +.It Pa /etc/ssh/sshrc Commands in this file are executed by .Nm when the user logs in just before the user's shell (or command) is started. @@ -1331,6 +935,10 @@ Contains additional definitions for environment variables, see section .Sx ENVIRONMENT above. .El +.Sh DIAGNOSTICS +.Nm +exits with the exit status of the remote command or with 255 +if an error occurred. .Sh AUTHORS OpenSSH is a derivative of the original and free ssh 1.2.12 release by Tatu Ylonen. @@ -1341,7 +949,6 @@ created OpenSSH. Markus Friedl contributed the support for SSH protocol versions 1.5 and 2.0. .Sh SEE ALSO -.Xr rlogin 1 , .Xr rsh 1 , .Xr scp 1 , .Xr sftp 1 , @@ -1349,6 +956,8 @@ protocol versions 1.5 and 2.0. .Xr ssh-agent 1 , .Xr ssh-keygen 1 , .Xr telnet 1 , +.Xr ssh_config 5 , +.Xr ssh-keysign 8 , .Xr sshd 8 .Rs .%A T. Ylonen @@ -1357,7 +966,7 @@ protocol versions 1.5 and 2.0. .%A T. Rinne .%A S. Lehtinen .%T "SSH Protocol Architecture" -.%N draft-ietf-secsh-architecture-07.txt -.%D January 2001 +.%N draft-ietf-secsh-architecture-12.txt +.%D January 2002 .%O work in progress material .Re