.\" (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.151 2002/05/06 23:34:33 millert Exp $
+.\" $OpenBSD: ssh.1,v 1.158 2002/06/20 19:56:07 stevesk Exp $
.Dd September 25, 1999
.Dt SSH 1
.Os
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:
.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 Compression
-option below.
+option.
.It Fl F Ar configfile
Specifies an alternative per-user configuration file.
If a configuration file is given on the command line,
.El
.Sh CONFIGURATION FILES
.Nm
-obtains configuration data from the following sources in
-the following order:
-command line options,
-feature-specific user configuration file(s) (see below),
-user's configuration file
-.Pq Pa $HOME/.ssh/config ,
-and system-wide configuration file
-.Pq Pa /etc/ssh/ssh_config .
-For compatibility with other
-.Nm
-versions, the following feature-specific user configuration files
-will be processed after the command line options but before the user's
-main configuration file, so options that other
-.Nm
-versions may not support don't need to go in the main configuration file:
-.Bl -tag -width Ds
-.It Pa $HOME/.ssh/config.gssapi
-Read if GSSAPI authentication is supported. This is a good place for
-the GssapiAuthentication and GssapiDelegateCredentials options.
-.It Pa $HOME/.ssh/config.krb
-Read if Kerberos authentication is supported. This is a good place
-for the KerberosAuthentication and KerberosTgtPassing options.
-.It Pa $HOME/.ssh/config.afs
-Read if AFS token passing is supported. This is a good place for the
-AfsTokenPassing option.
-.El
-.Pp
-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 .
-Configuration options may be separated by whitespace or
-optional whitespace and exactly one
-.Ql = ;
-the latter format is useful to avoid the need to quote whitespace
-when specifying configuration options using the
-.Nm ssh ,
-.Nm scp
-and
-.Nm sftp
-.Fl o
-option.
-.Pp
-The possible
-keywords and their meanings are as follows (note that
-keywords are case-insensitive and arguments 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 .
-This option applies to protocol version 1 only.
-.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 no user
-is present to supply the password.
-The argument must be
-.Dq yes
-or
-.Dq no .
-The default is
-.Dq no .
-.It Cm BindAddress
-Specify the interface to transmit from on machines with multiple
-interfaces or aliased addresses.
-Note that this option does not work if
-.Cm UsePrivilegedPort
-is set to
-.Dq yes .
-.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 ,
-.Dq 3des ,
-and
-.Dq des
-are supported.
-.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.
-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''
-.Ed
-.It Cm ClearAllForwardings
-Specifies that all local, remote and dynamic port forwardings
-specified in the configuration files or on the command line be
-cleared. This option is primarily useful when used from the
-.Nm
-command line to clear port forwardings set in
-configuration files, and is automatically set by
-.Xr scp 1
-and
-.Xr sftp 1 .
-The argument must be
-.Dq yes
-or
-.Dq no .
-The default is
-.Dq no .
-.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 .
-Note that this option applies to protocol version 1 only.
-.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 1.
-.It Cm DynamicForward
-Specifies that a TCP/IP port on the local machine be forwarded
-over the secure channel, and the application
-protocol is then used to determine where to connect to from the
-remote machine. The argument must be a port number.
-Currently the SOCKS4 protocol is supported, and
-.Nm
-will act as a SOCKS4 server.
-Multiple forwardings may be specified, and
-additional forwardings can be given on the command line. Only
-the superuser can forward privileged ports.
-.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.
-By default,
-.Nm
-binds local port forwardings to the loopback addresss. This
-prevents other remote hosts from connecting to forwarded ports.
-.Cm GatewayPorts
-can be used to specify that
-.Nm
-should bind local port forwardings to the wildcard address,
-thus allowing remote hosts to connect to 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 global
-host key database instead of
-.Pa /etc/ssh/ssh_known_hosts .
-.It Cm GssapiAuthentication
-Specifies whether authentication based on GSSAPI may be used, either using
-the result of a successful key exchange, or using GSSAPI user
-authentication.
-The default is
-.Dq yes .
-.It Cm GssapiDelegateCredentials
-Specifies whether GSSAPI credentials will be delegated (forwarded) to
-the server.
-The default is
-.Dq yes .
-.It Cm HostbasedAuthentication
-Specifies whether to try rhosts based authentication with public key
-authentication.
-The argument must be
-.Dq yes
-or
-.Dq no .
-The default is
-.Dq no .
-This option applies to protocol version 2 only and
-is similar to
-.Cm RhostsRSAAuthentication .
-.It Cm HostKeyAlgorithms
-Specifies 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 HostKeyAlias
-Specifies an alias that should be used instead of the
-real host name when looking up or saving the host key
-in the host key database files.
-This option is useful for tunneling ssh connections
-or for multiple servers running on a single host.
-.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 a file from which the user's RSA or DSA authentication identity
-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.
-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 TCP 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 .
-.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 the specified host and port from the remote machine.
-The first argument must be a port number, and the second must be
-.Ar host:port .
-IPv6 addresses can be specified with an alternative syntax:
-.Ar 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, DEBUG, DEBUG1, DEBUG2 and DEBUG3.
-The default is INFO. DEBUG and DEBUG1 are equivalent. DEBUG2
-and DEBUG3 each specify higher levels of verbose output.
-.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
-.Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 .
-.It Cm NoHostAuthenticationForLocalhost
-This option can be used if the home directory is shared across machines.
-In this case localhost will refer to a different machine on each of
-the machines and the user will get many warnings about changed host keys.
-However, this option disables host authentication for localhost.
-The argument to this keyword must be
-.Dq yes
-or
-.Dq no .
-The default is to check the host key for localhost.
-.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 .
-.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 hostbased,publickey,keyboard-interactive,password .
-.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 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 .
-This option applies to protocol version 2 only.
-.It Cm RemoteForward
-Specifies that a TCP/IP port on the remote machine be forwarded over
-the secure channel to the specified host and port from the local machine.
-The first argument must be a port number, and the second must be
-.Ar host:port .
-IPv6 addresses can be specified with an alternative syntax:
-.Ar 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
-.Cm RhostsRSAAuthentication ) .
-The argument to this keyword must be
-.Dq yes
-or
-.Dq no .
-The default is
-.Dq yes .
-This option applies to protocol version 1 only.
-.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 .
-This option applies to protocol version 1 only.
-.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.
-The argument to this keyword must be
-.Dq yes
-or
-.Dq no .
-The default is
-.Dq yes .
-.It Cm SmartcardDevice
-Specifies which smartcard device to use. The argument to this keyword is
-the device
-.Nm
-should use to communicate with a smartcard used for storing the user's
-private RSA key. By default, no device is specified and smartcard support
-is not activated.
-.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
-file, and refuses to connect to hosts whose host key has changed.
-This provides maximum protection against trojan horse attacks,
-however, can be annoying when the
-.Pa /etc/ssh/ssh_known_hosts
-file is poorly maintained, or connections to new hosts are
-frequently made.
-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 this option must be set to
-.Dq yes
-if
-.Cm RhostsAuthentication
-and
-.Cm RhostsRSAAuthentication
-authentications are needed with older servers.
-.It Cm User
-Specifies the user to log in as.
-This can be useful when a different user name is used 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 user
-host key database 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 .
-.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:
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 public keys (RSA/DSA) that can be used for logging in as this user.
The format of this file is described in the
would then be able to fool host authentication.
.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 .
-Since they are readable only by root
+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
-must be setuid root if these authentication methods are desired.
+is not setuid root.
.It Pa $HOME/.rhosts
This file is used in
.Pa \&.rhosts
.Xr ssh-agent 1 ,
.Xr ssh-keygen 1 ,
.Xr telnet 1 ,
+.Xr ssh_config 4 ,
+.Xr ssh-keysign 8,
.Xr sshd 8
.Rs
.%A T. Ylonen
andersk / gssapi-openssh.git / blobdiff