blob: c1bd7df41c68b680cac4fa01cdf180eeeeac943e [file] [log] [blame]
Ben Lindstrom9f049032002-06-21 00:59:05 +00001.\"
2.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
3.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
4.\" All rights reserved
5.\"
6.\" As far as I am concerned, the code I have written for this software
7.\" can be used freely for any purpose. Any derived versions of this
8.\" software must be clearly marked as such, and if the derived work is
9.\" incompatible with the protocol description in the RFC file, it must be
10.\" called by a name other than "ssh" or "Secure Shell".
11.\"
12.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
13.\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
14.\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
15.\"
16.\" Redistribution and use in source and binary forms, with or without
17.\" modification, are permitted provided that the following conditions
18.\" are met:
19.\" 1. Redistributions of source code must retain the above copyright
20.\" notice, this list of conditions and the following disclaimer.
21.\" 2. Redistributions in binary form must reproduce the above copyright
22.\" notice, this list of conditions and the following disclaimer in the
23.\" documentation and/or other materials provided with the distribution.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
26.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
27.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
28.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
29.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
30.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
31.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
32.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
34.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35.\"
jmc@openbsd.org08696272017-10-24 06:27:42 +000036.\" $OpenBSD: ssh_config.5,v 1.262 2017/10/24 06:27:42 jmc Exp $
37.Dd $Mdocdate: October 24 2017 $
Ben Lindstrom9f049032002-06-21 00:59:05 +000038.Dt SSH_CONFIG 5
39.Os
40.Sh NAME
41.Nm ssh_config
42.Nd OpenSSH SSH client configuration files
Ben Lindstrom9f049032002-06-21 00:59:05 +000043.Sh DESCRIPTION
Damien Miller45ee2b92006-03-15 11:56:18 +110044.Xr ssh 1
Ben Lindstrom9f049032002-06-21 00:59:05 +000045obtains configuration data from the following sources in
46the following order:
Damien Miller5c853b52006-03-15 11:37:02 +110047.Pp
Ben Lindstrom479b4762002-08-20 19:04:51 +000048.Bl -enum -offset indent -compact
49.It
50command-line options
51.It
52user's configuration file
Damien Miller167ea5d2005-05-26 12:04:02 +100053.Pq Pa ~/.ssh/config
Ben Lindstrom479b4762002-08-20 19:04:51 +000054.It
55system-wide configuration file
56.Pq Pa /etc/ssh/ssh_config
57.El
Ben Lindstrom9f049032002-06-21 00:59:05 +000058.Pp
59For each parameter, the first obtained value
60will be used.
Darren Tucker43d8e282005-02-09 09:51:08 +110061The configuration files contain sections separated by
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +000062.Cm Host
Ben Lindstrom9f049032002-06-21 00:59:05 +000063specifications, and that section is only applied for hosts that
64match one of the patterns given in the specification.
djm@openbsd.org957fbce2014-10-08 22:20:25 +000065The matched host name is usually the one given on the command line
66(see the
67.Cm CanonicalizeHostname
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +000068option for exceptions).
Ben Lindstrom9f049032002-06-21 00:59:05 +000069.Pp
70Since the first obtained value for each parameter is used, more
71host-specific declarations should be given near the beginning of the
72file, and general defaults at the end.
73.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +000074The file contains keyword-argument pairs, one per line.
75Lines starting with
Ben Lindstrom9f049032002-06-21 00:59:05 +000076.Ql #
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +000077and empty lines are interpreted as comments.
78Arguments may optionally be enclosed in double quotes
79.Pq \&"
80in order to represent arguments containing spaces.
Ben Lindstrom9f049032002-06-21 00:59:05 +000081Configuration options may be separated by whitespace or
82optional whitespace and exactly one
83.Ql = ;
84the latter format is useful to avoid the need to quote whitespace
85when specifying configuration options using the
86.Nm ssh ,
Damien Miller4aea9742006-03-15 11:59:39 +110087.Nm scp ,
Ben Lindstrom9f049032002-06-21 00:59:05 +000088and
89.Nm sftp
90.Fl o
91option.
92.Pp
93The possible
94keywords and their meanings are as follows (note that
95keywords are case-insensitive and arguments are case-sensitive):
96.Bl -tag -width Ds
97.It Cm Host
98Restricts the following declarations (up to the next
99.Cm Host
Damien Miller194fd902013-10-15 12:13:05 +1100100or
101.Cm Match
Ben Lindstrom9f049032002-06-21 00:59:05 +0000102keyword) to be only for those hosts that match one of the patterns
103given after the keyword.
Damien Millerfa51b162008-11-03 19:17:33 +1100104If more than one pattern is provided, they should be separated by whitespace.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000105A single
Damien Miller208f1ed2006-03-15 11:56:03 +1100106.Ql *
Ben Lindstrom9f049032002-06-21 00:59:05 +0000107as a pattern can be used to provide global
108defaults for all hosts.
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000109The host is usually the
Ben Lindstrom9f049032002-06-21 00:59:05 +0000110.Ar hostname
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000111argument given on the command line
112(see the
113.Cm CanonicalizeHostname
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000114keyword for exceptions).
Damien Millerf54a4b92006-03-15 11:54:36 +1100115.Pp
Damien Millerfe924212011-05-15 08:44:45 +1000116A pattern entry may be negated by prefixing it with an exclamation mark
117.Pq Sq !\& .
118If a negated entry is matched, then the
119.Cm Host
120entry is ignored, regardless of whether any other patterns on the line
121match.
122Negated matches are therefore useful to provide exceptions for wildcard
123matches.
124.Pp
Damien Millerf54a4b92006-03-15 11:54:36 +1100125See
126.Sx PATTERNS
127for more information on patterns.
Damien Millerd77b81f2013-10-17 11:39:00 +1100128.It Cm Match
Damien Miller194fd902013-10-15 12:13:05 +1100129Restricts the following declarations (up to the next
130.Cm Host
131or
132.Cm Match
133keyword) to be used only when the conditions following the
134.Cm Match
135keyword are satisfied.
sobrado@openbsd.orge3cbb062015-09-22 08:33:23 +0000136Match conditions are specified using one or more criteria
Damien Millercf31f382013-10-24 21:02:56 +1100137or the single token
138.Cm all
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000139which always matches.
140The available criteria keywords are:
141.Cm canonical ,
Damien Miller8a04be72013-10-23 16:29:40 +1100142.Cm exec ,
Damien Miller194fd902013-10-15 12:13:05 +1100143.Cm host ,
144.Cm originalhost ,
145.Cm user ,
146and
147.Cm localuser .
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000148The
149.Cm all
150criteria must appear alone or immediately after
jmc@openbsd.orgb1ba15f2014-10-09 06:21:31 +0000151.Cm canonical .
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000152Other criteria may be combined arbitrarily.
153All criteria but
154.Cm all
155and
156.Cm canonical
157require an argument.
158Criteria may be negated by prepending an exclamation mark
159.Pq Sq !\& .
Damien Miller194fd902013-10-15 12:13:05 +1100160.Pp
Damien Miller8e5a67f2013-10-23 16:30:25 +1100161The
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000162.Cm canonical
dtucker@openbsd.orgdd2cfeb2015-05-28 05:09:45 +0000163keyword matches only when the configuration file is being re-parsed
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000164after hostname canonicalization (see the
165.Cm CanonicalizeHostname
166option.)
167This may be useful to specify conditions that work with canonical host
168names only.
169The
Damien Miller8a04be72013-10-23 16:29:40 +1100170.Cm exec
Damien Miller8e5a67f2013-10-23 16:30:25 +1100171keyword executes the specified command under the user's shell.
Damien Miller194fd902013-10-15 12:13:05 +1100172If the command returns a zero exit status then the condition is considered true.
173Commands containing whitespace characters must be quoted.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000174Arguments to
175.Cm exec
176accept the tokens described in the
177.Sx TOKENS
178section.
Damien Miller194fd902013-10-15 12:13:05 +1100179.Pp
180The other keywords' criteria must be single entries or comma-separated
181lists and may use the wildcard and negation operators described in the
182.Sx PATTERNS
183section.
184The criteria for the
185.Cm host
186keyword are matched against the target hostname, after any substitution
187by the
188.Cm Hostname
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000189or
190.Cm CanonicalizeHostname
191options.
Damien Miller194fd902013-10-15 12:13:05 +1100192The
193.Cm originalhost
194keyword matches against the hostname as it was specified on the command-line.
195The
196.Cm user
197keyword matches against the target username on the remote host.
198The
199.Cm localuser
200keyword matches against the name of the local user running
201.Xr ssh 1
202(this keyword may be useful in system-wide
203.Nm
204files).
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000205.It Cm AddKeysToAgent
206Specifies whether keys should be automatically added to a running
jmc@openbsd.orge41a0712015-11-15 23:58:04 +0000207.Xr ssh-agent 1 .
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000208If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000209.Cm yes
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000210and a key is loaded from a file, the key and its passphrase are added to
211the agent with the default lifetime, as if by
212.Xr ssh-add 1 .
213If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000214.Cm ask ,
215.Xr ssh 1
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000216will require confirmation using the
217.Ev SSH_ASKPASS
218program before adding a key (see
219.Xr ssh-add 1
220for details).
221If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000222.Cm confirm ,
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000223each use of the key must be confirmed, as if the
224.Fl c
225option was specified to
226.Xr ssh-add 1 .
227If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000228.Cm no ,
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000229no keys are added to the agent.
230The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000231.Cm yes ,
232.Cm confirm ,
233.Cm ask ,
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000234or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000235.Cm no
236(the default).
Damien Miller20a8f972003-05-18 20:50:30 +1000237.It Cm AddressFamily
Damien Millerfbf486b2003-05-23 18:44:23 +1000238Specifies which address family to use when connecting.
239Valid arguments are
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000240.Cm any
241(the default),
242.Cm inet
Damien Miller45ee2b92006-03-15 11:56:18 +1100243(use IPv4 only), or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000244.Cm inet6
Darren Tucker79a7acf2005-02-09 09:48:57 +1100245(use IPv6 only).
Ben Lindstrom9f049032002-06-21 00:59:05 +0000246.It Cm BatchMode
247If set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000248.Cm yes ,
Ben Lindstrom9f049032002-06-21 00:59:05 +0000249passphrase/password querying will be disabled.
250This option is useful in scripts and other batch jobs where no user
251is present to supply the password.
252The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000253.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000254or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000255.Cm no
256(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +0000257.It Cm BindAddress
Darren Tucker89f4d472005-07-14 17:06:21 +1000258Use the specified address on the local machine as the source address of
Darren Tucker6c71d202005-07-14 17:06:50 +1000259the connection.
260Only useful on systems with more than one address.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000261Note that this option does not work if
262.Cm UsePrivilegedPort
263is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000264.Cm yes .
Damien Miller0faf7472013-10-17 11:47:23 +1100265.It Cm CanonicalDomains
Damien Miller607af342013-10-17 11:47:51 +1100266When
Damien Miller38505592013-10-17 11:48:13 +1100267.Cm CanonicalizeHostname
Damien Miller0faf7472013-10-17 11:47:23 +1100268is enabled, this option specifies the list of domain suffixes in which to
269search for the specified destination host.
Damien Miller38505592013-10-17 11:48:13 +1100270.It Cm CanonicalizeFallbackLocal
Damien Miller51682fa2013-10-17 11:48:31 +1100271Specifies whether to fail with an error when hostname canonicalization fails.
Damien Miller607af342013-10-17 11:47:51 +1100272The default,
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000273.Cm yes ,
Damien Miller607af342013-10-17 11:47:51 +1100274will attempt to look up the unqualified hostname using the system resolver's
Damien Miller0faf7472013-10-17 11:47:23 +1100275search rules.
276A value of
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000277.Cm no
Damien Miller0faf7472013-10-17 11:47:23 +1100278will cause
279.Xr ssh 1
280to fail instantly if
Damien Miller38505592013-10-17 11:48:13 +1100281.Cm CanonicalizeHostname
Damien Miller0faf7472013-10-17 11:47:23 +1100282is enabled and the target hostname cannot be found in any of the domains
283specified by
284.Cm CanonicalDomains .
Damien Miller38505592013-10-17 11:48:13 +1100285.It Cm CanonicalizeHostname
Damien Miller51682fa2013-10-17 11:48:31 +1100286Controls whether explicit hostname canonicalization is performed.
Damien Miller607af342013-10-17 11:47:51 +1100287The default,
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000288.Cm no ,
Damien Miller0faf7472013-10-17 11:47:23 +1100289is not to perform any name rewriting and let the system resolver handle all
290hostname lookups.
291If set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000292.Cm yes
Damien Miller0faf7472013-10-17 11:47:23 +1100293then, for connections that do not use a
294.Cm ProxyCommand ,
295.Xr ssh 1
Damien Miller38505592013-10-17 11:48:13 +1100296will attempt to canonicalize the hostname specified on the command line
Damien Miller0faf7472013-10-17 11:47:23 +1100297using the
298.Cm CanonicalDomains
299suffixes and
Damien Miller38505592013-10-17 11:48:13 +1100300.Cm CanonicalizePermittedCNAMEs
Damien Miller0faf7472013-10-17 11:47:23 +1100301rules.
302If
Damien Miller38505592013-10-17 11:48:13 +1100303.Cm CanonicalizeHostname
Damien Miller0faf7472013-10-17 11:47:23 +1100304is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000305.Cm always ,
Damien Miller51682fa2013-10-17 11:48:31 +1100306then canonicalization is applied to proxied connections too.
Damien Miller13f97b22014-02-24 15:57:55 +1100307.Pp
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000308If this option is enabled, then the configuration files are processed
309again using the new target name to pick up any new configuration in matching
Damien Miller13f97b22014-02-24 15:57:55 +1100310.Cm Host
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000311and
312.Cm Match
Damien Miller13f97b22014-02-24 15:57:55 +1100313stanzas.
Damien Miller38505592013-10-17 11:48:13 +1100314.It Cm CanonicalizeMaxDots
Damien Miller607af342013-10-17 11:47:51 +1100315Specifies the maximum number of dot characters in a hostname before
Damien Miller51682fa2013-10-17 11:48:31 +1100316canonicalization is disabled.
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000317The default, 1,
Damien Miller607af342013-10-17 11:47:51 +1100318allows a single dot (i.e. hostname.subdomain).
Damien Miller38505592013-10-17 11:48:13 +1100319.It Cm CanonicalizePermittedCNAMEs
Damien Miller607af342013-10-17 11:47:51 +1100320Specifies rules to determine whether CNAMEs should be followed when
Damien Miller38505592013-10-17 11:48:13 +1100321canonicalizing hostnames.
Damien Miller0faf7472013-10-17 11:47:23 +1100322The rules consist of one or more arguments of
Damien Miller607af342013-10-17 11:47:51 +1100323.Ar source_domain_list : Ns Ar target_domain_list ,
Damien Miller0faf7472013-10-17 11:47:23 +1100324where
325.Ar source_domain_list
Damien Miller51682fa2013-10-17 11:48:31 +1100326is a pattern-list of domains that may follow CNAMEs in canonicalization,
Damien Miller0faf7472013-10-17 11:47:23 +1100327and
328.Ar target_domain_list
Damien Miller607af342013-10-17 11:47:51 +1100329is a pattern-list of domains that they may resolve to.
Damien Miller0faf7472013-10-17 11:47:23 +1100330.Pp
331For example,
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000332.Qq *.a.example.com:*.b.example.com,*.c.example.com
Damien Miller0faf7472013-10-17 11:47:23 +1100333will allow hostnames matching
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000334.Qq *.a.example.com
Damien Miller38505592013-10-17 11:48:13 +1100335to be canonicalized to names in the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000336.Qq *.b.example.com
Damien Miller0faf7472013-10-17 11:47:23 +1100337or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000338.Qq *.c.example.com
Damien Miller0faf7472013-10-17 11:47:23 +1100339domains.
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000340.It Cm CertificateFile
341Specifies a file from which the user's certificate is read.
342A corresponding private key must be provided separately in order
343to use this certificate either
344from an
345.Cm IdentityFile
346directive or
347.Fl i
348flag to
349.Xr ssh 1 ,
350via
351.Xr ssh-agent 1 ,
352or via a
353.Cm PKCS11Provider .
354.Pp
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000355Arguments to
356.Cm CertificateFile
357may use the tilde syntax to refer to a user's home directory
358or the tokens described in the
359.Sx TOKENS
360section.
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000361.Pp
362It is possible to have multiple certificate files specified in
363configuration files; these certificates will be tried in sequence.
364Multiple
365.Cm CertificateFile
366directives will add to the list of certificates used for
367authentication.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000368.It Cm ChallengeResponseAuthentication
Damien Miller1faa7132006-03-15 11:55:31 +1100369Specifies whether to use challenge-response authentication.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000370The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000371.Cm yes
372(the default)
Ben Lindstrom9f049032002-06-21 00:59:05 +0000373or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000374.Cm no .
Ben Lindstrom9f049032002-06-21 00:59:05 +0000375.It Cm CheckHostIP
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000376If set to
377.Cm yes
378(the default),
Damien Miller45ee2b92006-03-15 11:56:18 +1100379.Xr ssh 1
380will additionally check the host IP address in the
Ben Lindstrom9f049032002-06-21 00:59:05 +0000381.Pa known_hosts
382file.
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000383This allows it to detect if a host key changed due to DNS spoofing
djm@openbsd.org5e678592015-06-02 09:10:40 +0000384and will add addresses of destination hosts to
385.Pa ~/.ssh/known_hosts
386in the process, regardless of the setting of
387.Cm StrictHostKeyChecking .
Ben Lindstrom9f049032002-06-21 00:59:05 +0000388If the option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000389.Cm no ,
Ben Lindstrom9f049032002-06-21 00:59:05 +0000390the check will not be executed.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000391.It Cm Ciphers
djm@openbsd.org788ac792017-04-30 23:18:22 +0000392Specifies the ciphers allowed and their order of preference.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000393Multiple ciphers must be comma-separated.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +0000394If the specified value begins with a
395.Sq +
396character, then the specified ciphers will be appended to the default set
397instead of replacing them.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +0000398If the specified value begins with a
399.Sq -
400character, then the specified ciphers (including wildcards) will be removed
401from the default set instead of replacing them.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +0000402.Pp
Damien Miller0fde8ac2013-11-21 14:12:23 +1100403The supported ciphers are:
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000404.Bd -literal -offset indent
Damien Millerc1621c82014-04-20 13:22:46 +10004053des-cbc
Damien Millerc1621c82014-04-20 13:22:46 +1000406aes128-cbc
Damien Millerc1621c82014-04-20 13:22:46 +1000407aes192-cbc
Damien Millerc1621c82014-04-20 13:22:46 +1000408aes256-cbc
Damien Millerc1621c82014-04-20 13:22:46 +1000409aes128-ctr
Damien Millerc1621c82014-04-20 13:22:46 +1000410aes192-ctr
Damien Millerc1621c82014-04-20 13:22:46 +1000411aes256-ctr
Damien Millerc1621c82014-04-20 13:22:46 +1000412aes128-gcm@openssh.com
Damien Millerc1621c82014-04-20 13:22:46 +1000413aes256-gcm@openssh.com
Damien Millerc1621c82014-04-20 13:22:46 +1000414chacha20-poly1305@openssh.com
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000415.Ed
Damien Miller0fde8ac2013-11-21 14:12:23 +1100416.Pp
Damien Miller45ee2b92006-03-15 11:56:18 +1100417The default is:
Damien Millerc1621c82014-04-20 13:22:46 +1000418.Bd -literal -offset indent
jmc@openbsd.org1f8d3d62015-08-14 15:32:41 +0000419chacha20-poly1305@openssh.com,
Damien Millerc1621c82014-04-20 13:22:46 +1000420aes128-ctr,aes192-ctr,aes256-ctr,
Damien Miller1d75abf2013-01-09 16:12:19 +1100421aes128-gcm@openssh.com,aes256-gcm@openssh.com,
djm@openbsd.orgda953182016-09-05 14:02:42 +0000422aes128-cbc,aes192-cbc,aes256-cbc
Ben Lindstrom9f049032002-06-21 00:59:05 +0000423.Ed
Damien Miller0fde8ac2013-11-21 14:12:23 +1100424.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000425The list of available ciphers may also be obtained using
426.Qq ssh -Q cipher .
Ben Lindstrom9f049032002-06-21 00:59:05 +0000427.It Cm ClearAllForwardings
Damien Miller45ee2b92006-03-15 11:56:18 +1100428Specifies that all local, remote, and dynamic port forwardings
Ben Lindstrom9f049032002-06-21 00:59:05 +0000429specified in the configuration files or on the command line be
Damien Miller495dca32003-04-01 21:42:14 +1000430cleared.
431This option is primarily useful when used from the
Damien Miller45ee2b92006-03-15 11:56:18 +1100432.Xr ssh 1
Ben Lindstrom9f049032002-06-21 00:59:05 +0000433command line to clear port forwardings set in
434configuration files, and is automatically set by
435.Xr scp 1
436and
437.Xr sftp 1 .
438The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000439.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000440or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000441.Cm no
442(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +0000443.It Cm Compression
444Specifies whether to use compression.
445The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000446.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000447or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000448.Cm no
449(the default).
naddy@openbsd.org9a82e242017-05-03 21:49:18 +0000450.It Cm ConnectionAttempts
451Specifies the number of tries (one per second) to make before exiting.
452The argument must be an integer.
453This may be useful in scripts if the connection sometimes fails.
454The default is 1.
Damien Millerb78d5eb2003-05-16 11:39:04 +1000455.It Cm ConnectTimeout
Damien Miller45ee2b92006-03-15 11:56:18 +1100456Specifies the timeout (in seconds) used when connecting to the
457SSH server, instead of using the default system TCP timeout.
Damien Millerfbf486b2003-05-23 18:44:23 +1000458This value is used only when the target is down or really unreachable,
459not when it refuses the connection.
Damien Miller0e220db2004-06-15 10:34:08 +1000460.It Cm ControlMaster
461Enables the sharing of multiple sessions over a single network connection.
462When set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000463.Cm yes ,
Damien Miller45ee2b92006-03-15 11:56:18 +1100464.Xr ssh 1
Damien Miller0e220db2004-06-15 10:34:08 +1000465will listen for connections on a control socket specified using the
466.Cm ControlPath
467argument.
468Additional sessions can connect to this socket using the same
469.Cm ControlPath
470with
471.Cm ControlMaster
472set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000473.Cm no
Damien Miller2234bac2004-06-30 22:38:52 +1000474(the default).
Damien Miller713de762005-11-05 15:13:49 +1100475These sessions will try to reuse the master instance's network connection
Damien Millerb3bfbb72005-11-05 15:11:48 +1100476rather than initiating new ones, but will fall back to connecting normally
477if the control socket does not exist, or is not listening.
478.Pp
Damien Miller23f07702004-06-18 01:19:03 +1000479Setting this to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000480.Cm ask
481will cause
482.Xr ssh 1
jmc@openbsd.org78de1672015-03-30 18:28:37 +0000483to listen for control connections, but require confirmation using
484.Xr ssh-askpass 1 .
Damien Millerdadfd4d2005-05-26 12:07:13 +1000485If the
486.Cm ControlPath
Damien Miller45ee2b92006-03-15 11:56:18 +1100487cannot be opened,
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000488.Xr ssh 1
489will continue without connecting to a master instance.
Damien Millerd14b1e72005-06-16 13:19:41 +1000490.Pp
Damien Miller13390022005-07-06 09:44:19 +1000491X11 and
Damien Millerfd94fba2005-07-06 09:44:59 +1000492.Xr ssh-agent 1
Damien Miller13390022005-07-06 09:44:19 +1000493forwarding is supported over these multiplexed connections, however the
Darren Tucker63551872005-12-20 16:14:15 +1100494display and agent forwarded will be the one belonging to the master
Damien Millerfd94fba2005-07-06 09:44:59 +1000495connection i.e. it is not possible to forward multiple displays or agents.
Damien Miller13390022005-07-06 09:44:19 +1000496.Pp
Damien Millerd14b1e72005-06-16 13:19:41 +1000497Two additional options allow for opportunistic multiplexing: try to use a
498master connection but fall back to creating a new one if one does not already
499exist.
500These options are:
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000501.Cm auto
Damien Millerd14b1e72005-06-16 13:19:41 +1000502and
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000503.Cm autoask .
Damien Millerd14b1e72005-06-16 13:19:41 +1000504The latter requires confirmation like the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000505.Cm ask
Damien Millerd14b1e72005-06-16 13:19:41 +1000506option.
Damien Miller0e220db2004-06-15 10:34:08 +1000507.It Cm ControlPath
Damien Miller6476cad2005-06-16 13:18:34 +1000508Specify the path to the control socket used for connection sharing as described
509in the
Damien Miller0e220db2004-06-15 10:34:08 +1000510.Cm ControlMaster
Damien Miller8f74c8f2005-06-26 08:56:03 +1000511section above or the string
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000512.Cm none
Damien Miller8f74c8f2005-06-26 08:56:03 +1000513to disable connection sharing.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000514Arguments to
515.Cm ControlPath
516may use the tilde syntax to refer to a user's home directory
517or the tokens described in the
518.Sx TOKENS
519section.
Damien Millerd14b1e72005-06-16 13:19:41 +1000520It is recommended that any
521.Cm ControlPath
522used for opportunistic connection sharing include
djm@openbsd.orgfc302562014-11-10 22:25:49 +0000523at least %h, %p, and %r (or alternatively %C) and be placed in a directory
524that is not writable by other users.
Damien Millerd14b1e72005-06-16 13:19:41 +1000525This ensures that shared connections are uniquely identified.
Damien Millere11e1ea2010-08-03 16:04:46 +1000526.It Cm ControlPersist
527When used in conjunction with
528.Cm ControlMaster ,
529specifies that the master connection should remain open
530in the background (waiting for future client connections)
531after the initial client connection has been closed.
532If set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000533.Cm no ,
Damien Millere11e1ea2010-08-03 16:04:46 +1000534then the master connection will not be placed into the background,
535and will close as soon as the initial client connection is closed.
536If set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000537.Cm yes
538or 0,
Damien Millere11e1ea2010-08-03 16:04:46 +1000539then the master connection will remain in the background indefinitely
540(until killed or closed via a mechanism such as the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000541.Qq ssh -O exit ) .
Damien Millere11e1ea2010-08-03 16:04:46 +1000542If set to a time in seconds, or a time in any of the formats documented in
543.Xr sshd_config 5 ,
544then the backgrounded master connection will automatically terminate
545after it has remained idle (with no client connections) for the
546specified time.
Damien Miller2234bac2004-06-30 22:38:52 +1000547.It Cm DynamicForward
Damien Millere9d001e2006-01-14 10:10:17 +1100548Specifies that a TCP port on the local machine be forwarded
Damien Miller2234bac2004-06-30 22:38:52 +1000549over the secure channel, and the application
550protocol is then used to determine where to connect to from the
551remote machine.
Darren Tuckerc8d64212005-10-03 18:13:42 +1000552.Pp
553The argument must be
554.Sm off
555.Oo Ar bind_address : Oc Ar port .
556.Sm on
Damien Miller7fa96602010-08-05 13:03:13 +1000557IPv6 addresses can be specified by enclosing addresses in square brackets.
Darren Tuckerc8d64212005-10-03 18:13:42 +1000558By default, the local port is bound in accordance with the
559.Cm GatewayPorts
560setting.
561However, an explicit
562.Ar bind_address
563may be used to bind the connection to a specific address.
564The
565.Ar bind_address
566of
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000567.Cm localhost
Darren Tuckerc8d64212005-10-03 18:13:42 +1000568indicates that the listening port be bound for local use only, while an
569empty address or
570.Sq *
571indicates that the port should be available from all interfaces.
572.Pp
Damien Miller2234bac2004-06-30 22:38:52 +1000573Currently the SOCKS4 and SOCKS5 protocols are supported, and
Damien Miller45ee2b92006-03-15 11:56:18 +1100574.Xr ssh 1
Damien Miller2234bac2004-06-30 22:38:52 +1000575will act as a SOCKS server.
576Multiple forwardings may be specified, and
577additional forwardings can be given on the command line.
578Only the superuser can forward privileged ports.
Darren Tucker674f71d2003-06-28 12:33:12 +1000579.It Cm EnableSSHKeysign
580Setting this option to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000581.Cm yes
Darren Tucker674f71d2003-06-28 12:33:12 +1000582in the global client configuration file
583.Pa /etc/ssh/ssh_config
584enables the use of the helper program
585.Xr ssh-keysign 8
586during
587.Cm HostbasedAuthentication .
588The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000589.Cm yes
Darren Tucker674f71d2003-06-28 12:33:12 +1000590or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000591.Cm no
592(the default).
Darren Tuckerf132c672003-10-15 15:58:18 +1000593This option should be placed in the non-hostspecific section.
Darren Tucker674f71d2003-06-28 12:33:12 +1000594See
595.Xr ssh-keysign 8
596for more information.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000597.It Cm EscapeChar
598Sets the escape character (default:
599.Ql ~ ) .
600The escape character can also
601be set on the command line.
602The argument should be a single character,
603.Ql ^
604followed by a letter, or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000605.Cm none
Ben Lindstrom9f049032002-06-21 00:59:05 +0000606to disable the escape
607character entirely (making the connection transparent for binary
608data).
Darren Tuckere7d4b192006-07-12 22:17:10 +1000609.It Cm ExitOnForwardFailure
610Specifies whether
611.Xr ssh 1
612should terminate the connection if it cannot set up all requested
djm@openbsd.orga954cdb2015-09-04 04:47:50 +0000613dynamic, tunnel, local, and remote port forwardings, (e.g.\&
jmc@openbsd.org5245bc12015-09-04 06:40:45 +0000614if either end is unable to bind and listen on a specified port).
djm@openbsd.orga954cdb2015-09-04 04:47:50 +0000615Note that
616.Cm ExitOnForwardFailure
617does not apply to connections made over port forwardings and will not,
618for example, cause
619.Xr ssh 1
620to exit if TCP connections to the ultimate forwarding destination fail.
Darren Tuckere7d4b192006-07-12 22:17:10 +1000621The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000622.Cm yes
Darren Tuckere7d4b192006-07-12 22:17:10 +1000623or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000624.Cm no
625(the default).
djm@openbsd.orgb79efde2014-12-21 23:12:42 +0000626.It Cm FingerprintHash
627Specifies the hash algorithm used when displaying key fingerprints.
628Valid options are:
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000629.Cm md5
djm@openbsd.orgb79efde2014-12-21 23:12:42 +0000630and
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000631.Cm sha256
632(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +0000633.It Cm ForwardAgent
634Specifies whether the connection to the authentication agent (if any)
635will be forwarded to the remote machine.
636The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000637.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000638or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000639.Cm no
640(the default).
Damien Milleraf653042002-09-04 16:40:37 +1000641.Pp
Damien Miller495dca32003-04-01 21:42:14 +1000642Agent forwarding should be enabled with caution.
643Users with the ability to bypass file permissions on the remote host
644(for the agent's Unix-domain socket)
645can access the local agent through the forwarded connection.
646An attacker cannot obtain key material from the agent,
Damien Milleraf653042002-09-04 16:40:37 +1000647however they can perform operations on the keys that enable them to
648authenticate using the identities loaded into the agent.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000649.It Cm ForwardX11
650Specifies whether X11 connections will be automatically redirected
651over the secure channel and
652.Ev DISPLAY
653set.
654The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000655.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000656or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000657.Cm no
658(the default).
Damien Milleraf653042002-09-04 16:40:37 +1000659.Pp
Damien Miller495dca32003-04-01 21:42:14 +1000660X11 forwarding should be enabled with caution.
661Users with the ability to bypass file permissions on the remote host
Darren Tucker0a118da2003-10-15 15:54:32 +1000662(for the user's X11 authorization database)
Damien Miller495dca32003-04-01 21:42:14 +1000663can access the local X11 display through the forwarded connection.
Darren Tucker0a118da2003-10-15 15:54:32 +1000664An attacker may then be able to perform activities such as keystroke monitoring
665if the
666.Cm ForwardX11Trusted
667option is also enabled.
Damien Miller1ab6a512010-06-26 10:02:24 +1000668.It Cm ForwardX11Timeout
Damien Millercede1db2010-07-02 13:33:48 +1000669Specify a timeout for untrusted X11 forwarding
670using the format described in the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000671.Sx TIME FORMATS
672section of
Damien Miller1ab6a512010-06-26 10:02:24 +1000673.Xr sshd_config 5 .
674X11 connections received by
675.Xr ssh 1
676after this time will be refused.
677The default is to disable untrusted X11 forwarding after twenty minutes has
678elapsed.
Darren Tucker0a118da2003-10-15 15:54:32 +1000679.It Cm ForwardX11Trusted
Darren Tuckerdcf6ec42004-05-13 13:03:56 +1000680If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000681.Cm yes ,
Damien Miller45ee2b92006-03-15 11:56:18 +1100682remote X11 clients will have full access to the original X11 display.
Damien Miller1717fd42005-03-01 21:17:31 +1100683.Pp
Darren Tucker0a118da2003-10-15 15:54:32 +1000684If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000685.Cm no
686(the default),
Damien Miller45ee2b92006-03-15 11:56:18 +1100687remote X11 clients will be considered untrusted and prevented
Darren Tucker0a118da2003-10-15 15:54:32 +1000688from stealing or tampering with data belonging to trusted X11
689clients.
Damien Miller1717fd42005-03-01 21:17:31 +1100690Furthermore, the
691.Xr xauth 1
692token used for the session will be set to expire after 20 minutes.
693Remote clients will be refused access after this time.
Darren Tucker0a118da2003-10-15 15:54:32 +1000694.Pp
Darren Tucker0a118da2003-10-15 15:54:32 +1000695See the X11 SECURITY extension specification for full details on
696the restrictions imposed on untrusted clients.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000697.It Cm GatewayPorts
698Specifies whether remote hosts are allowed to connect to local
699forwarded ports.
700By default,
Damien Miller45ee2b92006-03-15 11:56:18 +1100701.Xr ssh 1
Damien Miller495dca32003-04-01 21:42:14 +1000702binds local port forwardings to the loopback address.
703This prevents other remote hosts from connecting to forwarded ports.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000704.Cm GatewayPorts
Damien Miller45ee2b92006-03-15 11:56:18 +1100705can be used to specify that ssh
Ben Lindstrom9f049032002-06-21 00:59:05 +0000706should bind local port forwardings to the wildcard address,
707thus allowing remote hosts to connect to forwarded ports.
708The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000709.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000710or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000711.Cm no
712(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +0000713.It Cm GlobalKnownHostsFile
Damien Miller295ee632011-05-29 21:42:31 +1000714Specifies one or more files to use for the global
715host key database, separated by whitespace.
716The default is
717.Pa /etc/ssh/ssh_known_hosts ,
718.Pa /etc/ssh/ssh_known_hosts2 .
Darren Tucker0efd1552003-08-26 11:49:55 +1000719.It Cm GSSAPIAuthentication
Damien Millerbaafb982003-12-17 16:32:23 +1100720Specifies whether user authentication based on GSSAPI is allowed.
Damien Millerc2b98272003-09-03 12:13:30 +1000721The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000722.Cm no .
Darren Tucker0efd1552003-08-26 11:49:55 +1000723.It Cm GSSAPIDelegateCredentials
724Forward (delegate) credentials to the server.
725The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000726.Cm no .
Damien Millere1776152005-03-01 21:47:37 +1100727.It Cm HashKnownHosts
728Indicates that
Damien Miller45ee2b92006-03-15 11:56:18 +1100729.Xr ssh 1
Damien Millere1776152005-03-01 21:47:37 +1100730should hash host names and addresses when they are added to
Damien Miller167ea5d2005-05-26 12:04:02 +1000731.Pa ~/.ssh/known_hosts .
Damien Millere1776152005-03-01 21:47:37 +1100732These hashed names may be used normally by
Damien Miller45ee2b92006-03-15 11:56:18 +1100733.Xr ssh 1
Damien Millere1776152005-03-01 21:47:37 +1100734and
Damien Miller45ee2b92006-03-15 11:56:18 +1100735.Xr sshd 8 ,
Damien Millere1776152005-03-01 21:47:37 +1100736but they do not reveal identifying information should the file's contents
737be disclosed.
738The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000739.Cm no .
Damien Miller858bb7d2006-08-05 11:34:51 +1000740Note that existing names and addresses in known hosts files
741will not be converted automatically,
742but may be manually hashed using
Damien Miller4b42d7f2005-03-01 21:48:35 +1100743.Xr ssh-keygen 1 .
Ben Lindstrom9f049032002-06-21 00:59:05 +0000744.It Cm HostbasedAuthentication
745Specifies whether to try rhosts based authentication with public key
746authentication.
747The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000748.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000749or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000750.Cm no
751(the default).
djm@openbsd.org46347ed2015-01-30 11:43:14 +0000752.It Cm HostbasedKeyTypes
753Specifies the key types that will be used for hostbased authentication
754as a comma-separated pattern list.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +0000755Alternately if the specified value begins with a
756.Sq +
757character, then the specified key types will be appended to the default set
758instead of replacing them.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +0000759If the specified value begins with a
760.Sq -
761character, then the specified key types (including wildcards) will be removed
762from the default set instead of replacing them.
markus@openbsd.org3a1638d2015-07-10 06:21:53 +0000763The default for this option is:
764.Bd -literal -offset 3n
765ecdsa-sha2-nistp256-cert-v01@openssh.com,
766ecdsa-sha2-nistp384-cert-v01@openssh.com,
767ecdsa-sha2-nistp521-cert-v01@openssh.com,
768ssh-ed25519-cert-v01@openssh.com,
769ssh-rsa-cert-v01@openssh.com,
770ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
djm@openbsd.org3a13cb52016-02-17 08:57:34 +0000771ssh-ed25519,ssh-rsa
markus@openbsd.org3a1638d2015-07-10 06:21:53 +0000772.Ed
773.Pp
djm@openbsd.org46347ed2015-01-30 11:43:14 +0000774The
775.Fl Q
776option of
777.Xr ssh 1
778may be used to list supported key types.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000779.It Cm HostKeyAlgorithms
jmc@openbsd.orga685ae82016-02-17 07:38:19 +0000780Specifies the host key algorithms
Ben Lindstrom9f049032002-06-21 00:59:05 +0000781that the client wants to use in order of preference.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +0000782Alternately if the specified value begins with a
783.Sq +
784character, then the specified key types will be appended to the default set
785instead of replacing them.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +0000786If the specified value begins with a
787.Sq -
788character, then the specified key types (including wildcards) will be removed
789from the default set instead of replacing them.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000790The default for this option is:
Damien Millereb8b60e2010-08-31 22:41:14 +1000791.Bd -literal -offset 3n
792ecdsa-sha2-nistp256-cert-v01@openssh.com,
793ecdsa-sha2-nistp384-cert-v01@openssh.com,
794ecdsa-sha2-nistp521-cert-v01@openssh.com,
Damien Miller8ba0ead2013-12-18 17:46:27 +1100795ssh-ed25519-cert-v01@openssh.com,
markus@openbsd.org3a1638d2015-07-10 06:21:53 +0000796ssh-rsa-cert-v01@openssh.com,
Damien Millereb8b60e2010-08-31 22:41:14 +1000797ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
djm@openbsd.org3a13cb52016-02-17 08:57:34 +0000798ssh-ed25519,ssh-rsa
Damien Millereb8b60e2010-08-31 22:41:14 +1000799.Ed
Damien Millerd925dcd2010-12-01 12:21:51 +1100800.Pp
801If hostkeys are known for the destination host then this default is modified
802to prefer their algorithms.
djm@openbsd.org8f6784f2014-12-22 09:05:17 +0000803.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000804The list of available key types may also be obtained using
805.Qq ssh -Q key .
Ben Lindstrom9f049032002-06-21 00:59:05 +0000806.It Cm HostKeyAlias
807Specifies an alias that should be used instead of the
808real host name when looking up or saving the host key
djm@openbsd.org6f8ca3b2017-06-24 05:35:05 +0000809in the host key database files and when validating host certificates.
Damien Miller45ee2b92006-03-15 11:56:18 +1100810This option is useful for tunneling SSH connections
Ben Lindstrom9f049032002-06-21 00:59:05 +0000811or for multiple servers running on a single host.
812.It Cm HostName
813Specifies the real host name to log into.
814This can be used to specify nicknames or abbreviations for hosts.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000815Arguments to
816.Cm HostName
817accept the tokens described in the
818.Sx TOKENS
819section.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000820Numeric IP addresses are also permitted (both on the command line and in
821.Cm HostName
822specifications).
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000823The default is the name given on the command line.
Damien Millerbd394c32004-03-08 23:12:36 +1100824.It Cm IdentitiesOnly
825Specifies that
Damien Miller45ee2b92006-03-15 11:56:18 +1100826.Xr ssh 1
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000827should only use the authentication identity and certificate files explicitly
828configured in the
Damien Miller1a812582004-04-20 20:13:32 +1000829.Nm
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000830files
831or passed on the
832.Xr ssh 1
833command-line,
Damien Miller45ee2b92006-03-15 11:56:18 +1100834even if
835.Xr ssh-agent 1
Damien Millercb6b68b2012-12-03 09:49:52 +1100836or a
837.Cm PKCS11Provider
Damien Millerbd394c32004-03-08 23:12:36 +1100838offers more identities.
839The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000840.Cm yes
Damien Millerbd394c32004-03-08 23:12:36 +1100841or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000842.Cm no
843(the default).
Damien Miller45ee2b92006-03-15 11:56:18 +1100844This option is intended for situations where ssh-agent
Damien Millerbd394c32004-03-08 23:12:36 +1100845offers many different identities.
markus@openbsd.orgb02ad1c2016-05-04 12:21:53 +0000846.It Cm IdentityAgent
847Specifies the
848.Ux Ns -domain
849socket used to communicate with the authentication agent.
850.Pp
851This option overrides the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000852.Ev SSH_AUTH_SOCK
markus@openbsd.orgb02ad1c2016-05-04 12:21:53 +0000853environment variable and can be used to select a specific agent.
854Setting the socket name to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000855.Cm none
markus@openbsd.orgb02ad1c2016-05-04 12:21:53 +0000856disables the use of an authentication agent.
markus@openbsd.org1a75d142016-05-04 14:29:58 +0000857If the string
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000858.Qq SSH_AUTH_SOCK
markus@openbsd.org1a75d142016-05-04 14:29:58 +0000859is specified, the location of the socket will be read from the
860.Ev SSH_AUTH_SOCK
861environment variable.
markus@openbsd.orgb02ad1c2016-05-04 12:21:53 +0000862.Pp
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000863Arguments to
864.Cm IdentityAgent
865may use the tilde syntax to refer to a user's home directory
866or the tokens described in the
867.Sx TOKENS
868section.
Damien Miller957d4e42005-12-13 19:30:45 +1100869.It Cm IdentityFile
sobrado@openbsd.orgf70b22b2014-08-30 15:33:50 +0000870Specifies a file from which the user's DSA, ECDSA, Ed25519 or RSA authentication
Damien Millereb8b60e2010-08-31 22:41:14 +1000871identity is read.
Damien Miller957d4e42005-12-13 19:30:45 +1100872The default is
Damien Millereb8b60e2010-08-31 22:41:14 +1000873.Pa ~/.ssh/id_dsa ,
Damien Miller8ba0ead2013-12-18 17:46:27 +1100874.Pa ~/.ssh/id_ecdsa ,
875.Pa ~/.ssh/id_ed25519
Damien Miller957d4e42005-12-13 19:30:45 +1100876and
djm@openbsd.org788ac792017-04-30 23:18:22 +0000877.Pa ~/.ssh/id_rsa .
Damien Miller957d4e42005-12-13 19:30:45 +1100878Additionally, any identities represented by the authentication agent
Damien Miller7f2b4382013-07-18 16:10:29 +1000879will be used for authentication unless
880.Cm IdentitiesOnly
881is set.
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000882If no certificates have been explicitly specified by
883.Cm CertificateFile ,
Damien Miller5059d8d2010-03-05 21:31:11 +1100884.Xr ssh 1
885will try to load certificate information from the filename obtained by
886appending
887.Pa -cert.pub
888to the path of a specified
889.Cm IdentityFile .
Damien Miller6b1d53c2006-03-31 23:13:21 +1100890.Pp
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000891Arguments to
892.Cm IdentityFile
893may use the tilde syntax to refer to a user's home directory
894or the tokens described in the
895.Sx TOKENS
896section.
Damien Miller6b1d53c2006-03-31 23:13:21 +1100897.Pp
Damien Miller957d4e42005-12-13 19:30:45 +1100898It is possible to have
899multiple identity files specified in configuration files; all these
900identities will be tried in sequence.
Damien Miller6029e072011-06-20 14:22:49 +1000901Multiple
902.Cm IdentityFile
903directives will add to the list of identities tried (this behaviour
904differs from that of other configuration directives).
Damien Miller7f2b4382013-07-18 16:10:29 +1000905.Pp
906.Cm IdentityFile
907may be used in conjunction with
908.Cm IdentitiesOnly
909to select which identities in an agent are offered during authentication.
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000910.Cm IdentityFile
911may also be used in conjunction with
912.Cm CertificateFile
913in order to provide any certificate also needed for authentication with
914the identity.
Darren Tucker63e0df22013-05-16 20:30:31 +1000915.It Cm IgnoreUnknown
916Specifies a pattern-list of unknown options to be ignored if they are
917encountered in configuration parsing.
918This may be used to suppress errors if
919.Nm
920contains options that are unrecognised by
921.Xr ssh 1 .
922It is recommended that
923.Cm IgnoreUnknown
924be listed early in the configuration file as it will not be applied
925to unknown options that appear before it.
djm@openbsd.orgdc7990b2016-04-15 00:30:19 +0000926.It Cm Include
927Include the specified configuration file(s).
jmc@openbsd.org6aaabc22016-04-17 14:34:46 +0000928Multiple pathnames may be specified and each pathname may contain
djm@openbsd.orgdc7990b2016-04-15 00:30:19 +0000929.Xr glob 3
930wildcards and, for user configurations, shell-like
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000931.Sq ~
djm@openbsd.orgdc7990b2016-04-15 00:30:19 +0000932references to user home directories.
933Files without absolute paths are assumed to be in
934.Pa ~/.ssh
jmc@openbsd.org6aaabc22016-04-17 14:34:46 +0000935if included in a user configuration file or
djm@openbsd.orgdc7990b2016-04-15 00:30:19 +0000936.Pa /etc/ssh
937if included from the system configuration file.
938.Cm Include
939directive may appear inside a
940.Cm Match
941or
942.Cm Host
943block
944to perform conditional inclusion.
Damien Miller0dac6fb2010-11-20 15:19:38 +1100945.It Cm IPQoS
946Specifies the IPv4 type-of-service or DSCP class for connections.
947Accepted values are
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000948.Cm af11 ,
949.Cm af12 ,
950.Cm af13 ,
951.Cm af21 ,
952.Cm af22 ,
953.Cm af23 ,
954.Cm af31 ,
955.Cm af32 ,
956.Cm af33 ,
957.Cm af41 ,
958.Cm af42 ,
959.Cm af43 ,
960.Cm cs0 ,
961.Cm cs1 ,
962.Cm cs2 ,
963.Cm cs3 ,
964.Cm cs4 ,
965.Cm cs5 ,
966.Cm cs6 ,
967.Cm cs7 ,
968.Cm ef ,
969.Cm lowdelay ,
970.Cm throughput ,
971.Cm reliability ,
djm@openbsd.org51676ec2017-07-23 23:37:02 +0000972a numeric value, or
973.Cm none
974to use the operating system default.
Damien Miller928362d2010-12-26 14:26:45 +1100975This option may take one or two arguments, separated by whitespace.
Damien Miller0dac6fb2010-11-20 15:19:38 +1100976If one argument is specified, it is used as the packet class unconditionally.
977If two values are specified, the first is automatically selected for
978interactive sessions and the second for non-interactive sessions.
979The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000980.Cm lowdelay
Damien Miller0dac6fb2010-11-20 15:19:38 +1100981for interactive sessions and
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000982.Cm throughput
Damien Miller0dac6fb2010-11-20 15:19:38 +1100983for non-interactive sessions.
Damien Millercfb606c2007-10-26 14:24:48 +1000984.It Cm KbdInteractiveAuthentication
985Specifies whether to use keyboard-interactive authentication.
986The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000987.Cm yes
988(the default)
Damien Millercfb606c2007-10-26 14:24:48 +1000989or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000990.Cm no .
Darren Tucker636ca902004-11-05 20:22:00 +1100991.It Cm KbdInteractiveDevices
992Specifies the list of methods to use in keyboard-interactive authentication.
993Multiple method names must be comma-separated.
994The default is to use the server specified list.
Damien Miller9cfbaec2006-03-15 11:57:55 +1100995The methods available vary depending on what the server supports.
996For an OpenSSH server,
997it may be zero or more of:
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000998.Cm bsdauth ,
999.Cm pam ,
Damien Miller9cfbaec2006-03-15 11:57:55 +11001000and
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001001.Cm skey .
Damien Millerd5f62bf2010-09-24 22:11:14 +10001002.It Cm KexAlgorithms
1003Specifies the available KEX (Key Exchange) algorithms.
1004Multiple algorithms must be comma-separated.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +00001005Alternately if the specified value begins with a
1006.Sq +
1007character, then the specified methods will be appended to the default set
1008instead of replacing them.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +00001009If the specified value begins with a
1010.Sq -
1011character, then the specified methods (including wildcards) will be removed
1012from the default set instead of replacing them.
Damien Miller7fe2b1f2010-09-24 22:11:53 +10001013The default is:
1014.Bd -literal -offset indent
djm@openbsd.org16277fc2016-09-22 17:55:13 +00001015curve25519-sha256,curve25519-sha256@libssh.org,
Damien Miller7fe2b1f2010-09-24 22:11:53 +10001016ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,
1017diffie-hellman-group-exchange-sha256,
Damien Millerc1621c82014-04-20 13:22:46 +10001018diffie-hellman-group-exchange-sha1,
djm@openbsd.orgbdfd29f2015-07-03 03:47:00 +00001019diffie-hellman-group14-sha1
Damien Miller7fe2b1f2010-09-24 22:11:53 +10001020.Ed
djm@openbsd.org8f6784f2014-12-22 09:05:17 +00001021.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001022The list of available key exchange algorithms may also be obtained using
1023.Qq ssh -Q kex .
Damien Millerd27b9472005-12-13 19:29:02 +11001024.It Cm LocalCommand
1025Specifies a command to execute on the local machine after successfully
1026connecting to the server.
1027The command string extends to the end of the line, and is executed with
Darren Tucker63b31cb2007-12-02 23:09:30 +11001028the user's shell.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +00001029Arguments to
1030.Cm LocalCommand
1031accept the tokens described in the
1032.Sx TOKENS
1033section.
Darren Tucker78be8c52010-01-08 17:05:59 +11001034.Pp
1035The command is run synchronously and does not have access to the
1036session of the
1037.Xr ssh 1
1038that spawned it.
1039It should not be used for interactive commands.
1040.Pp
Damien Millerd27b9472005-12-13 19:29:02 +11001041This directive is ignored unless
1042.Cm PermitLocalCommand
1043has been enabled.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001044.It Cm LocalForward
Damien Millere9d001e2006-01-14 10:10:17 +11001045Specifies that a TCP port on the local machine be forwarded over
Ben Lindstrom9f049032002-06-21 00:59:05 +00001046the secure channel to the specified host and port from the remote machine.
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001047The first argument must be
Damien Millerf91ee4c2005-03-01 21:24:33 +11001048.Sm off
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001049.Oo Ar bind_address : Oc Ar port
Damien Millerf91ee4c2005-03-01 21:24:33 +11001050.Sm on
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001051and the second argument must be
1052.Ar host : Ns Ar hostport .
Damien Miller7fa96602010-08-05 13:03:13 +10001053IPv6 addresses can be specified by enclosing addresses in square brackets.
Damien Millerf8c55462005-03-02 12:03:05 +11001054Multiple forwardings may be specified, and additional forwardings can be
Damien Millerf91ee4c2005-03-01 21:24:33 +11001055given on the command line.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001056Only the superuser can forward privileged ports.
Damien Millerf91ee4c2005-03-01 21:24:33 +11001057By default, the local port is bound in accordance with the
1058.Cm GatewayPorts
1059setting.
1060However, an explicit
1061.Ar bind_address
1062may be used to bind the connection to a specific address.
1063The
1064.Ar bind_address
1065of
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001066.Cm localhost
Damien Millerf8c55462005-03-02 12:03:05 +11001067indicates that the listening port be bound for local use only, while an
1068empty address or
1069.Sq *
Damien Millerf91ee4c2005-03-01 21:24:33 +11001070indicates that the port should be available from all interfaces.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001071.It Cm LogLevel
1072Gives the verbosity level that is used when logging messages from
Damien Miller45ee2b92006-03-15 11:56:18 +11001073.Xr ssh 1 .
Ben Lindstrom9f049032002-06-21 00:59:05 +00001074The possible values are:
Damien Miller45ee2b92006-03-15 11:56:18 +11001075QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.
Damien Miller495dca32003-04-01 21:42:14 +10001076The default is INFO.
1077DEBUG and DEBUG1 are equivalent.
1078DEBUG2 and DEBUG3 each specify higher levels of verbose output.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001079.It Cm MACs
1080Specifies the MAC (message authentication code) algorithms
1081in order of preference.
jmc@openbsd.orga685ae82016-02-17 07:38:19 +00001082The MAC algorithm is used for data integrity protection.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001083Multiple algorithms must be comma-separated.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +00001084If the specified value begins with a
1085.Sq +
1086character, then the specified algorithms will be appended to the default set
1087instead of replacing them.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +00001088If the specified value begins with a
1089.Sq -
1090character, then the specified algorithms (including wildcards) will be removed
1091from the default set instead of replacing them.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +00001092.Pp
Damien Milleraf43a7a2012-12-12 10:46:31 +11001093The algorithms that contain
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001094.Qq -etm
Damien Milleraf43a7a2012-12-12 10:46:31 +11001095calculate the MAC after encryption (encrypt-then-mac).
1096These are considered safer and their use recommended.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +00001097.Pp
Damien Miller45ee2b92006-03-15 11:56:18 +11001098The default is:
Damien Miller5e7c30b2007-06-11 14:06:32 +10001099.Bd -literal -offset indent
Damien Milleraf43a7a2012-12-12 10:46:31 +11001100umac-64-etm@openssh.com,umac-128-etm@openssh.com,
1101hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,
djm@openbsd.orge4c918a2016-02-11 02:56:32 +00001102hmac-sha1-etm@openssh.com,
Damien Millerc1621c82014-04-20 13:22:46 +10001103umac-64@openssh.com,umac-128@openssh.com,
djm@openbsd.orge4c918a2016-02-11 02:56:32 +00001104hmac-sha2-256,hmac-sha2-512,hmac-sha1
Damien Miller5e7c30b2007-06-11 14:06:32 +10001105.Ed
djm@openbsd.org8f6784f2014-12-22 09:05:17 +00001106.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001107The list of available MAC algorithms may also be obtained using
1108.Qq ssh -Q mac .
Ben Lindstrom9f049032002-06-21 00:59:05 +00001109.It Cm NoHostAuthenticationForLocalhost
1110This option can be used if the home directory is shared across machines.
1111In this case localhost will refer to a different machine on each of
1112the machines and the user will get many warnings about changed host keys.
1113However, this option disables host authentication for localhost.
1114The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001115.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +00001116or
jmc@openbsd.org78142e32017-02-27 14:30:33 +00001117.Cm no
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001118(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +00001119.It Cm NumberOfPasswordPrompts
1120Specifies the number of password prompts before giving up.
1121The argument to this keyword must be an integer.
Damien Miller45ee2b92006-03-15 11:56:18 +11001122The default is 3.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001123.It Cm PasswordAuthentication
1124Specifies whether to use password authentication.
1125The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001126.Cm yes
1127(the default)
Ben Lindstrom9f049032002-06-21 00:59:05 +00001128or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001129.Cm no .
Damien Millerd27b9472005-12-13 19:29:02 +11001130.It Cm PermitLocalCommand
1131Allow local command execution via the
1132.Ic LocalCommand
1133option or using the
Damien Miller4b2319f2005-12-13 19:30:27 +11001134.Ic !\& Ns Ar command
Damien Millerd27b9472005-12-13 19:29:02 +11001135escape sequence in
1136.Xr ssh 1 .
1137The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001138.Cm yes
Damien Millerd27b9472005-12-13 19:29:02 +11001139or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001140.Cm no
1141(the default).
Damien Miller7ea845e2010-02-12 09:21:02 +11001142.It Cm PKCS11Provider
1143Specifies which PKCS#11 provider to use.
Damien Miller8e1ea4e2010-11-20 15:20:10 +11001144The argument to this keyword is the PKCS#11 shared library
Damien Miller7ea845e2010-02-12 09:21:02 +11001145.Xr ssh 1
Damien Millera7618442010-02-12 09:26:02 +11001146should use to communicate with a PKCS#11 token providing the user's
Damien Miller7ea845e2010-02-12 09:21:02 +11001147private RSA key.
Damien Miller957d4e42005-12-13 19:30:45 +11001148.It Cm Port
1149Specifies the port number to connect on the remote host.
Damien Miller45ee2b92006-03-15 11:56:18 +11001150The default is 22.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001151.It Cm PreferredAuthentications
jmc@openbsd.orga685ae82016-02-17 07:38:19 +00001152Specifies the order in which the client should try authentication methods.
Darren Tucker1adc2bd2005-03-14 23:14:20 +11001153This allows a client to prefer one method (e.g.\&
Ben Lindstrom9f049032002-06-21 00:59:05 +00001154.Cm keyboard-interactive )
Darren Tucker1adc2bd2005-03-14 23:14:20 +11001155over another method (e.g.\&
Damien Miller544378d2010-04-16 15:52:24 +10001156.Cm password ) .
1157The default is:
1158.Bd -literal -offset indent
1159gssapi-with-mic,hostbased,publickey,
1160keyboard-interactive,password
1161.Ed
Ben Lindstrom9f049032002-06-21 00:59:05 +00001162.It Cm ProxyCommand
1163Specifies the command to use to connect to the server.
1164The command
Damien Miller079bac22014-07-09 13:06:25 +10001165string extends to the end of the line, and is executed
1166using the user's shell
1167.Ql exec
1168directive to avoid a lingering shell process.
1169.Pp
jmc@openbsd.org80d1c962016-09-28 17:59:22 +00001170Arguments to
1171.Cm ProxyCommand
1172accept the tokens described in the
1173.Sx TOKENS
1174section.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001175The command can be basically anything,
1176and should read from its standard input and write to its standard output.
1177It should eventually connect an
1178.Xr sshd 8
1179server running on some machine, or execute
1180.Ic sshd -i
1181somewhere.
1182Host key management will be done using the
1183HostName of the host being connected (defaulting to the name typed by
1184the user).
Damien Miller495dca32003-04-01 21:42:14 +10001185Setting the command to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001186.Cm none
Damien Miller9f1e33a2003-02-24 11:57:32 +11001187disables this option entirely.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001188Note that
1189.Cm CheckHostIP
1190is not available for connects with a proxy command.
1191.Pp
Damien Millerebcfedc2005-05-26 12:13:56 +10001192This directive is useful in conjunction with
1193.Xr nc 1
1194and its proxy support.
Damien Millerdfec2942005-05-26 12:14:32 +10001195For example, the following directive would connect via an HTTP proxy at
Damien Millerebcfedc2005-05-26 12:13:56 +10001196192.0.2.0:
1197.Bd -literal -offset 3n
1198ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
1199.Ed
djm@openbsd.orged877ef2016-07-15 00:24:30 +00001200.It Cm ProxyJump
millert@openbsd.org887669e2017-10-21 23:06:24 +00001201Specifies one or more jump proxies as either
djm@openbsd.orged877ef2016-07-15 00:24:30 +00001202.Xo
1203.Sm off
jmc@openbsd.orge4eb7d92016-07-16 06:57:55 +00001204.Op Ar user No @
djm@openbsd.orged877ef2016-07-15 00:24:30 +00001205.Ar host
jmc@openbsd.orge4eb7d92016-07-16 06:57:55 +00001206.Op : Ns Ar port
djm@openbsd.orged877ef2016-07-15 00:24:30 +00001207.Sm on
millert@openbsd.org887669e2017-10-21 23:06:24 +00001208or an ssh URI
djm@openbsd.orged877ef2016-07-15 00:24:30 +00001209.Xc .
djm@openbsd.org286f5a72016-07-22 03:35:11 +00001210Multiple proxies may be separated by comma characters and will be visited
djm@openbsd.orgf00211e2016-07-22 07:00:46 +00001211sequentially.
djm@openbsd.orged877ef2016-07-15 00:24:30 +00001212Setting this option will cause
1213.Xr ssh 1
1214to connect to the target host by first making a
1215.Xr ssh 1
1216connection to the specified
1217.Cm ProxyJump
1218host and then establishing a
jmc@openbsd.orge4eb7d92016-07-16 06:57:55 +00001219TCP forwarding to the ultimate target from there.
djm@openbsd.orged877ef2016-07-15 00:24:30 +00001220.Pp
1221Note that this option will compete with the
1222.Cm ProxyCommand
1223option - whichever is specified first will prevent later instances of the
1224other from taking effect.
Damien Miller1262b662013-08-21 02:44:24 +10001225.It Cm ProxyUseFdpass
Damien Millerf2f6c312013-08-21 02:44:58 +10001226Specifies that
Damien Miller1262b662013-08-21 02:44:24 +10001227.Cm ProxyCommand
1228will pass a connected file descriptor back to
Damien Millerf2f6c312013-08-21 02:44:58 +10001229.Xr ssh 1
Damien Miller1262b662013-08-21 02:44:24 +10001230instead of continuing to execute and pass data.
1231The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001232.Cm no .
markus@openbsd.org3a1638d2015-07-10 06:21:53 +00001233.It Cm PubkeyAcceptedKeyTypes
1234Specifies the key types that will be used for public key authentication
1235as a comma-separated pattern list.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +00001236Alternately if the specified value begins with a
1237.Sq +
1238character, then the key types after it will be appended to the default
1239instead of replacing it.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +00001240If the specified value begins with a
1241.Sq -
1242character, then the specified key types (including wildcards) will be removed
1243from the default set instead of replacing them.
markus@openbsd.org3a1638d2015-07-10 06:21:53 +00001244The default for this option is:
1245.Bd -literal -offset 3n
1246ecdsa-sha2-nistp256-cert-v01@openssh.com,
1247ecdsa-sha2-nistp384-cert-v01@openssh.com,
1248ecdsa-sha2-nistp521-cert-v01@openssh.com,
1249ssh-ed25519-cert-v01@openssh.com,
1250ssh-rsa-cert-v01@openssh.com,
1251ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
djm@openbsd.org3a13cb52016-02-17 08:57:34 +00001252ssh-ed25519,ssh-rsa
markus@openbsd.org3a1638d2015-07-10 06:21:53 +00001253.Ed
1254.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001255The list of available key types may also be obtained using
1256.Qq ssh -Q key .
Ben Lindstrom9f049032002-06-21 00:59:05 +00001257.It Cm PubkeyAuthentication
1258Specifies whether to try public key authentication.
1259The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001260.Cm yes
1261(the default)
Ben Lindstrom9f049032002-06-21 00:59:05 +00001262or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001263.Cm no .
Darren Tucker62388b22006-01-20 11:31:47 +11001264.It Cm RekeyLimit
1265Specifies the maximum amount of data that may be transmitted before the
Darren Tuckerc53c2af2013-05-16 20:28:16 +10001266session key is renegotiated, optionally followed a maximum amount of
1267time that may pass before the session key is renegotiated.
1268The first argument is specified in bytes and may have a suffix of
Damien Millerddfddf12006-01-31 21:39:03 +11001269.Sq K ,
1270.Sq M ,
Darren Tucker62388b22006-01-20 11:31:47 +11001271or
Damien Millerddfddf12006-01-31 21:39:03 +11001272.Sq G
Darren Tucker62388b22006-01-20 11:31:47 +11001273to indicate Kilobytes, Megabytes, or Gigabytes, respectively.
1274The default is between
Damien Miller45ee2b92006-03-15 11:56:18 +11001275.Sq 1G
Darren Tucker62388b22006-01-20 11:31:47 +11001276and
Damien Miller45ee2b92006-03-15 11:56:18 +11001277.Sq 4G ,
Darren Tucker62388b22006-01-20 11:31:47 +11001278depending on the cipher.
Darren Tuckerc53c2af2013-05-16 20:28:16 +10001279The optional second value is specified in seconds and may use any of the
1280units documented in the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001281.Sx TIME FORMATS
1282section of
Darren Tuckerc53c2af2013-05-16 20:28:16 +10001283.Xr sshd_config 5 .
1284The default value for
1285.Cm RekeyLimit
1286is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001287.Cm default none ,
Darren Tuckerc53c2af2013-05-16 20:28:16 +10001288which means that rekeying is performed after the cipher's default amount
1289of data has been sent or received and no time based rekeying is done.
bluhm@openbsd.org1112b532017-05-30 18:58:37 +00001290.It Cm RemoteCommand
1291Specifies a command to execute on the remote machine after successfully
1292connecting to the server.
1293The command string extends to the end of the line, and is executed with
1294the user's shell.
jmc@openbsd.orga3bb2502017-05-30 19:38:17 +00001295Arguments to
1296.Cm RemoteCommand
1297accept the tokens described in the
1298.Sx TOKENS
1299section.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001300.It Cm RemoteForward
Damien Millere9d001e2006-01-14 10:10:17 +11001301Specifies that a TCP port on the remote machine be forwarded over
markus@openbsd.org609d7a62017-09-21 19:16:53 +00001302the secure channel.
1303The remote port may either be fowarded to a specified host and port
1304from the local machine, or may act as a SOCKS 4/5 proxy that allows a remote
1305client to connect to arbitrary destinations from the local machine.
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001306The first argument must be
Damien Millerf91ee4c2005-03-01 21:24:33 +11001307.Sm off
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001308.Oo Ar bind_address : Oc Ar port
Damien Millerf91ee4c2005-03-01 21:24:33 +11001309.Sm on
markus@openbsd.org609d7a62017-09-21 19:16:53 +00001310If forwarding to a specific destination then the second argument must be
1311.Ar host : Ns Ar hostport ,
1312otherwise if no destination argument is specified then the remote forwarding
1313will be established as a SOCKS proxy.
1314.Pp
Damien Miller7fa96602010-08-05 13:03:13 +10001315IPv6 addresses can be specified by enclosing addresses in square brackets.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001316Multiple forwardings may be specified, and additional
1317forwardings can be given on the command line.
Damien Millerde7532e2008-11-03 19:24:45 +11001318Privileged ports can be forwarded only when
1319logging in as root on the remote machine.
Damien Millere379e102009-02-14 16:34:39 +11001320.Pp
Damien Miller85c6d8a2009-02-14 16:34:21 +11001321If the
1322.Ar port
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001323argument is 0,
Damien Miller85c6d8a2009-02-14 16:34:21 +11001324the listen port will be dynamically allocated on the server and reported
1325to the client at run time.
Damien Millerf91ee4c2005-03-01 21:24:33 +11001326.Pp
1327If the
1328.Ar bind_address
1329is not specified, the default is to only bind to loopback addresses.
1330If the
1331.Ar bind_address
1332is
1333.Ql *
1334or an empty string, then the forwarding is requested to listen on all
1335interfaces.
1336Specifying a remote
1337.Ar bind_address
Damien Millerf8c55462005-03-02 12:03:05 +11001338will only succeed if the server's
1339.Cm GatewayPorts
Damien Millerf91ee4c2005-03-01 21:24:33 +11001340option is enabled (see
Damien Millerf8c55462005-03-02 12:03:05 +11001341.Xr sshd_config 5 ) .
Damien Miller21771e22011-05-15 08:45:50 +10001342.It Cm RequestTTY
1343Specifies whether to request a pseudo-tty for the session.
1344The argument may be one of:
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001345.Cm no
Damien Miller21771e22011-05-15 08:45:50 +10001346(never request a TTY),
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001347.Cm yes
Damien Miller21771e22011-05-15 08:45:50 +10001348(always request a TTY when standard input is a TTY),
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001349.Cm force
Damien Miller21771e22011-05-15 08:45:50 +10001350(always request a TTY) or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001351.Cm auto
Damien Miller21771e22011-05-15 08:45:50 +10001352(request a TTY when opening a login session).
1353This option mirrors the
1354.Fl t
1355and
1356.Fl T
1357flags for
1358.Xr ssh 1 .
djm@openbsd.org5e39a492014-12-04 02:24:32 +00001359.It Cm RevokedHostKeys
1360Specifies revoked host public keys.
1361Keys listed in this file will be refused for host authentication.
1362Note that if this file does not exist or is not readable,
1363then host authentication will be refused for all hosts.
1364Keys may be specified as a text file, listing one public key per line, or as
1365an OpenSSH Key Revocation List (KRL) as generated by
1366.Xr ssh-keygen 1 .
1367For more information on KRLs, see the KEY REVOCATION LISTS section in
1368.Xr ssh-keygen 1 .
Darren Tucker46bc0752004-05-02 22:11:30 +10001369.It Cm SendEnv
1370Specifies what variables from the local
1371.Xr environ 7
1372should be sent to the server.
Damien Miller45ee2b92006-03-15 11:56:18 +11001373The server must also support it, and the server must be configured to
Darren Tucker1e0c9bf2004-05-02 22:12:48 +10001374accept these environment variables.
dtucker@openbsd.org85b96ef2015-04-28 10:17:58 +00001375Note that the
1376.Ev TERM
jmc@openbsd.orgc1d5bcf2015-04-28 13:47:38 +00001377environment variable is always sent whenever a
dtucker@openbsd.org85b96ef2015-04-28 10:17:58 +00001378pseudo-terminal is requested as it is required by the protocol.
Darren Tucker46bc0752004-05-02 22:11:30 +10001379Refer to
1380.Cm AcceptEnv
1381in
1382.Xr sshd_config 5
1383for how to configure the server.
Damien Miller6def5512006-03-15 11:54:05 +11001384Variables are specified by name, which may contain wildcard characters.
Darren Tucker1e0c9bf2004-05-02 22:12:48 +10001385Multiple environment variables may be separated by whitespace or spread
Darren Tucker46bc0752004-05-02 22:11:30 +10001386across multiple
1387.Cm SendEnv
1388directives.
1389The default is not to send any environment variables.
Damien Millerf54a4b92006-03-15 11:54:36 +11001390.Pp
1391See
1392.Sx PATTERNS
1393for more information on patterns.
Damien Miller509b0102003-12-17 16:33:10 +11001394.It Cm ServerAliveCountMax
Damien Millerb7977702006-01-03 18:47:31 +11001395Sets the number of server alive messages (see below) which may be
Damien Miller509b0102003-12-17 16:33:10 +11001396sent without
Damien Miller45ee2b92006-03-15 11:56:18 +11001397.Xr ssh 1
Damien Miller509b0102003-12-17 16:33:10 +11001398receiving any messages back from the server.
1399If this threshold is reached while server alive messages are being sent,
Damien Miller45ee2b92006-03-15 11:56:18 +11001400ssh will disconnect from the server, terminating the session.
Damien Miller509b0102003-12-17 16:33:10 +11001401It is important to note that the use of server alive messages is very
1402different from
1403.Cm TCPKeepAlive
1404(below).
1405The server alive messages are sent through the encrypted channel
1406and therefore will not be spoofable.
1407The TCP keepalive option enabled by
1408.Cm TCPKeepAlive
1409is spoofable.
1410The server alive mechanism is valuable when the client or
1411server depend on knowing when a connection has become inactive.
1412.Pp
1413The default value is 3.
1414If, for example,
1415.Cm ServerAliveInterval
Damien Miller45ee2b92006-03-15 11:56:18 +11001416(see below) is set to 15 and
Damien Miller509b0102003-12-17 16:33:10 +11001417.Cm ServerAliveCountMax
Damien Miller45ee2b92006-03-15 11:56:18 +11001418is left at the default, if the server becomes unresponsive,
1419ssh will disconnect after approximately 45 seconds.
Damien Miller957d4e42005-12-13 19:30:45 +11001420.It Cm ServerAliveInterval
1421Sets a timeout interval in seconds after which if no data has been received
1422from the server,
Damien Miller45ee2b92006-03-15 11:56:18 +11001423.Xr ssh 1
Damien Miller957d4e42005-12-13 19:30:45 +11001424will send a message through the encrypted
1425channel to request a response from the server.
1426The default
1427is 0, indicating that these messages will not be sent to the server.
Damien Miller7acefbb2014-07-18 14:11:24 +10001428.It Cm StreamLocalBindMask
1429Sets the octal file creation mode mask
1430.Pq umask
1431used when creating a Unix-domain socket file for local or remote
1432port forwarding.
1433This option is only used for port forwarding to a Unix-domain socket file.
1434.Pp
1435The default value is 0177, which creates a Unix-domain socket file that is
1436readable and writable only by the owner.
1437Note that not all operating systems honor the file mode on Unix-domain
1438socket files.
1439.It Cm StreamLocalBindUnlink
1440Specifies whether to remove an existing Unix-domain socket file for local
1441or remote port forwarding before creating a new one.
1442If the socket file already exists and
1443.Cm StreamLocalBindUnlink
1444is not enabled,
1445.Nm ssh
1446will be unable to forward the port to the Unix-domain socket file.
1447This option is only used for port forwarding to a Unix-domain socket file.
1448.Pp
1449The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001450.Cm yes
Damien Miller7acefbb2014-07-18 14:11:24 +10001451or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001452.Cm no
1453(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +00001454.It Cm StrictHostKeyChecking
1455If this flag is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001456.Cm yes ,
Damien Miller45ee2b92006-03-15 11:56:18 +11001457.Xr ssh 1
Ben Lindstrom9f049032002-06-21 00:59:05 +00001458will never automatically add host keys to the
Damien Miller167ea5d2005-05-26 12:04:02 +10001459.Pa ~/.ssh/known_hosts
Ben Lindstrom9f049032002-06-21 00:59:05 +00001460file, and refuses to connect to hosts whose host key has changed.
1461This provides maximum protection against trojan horse attacks,
Damien Miller45ee2b92006-03-15 11:56:18 +11001462though it can be annoying when the
Ben Lindstrom9f049032002-06-21 00:59:05 +00001463.Pa /etc/ssh/ssh_known_hosts
Damien Miller45ee2b92006-03-15 11:56:18 +11001464file is poorly maintained or when connections to new hosts are
Ben Lindstrom9f049032002-06-21 00:59:05 +00001465frequently made.
1466This option forces the user to manually
1467add all new hosts.
jmc@openbsd.org149a8cd2017-09-04 06:34:43 +00001468.Pp
Ben Lindstrom9f049032002-06-21 00:59:05 +00001469If this flag is set to
djm@openbsd.org22376d22017-09-03 23:33:13 +00001470.Dq accept-new
jmc@openbsd.org149a8cd2017-09-04 06:34:43 +00001471then ssh will automatically add new host keys to the user
djm@openbsd.org22376d22017-09-03 23:33:13 +00001472known hosts files, but will not permit connections to hosts with
1473changed host keys.
1474If this flag is set to
1475.Dq no
1476or
1477.Dq off ,
jmc@openbsd.org149a8cd2017-09-04 06:34:43 +00001478ssh will automatically add new host keys to the user known hosts files
1479and allow connections to hosts with changed hostkeys to proceed,
1480subject to some restrictions.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001481If this flag is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001482.Cm ask
1483(the default),
Ben Lindstrom9f049032002-06-21 00:59:05 +00001484new host keys
1485will be added to the user known host files only after the user
1486has confirmed that is what they really want to do, and
Damien Miller45ee2b92006-03-15 11:56:18 +11001487ssh will refuse to connect to hosts whose host key has changed.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001488The host keys of
1489known hosts will be verified automatically in all cases.
jmc@openbsd.org47a287b2017-04-28 06:15:03 +00001490.It Cm SyslogFacility
1491Gives the facility code that is used when logging messages from
1492.Xr ssh 1 .
1493The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2,
1494LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
1495The default is USER.
Damien Miller12c150e2003-12-17 16:31:10 +11001496.It Cm TCPKeepAlive
1497Specifies whether the system should send TCP keepalive messages to the
1498other side.
1499If they are sent, death of the connection or crash of one
1500of the machines will be properly noticed.
1501However, this means that
1502connections will die if the route is down temporarily, and some people
1503find it annoying.
1504.Pp
1505The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001506.Cm yes
Damien Miller12c150e2003-12-17 16:31:10 +11001507(to send TCP keepalive messages), and the client will notice
1508if the network goes down or the remote host dies.
1509This is important in scripts, and many users want it too.
1510.Pp
1511To disable TCP keepalive messages, the value should be set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001512.Cm no .
Damien Millerd27b9472005-12-13 19:29:02 +11001513.It Cm Tunnel
Damien Miller991dba42006-07-10 20:16:27 +10001514Request
Damien Millerd27b9472005-12-13 19:29:02 +11001515.Xr tun 4
Damien Miller7746c392005-12-13 19:33:37 +11001516device forwarding between the client and the server.
Damien Millerd27b9472005-12-13 19:29:02 +11001517The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001518.Cm yes ,
1519.Cm point-to-point
Damien Miller991dba42006-07-10 20:16:27 +10001520(layer 3),
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001521.Cm ethernet
Damien Miller991dba42006-07-10 20:16:27 +10001522(layer 2),
Damien Millerd27b9472005-12-13 19:29:02 +11001523or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001524.Cm no
1525(the default).
Damien Miller991dba42006-07-10 20:16:27 +10001526Specifying
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001527.Cm yes
Damien Miller991dba42006-07-10 20:16:27 +10001528requests the default tunnel mode, which is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001529.Cm point-to-point .
Damien Millerd27b9472005-12-13 19:29:02 +11001530.It Cm TunnelDevice
Damien Miller991dba42006-07-10 20:16:27 +10001531Specifies the
Damien Millerd27b9472005-12-13 19:29:02 +11001532.Xr tun 4
Damien Miller991dba42006-07-10 20:16:27 +10001533devices to open on the client
1534.Pq Ar local_tun
1535and the server
1536.Pq Ar remote_tun .
1537.Pp
1538The argument must be
1539.Sm off
1540.Ar local_tun Op : Ar remote_tun .
1541.Sm on
1542The devices may be specified by numerical ID or the keyword
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001543.Cm any ,
Damien Miller991dba42006-07-10 20:16:27 +10001544which uses the next available tunnel device.
1545If
1546.Ar remote_tun
1547is not specified, it defaults to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001548.Cm any .
Damien Miller991dba42006-07-10 20:16:27 +10001549The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001550.Cm any:any .
djm@openbsd.org1d1092b2015-01-26 12:16:36 +00001551.It Cm UpdateHostKeys
djm@openbsd.org8d4f8722015-01-26 03:04:45 +00001552Specifies whether
1553.Xr ssh 1
1554should accept notifications of additional hostkeys from the server sent
1555after authentication has completed and add them to
1556.Cm UserKnownHostsFile .
1557The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001558.Cm yes ,
1559.Cm no
djm@openbsd.org523463a2015-02-16 22:13:32 +00001560(the default) or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001561.Cm ask .
djm@openbsd.org8d4f8722015-01-26 03:04:45 +00001562Enabling this option allows learning alternate hostkeys for a server
djm@openbsd.org1d1092b2015-01-26 12:16:36 +00001563and supports graceful key rotation by allowing a server to send replacement
1564public keys before old ones are removed.
djm@openbsd.org8d4f8722015-01-26 03:04:45 +00001565Additional hostkeys are only accepted if the key used to authenticate the
sobrado@openbsd.orge3cbb062015-09-22 08:33:23 +00001566host was already trusted or explicitly accepted by the user.
djm@openbsd.org523463a2015-02-16 22:13:32 +00001567If
1568.Cm UpdateHostKeys
1569is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001570.Cm ask ,
djm@openbsd.org523463a2015-02-16 22:13:32 +00001571then the user is asked to confirm the modifications to the known_hosts file.
djm@openbsd.org44732de2015-02-20 22:17:21 +00001572Confirmation is currently incompatible with
1573.Cm ControlPersist ,
1574and will be disabled if it is enabled.
djm@openbsd.org8d4f8722015-01-26 03:04:45 +00001575.Pp
1576Presently, only
1577.Xr sshd 8
1578from OpenSSH 6.8 and greater support the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001579.Qq hostkeys@openssh.com
djm@openbsd.org8d4f8722015-01-26 03:04:45 +00001580protocol extension used to inform the client of all the server's hostkeys.
Damien Millere8cd7412005-12-24 14:55:47 +11001581.It Cm UsePrivilegedPort
1582Specifies whether to use a privileged port for outgoing connections.
1583The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001584.Cm yes
Damien Millere8cd7412005-12-24 14:55:47 +11001585or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001586.Cm no
1587(the default).
Damien Millere8cd7412005-12-24 14:55:47 +11001588If set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001589.Cm yes ,
Damien Miller45ee2b92006-03-15 11:56:18 +11001590.Xr ssh 1
Damien Millere8cd7412005-12-24 14:55:47 +11001591must be setuid root.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001592.It Cm User
1593Specifies the user to log in as.
1594This can be useful when a different user name is used on different machines.
1595This saves the trouble of
1596having to remember to give the user name on the command line.
1597.It Cm UserKnownHostsFile
Damien Miller295ee632011-05-29 21:42:31 +10001598Specifies one or more files to use for the user
1599host key database, separated by whitespace.
1600The default is
1601.Pa ~/.ssh/known_hosts ,
1602.Pa ~/.ssh/known_hosts2 .
Damien Miller37876e92003-05-15 10:19:46 +10001603.It Cm VerifyHostKeyDNS
1604Specifies whether to verify the remote key using DNS and SSHFP resource
1605records.
Damien Miller150b5572003-11-17 21:19:29 +11001606If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001607.Cm yes ,
Damien Millerfe448472003-11-17 21:19:49 +11001608the client will implicitly trust keys that match a secure fingerprint
Damien Miller150b5572003-11-17 21:19:29 +11001609from DNS.
1610Insecure fingerprints will be handled as if this option was set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001611.Cm ask .
Damien Miller150b5572003-11-17 21:19:29 +11001612If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001613.Cm ask ,
Damien Miller150b5572003-11-17 21:19:29 +11001614information on fingerprint match will be displayed, but the user will still
1615need to confirm new host keys according to the
1616.Cm StrictHostKeyChecking
1617option.
Damien Miller37876e92003-05-15 10:19:46 +10001618The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001619.Cm no .
Damien Miller45ee2b92006-03-15 11:56:18 +11001620.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001621See also
1622.Sx VERIFYING HOST KEYS
1623in
Damien Miller45ee2b92006-03-15 11:56:18 +11001624.Xr ssh 1 .
Damien Miller10288242008-06-30 00:04:03 +10001625.It Cm VisualHostKey
1626If this flag is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001627.Cm yes ,
Damien Miller10288242008-06-30 00:04:03 +10001628an ASCII art representation of the remote host key fingerprint is
djm@openbsd.orgb79efde2014-12-21 23:12:42 +00001629printed in addition to the fingerprint string at login and
Damien Millera414cd32008-11-03 19:25:21 +11001630for unknown host keys.
Damien Miller10288242008-06-30 00:04:03 +10001631If this flag is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001632.Cm no
1633(the default),
Damien Millera414cd32008-11-03 19:25:21 +11001634no fingerprint strings are printed at login and
djm@openbsd.orgb79efde2014-12-21 23:12:42 +00001635only the fingerprint string will be printed for unknown host keys.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001636.It Cm XAuthLocation
Damien Miller05913ba2002-09-04 16:51:03 +10001637Specifies the full pathname of the
Ben Lindstrom9f049032002-06-21 00:59:05 +00001638.Xr xauth 1
1639program.
1640The default is
1641.Pa /usr/X11R6/bin/xauth .
1642.El
Damien Millerb5282c22006-03-15 11:59:08 +11001643.Sh PATTERNS
1644A
1645.Em pattern
1646consists of zero or more non-whitespace characters,
1647.Sq *
1648(a wildcard that matches zero or more characters),
1649or
1650.Sq ?\&
1651(a wildcard that matches exactly one character).
1652For example, to specify a set of declarations for any host in the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001653.Qq .co.uk
Damien Millerb5282c22006-03-15 11:59:08 +11001654set of domains,
1655the following pattern could be used:
1656.Pp
1657.Dl Host *.co.uk
1658.Pp
1659The following pattern
1660would match any host in the 192.168.0.[0-9] network range:
1661.Pp
1662.Dl Host 192.168.0.?
1663.Pp
1664A
1665.Em pattern-list
1666is a comma-separated list of patterns.
1667Patterns within pattern-lists may be negated
1668by preceding them with an exclamation mark
1669.Pq Sq !\& .
1670For example,
Damien Miller51682fa2013-10-17 11:48:31 +11001671to allow a key to be used from anywhere within an organization
Damien Millerb5282c22006-03-15 11:59:08 +11001672except from the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001673.Qq dialup
Damien Millerb5282c22006-03-15 11:59:08 +11001674pool,
1675the following entry (in authorized_keys) could be used:
1676.Pp
1677.Dl from=\&"!*.dialup.example.com,*.example.com\&"
djm@openbsd.org05b69e92017-10-18 02:49:44 +00001678.Pp
1679Note that a negated match will never produce a positive result by itself.
1680For example, attempting to match
1681.Qq host3
1682against the following pattern-list will fail:
1683.Pp
1684.Dl from=\&"!host1,!host2\&"
1685.Pp
1686The solution here is to include a term that will yield a positive match,
1687such as a wildcard:
1688.Pp
1689.Dl from=\&"!host1,!host2,*\&"
jmc@openbsd.org80d1c962016-09-28 17:59:22 +00001690.Sh TOKENS
1691Arguments to some keywords can make use of tokens,
1692which are expanded at runtime:
1693.Pp
1694.Bl -tag -width XXXX -offset indent -compact
1695.It %%
1696A literal
1697.Sq % .
1698.It \&%C
jmc@openbsd.org2b4f3ab2017-10-05 12:56:50 +00001699Hash of %l%h%p%r.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +00001700.It %d
1701Local user's home directory.
1702.It %h
1703The remote hostname.
1704.It %i
1705The local user ID.
1706.It %L
1707The local hostname.
1708.It %l
1709The local hostname, including the domain name.
1710.It %n
1711The original remote hostname, as given on the command line.
1712.It %p
1713The remote port.
1714.It %r
1715The remote username.
djm@openbsd.orgb7548b12017-10-23 05:08:00 +00001716.It \&%T
1717The local
1718.Xr tun 4
1719or
1720.Xr tap 4
1721network interface assigned if
jmc@openbsd.org08696272017-10-24 06:27:42 +00001722tunnel forwarding was requested, or
1723.Qq NONE
djm@openbsd.orgb7548b12017-10-23 05:08:00 +00001724otherwise.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +00001725.It %u
1726The local username.
1727.El
1728.Pp
1729.Cm Match exec
1730accepts the tokens %%, %h, %L, %l, %n, %p, %r, and %u.
1731.Pp
1732.Cm CertificateFile
1733accepts the tokens %%, %d, %h, %l, %r, and %u.
1734.Pp
1735.Cm ControlPath
1736accepts the tokens %%, %C, %h, %i, %L, %l, %n, %p, %r, and %u.
1737.Pp
1738.Cm HostName
1739accepts the tokens %% and %h.
1740.Pp
1741.Cm IdentityAgent
1742and
1743.Cm IdentityFile
1744accept the tokens %%, %d, %h, %l, %r, and %u.
1745.Pp
1746.Cm LocalCommand
djm@openbsd.orgb7548b12017-10-23 05:08:00 +00001747accepts the tokens %%, %C, %d, %h, %l, %n, %p, %r, %T, and %u.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +00001748.Pp
1749.Cm ProxyCommand
1750accepts the tokens %%, %h, %p, and %r.
jmc@openbsd.orga3bb2502017-05-30 19:38:17 +00001751.Pp
1752.Cm RemoteCommand
1753accepts the tokens %%, %C, %d, %h, %l, %n, %p, %r, and %u.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001754.Sh FILES
1755.Bl -tag -width Ds
Damien Miller167ea5d2005-05-26 12:04:02 +10001756.It Pa ~/.ssh/config
Ben Lindstrom9f049032002-06-21 00:59:05 +00001757This is the per-user configuration file.
1758The format of this file is described above.
Damien Miller45ee2b92006-03-15 11:56:18 +11001759This file is used by the SSH client.
Damien Millerc970cb92004-04-20 20:12:53 +10001760Because of the potential for abuse, this file must have strict permissions:
1761read/write for the user, and not accessible by others.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001762.It Pa /etc/ssh/ssh_config
1763Systemwide configuration file.
1764This file provides defaults for those
1765values that are not specified in the user's configuration file, and
1766for those users who do not have a configuration file.
1767This file must be world-readable.
1768.El
Damien Millerf1ce5052003-06-11 22:04:39 +10001769.Sh SEE ALSO
1770.Xr ssh 1
Ben Lindstrom9f049032002-06-21 00:59:05 +00001771.Sh AUTHORS
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001772.An -nosplit
Ben Lindstrom9f049032002-06-21 00:59:05 +00001773OpenSSH is a derivative of the original and free
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001774ssh 1.2.12 release by
1775.An Tatu Ylonen .
1776.An Aaron Campbell , Bob Beck , Markus Friedl ,
1777.An Niels Provos , Theo de Raadt
1778and
1779.An Dug Song
Ben Lindstrom9f049032002-06-21 00:59:05 +00001780removed many bugs, re-added newer features and
1781created OpenSSH.
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001782.An Markus Friedl
1783contributed the support for SSH protocol versions 1.5 and 2.0.