X-Git-Url: http://andersk.mit.edu/gitweb/openssh.git/blobdiff_plain/c5786b30b866e830b4ffe12e4e87e2b63207ed08..HEAD:/ssh_config.5

diff --git a/ssh_config.5 b/ssh_config.5
index 40fef73c..7d577360 100644
--- a/ssh_config.5
+++ b/ssh_config.5
@@ -34,18 +34,16 @@
 .\" (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.84 2006/02/24 23:20:07 jmc Exp $
-.Dd September 25, 1999
+.\" $OpenBSD: ssh_config.5,v 1.126 2010/01/09 23:04:13 dtucker Exp $
+.Dd $Mdocdate$
 .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 ~/.ssh/config
-.It Pa /etc/ssh/ssh_config
-.El
+.Nm ~/.ssh/config
+.Nm /etc/ssh/ssh_config
 .Sh DESCRIPTION
 .Xr ssh 1
 obtains configuration data from the following sources in
@@ -73,42 +71,7 @@ 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.
-.Sh PATTERNS
-A
-.Em pattern
-consists of zero or more non-whitespace characters,
-.Sq *
-(a wildcard that matches zero or more characters),
-or
-.Sq ?\&
-(a wildcard that matches exactly one character).
-For example, to specify a set of declarations for any host in the
-.Dq .co.uk
-set of domains,
-the following pattern could be used:
-.Pp
-.Dl Host *.co.uk
-.Pp
-The following pattern
-would match any host in the 192.168.0.[0-9] network range:
-.Pp
-.Dl Host 192.168.0.?
-.Pp
-A
-.Em pattern-list
-is a comma-separated list of patterns.
-Patterns within pattern-lists may be negated
-by preceding them with an exclamation mark
-.Pq Sq !\& .
-For example,
-to allow a key to be used from anywhere within an organisation
-except from the
-.Dq dialup
-pool,
-the following entry (in authorized_keys) could be used:
 .Pp
-.Dl from=\&"!*.dialup.example.com,*.example.com\&"
-.Sh FILE FORMAT
 The configuration file has the following format:
 .Pp
 Empty lines and lines starting with
@@ -122,11 +85,14 @@ optional whitespace and exactly one
 the latter format is useful to avoid the need to quote whitespace
 when specifying configuration options using the
 .Nm ssh ,
-.Nm scp
+.Nm scp ,
 and
 .Nm sftp
 .Fl o
 option.
