blob: a565f330dba1a590ffeb2a8b91150e2160442d51 [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.\"
djm@openbsd.org788ac792017-04-30 23:18:22 +000036.\" $OpenBSD: ssh_config.5,v 1.245 2017/04/30 23:18:22 djm Exp $
37.Dd $Mdocdate: April 30 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
43.Sh SYNOPSIS
Darren Tuckerbf6b3282007-02-19 22:08:17 +110044.Nm ~/.ssh/config
45.Nm /etc/ssh/ssh_config
Ben Lindstrom9f049032002-06-21 00:59:05 +000046.Sh DESCRIPTION
Damien Miller45ee2b92006-03-15 11:56:18 +110047.Xr ssh 1
Ben Lindstrom9f049032002-06-21 00:59:05 +000048obtains configuration data from the following sources in
49the following order:
Damien Miller5c853b52006-03-15 11:37:02 +110050.Pp
Ben Lindstrom479b4762002-08-20 19:04:51 +000051.Bl -enum -offset indent -compact
52.It
53command-line options
54.It
55user's configuration file
Damien Miller167ea5d2005-05-26 12:04:02 +100056.Pq Pa ~/.ssh/config
Ben Lindstrom479b4762002-08-20 19:04:51 +000057.It
58system-wide configuration file
59.Pq Pa /etc/ssh/ssh_config
60.El
Ben Lindstrom9f049032002-06-21 00:59:05 +000061.Pp
62For each parameter, the first obtained value
63will be used.
Darren Tucker43d8e282005-02-09 09:51:08 +110064The configuration files contain sections separated by
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +000065.Cm Host
Ben Lindstrom9f049032002-06-21 00:59:05 +000066specifications, and that section is only applied for hosts that
67match one of the patterns given in the specification.
djm@openbsd.org957fbce2014-10-08 22:20:25 +000068The matched host name is usually the one given on the command line
69(see the
70.Cm CanonicalizeHostname
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +000071option for exceptions).
Ben Lindstrom9f049032002-06-21 00:59:05 +000072.Pp
73Since the first obtained value for each parameter is used, more
74host-specific declarations should be given near the beginning of the
75file, and general defaults at the end.
76.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +000077The file contains keyword-argument pairs, one per line.
78Lines starting with
Ben Lindstrom9f049032002-06-21 00:59:05 +000079.Ql #
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +000080and empty lines are interpreted as comments.
81Arguments may optionally be enclosed in double quotes
82.Pq \&"
83in order to represent arguments containing spaces.
Ben Lindstrom9f049032002-06-21 00:59:05 +000084Configuration options may be separated by whitespace or
85optional whitespace and exactly one
86.Ql = ;
87the latter format is useful to avoid the need to quote whitespace
88when specifying configuration options using the
89.Nm ssh ,
Damien Miller4aea9742006-03-15 11:59:39 +110090.Nm scp ,
Ben Lindstrom9f049032002-06-21 00:59:05 +000091and
92.Nm sftp
93.Fl o
94option.
95.Pp
96The possible
97keywords and their meanings are as follows (note that
98keywords are case-insensitive and arguments are case-sensitive):
99.Bl -tag -width Ds
100.It Cm Host
101Restricts the following declarations (up to the next
102.Cm Host
Damien Miller194fd902013-10-15 12:13:05 +1100103or
104.Cm Match
Ben Lindstrom9f049032002-06-21 00:59:05 +0000105keyword) to be only for those hosts that match one of the patterns
106given after the keyword.
Damien Millerfa51b162008-11-03 19:17:33 +1100107If more than one pattern is provided, they should be separated by whitespace.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000108A single
Damien Miller208f1ed2006-03-15 11:56:03 +1100109.Ql *
Ben Lindstrom9f049032002-06-21 00:59:05 +0000110as a pattern can be used to provide global
111defaults for all hosts.
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000112The host is usually the
Ben Lindstrom9f049032002-06-21 00:59:05 +0000113.Ar hostname
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000114argument given on the command line
115(see the
116.Cm CanonicalizeHostname
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000117keyword for exceptions).
Damien Millerf54a4b92006-03-15 11:54:36 +1100118.Pp
Damien Millerfe924212011-05-15 08:44:45 +1000119A pattern entry may be negated by prefixing it with an exclamation mark
120.Pq Sq !\& .
121If a negated entry is matched, then the
122.Cm Host
123entry is ignored, regardless of whether any other patterns on the line
124match.
125Negated matches are therefore useful to provide exceptions for wildcard
126matches.
127.Pp
Damien Millerf54a4b92006-03-15 11:54:36 +1100128See
129.Sx PATTERNS
130for more information on patterns.
Damien Millerd77b81f2013-10-17 11:39:00 +1100131.It Cm Match
Damien Miller194fd902013-10-15 12:13:05 +1100132Restricts the following declarations (up to the next
133.Cm Host
134or
135.Cm Match
136keyword) to be used only when the conditions following the
137.Cm Match
138keyword are satisfied.
sobrado@openbsd.orge3cbb062015-09-22 08:33:23 +0000139Match conditions are specified using one or more criteria
Damien Millercf31f382013-10-24 21:02:56 +1100140or the single token
141.Cm all
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000142which always matches.
143The available criteria keywords are:
144.Cm canonical ,
Damien Miller8a04be72013-10-23 16:29:40 +1100145.Cm exec ,
Damien Miller194fd902013-10-15 12:13:05 +1100146.Cm host ,
147.Cm originalhost ,
148.Cm user ,
149and
150.Cm localuser .
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000151The
152.Cm all
153criteria must appear alone or immediately after
jmc@openbsd.orgb1ba15f2014-10-09 06:21:31 +0000154.Cm canonical .
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000155Other criteria may be combined arbitrarily.
156All criteria but
157.Cm all
158and
159.Cm canonical
160require an argument.
161Criteria may be negated by prepending an exclamation mark
162.Pq Sq !\& .
Damien Miller194fd902013-10-15 12:13:05 +1100163.Pp
Damien Miller8e5a67f2013-10-23 16:30:25 +1100164The
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000165.Cm canonical
dtucker@openbsd.orgdd2cfeb2015-05-28 05:09:45 +0000166keyword matches only when the configuration file is being re-parsed
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000167after hostname canonicalization (see the
168.Cm CanonicalizeHostname
169option.)
170This may be useful to specify conditions that work with canonical host
171names only.
172The
Damien Miller8a04be72013-10-23 16:29:40 +1100173.Cm exec
Damien Miller8e5a67f2013-10-23 16:30:25 +1100174keyword executes the specified command under the user's shell.
Damien Miller194fd902013-10-15 12:13:05 +1100175If the command returns a zero exit status then the condition is considered true.
176Commands containing whitespace characters must be quoted.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000177Arguments to
178.Cm exec
179accept the tokens described in the
180.Sx TOKENS
181section.
Damien Miller194fd902013-10-15 12:13:05 +1100182.Pp
183The other keywords' criteria must be single entries or comma-separated
184lists and may use the wildcard and negation operators described in the
185.Sx PATTERNS
186section.
187The criteria for the
188.Cm host
189keyword are matched against the target hostname, after any substitution
190by the
191.Cm Hostname
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000192or
193.Cm CanonicalizeHostname
194options.
Damien Miller194fd902013-10-15 12:13:05 +1100195The
196.Cm originalhost
197keyword matches against the hostname as it was specified on the command-line.
198The
199.Cm user
200keyword matches against the target username on the remote host.
201The
202.Cm localuser
203keyword matches against the name of the local user running
204.Xr ssh 1
205(this keyword may be useful in system-wide
206.Nm
207files).
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000208.It Cm AddKeysToAgent
209Specifies whether keys should be automatically added to a running
jmc@openbsd.orge41a0712015-11-15 23:58:04 +0000210.Xr ssh-agent 1 .
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000211If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000212.Cm yes
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000213and a key is loaded from a file, the key and its passphrase are added to
214the agent with the default lifetime, as if by
215.Xr ssh-add 1 .
216If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000217.Cm ask ,
218.Xr ssh 1
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000219will require confirmation using the
220.Ev SSH_ASKPASS
221program before adding a key (see
222.Xr ssh-add 1
223for details).
224If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000225.Cm confirm ,
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000226each use of the key must be confirmed, as if the
227.Fl c
228option was specified to
229.Xr ssh-add 1 .
230If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000231.Cm no ,
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000232no keys are added to the agent.
233The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000234.Cm yes ,
235.Cm confirm ,
236.Cm ask ,
jcs@openbsd.orgf361df42015-11-15 22:26:49 +0000237or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000238.Cm no
239(the default).
Damien Miller20a8f972003-05-18 20:50:30 +1000240.It Cm AddressFamily
Damien Millerfbf486b2003-05-23 18:44:23 +1000241Specifies which address family to use when connecting.
242Valid arguments are
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000243.Cm any
244(the default),
245.Cm inet
Damien Miller45ee2b92006-03-15 11:56:18 +1100246(use IPv4 only), or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000247.Cm inet6
Darren Tucker79a7acf2005-02-09 09:48:57 +1100248(use IPv6 only).
Ben Lindstrom9f049032002-06-21 00:59:05 +0000249.It Cm BatchMode
250If set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000251.Cm yes ,
Ben Lindstrom9f049032002-06-21 00:59:05 +0000252passphrase/password querying will be disabled.
253This option is useful in scripts and other batch jobs where no user
254is present to supply the password.
255The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000256.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000257or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000258.Cm no
259(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +0000260.It Cm BindAddress
Darren Tucker89f4d472005-07-14 17:06:21 +1000261Use the specified address on the local machine as the source address of
Darren Tucker6c71d202005-07-14 17:06:50 +1000262the connection.
263Only useful on systems with more than one address.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000264Note that this option does not work if
265.Cm UsePrivilegedPort
266is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000267.Cm yes .
Damien Miller0faf7472013-10-17 11:47:23 +1100268.It Cm CanonicalDomains
Damien Miller607af342013-10-17 11:47:51 +1100269When
Damien Miller38505592013-10-17 11:48:13 +1100270.Cm CanonicalizeHostname
Damien Miller0faf7472013-10-17 11:47:23 +1100271is enabled, this option specifies the list of domain suffixes in which to
272search for the specified destination host.
Damien Miller38505592013-10-17 11:48:13 +1100273.It Cm CanonicalizeFallbackLocal
Damien Miller51682fa2013-10-17 11:48:31 +1100274Specifies whether to fail with an error when hostname canonicalization fails.
Damien Miller607af342013-10-17 11:47:51 +1100275The default,
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000276.Cm yes ,
Damien Miller607af342013-10-17 11:47:51 +1100277will attempt to look up the unqualified hostname using the system resolver's
Damien Miller0faf7472013-10-17 11:47:23 +1100278search rules.
279A value of
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000280.Cm no
Damien Miller0faf7472013-10-17 11:47:23 +1100281will cause
282.Xr ssh 1
283to fail instantly if
Damien Miller38505592013-10-17 11:48:13 +1100284.Cm CanonicalizeHostname
Damien Miller0faf7472013-10-17 11:47:23 +1100285is enabled and the target hostname cannot be found in any of the domains
286specified by
287.Cm CanonicalDomains .
Damien Miller38505592013-10-17 11:48:13 +1100288.It Cm CanonicalizeHostname
Damien Miller51682fa2013-10-17 11:48:31 +1100289Controls whether explicit hostname canonicalization is performed.
Damien Miller607af342013-10-17 11:47:51 +1100290The default,
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000291.Cm no ,
Damien Miller0faf7472013-10-17 11:47:23 +1100292is not to perform any name rewriting and let the system resolver handle all
293hostname lookups.
294If set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000295.Cm yes
Damien Miller0faf7472013-10-17 11:47:23 +1100296then, for connections that do not use a
297.Cm ProxyCommand ,
298.Xr ssh 1
Damien Miller38505592013-10-17 11:48:13 +1100299will attempt to canonicalize the hostname specified on the command line
Damien Miller0faf7472013-10-17 11:47:23 +1100300using the
301.Cm CanonicalDomains
302suffixes and
Damien Miller38505592013-10-17 11:48:13 +1100303.Cm CanonicalizePermittedCNAMEs
Damien Miller0faf7472013-10-17 11:47:23 +1100304rules.
305If
Damien Miller38505592013-10-17 11:48:13 +1100306.Cm CanonicalizeHostname
Damien Miller0faf7472013-10-17 11:47:23 +1100307is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000308.Cm always ,
Damien Miller51682fa2013-10-17 11:48:31 +1100309then canonicalization is applied to proxied connections too.
Damien Miller13f97b22014-02-24 15:57:55 +1100310.Pp
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000311If this option is enabled, then the configuration files are processed
312again using the new target name to pick up any new configuration in matching
Damien Miller13f97b22014-02-24 15:57:55 +1100313.Cm Host
djm@openbsd.org957fbce2014-10-08 22:20:25 +0000314and
315.Cm Match
Damien Miller13f97b22014-02-24 15:57:55 +1100316stanzas.
Damien Miller38505592013-10-17 11:48:13 +1100317.It Cm CanonicalizeMaxDots
Damien Miller607af342013-10-17 11:47:51 +1100318Specifies the maximum number of dot characters in a hostname before
Damien Miller51682fa2013-10-17 11:48:31 +1100319canonicalization is disabled.
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000320The default, 1,
Damien Miller607af342013-10-17 11:47:51 +1100321allows a single dot (i.e. hostname.subdomain).
Damien Miller38505592013-10-17 11:48:13 +1100322.It Cm CanonicalizePermittedCNAMEs
Damien Miller607af342013-10-17 11:47:51 +1100323Specifies rules to determine whether CNAMEs should be followed when
Damien Miller38505592013-10-17 11:48:13 +1100324canonicalizing hostnames.
Damien Miller0faf7472013-10-17 11:47:23 +1100325The rules consist of one or more arguments of
Damien Miller607af342013-10-17 11:47:51 +1100326.Ar source_domain_list : Ns Ar target_domain_list ,
Damien Miller0faf7472013-10-17 11:47:23 +1100327where
328.Ar source_domain_list
Damien Miller51682fa2013-10-17 11:48:31 +1100329is a pattern-list of domains that may follow CNAMEs in canonicalization,
Damien Miller0faf7472013-10-17 11:47:23 +1100330and
331.Ar target_domain_list
Damien Miller607af342013-10-17 11:47:51 +1100332is a pattern-list of domains that they may resolve to.
Damien Miller0faf7472013-10-17 11:47:23 +1100333.Pp
334For example,
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000335.Qq *.a.example.com:*.b.example.com,*.c.example.com
Damien Miller0faf7472013-10-17 11:47:23 +1100336will allow hostnames matching
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000337.Qq *.a.example.com
Damien Miller38505592013-10-17 11:48:13 +1100338to be canonicalized to names in the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000339.Qq *.b.example.com
Damien Miller0faf7472013-10-17 11:47:23 +1100340or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000341.Qq *.c.example.com
Damien Miller0faf7472013-10-17 11:47:23 +1100342domains.
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000343.It Cm CertificateFile
344Specifies a file from which the user's certificate is read.
345A corresponding private key must be provided separately in order
346to use this certificate either
347from an
348.Cm IdentityFile
349directive or
350.Fl i
351flag to
352.Xr ssh 1 ,
353via
354.Xr ssh-agent 1 ,
355or via a
356.Cm PKCS11Provider .
357.Pp
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000358Arguments to
359.Cm CertificateFile
360may use the tilde syntax to refer to a user's home directory
361or the tokens described in the
362.Sx TOKENS
363section.
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000364.Pp
365It is possible to have multiple certificate files specified in
366configuration files; these certificates will be tried in sequence.
367Multiple
368.Cm CertificateFile
369directives will add to the list of certificates used for
370authentication.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000371.It Cm ChallengeResponseAuthentication
Damien Miller1faa7132006-03-15 11:55:31 +1100372Specifies whether to use challenge-response authentication.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000373The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000374.Cm yes
375(the default)
Ben Lindstrom9f049032002-06-21 00:59:05 +0000376or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000377.Cm no .
Ben Lindstrom9f049032002-06-21 00:59:05 +0000378.It Cm CheckHostIP
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000379If set to
380.Cm yes
381(the default),
Damien Miller45ee2b92006-03-15 11:56:18 +1100382.Xr ssh 1
383will additionally check the host IP address in the
Ben Lindstrom9f049032002-06-21 00:59:05 +0000384.Pa known_hosts
385file.
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000386This allows it to detect if a host key changed due to DNS spoofing
djm@openbsd.org5e678592015-06-02 09:10:40 +0000387and will add addresses of destination hosts to
388.Pa ~/.ssh/known_hosts
389in the process, regardless of the setting of
390.Cm StrictHostKeyChecking .
Ben Lindstrom9f049032002-06-21 00:59:05 +0000391If the option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000392.Cm no ,
Ben Lindstrom9f049032002-06-21 00:59:05 +0000393the check will not be executed.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000394.It Cm Ciphers
djm@openbsd.org788ac792017-04-30 23:18:22 +0000395Specifies the ciphers allowed and their order of preference.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000396Multiple ciphers must be comma-separated.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +0000397If the specified value begins with a
398.Sq +
399character, then the specified ciphers will be appended to the default set
400instead of replacing them.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +0000401If the specified value begins with a
402.Sq -
403character, then the specified ciphers (including wildcards) will be removed
404from the default set instead of replacing them.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +0000405.Pp
Damien Miller0fde8ac2013-11-21 14:12:23 +1100406The supported ciphers are:
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000407.Bd -literal -offset indent
Damien Millerc1621c82014-04-20 13:22:46 +10004083des-cbc
Damien Millerc1621c82014-04-20 13:22:46 +1000409aes128-cbc
Damien Millerc1621c82014-04-20 13:22:46 +1000410aes192-cbc
Damien Millerc1621c82014-04-20 13:22:46 +1000411aes256-cbc
Damien Millerc1621c82014-04-20 13:22:46 +1000412aes128-ctr
Damien Millerc1621c82014-04-20 13:22:46 +1000413aes192-ctr
Damien Millerc1621c82014-04-20 13:22:46 +1000414aes256-ctr
Damien Millerc1621c82014-04-20 13:22:46 +1000415aes128-gcm@openssh.com
Damien Millerc1621c82014-04-20 13:22:46 +1000416aes256-gcm@openssh.com
Damien Millerc1621c82014-04-20 13:22:46 +1000417arcfour
Damien Millerc1621c82014-04-20 13:22:46 +1000418arcfour128
Damien Millerc1621c82014-04-20 13:22:46 +1000419arcfour256
Damien Millerc1621c82014-04-20 13:22:46 +1000420blowfish-cbc
Damien Millerc1621c82014-04-20 13:22:46 +1000421cast128-cbc
Damien Millerc1621c82014-04-20 13:22:46 +1000422chacha20-poly1305@openssh.com
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000423.Ed
Damien Miller0fde8ac2013-11-21 14:12:23 +1100424.Pp
Damien Miller45ee2b92006-03-15 11:56:18 +1100425The default is:
Damien Millerc1621c82014-04-20 13:22:46 +1000426.Bd -literal -offset indent
jmc@openbsd.org1f8d3d62015-08-14 15:32:41 +0000427chacha20-poly1305@openssh.com,
Damien Millerc1621c82014-04-20 13:22:46 +1000428aes128-ctr,aes192-ctr,aes256-ctr,
Damien Miller1d75abf2013-01-09 16:12:19 +1100429aes128-gcm@openssh.com,aes256-gcm@openssh.com,
djm@openbsd.orgda953182016-09-05 14:02:42 +0000430aes128-cbc,aes192-cbc,aes256-cbc
Ben Lindstrom9f049032002-06-21 00:59:05 +0000431.Ed
Damien Miller0fde8ac2013-11-21 14:12:23 +1100432.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000433The list of available ciphers may also be obtained using
434.Qq ssh -Q cipher .
Ben Lindstrom9f049032002-06-21 00:59:05 +0000435.It Cm ClearAllForwardings
Damien Miller45ee2b92006-03-15 11:56:18 +1100436Specifies that all local, remote, and dynamic port forwardings
Ben Lindstrom9f049032002-06-21 00:59:05 +0000437specified in the configuration files or on the command line be
Damien Miller495dca32003-04-01 21:42:14 +1000438cleared.
439This option is primarily useful when used from the
Damien Miller45ee2b92006-03-15 11:56:18 +1100440.Xr ssh 1
Ben Lindstrom9f049032002-06-21 00:59:05 +0000441command line to clear port forwardings set in
442configuration files, and is automatically set by
443.Xr scp 1
444and
445.Xr sftp 1 .
446The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000447.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000448or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000449.Cm no
450(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +0000451.It Cm Compression
452Specifies whether to use compression.
453The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000454.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000455or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000456.Cm no
457(the default).
Damien Millerb78d5eb2003-05-16 11:39:04 +1000458.It Cm ConnectTimeout
Damien Miller45ee2b92006-03-15 11:56:18 +1100459Specifies the timeout (in seconds) used when connecting to the
460SSH server, instead of using the default system TCP timeout.
Damien Millerfbf486b2003-05-23 18:44:23 +1000461This value is used only when the target is down or really unreachable,
462not when it refuses the connection.
Damien Miller0e220db2004-06-15 10:34:08 +1000463.It Cm ControlMaster
464Enables the sharing of multiple sessions over a single network connection.
465When set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000466.Cm yes ,
Damien Miller45ee2b92006-03-15 11:56:18 +1100467.Xr ssh 1
Damien Miller0e220db2004-06-15 10:34:08 +1000468will listen for connections on a control socket specified using the
469.Cm ControlPath
470argument.
471Additional sessions can connect to this socket using the same
472.Cm ControlPath
473with
474.Cm ControlMaster
475set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000476.Cm no
Damien Miller2234bac2004-06-30 22:38:52 +1000477(the default).
Damien Miller713de762005-11-05 15:13:49 +1100478These sessions will try to reuse the master instance's network connection
Damien Millerb3bfbb72005-11-05 15:11:48 +1100479rather than initiating new ones, but will fall back to connecting normally
480if the control socket does not exist, or is not listening.
481.Pp
Damien Miller23f07702004-06-18 01:19:03 +1000482Setting this to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000483.Cm ask
484will cause
485.Xr ssh 1
jmc@openbsd.org78de1672015-03-30 18:28:37 +0000486to listen for control connections, but require confirmation using
487.Xr ssh-askpass 1 .
Damien Millerdadfd4d2005-05-26 12:07:13 +1000488If the
489.Cm ControlPath
Damien Miller45ee2b92006-03-15 11:56:18 +1100490cannot be opened,
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000491.Xr ssh 1
492will continue without connecting to a master instance.
Damien Millerd14b1e72005-06-16 13:19:41 +1000493.Pp
Damien Miller13390022005-07-06 09:44:19 +1000494X11 and
Damien Millerfd94fba2005-07-06 09:44:59 +1000495.Xr ssh-agent 1
Damien Miller13390022005-07-06 09:44:19 +1000496forwarding is supported over these multiplexed connections, however the
Darren Tucker63551872005-12-20 16:14:15 +1100497display and agent forwarded will be the one belonging to the master
Damien Millerfd94fba2005-07-06 09:44:59 +1000498connection i.e. it is not possible to forward multiple displays or agents.
Damien Miller13390022005-07-06 09:44:19 +1000499.Pp
Damien Millerd14b1e72005-06-16 13:19:41 +1000500Two additional options allow for opportunistic multiplexing: try to use a
501master connection but fall back to creating a new one if one does not already
502exist.
503These options are:
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000504.Cm auto
Damien Millerd14b1e72005-06-16 13:19:41 +1000505and
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000506.Cm autoask .
Damien Millerd14b1e72005-06-16 13:19:41 +1000507The latter requires confirmation like the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000508.Cm ask
Damien Millerd14b1e72005-06-16 13:19:41 +1000509option.
Damien Miller0e220db2004-06-15 10:34:08 +1000510.It Cm ControlPath
Damien Miller6476cad2005-06-16 13:18:34 +1000511Specify the path to the control socket used for connection sharing as described
512in the
Damien Miller0e220db2004-06-15 10:34:08 +1000513.Cm ControlMaster
Damien Miller8f74c8f2005-06-26 08:56:03 +1000514section above or the string
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000515.Cm none
Damien Miller8f74c8f2005-06-26 08:56:03 +1000516to disable connection sharing.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000517Arguments to
518.Cm ControlPath
519may use the tilde syntax to refer to a user's home directory
520or the tokens described in the
521.Sx TOKENS
522section.
Damien Millerd14b1e72005-06-16 13:19:41 +1000523It is recommended that any
524.Cm ControlPath
525used for opportunistic connection sharing include
djm@openbsd.orgfc302562014-11-10 22:25:49 +0000526at least %h, %p, and %r (or alternatively %C) and be placed in a directory
527that is not writable by other users.
Damien Millerd14b1e72005-06-16 13:19:41 +1000528This ensures that shared connections are uniquely identified.
Damien Millere11e1ea2010-08-03 16:04:46 +1000529.It Cm ControlPersist
530When used in conjunction with
531.Cm ControlMaster ,
532specifies that the master connection should remain open
533in the background (waiting for future client connections)
534after the initial client connection has been closed.
535If set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000536.Cm no ,
Damien Millere11e1ea2010-08-03 16:04:46 +1000537then the master connection will not be placed into the background,
538and will close as soon as the initial client connection is closed.
539If set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000540.Cm yes
541or 0,
Damien Millere11e1ea2010-08-03 16:04:46 +1000542then the master connection will remain in the background indefinitely
543(until killed or closed via a mechanism such as the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000544.Qq ssh -O exit ) .
Damien Millere11e1ea2010-08-03 16:04:46 +1000545If set to a time in seconds, or a time in any of the formats documented in
546.Xr sshd_config 5 ,
547then the backgrounded master connection will automatically terminate
548after it has remained idle (with no client connections) for the
549specified time.
Damien Miller2234bac2004-06-30 22:38:52 +1000550.It Cm DynamicForward
Damien Millere9d001e2006-01-14 10:10:17 +1100551Specifies that a TCP port on the local machine be forwarded
Damien Miller2234bac2004-06-30 22:38:52 +1000552over the secure channel, and the application
553protocol is then used to determine where to connect to from the
554remote machine.
Darren Tuckerc8d64212005-10-03 18:13:42 +1000555.Pp
556The argument must be
557.Sm off
558.Oo Ar bind_address : Oc Ar port .
559.Sm on
Damien Miller7fa96602010-08-05 13:03:13 +1000560IPv6 addresses can be specified by enclosing addresses in square brackets.
Darren Tuckerc8d64212005-10-03 18:13:42 +1000561By default, the local port is bound in accordance with the
562.Cm GatewayPorts
563setting.
564However, an explicit
565.Ar bind_address
566may be used to bind the connection to a specific address.
567The
568.Ar bind_address
569of
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000570.Cm localhost
Darren Tuckerc8d64212005-10-03 18:13:42 +1000571indicates that the listening port be bound for local use only, while an
572empty address or
573.Sq *
574indicates that the port should be available from all interfaces.
575.Pp
Damien Miller2234bac2004-06-30 22:38:52 +1000576Currently the SOCKS4 and SOCKS5 protocols are supported, and
Damien Miller45ee2b92006-03-15 11:56:18 +1100577.Xr ssh 1
Damien Miller2234bac2004-06-30 22:38:52 +1000578will act as a SOCKS server.
579Multiple forwardings may be specified, and
580additional forwardings can be given on the command line.
581Only the superuser can forward privileged ports.
Darren Tucker674f71d2003-06-28 12:33:12 +1000582.It Cm EnableSSHKeysign
583Setting this option to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000584.Cm yes
Darren Tucker674f71d2003-06-28 12:33:12 +1000585in the global client configuration file
586.Pa /etc/ssh/ssh_config
587enables the use of the helper program
588.Xr ssh-keysign 8
589during
590.Cm HostbasedAuthentication .
591The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000592.Cm yes
Darren Tucker674f71d2003-06-28 12:33:12 +1000593or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000594.Cm no
595(the default).
Darren Tuckerf132c672003-10-15 15:58:18 +1000596This option should be placed in the non-hostspecific section.
Darren Tucker674f71d2003-06-28 12:33:12 +1000597See
598.Xr ssh-keysign 8
599for more information.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000600.It Cm EscapeChar
601Sets the escape character (default:
602.Ql ~ ) .
603The escape character can also
604be set on the command line.
605The argument should be a single character,
606.Ql ^
607followed by a letter, or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000608.Cm none
Ben Lindstrom9f049032002-06-21 00:59:05 +0000609to disable the escape
610character entirely (making the connection transparent for binary
611data).
Darren Tuckere7d4b192006-07-12 22:17:10 +1000612.It Cm ExitOnForwardFailure
613Specifies whether
614.Xr ssh 1
615should terminate the connection if it cannot set up all requested
djm@openbsd.orga954cdb2015-09-04 04:47:50 +0000616dynamic, tunnel, local, and remote port forwardings, (e.g.\&
jmc@openbsd.org5245bc12015-09-04 06:40:45 +0000617if either end is unable to bind and listen on a specified port).
djm@openbsd.orga954cdb2015-09-04 04:47:50 +0000618Note that
619.Cm ExitOnForwardFailure
620does not apply to connections made over port forwardings and will not,
621for example, cause
622.Xr ssh 1
623to exit if TCP connections to the ultimate forwarding destination fail.
Darren Tuckere7d4b192006-07-12 22:17:10 +1000624The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000625.Cm yes
Darren Tuckere7d4b192006-07-12 22:17:10 +1000626or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000627.Cm no
628(the default).
djm@openbsd.orgb79efde2014-12-21 23:12:42 +0000629.It Cm FingerprintHash
630Specifies the hash algorithm used when displaying key fingerprints.
631Valid options are:
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000632.Cm md5
djm@openbsd.orgb79efde2014-12-21 23:12:42 +0000633and
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000634.Cm sha256
635(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +0000636.It Cm ForwardAgent
637Specifies whether the connection to the authentication agent (if any)
638will be forwarded to the remote machine.
639The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000640.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000641or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000642.Cm no
643(the default).
Damien Milleraf653042002-09-04 16:40:37 +1000644.Pp
Damien Miller495dca32003-04-01 21:42:14 +1000645Agent forwarding should be enabled with caution.
646Users with the ability to bypass file permissions on the remote host
647(for the agent's Unix-domain socket)
648can access the local agent through the forwarded connection.
649An attacker cannot obtain key material from the agent,
Damien Milleraf653042002-09-04 16:40:37 +1000650however they can perform operations on the keys that enable them to
651authenticate using the identities loaded into the agent.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000652.It Cm ForwardX11
653Specifies whether X11 connections will be automatically redirected
654over the secure channel and
655.Ev DISPLAY
656set.
657The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000658.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000659or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000660.Cm no
661(the default).
Damien Milleraf653042002-09-04 16:40:37 +1000662.Pp
Damien Miller495dca32003-04-01 21:42:14 +1000663X11 forwarding should be enabled with caution.
664Users with the ability to bypass file permissions on the remote host
Darren Tucker0a118da2003-10-15 15:54:32 +1000665(for the user's X11 authorization database)
Damien Miller495dca32003-04-01 21:42:14 +1000666can access the local X11 display through the forwarded connection.
Darren Tucker0a118da2003-10-15 15:54:32 +1000667An attacker may then be able to perform activities such as keystroke monitoring
668if the
669.Cm ForwardX11Trusted
670option is also enabled.
Damien Miller1ab6a512010-06-26 10:02:24 +1000671.It Cm ForwardX11Timeout
Damien Millercede1db2010-07-02 13:33:48 +1000672Specify a timeout for untrusted X11 forwarding
673using the format described in the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000674.Sx TIME FORMATS
675section of
Damien Miller1ab6a512010-06-26 10:02:24 +1000676.Xr sshd_config 5 .
677X11 connections received by
678.Xr ssh 1
679after this time will be refused.
680The default is to disable untrusted X11 forwarding after twenty minutes has
681elapsed.
Darren Tucker0a118da2003-10-15 15:54:32 +1000682.It Cm ForwardX11Trusted
Darren Tuckerdcf6ec42004-05-13 13:03:56 +1000683If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000684.Cm yes ,
Damien Miller45ee2b92006-03-15 11:56:18 +1100685remote X11 clients will have full access to the original X11 display.
Damien Miller1717fd42005-03-01 21:17:31 +1100686.Pp
Darren Tucker0a118da2003-10-15 15:54:32 +1000687If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000688.Cm no
689(the default),
Damien Miller45ee2b92006-03-15 11:56:18 +1100690remote X11 clients will be considered untrusted and prevented
Darren Tucker0a118da2003-10-15 15:54:32 +1000691from stealing or tampering with data belonging to trusted X11
692clients.
Damien Miller1717fd42005-03-01 21:17:31 +1100693Furthermore, the
694.Xr xauth 1
695token used for the session will be set to expire after 20 minutes.
696Remote clients will be refused access after this time.
Darren Tucker0a118da2003-10-15 15:54:32 +1000697.Pp
Darren Tucker0a118da2003-10-15 15:54:32 +1000698See the X11 SECURITY extension specification for full details on
699the restrictions imposed on untrusted clients.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000700.It Cm GatewayPorts
701Specifies whether remote hosts are allowed to connect to local
702forwarded ports.
703By default,
Damien Miller45ee2b92006-03-15 11:56:18 +1100704.Xr ssh 1
Damien Miller495dca32003-04-01 21:42:14 +1000705binds local port forwardings to the loopback address.
706This prevents other remote hosts from connecting to forwarded ports.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000707.Cm GatewayPorts
Damien Miller45ee2b92006-03-15 11:56:18 +1100708can be used to specify that ssh
Ben Lindstrom9f049032002-06-21 00:59:05 +0000709should bind local port forwardings to the wildcard address,
710thus allowing remote hosts to connect to forwarded ports.
711The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000712.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000713or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000714.Cm no
715(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +0000716.It Cm GlobalKnownHostsFile
Damien Miller295ee632011-05-29 21:42:31 +1000717Specifies one or more files to use for the global
718host key database, separated by whitespace.
719The default is
720.Pa /etc/ssh/ssh_known_hosts ,
721.Pa /etc/ssh/ssh_known_hosts2 .
Darren Tucker0efd1552003-08-26 11:49:55 +1000722.It Cm GSSAPIAuthentication
Damien Millerbaafb982003-12-17 16:32:23 +1100723Specifies whether user authentication based on GSSAPI is allowed.
Damien Millerc2b98272003-09-03 12:13:30 +1000724The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000725.Cm no .
Darren Tucker0efd1552003-08-26 11:49:55 +1000726.It Cm GSSAPIDelegateCredentials
727Forward (delegate) credentials to the server.
728The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000729.Cm no .
Damien Millere1776152005-03-01 21:47:37 +1100730.It Cm HashKnownHosts
731Indicates that
Damien Miller45ee2b92006-03-15 11:56:18 +1100732.Xr ssh 1
Damien Millere1776152005-03-01 21:47:37 +1100733should hash host names and addresses when they are added to
Damien Miller167ea5d2005-05-26 12:04:02 +1000734.Pa ~/.ssh/known_hosts .
Damien Millere1776152005-03-01 21:47:37 +1100735These hashed names may be used normally by
Damien Miller45ee2b92006-03-15 11:56:18 +1100736.Xr ssh 1
Damien Millere1776152005-03-01 21:47:37 +1100737and
Damien Miller45ee2b92006-03-15 11:56:18 +1100738.Xr sshd 8 ,
Damien Millere1776152005-03-01 21:47:37 +1100739but they do not reveal identifying information should the file's contents
740be disclosed.
741The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000742.Cm no .
Damien Miller858bb7d2006-08-05 11:34:51 +1000743Note that existing names and addresses in known hosts files
744will not be converted automatically,
745but may be manually hashed using
Damien Miller4b42d7f2005-03-01 21:48:35 +1100746.Xr ssh-keygen 1 .
Ben Lindstrom9f049032002-06-21 00:59:05 +0000747.It Cm HostbasedAuthentication
748Specifies whether to try rhosts based authentication with public key
749authentication.
750The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000751.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +0000752or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000753.Cm no
754(the default).
djm@openbsd.org46347ed2015-01-30 11:43:14 +0000755.It Cm HostbasedKeyTypes
756Specifies the key types that will be used for hostbased authentication
757as a comma-separated pattern list.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +0000758Alternately if the specified value begins with a
759.Sq +
760character, then the specified key types will be appended to the default set
761instead of replacing them.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +0000762If the specified value begins with a
763.Sq -
764character, then the specified key types (including wildcards) will be removed
765from the default set instead of replacing them.
markus@openbsd.org3a1638d2015-07-10 06:21:53 +0000766The default for this option is:
767.Bd -literal -offset 3n
768ecdsa-sha2-nistp256-cert-v01@openssh.com,
769ecdsa-sha2-nistp384-cert-v01@openssh.com,
770ecdsa-sha2-nistp521-cert-v01@openssh.com,
771ssh-ed25519-cert-v01@openssh.com,
772ssh-rsa-cert-v01@openssh.com,
773ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
djm@openbsd.org3a13cb52016-02-17 08:57:34 +0000774ssh-ed25519,ssh-rsa
markus@openbsd.org3a1638d2015-07-10 06:21:53 +0000775.Ed
776.Pp
djm@openbsd.org46347ed2015-01-30 11:43:14 +0000777The
778.Fl Q
779option of
780.Xr ssh 1
781may be used to list supported key types.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000782.It Cm HostKeyAlgorithms
jmc@openbsd.orga685ae82016-02-17 07:38:19 +0000783Specifies the host key algorithms
Ben Lindstrom9f049032002-06-21 00:59:05 +0000784that the client wants to use in order of preference.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +0000785Alternately if the specified value begins with a
786.Sq +
787character, then the specified key types will be appended to the default set
788instead of replacing them.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +0000789If the specified value begins with a
790.Sq -
791character, then the specified key types (including wildcards) will be removed
792from the default set instead of replacing them.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000793The default for this option is:
Damien Millereb8b60e2010-08-31 22:41:14 +1000794.Bd -literal -offset 3n
795ecdsa-sha2-nistp256-cert-v01@openssh.com,
796ecdsa-sha2-nistp384-cert-v01@openssh.com,
797ecdsa-sha2-nistp521-cert-v01@openssh.com,
Damien Miller8ba0ead2013-12-18 17:46:27 +1100798ssh-ed25519-cert-v01@openssh.com,
markus@openbsd.org3a1638d2015-07-10 06:21:53 +0000799ssh-rsa-cert-v01@openssh.com,
Damien Millereb8b60e2010-08-31 22:41:14 +1000800ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
djm@openbsd.org3a13cb52016-02-17 08:57:34 +0000801ssh-ed25519,ssh-rsa
Damien Millereb8b60e2010-08-31 22:41:14 +1000802.Ed
Damien Millerd925dcd2010-12-01 12:21:51 +1100803.Pp
804If hostkeys are known for the destination host then this default is modified
805to prefer their algorithms.
djm@openbsd.org8f6784f2014-12-22 09:05:17 +0000806.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000807The list of available key types may also be obtained using
808.Qq ssh -Q key .
Ben Lindstrom9f049032002-06-21 00:59:05 +0000809.It Cm HostKeyAlias
810Specifies an alias that should be used instead of the
811real host name when looking up or saving the host key
812in the host key database files.
Damien Miller45ee2b92006-03-15 11:56:18 +1100813This option is useful for tunneling SSH connections
Ben Lindstrom9f049032002-06-21 00:59:05 +0000814or for multiple servers running on a single host.
815.It Cm HostName
816Specifies the real host name to log into.
817This can be used to specify nicknames or abbreviations for hosts.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000818Arguments to
819.Cm HostName
820accept the tokens described in the
821.Sx TOKENS
822section.
Ben Lindstrom9f049032002-06-21 00:59:05 +0000823Numeric IP addresses are also permitted (both on the command line and in
824.Cm HostName
825specifications).
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000826The default is the name given on the command line.
Damien Millerbd394c32004-03-08 23:12:36 +1100827.It Cm IdentitiesOnly
828Specifies that
Damien Miller45ee2b92006-03-15 11:56:18 +1100829.Xr ssh 1
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000830should only use the authentication identity and certificate files explicitly
831configured in the
Damien Miller1a812582004-04-20 20:13:32 +1000832.Nm
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000833files
834or passed on the
835.Xr ssh 1
836command-line,
Damien Miller45ee2b92006-03-15 11:56:18 +1100837even if
838.Xr ssh-agent 1
Damien Millercb6b68b2012-12-03 09:49:52 +1100839or a
840.Cm PKCS11Provider
Damien Millerbd394c32004-03-08 23:12:36 +1100841offers more identities.
842The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000843.Cm yes
Damien Millerbd394c32004-03-08 23:12:36 +1100844or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000845.Cm no
846(the default).
Damien Miller45ee2b92006-03-15 11:56:18 +1100847This option is intended for situations where ssh-agent
Damien Millerbd394c32004-03-08 23:12:36 +1100848offers many different identities.
markus@openbsd.orgb02ad1c2016-05-04 12:21:53 +0000849.It Cm IdentityAgent
850Specifies the
851.Ux Ns -domain
852socket used to communicate with the authentication agent.
853.Pp
854This option overrides the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000855.Ev SSH_AUTH_SOCK
markus@openbsd.orgb02ad1c2016-05-04 12:21:53 +0000856environment variable and can be used to select a specific agent.
857Setting the socket name to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000858.Cm none
markus@openbsd.orgb02ad1c2016-05-04 12:21:53 +0000859disables the use of an authentication agent.
markus@openbsd.org1a75d142016-05-04 14:29:58 +0000860If the string
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000861.Qq SSH_AUTH_SOCK
markus@openbsd.org1a75d142016-05-04 14:29:58 +0000862is specified, the location of the socket will be read from the
863.Ev SSH_AUTH_SOCK
864environment variable.
markus@openbsd.orgb02ad1c2016-05-04 12:21:53 +0000865.Pp
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000866Arguments to
867.Cm IdentityAgent
868may use the tilde syntax to refer to a user's home directory
869or the tokens described in the
870.Sx TOKENS
871section.
Damien Miller957d4e42005-12-13 19:30:45 +1100872.It Cm IdentityFile
sobrado@openbsd.orgf70b22b2014-08-30 15:33:50 +0000873Specifies a file from which the user's DSA, ECDSA, Ed25519 or RSA authentication
Damien Millereb8b60e2010-08-31 22:41:14 +1000874identity is read.
Damien Miller957d4e42005-12-13 19:30:45 +1100875The default is
Damien Millereb8b60e2010-08-31 22:41:14 +1000876.Pa ~/.ssh/id_dsa ,
Damien Miller8ba0ead2013-12-18 17:46:27 +1100877.Pa ~/.ssh/id_ecdsa ,
878.Pa ~/.ssh/id_ed25519
Damien Miller957d4e42005-12-13 19:30:45 +1100879and
djm@openbsd.org788ac792017-04-30 23:18:22 +0000880.Pa ~/.ssh/id_rsa .
Damien Miller957d4e42005-12-13 19:30:45 +1100881Additionally, any identities represented by the authentication agent
Damien Miller7f2b4382013-07-18 16:10:29 +1000882will be used for authentication unless
883.Cm IdentitiesOnly
884is set.
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000885If no certificates have been explicitly specified by
886.Cm CertificateFile ,
Damien Miller5059d8d2010-03-05 21:31:11 +1100887.Xr ssh 1
888will try to load certificate information from the filename obtained by
889appending
890.Pa -cert.pub
891to the path of a specified
892.Cm IdentityFile .
Damien Miller6b1d53c2006-03-31 23:13:21 +1100893.Pp
jmc@openbsd.org80d1c962016-09-28 17:59:22 +0000894Arguments to
895.Cm IdentityFile
896may use the tilde syntax to refer to a user's home directory
897or the tokens described in the
898.Sx TOKENS
899section.
Damien Miller6b1d53c2006-03-31 23:13:21 +1100900.Pp
Damien Miller957d4e42005-12-13 19:30:45 +1100901It is possible to have
902multiple identity files specified in configuration files; all these
903identities will be tried in sequence.
Damien Miller6029e072011-06-20 14:22:49 +1000904Multiple
905.Cm IdentityFile
906directives will add to the list of identities tried (this behaviour
907differs from that of other configuration directives).
Damien Miller7f2b4382013-07-18 16:10:29 +1000908.Pp
909.Cm IdentityFile
910may be used in conjunction with
911.Cm IdentitiesOnly
912to select which identities in an agent are offered during authentication.
djm@openbsd.org4e44a792015-09-24 06:15:11 +0000913.Cm IdentityFile
914may also be used in conjunction with
915.Cm CertificateFile
916in order to provide any certificate also needed for authentication with
917the identity.
Darren Tucker63e0df22013-05-16 20:30:31 +1000918.It Cm IgnoreUnknown
919Specifies a pattern-list of unknown options to be ignored if they are
920encountered in configuration parsing.
921This may be used to suppress errors if
922.Nm
923contains options that are unrecognised by
924.Xr ssh 1 .
925It is recommended that
926.Cm IgnoreUnknown
927be listed early in the configuration file as it will not be applied
928to unknown options that appear before it.
djm@openbsd.orgdc7990b2016-04-15 00:30:19 +0000929.It Cm Include
930Include the specified configuration file(s).
jmc@openbsd.org6aaabc22016-04-17 14:34:46 +0000931Multiple pathnames may be specified and each pathname may contain
djm@openbsd.orgdc7990b2016-04-15 00:30:19 +0000932.Xr glob 3
933wildcards and, for user configurations, shell-like
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000934.Sq ~
djm@openbsd.orgdc7990b2016-04-15 00:30:19 +0000935references to user home directories.
936Files without absolute paths are assumed to be in
937.Pa ~/.ssh
jmc@openbsd.org6aaabc22016-04-17 14:34:46 +0000938if included in a user configuration file or
djm@openbsd.orgdc7990b2016-04-15 00:30:19 +0000939.Pa /etc/ssh
940if included from the system configuration file.
941.Cm Include
942directive may appear inside a
943.Cm Match
944or
945.Cm Host
946block
947to perform conditional inclusion.
Damien Miller0dac6fb2010-11-20 15:19:38 +1100948.It Cm IPQoS
949Specifies the IPv4 type-of-service or DSCP class for connections.
950Accepted values are
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000951.Cm af11 ,
952.Cm af12 ,
953.Cm af13 ,
954.Cm af21 ,
955.Cm af22 ,
956.Cm af23 ,
957.Cm af31 ,
958.Cm af32 ,
959.Cm af33 ,
960.Cm af41 ,
961.Cm af42 ,
962.Cm af43 ,
963.Cm cs0 ,
964.Cm cs1 ,
965.Cm cs2 ,
966.Cm cs3 ,
967.Cm cs4 ,
968.Cm cs5 ,
969.Cm cs6 ,
970.Cm cs7 ,
971.Cm ef ,
972.Cm lowdelay ,
973.Cm throughput ,
974.Cm reliability ,
Damien Miller0dac6fb2010-11-20 15:19:38 +1100975or a numeric value.
Damien Miller928362d2010-12-26 14:26:45 +1100976This option may take one or two arguments, separated by whitespace.
Damien Miller0dac6fb2010-11-20 15:19:38 +1100977If one argument is specified, it is used as the packet class unconditionally.
978If two values are specified, the first is automatically selected for
979interactive sessions and the second for non-interactive sessions.
980The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000981.Cm lowdelay
Damien Miller0dac6fb2010-11-20 15:19:38 +1100982for interactive sessions and
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000983.Cm throughput
Damien Miller0dac6fb2010-11-20 15:19:38 +1100984for non-interactive sessions.
Damien Millercfb606c2007-10-26 14:24:48 +1000985.It Cm KbdInteractiveAuthentication
986Specifies whether to use keyboard-interactive authentication.
987The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000988.Cm yes
989(the default)
Damien Millercfb606c2007-10-26 14:24:48 +1000990or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000991.Cm no .
Darren Tucker636ca902004-11-05 20:22:00 +1100992.It Cm KbdInteractiveDevices
993Specifies the list of methods to use in keyboard-interactive authentication.
994Multiple method names must be comma-separated.
995The default is to use the server specified list.
Damien Miller9cfbaec2006-03-15 11:57:55 +1100996The methods available vary depending on what the server supports.
997For an OpenSSH server,
998it may be zero or more of:
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +0000999.Cm bsdauth ,
1000.Cm pam ,
Damien Miller9cfbaec2006-03-15 11:57:55 +11001001and
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001002.Cm skey .
Damien Millerd5f62bf2010-09-24 22:11:14 +10001003.It Cm KexAlgorithms
1004Specifies the available KEX (Key Exchange) algorithms.
1005Multiple algorithms must be comma-separated.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +00001006Alternately if the specified value begins with a
1007.Sq +
1008character, then the specified methods will be appended to the default set
1009instead of replacing them.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +00001010If the specified value begins with a
1011.Sq -
1012character, then the specified methods (including wildcards) will be removed
1013from the default set instead of replacing them.
Damien Miller7fe2b1f2010-09-24 22:11:53 +10001014The default is:
1015.Bd -literal -offset indent
djm@openbsd.org16277fc2016-09-22 17:55:13 +00001016curve25519-sha256,curve25519-sha256@libssh.org,
Damien Miller7fe2b1f2010-09-24 22:11:53 +10001017ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,
1018diffie-hellman-group-exchange-sha256,
Damien Millerc1621c82014-04-20 13:22:46 +10001019diffie-hellman-group-exchange-sha1,
djm@openbsd.orgbdfd29f2015-07-03 03:47:00 +00001020diffie-hellman-group14-sha1
Damien Miller7fe2b1f2010-09-24 22:11:53 +10001021.Ed
djm@openbsd.org8f6784f2014-12-22 09:05:17 +00001022.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001023The list of available key exchange algorithms may also be obtained using
1024.Qq ssh -Q kex .
Damien Millerd27b9472005-12-13 19:29:02 +11001025.It Cm LocalCommand
1026Specifies a command to execute on the local machine after successfully
1027connecting to the server.
1028The command string extends to the end of the line, and is executed with
Darren Tucker63b31cb2007-12-02 23:09:30 +11001029the user's shell.
jmc@openbsd.org80d1c962016-09-28 17:59:22 +00001030Arguments to
1031.Cm LocalCommand
1032accept the tokens described in the
1033.Sx TOKENS
1034section.
Darren Tucker78be8c52010-01-08 17:05:59 +11001035.Pp
1036The command is run synchronously and does not have access to the
1037session of the
1038.Xr ssh 1
1039that spawned it.
1040It should not be used for interactive commands.
1041.Pp
Damien Millerd27b9472005-12-13 19:29:02 +11001042This directive is ignored unless
1043.Cm PermitLocalCommand
1044has been enabled.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001045.It Cm LocalForward
Damien Millere9d001e2006-01-14 10:10:17 +11001046Specifies that a TCP port on the local machine be forwarded over
Ben Lindstrom9f049032002-06-21 00:59:05 +00001047the secure channel to the specified host and port from the remote machine.
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001048The first argument must be
Damien Millerf91ee4c2005-03-01 21:24:33 +11001049.Sm off
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001050.Oo Ar bind_address : Oc Ar port
Damien Millerf91ee4c2005-03-01 21:24:33 +11001051.Sm on
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001052and the second argument must be
1053.Ar host : Ns Ar hostport .
Damien Miller7fa96602010-08-05 13:03:13 +10001054IPv6 addresses can be specified by enclosing addresses in square brackets.
Damien Millerf8c55462005-03-02 12:03:05 +11001055Multiple forwardings may be specified, and additional forwardings can be
Damien Millerf91ee4c2005-03-01 21:24:33 +11001056given on the command line.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001057Only the superuser can forward privileged ports.
Damien Millerf91ee4c2005-03-01 21:24:33 +11001058By default, the local port is bound in accordance with the
1059.Cm GatewayPorts
1060setting.
1061However, an explicit
1062.Ar bind_address
1063may be used to bind the connection to a specific address.
1064The
1065.Ar bind_address
1066of
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001067.Cm localhost
Damien Millerf8c55462005-03-02 12:03:05 +11001068indicates that the listening port be bound for local use only, while an
1069empty address or
1070.Sq *
Damien Millerf91ee4c2005-03-01 21:24:33 +11001071indicates that the port should be available from all interfaces.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001072.It Cm LogLevel
1073Gives the verbosity level that is used when logging messages from
Damien Miller45ee2b92006-03-15 11:56:18 +11001074.Xr ssh 1 .
Ben Lindstrom9f049032002-06-21 00:59:05 +00001075The possible values are:
Damien Miller45ee2b92006-03-15 11:56:18 +11001076QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.
Damien Miller495dca32003-04-01 21:42:14 +10001077The default is INFO.
1078DEBUG and DEBUG1 are equivalent.
1079DEBUG2 and DEBUG3 each specify higher levels of verbose output.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001080.It Cm MACs
1081Specifies the MAC (message authentication code) algorithms
1082in order of preference.
jmc@openbsd.orga685ae82016-02-17 07:38:19 +00001083The MAC algorithm is used for data integrity protection.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001084Multiple algorithms must be comma-separated.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +00001085If the specified value begins with a
1086.Sq +
1087character, then the specified algorithms will be appended to the default set
1088instead of replacing them.
djm@openbsd.org68bc8cf2017-02-03 23:01:19 +00001089If the specified value begins with a
1090.Sq -
1091character, then the specified algorithms (including wildcards) will be removed
1092from the default set instead of replacing them.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +00001093.Pp
Damien Milleraf43a7a2012-12-12 10:46:31 +11001094The algorithms that contain
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001095.Qq -etm
Damien Milleraf43a7a2012-12-12 10:46:31 +11001096calculate the MAC after encryption (encrypt-then-mac).
1097These are considered safer and their use recommended.
djm@openbsd.orgf9eca242015-07-30 00:01:34 +00001098.Pp
Damien Miller45ee2b92006-03-15 11:56:18 +11001099The default is:
Damien Miller5e7c30b2007-06-11 14:06:32 +10001100.Bd -literal -offset indent
Damien Milleraf43a7a2012-12-12 10:46:31 +11001101umac-64-etm@openssh.com,umac-128-etm@openssh.com,
1102hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,
djm@openbsd.orge4c918a2016-02-11 02:56:32 +00001103hmac-sha1-etm@openssh.com,
Damien Millerc1621c82014-04-20 13:22:46 +10001104umac-64@openssh.com,umac-128@openssh.com,
djm@openbsd.orge4c918a2016-02-11 02:56:32 +00001105hmac-sha2-256,hmac-sha2-512,hmac-sha1
Damien Miller5e7c30b2007-06-11 14:06:32 +10001106.Ed
djm@openbsd.org8f6784f2014-12-22 09:05:17 +00001107.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001108The list of available MAC algorithms may also be obtained using
1109.Qq ssh -Q mac .
Ben Lindstrom9f049032002-06-21 00:59:05 +00001110.It Cm NoHostAuthenticationForLocalhost
1111This option can be used if the home directory is shared across machines.
1112In this case localhost will refer to a different machine on each of
1113the machines and the user will get many warnings about changed host keys.
1114However, this option disables host authentication for localhost.
1115The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001116.Cm yes
Ben Lindstrom9f049032002-06-21 00:59:05 +00001117or
jmc@openbsd.org78142e32017-02-27 14:30:33 +00001118.Cm no
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001119(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +00001120.It Cm NumberOfPasswordPrompts
1121Specifies the number of password prompts before giving up.
1122The argument to this keyword must be an integer.
Damien Miller45ee2b92006-03-15 11:56:18 +11001123The default is 3.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001124.It Cm PasswordAuthentication
1125Specifies whether to use password authentication.
1126The argument to this keyword must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001127.Cm yes
1128(the default)
Ben Lindstrom9f049032002-06-21 00:59:05 +00001129or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001130.Cm no .
Damien Millerd27b9472005-12-13 19:29:02 +11001131.It Cm PermitLocalCommand
1132Allow local command execution via the
1133.Ic LocalCommand
1134option or using the
Damien Miller4b2319f2005-12-13 19:30:27 +11001135.Ic !\& Ns Ar command
Damien Millerd27b9472005-12-13 19:29:02 +11001136escape sequence in
1137.Xr ssh 1 .
1138The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001139.Cm yes
Damien Millerd27b9472005-12-13 19:29:02 +11001140or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001141.Cm no
1142(the default).
Damien Miller7ea845e2010-02-12 09:21:02 +11001143.It Cm PKCS11Provider
1144Specifies which PKCS#11 provider to use.
Damien Miller8e1ea4e2010-11-20 15:20:10 +11001145The argument to this keyword is the PKCS#11 shared library
Damien Miller7ea845e2010-02-12 09:21:02 +11001146.Xr ssh 1
Damien Millera7618442010-02-12 09:26:02 +11001147should use to communicate with a PKCS#11 token providing the user's
Damien Miller7ea845e2010-02-12 09:21:02 +11001148private RSA key.
Damien Miller957d4e42005-12-13 19:30:45 +11001149.It Cm Port
1150Specifies the port number to connect on the remote host.
Damien Miller45ee2b92006-03-15 11:56:18 +11001151The default is 22.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001152.It Cm PreferredAuthentications
jmc@openbsd.orga685ae82016-02-17 07:38:19 +00001153Specifies the order in which the client should try authentication methods.
Darren Tucker1adc2bd2005-03-14 23:14:20 +11001154This allows a client to prefer one method (e.g.\&
Ben Lindstrom9f049032002-06-21 00:59:05 +00001155.Cm keyboard-interactive )
Darren Tucker1adc2bd2005-03-14 23:14:20 +11001156over another method (e.g.\&
Damien Miller544378d2010-04-16 15:52:24 +10001157.Cm password ) .
1158The default is:
1159.Bd -literal -offset indent
1160gssapi-with-mic,hostbased,publickey,
1161keyboard-interactive,password
1162.Ed
Ben Lindstrom9f049032002-06-21 00:59:05 +00001163.It Cm ProxyCommand
1164Specifies the command to use to connect to the server.
1165The command
Damien Miller079bac22014-07-09 13:06:25 +10001166string extends to the end of the line, and is executed
1167using the user's shell
1168.Ql exec
1169directive to avoid a lingering shell process.
1170.Pp
jmc@openbsd.org80d1c962016-09-28 17:59:22 +00001171Arguments to
1172.Cm ProxyCommand
1173accept the tokens described in the
1174.Sx TOKENS
1175section.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001176The command can be basically anything,
1177and should read from its standard input and write to its standard output.
1178It should eventually connect an
1179.Xr sshd 8
1180server running on some machine, or execute
1181.Ic sshd -i
1182somewhere.
1183Host key management will be done using the
1184HostName of the host being connected (defaulting to the name typed by
1185the user).
Damien Miller495dca32003-04-01 21:42:14 +10001186Setting the command to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001187.Cm none
Damien Miller9f1e33a2003-02-24 11:57:32 +11001188disables this option entirely.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001189Note that
1190.Cm CheckHostIP
1191is not available for connects with a proxy command.
1192.Pp
Damien Millerebcfedc2005-05-26 12:13:56 +10001193This directive is useful in conjunction with
1194.Xr nc 1
1195and its proxy support.
Damien Millerdfec2942005-05-26 12:14:32 +10001196For example, the following directive would connect via an HTTP proxy at
Damien Millerebcfedc2005-05-26 12:13:56 +10001197192.0.2.0:
1198.Bd -literal -offset 3n
1199ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
1200.Ed
djm@openbsd.orged877ef2016-07-15 00:24:30 +00001201.It Cm ProxyJump
1202Specifies one or more jump proxies as
1203.Xo
1204.Sm off
jmc@openbsd.orge4eb7d92016-07-16 06:57:55 +00001205.Op Ar user No @
djm@openbsd.orged877ef2016-07-15 00:24:30 +00001206.Ar host
jmc@openbsd.orge4eb7d92016-07-16 06:57:55 +00001207.Op : Ns Ar port
djm@openbsd.orged877ef2016-07-15 00:24:30 +00001208.Sm on
1209.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.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001290.It Cm RemoteForward
Damien Millere9d001e2006-01-14 10:10:17 +11001291Specifies that a TCP port on the remote machine be forwarded over
Ben Lindstrom9f049032002-06-21 00:59:05 +00001292the secure channel to the specified host and port from the local machine.
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001293The first argument must be
Damien Millerf91ee4c2005-03-01 21:24:33 +11001294.Sm off
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001295.Oo Ar bind_address : Oc Ar port
Damien Millerf91ee4c2005-03-01 21:24:33 +11001296.Sm on
Darren Tucker5ede2ad2005-03-31 21:31:10 +10001297and the second argument must be
1298.Ar host : Ns Ar hostport .
Damien Miller7fa96602010-08-05 13:03:13 +10001299IPv6 addresses can be specified by enclosing addresses in square brackets.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001300Multiple forwardings may be specified, and additional
1301forwardings can be given on the command line.
Damien Millerde7532e2008-11-03 19:24:45 +11001302Privileged ports can be forwarded only when
1303logging in as root on the remote machine.
Damien Millere379e102009-02-14 16:34:39 +11001304.Pp
Damien Miller85c6d8a2009-02-14 16:34:21 +11001305If the
1306.Ar port
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001307argument is 0,
Damien Miller85c6d8a2009-02-14 16:34:21 +11001308the listen port will be dynamically allocated on the server and reported
1309to the client at run time.
Damien Millerf91ee4c2005-03-01 21:24:33 +11001310.Pp
1311If the
1312.Ar bind_address
1313is not specified, the default is to only bind to loopback addresses.
1314If the
1315.Ar bind_address
1316is
1317.Ql *
1318or an empty string, then the forwarding is requested to listen on all
1319interfaces.
1320Specifying a remote
1321.Ar bind_address
Damien Millerf8c55462005-03-02 12:03:05 +11001322will only succeed if the server's
1323.Cm GatewayPorts
Damien Millerf91ee4c2005-03-01 21:24:33 +11001324option is enabled (see
Damien Millerf8c55462005-03-02 12:03:05 +11001325.Xr sshd_config 5 ) .
Damien Miller21771e22011-05-15 08:45:50 +10001326.It Cm RequestTTY
1327Specifies whether to request a pseudo-tty for the session.
1328The argument may be one of:
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001329.Cm no
Damien Miller21771e22011-05-15 08:45:50 +10001330(never request a TTY),
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001331.Cm yes
Damien Miller21771e22011-05-15 08:45:50 +10001332(always request a TTY when standard input is a TTY),
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001333.Cm force
Damien Miller21771e22011-05-15 08:45:50 +10001334(always request a TTY) or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001335.Cm auto
Damien Miller21771e22011-05-15 08:45:50 +10001336(request a TTY when opening a login session).
1337This option mirrors the
1338.Fl t
1339and
1340.Fl T
1341flags for
1342.Xr ssh 1 .
djm@openbsd.org5e39a492014-12-04 02:24:32 +00001343.It Cm RevokedHostKeys
1344Specifies revoked host public keys.
1345Keys listed in this file will be refused for host authentication.
1346Note that if this file does not exist or is not readable,
1347then host authentication will be refused for all hosts.
1348Keys may be specified as a text file, listing one public key per line, or as
1349an OpenSSH Key Revocation List (KRL) as generated by
1350.Xr ssh-keygen 1 .
1351For more information on KRLs, see the KEY REVOCATION LISTS section in
1352.Xr ssh-keygen 1 .
Darren Tucker46bc0752004-05-02 22:11:30 +10001353.It Cm SendEnv
1354Specifies what variables from the local
1355.Xr environ 7
1356should be sent to the server.
Damien Miller45ee2b92006-03-15 11:56:18 +11001357The server must also support it, and the server must be configured to
Darren Tucker1e0c9bf2004-05-02 22:12:48 +10001358accept these environment variables.
dtucker@openbsd.org85b96ef2015-04-28 10:17:58 +00001359Note that the
1360.Ev TERM
jmc@openbsd.orgc1d5bcf2015-04-28 13:47:38 +00001361environment variable is always sent whenever a
dtucker@openbsd.org85b96ef2015-04-28 10:17:58 +00001362pseudo-terminal is requested as it is required by the protocol.
Darren Tucker46bc0752004-05-02 22:11:30 +10001363Refer to
1364.Cm AcceptEnv
1365in
1366.Xr sshd_config 5
1367for how to configure the server.
Damien Miller6def5512006-03-15 11:54:05 +11001368Variables are specified by name, which may contain wildcard characters.
Darren Tucker1e0c9bf2004-05-02 22:12:48 +10001369Multiple environment variables may be separated by whitespace or spread
Darren Tucker46bc0752004-05-02 22:11:30 +10001370across multiple
1371.Cm SendEnv
1372directives.
1373The default is not to send any environment variables.
Damien Millerf54a4b92006-03-15 11:54:36 +11001374.Pp
1375See
1376.Sx PATTERNS
1377for more information on patterns.
Damien Miller509b0102003-12-17 16:33:10 +11001378.It Cm ServerAliveCountMax
Damien Millerb7977702006-01-03 18:47:31 +11001379Sets the number of server alive messages (see below) which may be
Damien Miller509b0102003-12-17 16:33:10 +11001380sent without
Damien Miller45ee2b92006-03-15 11:56:18 +11001381.Xr ssh 1
Damien Miller509b0102003-12-17 16:33:10 +11001382receiving any messages back from the server.
1383If this threshold is reached while server alive messages are being sent,
Damien Miller45ee2b92006-03-15 11:56:18 +11001384ssh will disconnect from the server, terminating the session.
Damien Miller509b0102003-12-17 16:33:10 +11001385It is important to note that the use of server alive messages is very
1386different from
1387.Cm TCPKeepAlive
1388(below).
1389The server alive messages are sent through the encrypted channel
1390and therefore will not be spoofable.
1391The TCP keepalive option enabled by
1392.Cm TCPKeepAlive
1393is spoofable.
1394The server alive mechanism is valuable when the client or
1395server depend on knowing when a connection has become inactive.
1396.Pp
1397The default value is 3.
1398If, for example,
1399.Cm ServerAliveInterval
Damien Miller45ee2b92006-03-15 11:56:18 +11001400(see below) is set to 15 and
Damien Miller509b0102003-12-17 16:33:10 +11001401.Cm ServerAliveCountMax
Damien Miller45ee2b92006-03-15 11:56:18 +11001402is left at the default, if the server becomes unresponsive,
1403ssh will disconnect after approximately 45 seconds.
Damien Miller957d4e42005-12-13 19:30:45 +11001404.It Cm ServerAliveInterval
1405Sets a timeout interval in seconds after which if no data has been received
1406from the server,
Damien Miller45ee2b92006-03-15 11:56:18 +11001407.Xr ssh 1
Damien Miller957d4e42005-12-13 19:30:45 +11001408will send a message through the encrypted
1409channel to request a response from the server.
1410The default
1411is 0, indicating that these messages will not be sent to the server.
Damien Miller7acefbb2014-07-18 14:11:24 +10001412.It Cm StreamLocalBindMask
1413Sets the octal file creation mode mask
1414.Pq umask
1415used when creating a Unix-domain socket file for local or remote
1416port forwarding.
1417This option is only used for port forwarding to a Unix-domain socket file.
1418.Pp
1419The default value is 0177, which creates a Unix-domain socket file that is
1420readable and writable only by the owner.
1421Note that not all operating systems honor the file mode on Unix-domain
1422socket files.
1423.It Cm StreamLocalBindUnlink
1424Specifies whether to remove an existing Unix-domain socket file for local
1425or remote port forwarding before creating a new one.
1426If the socket file already exists and
1427.Cm StreamLocalBindUnlink
1428is not enabled,
1429.Nm ssh
1430will be unable to forward the port to the Unix-domain socket file.
1431This option is only used for port forwarding to a Unix-domain socket file.
1432.Pp
1433The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001434.Cm yes
Damien Miller7acefbb2014-07-18 14:11:24 +10001435or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001436.Cm no
1437(the default).
Ben Lindstrom9f049032002-06-21 00:59:05 +00001438.It Cm StrictHostKeyChecking
1439If this flag is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001440.Cm yes ,
Damien Miller45ee2b92006-03-15 11:56:18 +11001441.Xr ssh 1
Ben Lindstrom9f049032002-06-21 00:59:05 +00001442will never automatically add host keys to the
Damien Miller167ea5d2005-05-26 12:04:02 +10001443.Pa ~/.ssh/known_hosts
Ben Lindstrom9f049032002-06-21 00:59:05 +00001444file, and refuses to connect to hosts whose host key has changed.
1445This provides maximum protection against trojan horse attacks,
Damien Miller45ee2b92006-03-15 11:56:18 +11001446though it can be annoying when the
Ben Lindstrom9f049032002-06-21 00:59:05 +00001447.Pa /etc/ssh/ssh_known_hosts
Damien Miller45ee2b92006-03-15 11:56:18 +11001448file is poorly maintained or when connections to new hosts are
Ben Lindstrom9f049032002-06-21 00:59:05 +00001449frequently made.
1450This option forces the user to manually
1451add all new hosts.
1452If this flag is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001453.Cm no ,
Damien Miller45ee2b92006-03-15 11:56:18 +11001454ssh will automatically add new host keys to the
Ben Lindstrom9f049032002-06-21 00:59:05 +00001455user known hosts files.
1456If this flag is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001457.Cm ask
1458(the default),
Ben Lindstrom9f049032002-06-21 00:59:05 +00001459new host keys
1460will be added to the user known host files only after the user
1461has confirmed that is what they really want to do, and
Damien Miller45ee2b92006-03-15 11:56:18 +11001462ssh will refuse to connect to hosts whose host key has changed.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001463The host keys of
1464known hosts will be verified automatically in all cases.
jmc@openbsd.org47a287b2017-04-28 06:15:03 +00001465.It Cm SyslogFacility
1466Gives the facility code that is used when logging messages from
1467.Xr ssh 1 .
1468The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2,
1469LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
1470The default is USER.
Damien Miller12c150e2003-12-17 16:31:10 +11001471.It Cm TCPKeepAlive
1472Specifies whether the system should send TCP keepalive messages to the
1473other side.
1474If they are sent, death of the connection or crash of one
1475of the machines will be properly noticed.
1476However, this means that
1477connections will die if the route is down temporarily, and some people
1478find it annoying.
1479.Pp
1480The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001481.Cm yes
Damien Miller12c150e2003-12-17 16:31:10 +11001482(to send TCP keepalive messages), and the client will notice
1483if the network goes down or the remote host dies.
1484This is important in scripts, and many users want it too.
1485.Pp
1486To disable TCP keepalive messages, the value should be set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001487.Cm no .
Damien Millerd27b9472005-12-13 19:29:02 +11001488.It Cm Tunnel
Damien Miller991dba42006-07-10 20:16:27 +10001489Request
Damien Millerd27b9472005-12-13 19:29:02 +11001490.Xr tun 4
Damien Miller7746c392005-12-13 19:33:37 +11001491device forwarding between the client and the server.
Damien Millerd27b9472005-12-13 19:29:02 +11001492The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001493.Cm yes ,
1494.Cm point-to-point
Damien Miller991dba42006-07-10 20:16:27 +10001495(layer 3),
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001496.Cm ethernet
Damien Miller991dba42006-07-10 20:16:27 +10001497(layer 2),
Damien Millerd27b9472005-12-13 19:29:02 +11001498or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001499.Cm no
1500(the default).
Damien Miller991dba42006-07-10 20:16:27 +10001501Specifying
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001502.Cm yes
Damien Miller991dba42006-07-10 20:16:27 +10001503requests the default tunnel mode, which is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001504.Cm point-to-point .
Damien Millerd27b9472005-12-13 19:29:02 +11001505.It Cm TunnelDevice
Damien Miller991dba42006-07-10 20:16:27 +10001506Specifies the
Damien Millerd27b9472005-12-13 19:29:02 +11001507.Xr tun 4
Damien Miller991dba42006-07-10 20:16:27 +10001508devices to open on the client
1509.Pq Ar local_tun
1510and the server
1511.Pq Ar remote_tun .
1512.Pp
1513The argument must be
1514.Sm off
1515.Ar local_tun Op : Ar remote_tun .
1516.Sm on
1517The devices may be specified by numerical ID or the keyword
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001518.Cm any ,
Damien Miller991dba42006-07-10 20:16:27 +10001519which uses the next available tunnel device.
1520If
1521.Ar remote_tun
1522is not specified, it defaults to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001523.Cm any .
Damien Miller991dba42006-07-10 20:16:27 +10001524The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001525.Cm any:any .
djm@openbsd.org1d1092b2015-01-26 12:16:36 +00001526.It Cm UpdateHostKeys
djm@openbsd.org8d4f8722015-01-26 03:04:45 +00001527Specifies whether
1528.Xr ssh 1
1529should accept notifications of additional hostkeys from the server sent
1530after authentication has completed and add them to
1531.Cm UserKnownHostsFile .
1532The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001533.Cm yes ,
1534.Cm no
djm@openbsd.org523463a2015-02-16 22:13:32 +00001535(the default) or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001536.Cm ask .
djm@openbsd.org8d4f8722015-01-26 03:04:45 +00001537Enabling this option allows learning alternate hostkeys for a server
djm@openbsd.org1d1092b2015-01-26 12:16:36 +00001538and supports graceful key rotation by allowing a server to send replacement
1539public keys before old ones are removed.
djm@openbsd.org8d4f8722015-01-26 03:04:45 +00001540Additional hostkeys are only accepted if the key used to authenticate the
sobrado@openbsd.orge3cbb062015-09-22 08:33:23 +00001541host was already trusted or explicitly accepted by the user.
djm@openbsd.org523463a2015-02-16 22:13:32 +00001542If
1543.Cm UpdateHostKeys
1544is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001545.Cm ask ,
djm@openbsd.org523463a2015-02-16 22:13:32 +00001546then the user is asked to confirm the modifications to the known_hosts file.
djm@openbsd.org44732de2015-02-20 22:17:21 +00001547Confirmation is currently incompatible with
1548.Cm ControlPersist ,
1549and will be disabled if it is enabled.
djm@openbsd.org8d4f8722015-01-26 03:04:45 +00001550.Pp
1551Presently, only
1552.Xr sshd 8
1553from OpenSSH 6.8 and greater support the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001554.Qq hostkeys@openssh.com
djm@openbsd.org8d4f8722015-01-26 03:04:45 +00001555protocol extension used to inform the client of all the server's hostkeys.
Damien Millere8cd7412005-12-24 14:55:47 +11001556.It Cm UsePrivilegedPort
1557Specifies whether to use a privileged port for outgoing connections.
1558The argument must be
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001559.Cm yes
Damien Millere8cd7412005-12-24 14:55:47 +11001560or
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001561.Cm no
1562(the default).
Damien Millere8cd7412005-12-24 14:55:47 +11001563If set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001564.Cm yes ,
Damien Miller45ee2b92006-03-15 11:56:18 +11001565.Xr ssh 1
Damien Millere8cd7412005-12-24 14:55:47 +11001566must be setuid root.
1567Note that this option must be set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001568.Cm yes
Damien Millere8cd7412005-12-24 14:55:47 +11001569for
1570.Cm RhostsRSAAuthentication
1571with older servers.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001572.It Cm User
1573Specifies the user to log in as.
1574This can be useful when a different user name is used on different machines.
1575This saves the trouble of
1576having to remember to give the user name on the command line.
1577.It Cm UserKnownHostsFile
Damien Miller295ee632011-05-29 21:42:31 +10001578Specifies one or more files to use for the user
1579host key database, separated by whitespace.
1580The default is
1581.Pa ~/.ssh/known_hosts ,
1582.Pa ~/.ssh/known_hosts2 .
Damien Miller37876e92003-05-15 10:19:46 +10001583.It Cm VerifyHostKeyDNS
1584Specifies whether to verify the remote key using DNS and SSHFP resource
1585records.
Damien Miller150b5572003-11-17 21:19:29 +11001586If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001587.Cm yes ,
Damien Millerfe448472003-11-17 21:19:49 +11001588the client will implicitly trust keys that match a secure fingerprint
Damien Miller150b5572003-11-17 21:19:29 +11001589from DNS.
1590Insecure fingerprints will be handled as if this option was set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001591.Cm ask .
Damien Miller150b5572003-11-17 21:19:29 +11001592If this option is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001593.Cm ask ,
Damien Miller150b5572003-11-17 21:19:29 +11001594information on fingerprint match will be displayed, but the user will still
1595need to confirm new host keys according to the
1596.Cm StrictHostKeyChecking
1597option.
Damien Miller37876e92003-05-15 10:19:46 +10001598The default is
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001599.Cm no .
Damien Miller45ee2b92006-03-15 11:56:18 +11001600.Pp
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001601See also
1602.Sx VERIFYING HOST KEYS
1603in
Damien Miller45ee2b92006-03-15 11:56:18 +11001604.Xr ssh 1 .
Damien Miller10288242008-06-30 00:04:03 +10001605.It Cm VisualHostKey
1606If this flag is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001607.Cm yes ,
Damien Miller10288242008-06-30 00:04:03 +10001608an ASCII art representation of the remote host key fingerprint is
djm@openbsd.orgb79efde2014-12-21 23:12:42 +00001609printed in addition to the fingerprint string at login and
Damien Millera414cd32008-11-03 19:25:21 +11001610for unknown host keys.
Damien Miller10288242008-06-30 00:04:03 +10001611If this flag is set to
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001612.Cm no
1613(the default),
Damien Millera414cd32008-11-03 19:25:21 +11001614no fingerprint strings are printed at login and
djm@openbsd.orgb79efde2014-12-21 23:12:42 +00001615only the fingerprint string will be printed for unknown host keys.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001616.It Cm XAuthLocation
Damien Miller05913ba2002-09-04 16:51:03 +10001617Specifies the full pathname of the
Ben Lindstrom9f049032002-06-21 00:59:05 +00001618.Xr xauth 1
1619program.
1620The default is
1621.Pa /usr/X11R6/bin/xauth .
1622.El
Damien Millerb5282c22006-03-15 11:59:08 +11001623.Sh PATTERNS
1624A
1625.Em pattern
1626consists of zero or more non-whitespace characters,
1627.Sq *
1628(a wildcard that matches zero or more characters),
1629or
1630.Sq ?\&
1631(a wildcard that matches exactly one character).
1632For example, to specify a set of declarations for any host in the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001633.Qq .co.uk
Damien Millerb5282c22006-03-15 11:59:08 +11001634set of domains,
1635the following pattern could be used:
1636.Pp
1637.Dl Host *.co.uk
1638.Pp
1639The following pattern
1640would match any host in the 192.168.0.[0-9] network range:
1641.Pp
1642.Dl Host 192.168.0.?
1643.Pp
1644A
1645.Em pattern-list
1646is a comma-separated list of patterns.
1647Patterns within pattern-lists may be negated
1648by preceding them with an exclamation mark
1649.Pq Sq !\& .
1650For example,
Damien Miller51682fa2013-10-17 11:48:31 +11001651to allow a key to be used from anywhere within an organization
Damien Millerb5282c22006-03-15 11:59:08 +11001652except from the
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001653.Qq dialup
Damien Millerb5282c22006-03-15 11:59:08 +11001654pool,
1655the following entry (in authorized_keys) could be used:
1656.Pp
1657.Dl from=\&"!*.dialup.example.com,*.example.com\&"
jmc@openbsd.org80d1c962016-09-28 17:59:22 +00001658.Sh TOKENS
1659Arguments to some keywords can make use of tokens,
1660which are expanded at runtime:
1661.Pp
1662.Bl -tag -width XXXX -offset indent -compact
1663.It %%
1664A literal
1665.Sq % .
1666.It \&%C
1667Shorthand for %l%h%p%r.
1668.It %d
1669Local user's home directory.
1670.It %h
1671The remote hostname.
1672.It %i
1673The local user ID.
1674.It %L
1675The local hostname.
1676.It %l
1677The local hostname, including the domain name.
1678.It %n
1679The original remote hostname, as given on the command line.
1680.It %p
1681The remote port.
1682.It %r
1683The remote username.
1684.It %u
1685The local username.
1686.El
1687.Pp
1688.Cm Match exec
1689accepts the tokens %%, %h, %L, %l, %n, %p, %r, and %u.
1690.Pp
1691.Cm CertificateFile
1692accepts the tokens %%, %d, %h, %l, %r, and %u.
1693.Pp
1694.Cm ControlPath
1695accepts the tokens %%, %C, %h, %i, %L, %l, %n, %p, %r, and %u.
1696.Pp
1697.Cm HostName
1698accepts the tokens %% and %h.
1699.Pp
1700.Cm IdentityAgent
1701and
1702.Cm IdentityFile
1703accept the tokens %%, %d, %h, %l, %r, and %u.
1704.Pp
1705.Cm LocalCommand
1706accepts the tokens %%, %C, %d, %h, %l, %n, %p, %r, and %u.
1707.Pp
1708.Cm ProxyCommand
1709accepts the tokens %%, %h, %p, and %r.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001710.Sh FILES
1711.Bl -tag -width Ds
Damien Miller167ea5d2005-05-26 12:04:02 +10001712.It Pa ~/.ssh/config
Ben Lindstrom9f049032002-06-21 00:59:05 +00001713This is the per-user configuration file.
1714The format of this file is described above.
Damien Miller45ee2b92006-03-15 11:56:18 +11001715This file is used by the SSH client.
Damien Millerc970cb92004-04-20 20:12:53 +10001716Because of the potential for abuse, this file must have strict permissions:
1717read/write for the user, and not accessible by others.
Ben Lindstrom9f049032002-06-21 00:59:05 +00001718.It Pa /etc/ssh/ssh_config
1719Systemwide configuration file.
1720This file provides defaults for those
1721values that are not specified in the user's configuration file, and
1722for those users who do not have a configuration file.
1723This file must be world-readable.
1724.El
Damien Millerf1ce5052003-06-11 22:04:39 +10001725.Sh SEE ALSO
1726.Xr ssh 1
Ben Lindstrom9f049032002-06-21 00:59:05 +00001727.Sh AUTHORS
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001728.An -nosplit
Ben Lindstrom9f049032002-06-21 00:59:05 +00001729OpenSSH is a derivative of the original and free
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001730ssh 1.2.12 release by
1731.An Tatu Ylonen .
1732.An Aaron Campbell , Bob Beck , Markus Friedl ,
1733.An Niels Provos , Theo de Raadt
1734and
1735.An Dug Song
Ben Lindstrom9f049032002-06-21 00:59:05 +00001736removed many bugs, re-added newer features and
1737created OpenSSH.
jmc@openbsd.orgfd2a8f12016-10-15 19:56:25 +00001738.An Markus Friedl
1739contributed the support for SSH protocol versions 1.5 and 2.0.