SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
NAME
ssh_config - OpenSSH SSH client configuration files
SYNOPSIS
$HOME/.ssh/config
/etc/openssh/ssh_config
DESCRIPTION
ssh obtains configuration data from the following sources in
the following order:
1. command-line options
2. user's configuration file ($HOME/.ssh/config)
3. system-wide configuration file
(/etc/openssh/ssh_config)
For each parameter, the first obtained value will be
used. The configuration files contain sections
bracketed by ``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.
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.
The configuration file has the following format:
Empty lines and lines starting with `#' are comments.
Otherwise a line is of the format ``keyword
arguments''. Configuration options may be separated by
whitespace or optional whitespace and exactly one `=' ;
the latter format is useful to avoid the need to quote
whitespace when specifying configuration options using
the ssh, scp and sftp -o option.
The possible keywords and their meanings are as follows
(note that keywords are case-insensitive and arguments
are case-sensitive):
Host Restricts the following declarations (up to the next
Host keyword) to be only for those hosts that match one
of the patterns given after the keyword. `*' and `?'
can be used as wildcards in the patterns. A single `*'
as a pattern can be used to provide global defaults for
all hosts. The host is the hostname argument given on
Page 1 (printed 10/26/05)
SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
the command line (i.e., the name is not converted to a
canonicalized host name before matching).
AddressFamily
Specifies which address family to use when connecting.
Valid arguments are ``any'', ``inet'' (Use IPv4 only)
or ``inet6'' (Use IPv6 only.)
BatchMode
If set to ``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 ``yes'' or ``no''. The
default is ``no''.
BindAddress
Specify the interface to transmit from on machines with
multiple interfaces or aliased addresses. Note that
this option does not work if UsePrivilegedPort is set
to ``yes''.
ChallengeResponseAuthentication
Specifies whether to use challenge response
authentication. The argument to this keyword must be
``yes'' or ``no''. The default is ``yes''.
CheckHostIP
If this flag is set to ``yes'', ssh will additionally
check the host IP address in the known_hosts file.
This allows ssh to detect if a host key changed due to
DNS spoofing. If the option is set to ``no'', the
check will not be executed. The default is ``yes''.
Cipher
Specifies the cipher to use for encrypting the session
in protocol version 1. Currently, ``blowfish'',
``3des'', and ``des'' are supported. des is only
supported in the ssh client for interoperability with
legacy protocol 1 implementations that do not support
the 3des cipher. Its use is strongly discouraged due
to cryptographic weaknesses. The default is ``3des''.
Ciphers
Specifies the ciphers allowed for protocol version 2 in
order of preference. Multiple ciphers must be comma-
separated. The supported ciphers are ``3des-cbc'',
``aes128-cbc'', ``aes192-cbc'', ``aes256-cbc'',
``aes128-ctr'', ``aes192-ctr'', ``aes256-ctr'',
``arcfour'', ``blowfish-cbc'', and ``cast128-cbc''.
The default is
``aes128-cbc,3des-cbc,blowfish-cbc,cast128-
Page 2 (printed 10/26/05)
SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
cbc,arcfour,
aes192-cbc,aes256-cbc''
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 ssh command line to clear
port forwardings set in configuration files, and is
automatically set by scp(1) and sftp(1). The argument
must be ``yes'' or ``no''. The default is ``no''.
Compression
Specifies whether to use compression. The argument
must be ``yes'' or ``no''. The default is ``no''.
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 gzip(1). Note that this
option applies to protocol version 1 only.
ConnectionAttempts
Specifies the number of tries (one per second) to make
before exiting. The argument must be an integer. This
may be useful in scripts if the connection sometimes
fails. The default is 1.
ConnectTimeout
Specifies the timeout (in seconds) used when connecting
to the ssh server, instead of using the default system
TCP timeout. This value is used only when the target
is down or really unreachable, not when it refuses the
connection.
ControlMaster
Enables the sharing of multiple sessions over a single
network connection. When set to ``yes'' ssh will
listen for connections on a control socket specified
using the ControlPath argument. Additional sessions
can connect to this socket using the same ControlPath
with ControlMaster set to ``no'' (the default). These
sessions will reuse the master instance's network
connection rather than initiating new ones. Setting
this to ``ask'' will cause ssh to listen for control
connections, but require confirmation using the
SSH_ASKPASS program before they are accepted (see ssh-
add(1) for details).
ControlPath
Page 3 (printed 10/26/05)
SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
Specify the path to the control socket used for
connection sharing. See ControlMaster above.
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 and SOCKS5 protocols are
supported, and ssh will act as a SOCKS server.
Multiple forwardings may be specified, and additional
forwardings can be given on the command line. Only the
superuser can forward privileged ports.
EnableSSHKeysign
Setting this option to ``yes'' in the global client
configuration file /etc/openssh/ssh_config enables the
use of the helper program ssh-keysign(8) during
HostbasedAuthentication. The argument must be ``yes''
or ``no''. The default is ``no''. This option should
be placed in the non-hostspecific section. See ssh-
keysign(8) for more information.
EscapeChar
Sets the escape character (default: `~' ) . The
escape character can also be set on the command line.
The argument should be a single character, `^' followed
by a letter, or ``none'' to disable the escape
character entirely (making the connection transparent
for binary data).
ForwardAgent
Specifies whether the connection to the authentication
agent (if any) will be forwarded to the remote machine.
The argument must be ``yes'' or ``no''. The default is
``no''.
Agent forwarding should be enabled with caution. Users
with the ability to bypass file permissions on the
remote host (for the agent's Unix-domain socket) can
access the local agent through the forwarded
connection. An attacker cannot obtain key material
from the agent, however they can perform operations on
the keys that enable them to authenticate using the
identities loaded into the agent.
ForwardX11
Specifies whether X11 connections will be automatically
redirected over the secure channel and DISPLAY set.
The argument must be ``yes'' or ``no''. The default is
``no''.
Page 4 (printed 10/26/05)
SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
X11 forwarding should be enabled with caution. Users
with the ability to bypass file permissions on the
remote host (for the user's X11 authorization database)
can access the local X11 display through the forwarded
connection. An attacker may then be able to perform
activities such as keystroke monitoring if the
ForwardX11Trusted option is also enabled.
ForwardX11Trusted
If this option is set to ``yes'' then remote X11
clients will have full access to the original X11
display. If this option is set to ``no'' then remote
X11 clients will be considered untrusted and prevented
from stealing or tampering with data belonging to
trusted X11 clients.
The default is ``no''.
See the X11 SECURITY extension specification for full
details on the restrictions imposed on untrusted
clients.
GatewayPorts
Specifies whether remote hosts are allowed to connect
to local forwarded ports. By default, ssh binds local
port forwardings to the loopback address. This
prevents other remote hosts from connecting to
forwarded ports. GatewayPorts can be used to specify
that ssh should bind local port forwardings to the
wildcard address, thus allowing remote hosts to connect
to forwarded ports. The argument must be ``yes'' or
``no''. The default is ``no''.
GlobalKnownHostsFile
Specifies a file to use for the global host key
database instead of /etc/openssh/ssh_known_hosts.
GSSAPIAuthentication
Specifies whether user authentication based on GSSAPI
is allowed. The default is ``no''. Note that this
option applies to protocol version 2 only.
GSSAPIDelegateCredentials
Forward (delegate) credentials to the server. The
default is ``no''. Note that this option applies to
protocol version 2 only.
HostbasedAuthentication
Specifies whether to try rhosts based authentication
with public key authentication. The argument must be
``yes'' or ``no''. The default is ``no''. This option
applies to protocol version 2 only and is similar to
Page 5 (printed 10/26/05)
SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
RhostsRSAAuthentication.
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: ``ssh-rsa,ssh-dss''.
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.
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 HostName specifications).
IdentityFile
Specifies a file from which the user's RSA or DSA
authentication identity is read. The default is
$HOME/.ssh/identity for protocol version 1, and
$HOME/.ssh/id_rsa and $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.
IdentitiesOnly
Specifies that ssh should only use the authentication
identity files configured in the ssh_config files, even
if the ssh-agent offers more identities. The argument
to this keyword must be ``yes'' or ``no''. This option
is intented for situations where ssh-agent offers many
different identities. The default is ``no''.
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
host:port. IPv6 addresses can be specified with an
alternative syntax: host/port. Multiple forwardings
may be specified, and additional forwardings can be
given on the command line. Only the superuser can
forward privileged ports.
Page 6 (printed 10/26/05)
SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
LogLevel
Gives the verbosity level that is used when logging
messages from 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.
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 ``hmac-md5,hmac-sha1,hmac-
ripemd160,hmac-sha1-96,hmac-md5-96''.
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
``yes'' or ``no''. The default is to check the host
key for localhost.
NumberOfPasswordPrompts
Specifies the number of password prompts before giving
up. The argument to this keyword must be an integer.
Default is 3.
PasswordAuthentication
Specifies whether to use password authentication. The
argument to this keyword must be ``yes'' or ``no''.
The default is ``yes''.
Port Specifies the port number to connect on the remote
host. Default is 22.
PreferredAuthentications
Specifies the order in which the client should try
protocol 2 authentication methods. This allows a
client to prefer one method (e.g. keyboard-
interactive) over another method (e.g. password) The
default for this option is:
``hostbased,publickey,keyboard-interactive,password''.
Protocol
Specifies the protocol versions ssh should support in
order of preference. The possible values are ``1'' and
``2''. Multiple versions must be comma-separated. The
default is ``2,1''. This means that ssh tries version
2 and falls back to version 1 if version 2 is not
Page 7 (printed 10/26/05)
SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
available.
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 /bin/sh. In the command string, `%h'
will be substituted by the host name to connect and
`%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 sshd(8) server running on some machine, or
execute 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). Setting
the command to ``none'' disables this option entirely.
Note that CheckHostIP is not available for connects
with a proxy command.
PubkeyAuthentication
Specifies whether to try public key authentication.
The argument to this keyword must be ``yes'' or ``no''.
The default is ``yes''. This option applies to
protocol version 2 only.
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
host:port. IPv6 addresses can be specified with an
alternative syntax: host/port. Multiple forwardings
may be specified, and additional forwardings can be
given on the command line. Only the superuser can
forward privileged ports.
RhostsRSAAuthentication
Specifies whether to try rhosts based authentication
with RSA host authentication. The argument must be
``yes'' or ``no''. The default is ``no''. This option
applies to protocol version 1 only and requires ssh to
be setuid root.
RSAAuthentication
Specifies whether to try RSA authentication. The
argument to this keyword must be ``yes'' or ``no''.
RSA authentication will only be attempted if the
identity file exists, or an authentication agent is
running. The default is ``yes''. Note that this
option applies to protocol version 1 only.
SendEnv
Page 8 (printed 10/26/05)
SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
Specifies what variables from the local environ(7)
should be sent to the server. Note that environment
passing is only supported for protocol 2, the server
must also support it, and the server must be configured
to accept these environment variables. Refer to
AcceptEnv in sshd_config(5) for how to configure the
server. Variables are specified by name, which may
contain the wildcard characters `*' and `?'. Multiple
environment variables may be separated by whitespace or
spread across multiple SendEnv directives. The default
is not to send any environment variables.
ServerAliveInterval
Sets a timeout interval in seconds after which if no
data has been received from the server, ssh will send a
message through the encrypted channel to request a
response from the server. The default is 0, indicating
that these messages will not be sent to the server.
This option applies to protocol version 2 only.
ServerAliveCountMax
Sets the number of server alive messages (see above)
which may be sent without ssh receiving any messages
back from the server. If this threshold is reached
while server alive messages are being sent, ssh will
disconnect from the server, terminating the session.
It is important to note that the use of server alive
messages is very different from TCPKeepAlive (below).
The server alive messages are sent through the
encrypted channel and therefore will not be spoofable.
The TCP keepalive option enabled by TCPKeepAlive is
spoofable. The server alive mechanism is valuable when
the client or server depend on knowing when a
connection has become inactive.
The default value is 3. If, for example,
ServerAliveInterval (above) is set to 15, and
ServerAliveCountMax is left at the default, if the
server becomes unresponsive ssh will disconnect after
approximately 45 seconds.
SmartcardDevice
Specifies which smartcard device to use. The argument
to this keyword is the device ssh 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.
StrictHostKeyChecking
If this flag is set to ``yes'', ssh will never
automatically add host keys to the
$HOME/.ssh/known_hosts file, and refuses to connect to
Page 9 (printed 10/26/05)
SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
hosts whose host key has changed. This provides
maximum protection against trojan horse attacks,
however, can be annoying when the
/etc/openssh/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 ``no'', ssh will automatically
add new host keys to the user known hosts files. If
this flag is set to ``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
ssh 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
``yes'', ``no'' or ``ask''. The default is ``ask''.
TCPKeepAlive
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.
The default is ``yes'' (to send TCP keepalive
messages), 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.
To disable TCP keepalive messages, the value should be
set to ``no''.
UsePrivilegedPort
Specifies whether to use a privileged port for outgoing
connections. The argument must be ``yes'' or ``no''.
The default is ``no''. If set to ``yes'' ssh must be
setuid root. Note that this option must be set to
``yes'' for RhostsRSAAuthentication with older servers.
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.
UserKnownHostsFile
Specifies a file to use for the user host key database
instead of $HOME/.ssh/known_hosts.
VerifyHostKeyDNS
Specifies whether to verify the remote key using DNS
and SSHFP resource records. If this option is set to
``yes'', the client will implicitly trust keys that
Page 10 (printed 10/26/05)
SSH_CONFIG(5) UNIX System V (September 25, 1999) SSH_CONFIG(5)
match a secure fingerprint from DNS. Insecure
fingerprints will be handled as if this option was set
to ``ask''. If this option is set to ``ask'',
information on fingerprint match will be displayed, but
the user will still need to confirm new host keys
according to the StrictHostKeyChecking option. The
argument must be ``yes'', ``no'' or ``ask''. The
default is ``no''. Note that this option applies to
protocol version 2 only.
XAuthLocation
Specifies the full pathname of the xauth(1) program.
The default is /usr/bin/X11/xauth.
FILES
$HOME/.ssh/config
This is the per-user configuration file. The format of
this file is described above. This file is used by the
ssh client. Because of the potential for abuse, this
file must have strict permissions: read/write for the
user, and not accessible by others.
/etc/openssh/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.
SEE ALSO
ssh(1)
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.
Page 11 (printed 10/26/05)