+Arguments may optionally be enclosed in double quotes
+.Pq \&"
+in order to represent arguments containing spaces.
 .Pp
 The possible
 keywords and their meanings are as follows (note that
@@ -137,6 +103,7 @@ 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.
+If more than one pattern is provided, they should be separated by whitespace.
 A single
 .Ql *
 as a pattern can be used to provide global
@@ -237,9 +204,9 @@ and
 .Dq cast128-cbc .
 The default is:
 .Bd -literal -offset 3n
-aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128,
-arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr,
-aes192-ctr,aes256-ctr
+aes128-ctr,aes192-ctr,aes256-ctr,arcfour256,arcfour128,
+aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,aes192-cbc,
+aes256-cbc,arcfour
 .Ed
 .It Cm ClearAllForwardings
 Specifies that all local, remote, and dynamic port forwardings
@@ -417,6 +384,17 @@ followed by a letter, or
 to disable the escape
 character entirely (making the connection transparent for binary
 data).
+.It Cm ExitOnForwardFailure
+Specifies whether
+.Xr ssh 1
+should terminate the connection if it cannot set up all requested
+dynamic, tunnel, local, and remote port forwardings.
+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.
@@ -518,8 +496,9 @@ but they do not reveal identifying information should the file's contents
 be disclosed.
 The default is
 .Dq no .
-Note that hashing of names and addresses will not be retrospectively applied
-to existing known hosts files, but these may be manually hashed using
+Note that existing names and addresses in known hosts files
+will not be converted automatically,
+but may be manually hashed using
 .Xr ssh-keygen 1 .
 .It Cm HostbasedAuthentication
 Specifies whether to try rhosts based authentication with public key
@@ -580,20 +559,70 @@ and
 for protocol version 2.
 Additionally, any identities represented by the authentication agent
 will be used for authentication.
+.Pp
 The file name may use the tilde
-syntax to refer to a user's home directory.
+syntax to refer to a user's home directory or one of the following
+escape characters:
+.Ql %d
+(local user's home directory),
+.Ql %u
+(local user name),
+.Ql %l
+(local host name),
+.Ql %h
+(remote host name) or
+.Ql %r
+(remote user name).
+.Pp
 It is possible to have
 multiple identity files specified in configuration files; all these
 identities will be tried in sequence.
+.It Cm KbdInteractiveAuthentication
+Specifies whether to use keyboard-interactive authentication.
+The argument to this keyword must be
+.Dq yes
+or
+.Dq no .
+The default is
+.Dq yes .
 .It Cm KbdInteractiveDevices
 Specifies the list of methods to use in keyboard-interactive authentication.
 Multiple method names must be comma-separated.
 The default is to use the server specified list.
+The methods available vary depending on what the server supports.
+For an OpenSSH server,
+it may be zero or more of:
+.Dq bsdauth ,
+.Dq pam ,
+and
+.Dq skey .
 .It Cm LocalCommand
 Specifies a command to execute on the local machine after successfully
 connecting to the server.
 The command string extends to the end of the line, and is executed with
-.Pa /bin/sh .
+the user's shell.
+The following escape character substitutions will be performed:
+.Ql %d
+(local user's home directory),
+.Ql %h
+(remote host name),
+.Ql %l
+(local host name),
+.Ql %n
+(host name as provided on the command line),
+.Ql %p
+(remote port),
+.Ql %r
+(remote user name) or
+.Ql %u
+(local user name).
+.Pp
+The command is run synchronously and does not have access to the
+session of the
+.Xr ssh 1
+that spawned it.
+It should not be used for interactive commands.
+.Pp
 This directive is ignored unless
 .Cm PermitLocalCommand
 has been enabled.
@@ -643,7 +672,10 @@ 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 .
+.Bd -literal -offset indent
+hmac-md5,hmac-sha1,umac-64@openssh.com,
+hmac-ripemd160,hmac-sha1-96,hmac-md5-96
+.Ed
 .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
@@ -690,7 +722,12 @@ This allows a client to prefer one method (e.g.\&
 over another method (e.g.\&
 .Cm password )
 The default for this option is:
-.Dq hostbased,publickey,keyboard-interactive,password .
+.Do gssapi-with-mic ,
+hostbased,
+publickey,
+keyboard-interactive,
+password
+.Dc .
 .It Cm Protocol
 Specifies the protocol versions
 .Xr ssh 1
@@ -700,16 +737,18 @@ The possible values are
 and
 .Sq 2 .
 Multiple versions must be comma-separated.
-The default is
-.Dq 2,1 .
-This means that ssh
-tries version 2 and falls back to version 1
+When this option is set to
+.Dq 2,1
+.Nm ssh
+will try version 2 and fall back to version 1
 if version 2 is not available.
+The default is
+.Sq 2 .
 .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 .
+the user's shell.
 In the command string,
 .Ql %h
 will be substituted by the host name to
@@ -781,7 +820,15 @@ and
 .Ar host Ns / Ns Ar hostport .
 Multiple forwardings may be specified, and additional
 forwardings can be given on the command line.
-Only the superuser can forward privileged ports.
+Privileged ports can be forwarded only when
+logging in as root on the remote machine.
+.Pp
+If the
+.Ar port
+argument is
+.Ql 0 ,
+the listen port will be dynamically allocated on the server and reported
+to the client at run time.
 .Pp
 If the
 .Ar bind_address
@@ -870,6 +917,7 @@ If, for example,
 .Cm ServerAliveCountMax
 is left at the default, if the server becomes unresponsive,
 ssh will disconnect after approximately 45 seconds.
+This option applies to protocol version 2 only.
 .It Cm ServerAliveInterval
 Sets a timeout interval in seconds after which if no data has been received
 from the server,
@@ -937,24 +985,44 @@ This is important in scripts, and many users want it too.
 To disable TCP keepalive messages, the value should be set to
 .Dq no .
 .It Cm Tunnel
-Request starting
+Request
 .Xr tun 4
 device forwarding between the client and the server.
-This option also allows requesting layer 2 (ethernet)
-instead of layer 3 (point-to-point) tunneling from the server.
 The argument must be
 .Dq yes ,
-.Dq point-to-point ,
-.Dq ethernet ,
+.Dq point-to-point
+(layer 3),
+.Dq ethernet
+(layer 2),
 or
 .Dq no .
+Specifying
+.Dq yes
+requests the default tunnel mode, which is
+.Dq point-to-point .
 The default is
 .Dq no .
 .It Cm TunnelDevice
-Force a specified
+Specifies the
 .Xr tun 4
-device on the client.
-Without this option, the next available device will be used.
+devices to open on the client
+.Pq Ar local_tun
+and the server
+.Pq Ar remote_tun .
+.Pp
+The argument must be
+.Sm off
+.Ar local_tun Op : Ar remote_tun .
+.Sm on
+The devices may be specified by numerical ID or the keyword
+.Dq any ,
+which uses the next available tunnel device.
+If
+.Ar remote_tun
+is not specified, it defaults to
+.Dq any .
+The default is
+.Dq any:any .
 .It Cm UsePrivilegedPort
 Specifies whether to use a privileged port for outgoing connections.
 The argument must be
@@ -1009,6 +1077,18 @@ See also
 .Sx VERIFYING HOST KEYS
 in
 .Xr ssh 1 .
+.It Cm VisualHostKey
+If this flag is set to
+.Dq yes ,
+an ASCII art representation of the remote host key fingerprint is
+printed in addition to the hex fingerprint string at login and
+for unknown host keys.
+If this flag is set to
+.Dq no ,
+no fingerprint strings are printed at login and
+only the hex fingerprint string will be printed for unknown host keys.
+The default is
+.Dq no .
 .It Cm XAuthLocation
 Specifies the full pathname of the
 .Xr xauth 1
@@ -1016,6 +1096,41 @@ program.
 The default is
 .Pa /usr/X11R6/bin/xauth .
 .El
+.Sh PATTERNS
+A
+.Em pattern
+consists of zero or more non-whitespace characters,
+.Sq *
+(a wildcard that matches zero or more characters),
+or
+.Sq ?\&
+(a wildcard that matches exactly one character).
+For example, to specify a set of declarations for any host in the
+.Dq .co.uk
+set of domains,
+the following pattern could be used:
+.Pp
+.Dl Host *.co.uk
+.Pp
+The following pattern
+would match any host in the 192.168.0.[0-9] network range:
+.Pp
+.Dl Host 192.168.0.?
+.Pp
+A
+.Em pattern-list
+is a comma-separated list of patterns.
+Patterns within pattern-lists may be negated
+by preceding them with an exclamation mark
+.Pq Sq !\& .
+For example,
+to allow a key to be used from anywhere within an organisation
+except from the
+.Dq dialup
+pool,
+the following entry (in authorized_keys) could be used:
+.Pp
+.Dl from=\&"!*.dialup.example.com,*.example.com\&"
 .Sh FILES
 .Bl -tag -width Ds
 .It Pa ~/.ssh/config