ssh_config.5

OpenSSL Source code for SFTP, SSH, and many others

.\"  -*- nroff -*-
.\"
.\" Author: Tatu Ylonen <[e-mail]>
.\" Copyright (c) 1995 Tatu Ylonen <[e-mail]>, Espoo, Finland
.\"                    All rights reserved
.\"
.\" 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.
.\"
.\" 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_config.5,v 1.1 2002/06/20 19:56:07 stevesk Exp $
.Dd September 25, 1999
.Dt SSH_CONFIG 5
.Os
.Sh NAME
.Nm ssh_config
.Nd OpenSSH SSH client configuration files
.Sh SYNOPSIS
.Bl -tag -width Ds -compact
.It Pa $HOME/.ssh/config
.It Pa /etc/ssh/ssh_config
.El
.Sh DESCRIPTION
.Nm ssh
obtains configuration data from the following sources in
the following order:
command line options, user's configuration file
.Pq Pa $HOME/.ssh/config ,
and system-wide configuration file
.Pq Pa /etc/ssh/ssh_config .
.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 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 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 ssh
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 ssh
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 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 ssh
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 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 ssh
binds local port forwardings to the loopback address.  This
prevents other remote hosts from connecting to forwarded ports.
.Cm GatewayPorts
can be used to specify that
.Nm ssh
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 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