X-Git-Url: http://andersk.mit.edu/gitweb/openssh.git/blobdiff_plain/371ecff9fbd011285195f288b3db235159306126..87f4111f950926281d982aa6a69f1e487b7190d6:/ssh.1 diff --git a/ssh.1 b/ssh.1 index b7be8dae..fa25d564 100644 --- a/ssh.1 +++ b/ssh.1 @@ -1,36 +1,63 @@ .\" -*- nroff -*- .\" -.\" ssh.1.in -.\" .\" Author: Tatu Ylonen -.\" .\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland .\" All rights reserved .\" -.\" Created: Sat Apr 22 21:55:14 1995 ylo +.\" As far as I am concerned, the code I have written for this software +.\" can be used freely for any purpose. Any derived versions of this +.\" software must be clearly marked as such, and if the derived work is +.\" incompatible with the protocol description in the RFC file, it must be +.\" called by a name other than "ssh" or "Secure Shell". +.\" +.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. +.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. +.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. .\" -.\" $Id$ +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. .\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (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.164 2002/08/29 16:02:54 stevesk Exp $ .Dd September 25, 1999 .Dt SSH 1 .Os .Sh NAME .Nm ssh -.Nd OpenSSH secure shell client (remote login program) +.Nd OpenSSH SSH client (remote login program) .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 afgknqtvxCPX246 -.Op Fl c Ar blowfish | 3des +.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 .Op Fl l Ar login_name +.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 : @@ -47,11 +74,12 @@ .Sm on .Xc .Oc -.Op Ar hostname | user@hostname +.Op Fl D Ar port +.Ar hostname | user@hostname .Op Ar command .Sh DESCRIPTION .Nm -(Secure Shell) is a program for logging into a remote machine and for +(SSH client) is a program for logging into a remote machine and for executing commands on a remote machine. It is intended to replace rlogin and rsh, and provide secure encrypted communications between @@ -63,7 +91,10 @@ arbitrary TCP/IP ports can also be forwarded over the secure channel. connects and logs into the specified .Ar hostname . The user must prove -his/her identity to the remote machine using one of several methods. +his/her identity to the remote machine using one of several methods +depending on the protocol version used: +.Pp +.Ss SSH protocol version 1 .Pp First, if the machine the user logs in from is listed in .Pa /etc/hosts.equiv @@ -82,20 +113,20 @@ 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 method combined with RSA-based host authentication. It means that if the login would be permitted by -.Pa \&.rhosts , -.Pa \&.shosts , +.Pa $HOME/.rhosts , +.Pa $HOME/.shosts , .Pa /etc/hosts.equiv , 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 @@ -105,7 +136,7 @@ This authentication method closes security holes due to IP spoofing, DNS spoofing and routing spoofing. [Note to the administrator: .Pa /etc/hosts.equiv , -.Pa \&.rhosts , +.Pa $HOME/.rhosts , and the rlogin/rsh protocol in general, are inherently insecure and should be disabled if security is desired.] .Pp @@ -143,18 +174,18 @@ implements the RSA authentication protocol automatically. The user creates his/her RSA key pair by running .Xr ssh-keygen 1 . This stores the private key in -.Pa \&.ssh/identity +.Pa $HOME/.ssh/identity and the public key in -.Pa \&.ssh/identity.pub +.Pa $HOME/.ssh/identity.pub in the user's home directory. The user should then copy the .Pa identity.pub to -.Pa \&.ssh/authorized_keys +.Pa $HOME/.ssh/authorized_keys in his/her home directory on the remote machine (the .Pa authorized_keys file corresponds to the conventional -.Pa \&.rhosts +.Pa $HOME/.rhosts file, and has one key per line, though the lines can be very long). After this, the user can log in without giving the password. @@ -174,6 +205,45 @@ The password is sent to the remote host for checking; however, since all communications are encrypted, the password cannot be seen by someone listening on the network. .Pp +.Ss SSH protocol version 2 +.Pp +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 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_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. +.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) +and integrity (hmac-md5, hmac-sha1). +Note that protocol 1 lacks a strong mechanism for ensuring the +integrity of the connection. +.Pp +.Ss Login session and remote execution +.Pp When the user's identity has been accepted by the server, the server either executes the given command, or logs into the machine and gives the user a normal shell on the remote machine. @@ -181,30 +251,7 @@ All communication with the remote command or shell will be automatically encrypted. .Pp If a pseudo-terminal has been allocated (normal login session), the -user can disconnect with -.Ic ~. , -and suspend -.Nm -with -.Ic ~^Z . -All forwarded connections can be listed with -.Ic ~# -and if -the session blocks waiting for forwarded X11 or TCP/IP -connections to terminate, it can be backgrounded with -.Ic ~& -(this should not be used while the user shell is active, as it can cause the -shell to hang). -All available escapes can be listed with -.Ic ~? . -.Pp -A single tilde character can be sent as -.Ic ~~ -(or by following the tilde by a character other than those described above). -The escape character must always follow a newline to be interpreted as -special. -The escape character can be changed in configuration files -or on the command line. +user may use the escape characters noted below. .Pp If no pseudo tty has been allocated, the session is transparent and can be used to reliably transfer binary @@ -213,13 +260,66 @@ On most systems, setting the escape character to .Dq none will also make the session transparent even if a tty is used. .Pp -The session terminates when the command or shell in on the remote -machine exists and all X11 and TCP/IP connections have been closed. +The session terminates when the command or shell on the remote +machine exits and all X11 and TCP/IP connections have been closed. The exit status of the remote program is returned as the exit status of .Nm ssh . .Pp -If the user is using X11 (the +.Ss Escape Characters +.Pp +When a pseudo terminal has been requested, ssh supports a number of functions +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 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 +.Fl e +option. +.Pp +The supported escapes (assuming the default +.Ql ~ ) +are: +.Bl -tag -width Ds +.It Cm ~. +Disconnect +.It Cm ~^Z +Background ssh +.It Cm ~# +List forwarded connections +.It Cm ~& +Background ssh at logout when waiting for forwarded connection / X11 sessions +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) +.El +.Pp +.Ss X11 and TCP forwarding +.Pp +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 @@ -253,23 +353,33 @@ 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 trough firewalls. +electronic purse; another is going through firewalls. +.Pp +.Ss Server authentication .Pp .Nm -automatically maintains and checks a database containing RSA-based +automatically maintains and checks a database containing identifications for all hosts it has ever been used with. -The database is stored in -.Pa \&.ssh/known_hosts +Host keys are stored in +.Pa $HOME/.ssh/known_hosts in the user's home directory. Additionally, the file -.Pa /etc/ssh_known_hosts +.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 @@ -282,26 +392,43 @@ 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. -.Sh OPTIONS +.Pp +The options are as follows: .Bl -tag -width Ds .It Fl a Disables forwarding of the authentication agent connection. -This may also be specified on a per-host basis in the configuration file. -.It Fl c Ar blowfish|3des +.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 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 supported in 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. +See +.Cm Ciphers +for more information. .It Fl e Ar ch|^ch|none Sets the escape character for sessions with a pty (default: .Ql ~ ) . @@ -330,23 +457,40 @@ 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 -RSA authentication is read. -Default is -.Pa \&.ssh/identity -in the user's home directory. +Selects a file from which the identity (private key) for +RSA or DSA authentication is read. +The default is +.Pa $HOME/.ssh/identity +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. .It Fl l Ar login_name Specifies the user to log in as on the remote machine. This also may be specified on a per-host basis in the configuration file. +.It Fl m Ar mac_spec +Additionally, for protocol version 2 a comma-separated list of MAC +(message authentication code) algorithms can +be specified in order of preference. +See the +.Cm MACs +keyword for more information. .It Fl n Redirects stdin from .Pa /dev/null @@ -367,32 +511,37 @@ program will be put in the background. needs to ask for a password or passphrase; see also the .Fl f option.) +.It Fl N +Do not execute a remote command. +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 . .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 applications (eg. sftp). The +subsystem is specified as the remote command. .It Fl t Force pseudo-tty allocation. This can be used to execute arbitrary screen-based programs on a remote machine, which can be very useful, e.g., when implementing menu services. +Multiple +.Fl t +options force tty allocation, even if +.Nm +has no local tty. +.It Fl T +Disable pseudo-tty allocation. .It Fl v Verbose mode. Causes @@ -400,14 +549,15 @@ Causes to print debugging messages about its progress. This is helpful in debugging connection, authentication, and configuration problems. -The verbose mode is also used to display -.Xr skey 1 -challenges, if the user entered "s/key" as password. +Multiple +.Fl v +options increases the verbosity. +Maximum is 3. .It Fl x Disables X11 forwarding. -This can also be specified on a per-host basis in a configuration file. .It Fl X Enables X11 forwarding. +This can also be specified on a per-host basis in a configuration file. .It Fl C Requests compression of all data (including stdin, stdout, stderr, and data for forwarded X11 and TCP/IP connections). @@ -417,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. @@ -455,10 +613,30 @@ 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 +to try protocol version 1 only. .It Fl 2 Forces .Nm -to use protocol version 2 only. +to try protocol version 2 only. .It Fl 4 Forces .Nm @@ -470,388 +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 . -.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. -.It Cm Cipher -Specifies the cipher to use for encrypting the session. -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 -.Dq blowfish-cbc,3des-cbc,arcfour,cast128-cbc . -.It Cm Compression -Specifies whether to use compression. -The argument must be -.Dq yes -or -.Dq no . -.It Cm CompressionLevel -Specifies the compression level to use if compression is enable. -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. -.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 . -.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 . -.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 instead of -.Pa /etc/ssh_known_hosts . -.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 .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 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 . -.It Cm Port -Specifies the port number to connect on the remote host. -Default is 22. -.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 1 . -.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 . -.It Cm RhostsRSAAuthentication -Specifies whether to try rhosts based authentication with RSA host -authentication. -This is the primary authentication method for most sites. -The argument must be -.Dq yes -or -.Dq no . -.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. -.It Cm SkeyAuthentication -Specifies whether to use -.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 -ssh will never automatically add host keys to the -.Pa $HOME/.ssh/known_hosts -file, and refuses to connect 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 -files installed and frequently -connect new hosts. -Basically this option forces the user to manually -add any new hosts. -Normally this option is disabled, and new hosts -will automatically be added to the known host files. -The host keys of -known hosts will be verified automatically in either case. -The argument must be -.Dq yes -or -.Dq no . -.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 yes . -Note that setting this option to -.Dq no -turns off -.Cm RhostsAuthentication -and -.Cm RhostsRSAAuthentication . -.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 instead of -.Pa $HOME/.ssh/known_hosts . -.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 . +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: @@ -869,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 @@ -879,20 +681,47 @@ 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. The variable contains three space-separated values: client ip-address, client port number, and server port number. +.It Ev SSH_ORIGINAL_COMMAND +The variable contains the original command line if a forced command +is executed. +It can be used to extract the original arguments. .It Ev SSH_TTY This is set to the name of the tty (path to the device) associated with the current shell or command. @@ -900,7 +729,7 @@ If the current session has no tty, this variable is not set. .It Ev TZ The timezone variable is set to indicate the present timezone if it -was set when the daemon was started (e.i., the daemon passes the value +was set when the daemon was started (i.e., the daemon passes the value on to new connections). .It Ev USER Set to the name of the user logging in. @@ -912,59 +741,68 @@ 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 -Records host keys for all hosts the user has logged into (that are not +Records host keys for all hosts the user has logged into that are not in -.Pa /etc/ssh_known_hosts ) . +.Pa /etc/ssh/ssh_known_hosts . See .Xr sshd 8 . -.It Pa $HOME/.ssh/identity -Contains the RSA authentication identity of the user. -This file -contains sensitive data and should be readable by the user but not +.It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa +Contains the authentication identity of the user. +They are for protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively. +These files +contain sensitive data and should be readable by the user but not accessible by others (read/write/execute). Note that .Nm -ignores this file if it is accessible by others. +ignores a private key file if it is accessible by others. It is possible to specify a passphrase when generating the key; the passphrase will be used to encrypt the sensitive part of this file using 3DES. -.It Pa $HOME/.ssh/identity.pub +.It Pa $HOME/.ssh/identity.pub, $HOME/.ssh/id_dsa.pub, $HOME/.ssh/id_rsa.pub Contains the public key for authentication (public part of the identity file in human-readable form). -The contents of this file should be added to +The contents of the +.Pa $HOME/.ssh/identity.pub +file should be added to +.Pa $HOME/.ssh/authorized_keys +on all machines +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_keys on all machines -where you wish to log in using RSA authentication. -This file is not +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. -This file is -never used automatically and is not necessary; it is only provided for +These files are +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). +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 +.It Pa /etc/ssh/ssh_known_hosts Systemwide list of known host keys. This file should be prepared by the system administrator to contain the public host keys of all machines in the @@ -972,8 +810,7 @@ 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. @@ -988,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 @@ -1004,7 +862,7 @@ also used by rlogin and rsh, which makes using this file insecure.) Each line of the file contains a host name (in the canonical form returned by name servers), and then a user name on that host, separated by a space. -One some machines this file may need to be +On some machines this file may need to be world-readable if the user's home directory is on a NFS partition, because .Xr sshd 8 @@ -1019,13 +877,13 @@ 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 -will automatically add the host key inxi +will automatically add the host key to .Pa $HOME/.ssh/known_hosts . .It Pa $HOME/.shosts This file is used exactly the same way as @@ -1034,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 @@ -1057,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. @@ -1076,43 +934,39 @@ manual page for more information. Contains additional definitions for environment variables, see section .Sx ENVIRONMENT above. -.It Pa libcrypto.so.X.1 -A version of this library which includes support for the RSA algorithm -is required for proper operation. -.Sh AUTHOR -OpenSSH -is a derivative of the original (free) ssh 1.2.12 release by Tatu Ylonen, -but with bugs removed and newer features re-added. -Rapidly after the -1.2.12 release, newer versions of the original ssh bore successively -more restrictive licenses, and thus demand for a free version was born. -This version of OpenSSH -.Bl -bullet -.It -has all components of a restrictive nature (i.e., patents) -directly removed from the source code; any licensed or patented components -are chosen from -external libraries. -.It -has been updated to support ssh protocol 1.5, making it compatible with -all other ssh protocol 1 clients and servers. -.It -contains added support for -.Xr kerberos 8 -authentication and ticket passing. -.It -supports one-time password authentication with -.Xr skey 1 . .El -.Pp -OpenSSH has been created by Aaron Campbell, Bob Beck, Markus Friedl, -Niels Provos, Theo de Raadt, and Dug Song. +.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. +Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, +Theo de Raadt and Dug Song +removed many bugs, re-added newer features and +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 , .Xr ssh-add 1 , .Xr ssh-agent 1 , .Xr ssh-keygen 1 , .Xr telnet 1 , -.Xr sshd 8 , +.Xr ssh_config 5 , +.Xr ssh-keysign 8 , +.Xr sshd 8 +.Rs +.%A T. Ylonen +.%A T. Kivinen +.%A M. Saarinen +.%A T. Rinne +.%A S. Lehtinen +.%T "SSH Protocol Architecture" +.%N draft-ietf-secsh-architecture-12.txt +.%D January 2002 +.%O work in progress material +.Re