version 1.139.2.4, 2002/05/17 00:03:24 |
version 1.139.2.5, 2002/06/22 07:23:18 |
|
|
otherwise be used to circumvent the encryption. |
otherwise be used to circumvent the encryption. |
The |
The |
.Cm StrictHostKeyChecking |
.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. |
host key is not known or has changed. |
.Pp |
.Pp |
The options are as follows: |
The options are as follows: |
|
|
.Dq level |
.Dq level |
can be controlled by the |
can be controlled by the |
.Cm CompressionLevel |
.Cm CompressionLevel |
option (see below). |
option. |
Compression is desirable on modem lines and other |
Compression is desirable on modem lines and other |
slow connections, but will only slow down things on fast networks. |
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 |
The default value can be set on a host-by-host basis in the |
configuration files; see the |
configuration files; see the |
.Cm Compression |
.Cm Compression |
option below. |
option. |
.It Fl F Ar configfile |
.It Fl F Ar configfile |
Specifies an alternative per-user configuration file. |
Specifies an alternative per-user configuration file. |
If a configuration file is given on the command line, |
If a configuration file is given on the command line, |
|
|
.El |
.El |
.Sh CONFIGURATION FILES |
.Sh CONFIGURATION FILES |
.Nm |
.Nm |
obtains configuration data from the following sources in |
may additionally obtain configuration data from |
the following order: |
a per-user configuration file and a system-wide configuration file. |
command line options, user's configuration file |
The file format and configuration options are described in |
.Pq Pa $HOME/.ssh/config , |
.Xr ssh_config 5 . |
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 . |
|
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_known_hosts . |
|
.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_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 |
|
.Sh ENVIRONMENT |
.Sh ENVIRONMENT |
.Nm |
.Nm |
will normally set the following environment variables: |
will normally set the following environment variables: |
|
|
the convenience of the user. |
the convenience of the user. |
.It Pa $HOME/.ssh/config |
.It Pa $HOME/.ssh/config |
This is the per-user configuration file. |
This is the per-user configuration file. |
The format of this file is described above. |
The file format and configuration options are described in |
This file is used by the |
.Xr ssh_config 5 . |
.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. |
|
.It Pa $HOME/.ssh/authorized_keys |
.It Pa $HOME/.ssh/authorized_keys |
Lists the public keys (RSA/DSA) 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 |
The format of this file is described in the |
|
|
does not convert the user-supplied name to a canonical name before |
does not convert the user-supplied name to a canonical name before |
checking the key, because someone with access to the name servers |
checking the key, because someone with access to the name servers |
would then be able to fool host authentication. |
would then be able to fool host authentication. |
.It Pa /etc/ssh_config |
.It Pa /etc/ssh/ssh_config |
Systemwide configuration file. |
Systemwide configuration file. |
This file provides defaults for those |
The file format and configuration options are described in |
values that are not specified in the user's configuration file, and |
.Xr ssh_config 5 . |
for those users who do not have a configuration file. |
.It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key |
This file must be world-readable. |
|
.It Pa /etc/ssh_host_key, /etc/ssh_host_dsa_key, /etc/ssh_host_rsa_key |
|
These three files contain the private parts of the host keys |
These three files contain the private parts of the host keys |
and are used for |
and are used for |
.Cm RhostsRSAAuthentication |
.Cm RhostsRSAAuthentication |
and |
and |
.Cm HostbasedAuthentication . |
.Cm HostbasedAuthentication . |
Since they are readable only by root |
If the protocol version 1 |
|
.Cm RhostsRSAAuthentication |
|
method is used, |
.Nm |
.Nm |
must be setuid root if these authentication methods are desired. |
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 |
.It Pa $HOME/.rhosts |
This file is used in |
This file is used in |
.Pa \&.rhosts |
.Pa \&.rhosts |
|
|
.Xr ssh-agent 1 , |
.Xr ssh-agent 1 , |
.Xr ssh-keygen 1 , |
.Xr ssh-keygen 1 , |
.Xr telnet 1 , |
.Xr telnet 1 , |
|
.Xr ssh_config 4 , |
|
.Xr ssh-keysign 8, |
.Xr sshd 8 |
.Xr sshd 8 |
.Rs |
.Rs |
.%A T. Ylonen |
.%A T. Ylonen |