xref: /freebsd/crypto/openssh/ssh_config.5 (revision faf139cc5dd3396181c11922bc6685c0c59b7b24)
1.\"
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.\"
36.\" $OpenBSD: ssh_config.5,v 1.228 2016/02/20 23:01:46 sobrado Exp $
37.\" $FreeBSD$
38.Dd $Mdocdate: February 20 2016 $
39.Dt SSH_CONFIG 5
40.Os
41.Sh NAME
42.Nm ssh_config
43.Nd OpenSSH SSH client configuration files
44.Sh SYNOPSIS
45.Nm ~/.ssh/config
46.Nm /etc/ssh/ssh_config
47.Sh DESCRIPTION
48.Xr ssh 1
49obtains configuration data from the following sources in
50the following order:
51.Pp
52.Bl -enum -offset indent -compact
53.It
54command-line options
55.It
56user's configuration file
57.Pq Pa ~/.ssh/config
58.It
59system-wide configuration file
60.Pq Pa /etc/ssh/ssh_config
61.El
62.Pp
63For each parameter, the first obtained value
64will be used.
65The configuration files contain sections separated by
66.Dq Host
67specifications, and that section is only applied for hosts that
68match one of the patterns given in the specification.
69The matched host name is usually the one given on the command line
70(see the
71.Cm CanonicalizeHostname
72option for exceptions.)
73.Pp
74Since the first obtained value for each parameter is used, more
75host-specific declarations should be given near the beginning of the
76file, and general defaults at the end.
77.Pp
78The configuration file has the following format:
79.Pp
80Empty lines and lines starting with
81.Ql #
82are comments.
83Otherwise a line is of the format
84.Dq keyword arguments .
85Configuration options may be separated by whitespace or
86optional whitespace and exactly one
87.Ql = ;
88the latter format is useful to avoid the need to quote whitespace
89when specifying configuration options using the
90.Nm ssh ,
91.Nm scp ,
92and
93.Nm sftp
94.Fl o
95option.
96Arguments may optionally be enclosed in double quotes
97.Pq \&"
98in order to represent arguments containing spaces.
99.Pp
100The possible
101keywords and their meanings are as follows (note that
102keywords are case-insensitive and arguments are case-sensitive):
103.Bl -tag -width Ds
104.It Cm Host
105Restricts the following declarations (up to the next
106.Cm Host
107or
108.Cm Match
109keyword) to be only for those hosts that match one of the patterns
110given after the keyword.
111If more than one pattern is provided, they should be separated by whitespace.
112A single
113.Ql *
114as a pattern can be used to provide global
115defaults for all hosts.
116The host is usually the
117.Ar hostname
118argument given on the command line
119(see the
120.Cm CanonicalizeHostname
121option for exceptions.)
122.Pp
123A pattern entry may be negated by prefixing it with an exclamation mark
124.Pq Sq !\& .
125If a negated entry is matched, then the
126.Cm Host
127entry is ignored, regardless of whether any other patterns on the line
128match.
129Negated matches are therefore useful to provide exceptions for wildcard
130matches.
131.Pp
132See
133.Sx PATTERNS
134for more information on patterns.
135.It Cm Match
136Restricts the following declarations (up to the next
137.Cm Host
138or
139.Cm Match
140keyword) to be used only when the conditions following the
141.Cm Match
142keyword are satisfied.
143Match conditions are specified using one or more criteria
144or the single token
145.Cm all
146which always matches.
147The available criteria keywords are:
148.Cm canonical ,
149.Cm exec ,
150.Cm host ,
151.Cm originalhost ,
152.Cm user ,
153and
154.Cm localuser .
155The
156.Cm all
157criteria must appear alone or immediately after
158.Cm canonical .
159Other criteria may be combined arbitrarily.
160All criteria but
161.Cm all
162and
163.Cm canonical
164require an argument.
165Criteria may be negated by prepending an exclamation mark
166.Pq Sq !\& .
167.Pp
168The
169.Cm canonical
170keyword matches only when the configuration file is being re-parsed
171after hostname canonicalization (see the
172.Cm CanonicalizeHostname
173option.)
174This may be useful to specify conditions that work with canonical host
175names only.
176The
177.Cm exec
178keyword executes the specified command under the user's shell.
179If the command returns a zero exit status then the condition is considered true.
180Commands containing whitespace characters must be quoted.
181The following character sequences in the command will be expanded prior to
182execution:
183.Ql %L
184will be substituted by the first component of the local host name,
185.Ql %l
186will be substituted by the local host name (including any domain name),
187.Ql %h
188will be substituted by the target host name,
189.Ql %n
190will be substituted by the original target host name
191specified on the command-line,
192.Ql %p
193the destination port,
194.Ql %r
195by the remote login username, and
196.Ql %u
197by the username of the user running
198.Xr ssh 1 .
199.Pp
200The other keywords' criteria must be single entries or comma-separated
201lists and may use the wildcard and negation operators described in the
202.Sx PATTERNS
203section.
204The criteria for the
205.Cm host
206keyword are matched against the target hostname, after any substitution
207by the
208.Cm Hostname
209or
210.Cm CanonicalizeHostname
211options.
212The
213.Cm originalhost
214keyword matches against the hostname as it was specified on the command-line.
215The
216.Cm user
217keyword matches against the target username on the remote host.
218The
219.Cm localuser
220keyword matches against the name of the local user running
221.Xr ssh 1
222(this keyword may be useful in system-wide
223.Nm
224files).
225.It Cm AddKeysToAgent
226Specifies whether keys should be automatically added to a running
227.Xr ssh-agent 1 .
228If this option is set to
229.Dq yes
230and a key is loaded from a file, the key and its passphrase are added to
231the agent with the default lifetime, as if by
232.Xr ssh-add 1 .
233If this option is set to
234.Dq ask ,
235.Nm ssh
236will require confirmation using the
237.Ev SSH_ASKPASS
238program before adding a key (see
239.Xr ssh-add 1
240for details).
241If this option is set to
242.Dq confirm ,
243each use of the key must be confirmed, as if the
244.Fl c
245option was specified to
246.Xr ssh-add 1 .
247If this option is set to
248.Dq no ,
249no keys are added to the agent.
250The argument must be
251.Dq yes ,
252.Dq confirm ,
253.Dq ask ,
254or
255.Dq no .
256The default is
257.Dq no .
258.It Cm AddressFamily
259Specifies which address family to use when connecting.
260Valid arguments are
261.Dq any ,
262.Dq inet
263(use IPv4 only), or
264.Dq inet6
265(use IPv6 only).
266The default is
267.Dq any .
268.It Cm BatchMode
269If set to
270.Dq yes ,
271passphrase/password querying will be disabled.
272This option is useful in scripts and other batch jobs where no user
273is present to supply the password.
274The argument must be
275.Dq yes
276or
277.Dq no .
278The default is
279.Dq no .
280.It Cm BindAddress
281Use the specified address on the local machine as the source address of
282the connection.
283Only useful on systems with more than one address.
284Note that this option does not work if
285.Cm UsePrivilegedPort
286is set to
287.Dq yes .
288.It Cm CanonicalDomains
289When
290.Cm CanonicalizeHostname
291is enabled, this option specifies the list of domain suffixes in which to
292search for the specified destination host.
293.It Cm CanonicalizeFallbackLocal
294Specifies whether to fail with an error when hostname canonicalization fails.
295The default,
296.Dq yes ,
297will attempt to look up the unqualified hostname using the system resolver's
298search rules.
299A value of
300.Dq no
301will cause
302.Xr ssh 1
303to fail instantly if
304.Cm CanonicalizeHostname
305is enabled and the target hostname cannot be found in any of the domains
306specified by
307.Cm CanonicalDomains .
308.It Cm CanonicalizeHostname
309Controls whether explicit hostname canonicalization is performed.
310The default,
311.Dq no ,
312is not to perform any name rewriting and let the system resolver handle all
313hostname lookups.
314If set to
315.Dq yes
316then, for connections that do not use a
317.Cm ProxyCommand ,
318.Xr ssh 1
319will attempt to canonicalize the hostname specified on the command line
320using the
321.Cm CanonicalDomains
322suffixes and
323.Cm CanonicalizePermittedCNAMEs
324rules.
325If
326.Cm CanonicalizeHostname
327is set to
328.Dq always ,
329then canonicalization is applied to proxied connections too.
330.Pp
331If this option is enabled, then the configuration files are processed
332again using the new target name to pick up any new configuration in matching
333.Cm Host
334and
335.Cm Match
336stanzas.
337.It Cm CanonicalizeMaxDots
338Specifies the maximum number of dot characters in a hostname before
339canonicalization is disabled.
340The default,
341.Dq 1 ,
342allows a single dot (i.e. hostname.subdomain).
343.It Cm CanonicalizePermittedCNAMEs
344Specifies rules to determine whether CNAMEs should be followed when
345canonicalizing hostnames.
346The rules consist of one or more arguments of
347.Ar source_domain_list : Ns Ar target_domain_list ,
348where
349.Ar source_domain_list
350is a pattern-list of domains that may follow CNAMEs in canonicalization,
351and
352.Ar target_domain_list
353is a pattern-list of domains that they may resolve to.
354.Pp
355For example,
356.Dq *.a.example.com:*.b.example.com,*.c.example.com
357will allow hostnames matching
358.Dq *.a.example.com
359to be canonicalized to names in the
360.Dq *.b.example.com
361or
362.Dq *.c.example.com
363domains.
364.It Cm CertificateFile
365Specifies a file from which the user's certificate is read.
366A corresponding private key must be provided separately in order
367to use this certificate either
368from an
369.Cm IdentityFile
370directive or
371.Fl i
372flag to
373.Xr ssh 1 ,
374via
375.Xr ssh-agent 1 ,
376or via a
377.Cm PKCS11Provider .
378.Pp
379The file name may use the tilde
380syntax to refer to a user's home directory or one of the following
381escape characters:
382.Ql %d
383(local user's home directory),
384.Ql %u
385(local user name),
386.Ql %l
387(local host name),
388.Ql %h
389(remote host name) or
390.Ql %r
391(remote user name).
392.Pp
393It is possible to have multiple certificate files specified in
394configuration files; these certificates will be tried in sequence.
395Multiple
396.Cm CertificateFile
397directives will add to the list of certificates used for
398authentication.
399.It Cm ChallengeResponseAuthentication
400Specifies whether to use challenge-response authentication.
401The argument to this keyword must be
402.Dq yes
403or
404.Dq no .
405The default is
406.Dq yes .
407.It Cm CheckHostIP
408If this flag is set to
409.Dq yes ,
410.Xr ssh 1
411will additionally check the host IP address in the
412.Pa known_hosts
413file.
414This allows ssh to detect if a host key changed due to DNS spoofing
415and will add addresses of destination hosts to
416.Pa ~/.ssh/known_hosts
417in the process, regardless of the setting of
418.Cm StrictHostKeyChecking .
419If the option is set to
420.Dq no ,
421the check will not be executed.
422The default is
423.Dq no .
424.It Cm Cipher
425Specifies the cipher to use for encrypting the session
426in protocol version 1.
427Currently,
428.Dq blowfish ,
429.Dq 3des ,
430and
431.Dq des
432are supported.
433.Ar des
434is only supported in the
435.Xr ssh 1
436client for interoperability with legacy protocol 1 implementations
437that do not support the
438.Ar 3des
439cipher.
440Its use is strongly discouraged due to cryptographic weaknesses.
441The default is
442.Dq 3des .
443.It Cm Ciphers
444Specifies the ciphers allowed for protocol version 2
445in order of preference.
446Multiple ciphers must be comma-separated.
447If the specified value begins with a
448.Sq +
449character, then the specified ciphers will be appended to the default set
450instead of replacing them.
451.Pp
452The supported ciphers are:
453.Pp
454.Bl -item -compact -offset indent
455.It
4563des-cbc
457.It
458aes128-cbc
459.It
460aes192-cbc
461.It
462aes256-cbc
463.It
464aes128-ctr
465.It
466aes192-ctr
467.It
468aes256-ctr
469.It
470aes128-gcm@openssh.com
471.It
472aes256-gcm@openssh.com
473.It
474arcfour
475.It
476arcfour128
477.It
478arcfour256
479.It
480blowfish-cbc
481.It
482cast128-cbc
483.It
484chacha20-poly1305@openssh.com
485.El
486.Pp
487The default is:
488.Bd -literal -offset indent
489chacha20-poly1305@openssh.com,
490aes128-ctr,aes192-ctr,aes256-ctr,
491aes128-gcm@openssh.com,aes256-gcm@openssh.com,
492aes128-cbc,aes192-cbc,aes256-cbc,3des-cbc
493.Ed
494.Pp
495The list of available ciphers may also be obtained using the
496.Fl Q
497option of
498.Xr ssh 1
499with an argument of
500.Dq cipher .
501.It Cm ClearAllForwardings
502Specifies that all local, remote, and dynamic port forwardings
503specified in the configuration files or on the command line be
504cleared.
505This option is primarily useful when used from the
506.Xr ssh 1
507command line to clear port forwardings set in
508configuration files, and is automatically set by
509.Xr scp 1
510and
511.Xr sftp 1 .
512The argument must be
513.Dq yes
514or
515.Dq no .
516The default is
517.Dq no .
518.It Cm Compression
519Specifies whether to use compression.
520The argument must be
521.Dq yes
522or
523.Dq no .
524The default is
525.Dq no .
526.It Cm CompressionLevel
527Specifies the compression level to use if compression is enabled.
528The argument must be an integer from 1 (fast) to 9 (slow, best).
529The default level is 6, which is good for most applications.
530The meaning of the values is the same as in
531.Xr gzip 1 .
532Note that this option applies to protocol version 1 only.
533.It Cm ConnectionAttempts
534Specifies the number of tries (one per second) to make before exiting.
535The argument must be an integer.
536This may be useful in scripts if the connection sometimes fails.
537The default is 1.
538.It Cm ConnectTimeout
539Specifies the timeout (in seconds) used when connecting to the
540SSH server, instead of using the default system TCP timeout.
541This value is used only when the target is down or really unreachable,
542not when it refuses the connection.
543.It Cm ControlMaster
544Enables the sharing of multiple sessions over a single network connection.
545When set to
546.Dq yes ,
547.Xr ssh 1
548will listen for connections on a control socket specified using the
549.Cm ControlPath
550argument.
551Additional sessions can connect to this socket using the same
552.Cm ControlPath
553with
554.Cm ControlMaster
555set to
556.Dq no
557(the default).
558These sessions will try to reuse the master instance's network connection
559rather than initiating new ones, but will fall back to connecting normally
560if the control socket does not exist, or is not listening.
561.Pp
562Setting this to
563.Dq ask
564will cause ssh
565to listen for control connections, but require confirmation using
566.Xr ssh-askpass 1 .
567If the
568.Cm ControlPath
569cannot be opened,
570ssh will continue without connecting to a master instance.
571.Pp
572X11 and
573.Xr ssh-agent 1
574forwarding is supported over these multiplexed connections, however the
575display and agent forwarded will be the one belonging to the master
576connection i.e. it is not possible to forward multiple displays or agents.
577.Pp
578Two additional options allow for opportunistic multiplexing: try to use a
579master connection but fall back to creating a new one if one does not already
580exist.
581These options are:
582.Dq auto
583and
584.Dq autoask .
585The latter requires confirmation like the
586.Dq ask
587option.
588.It Cm ControlPath
589Specify the path to the control socket used for connection sharing as described
590in the
591.Cm ControlMaster
592section above or the string
593.Dq none
594to disable connection sharing.
595In the path,
596.Ql %L
597will be substituted by the first component of the local host name,
598.Ql %l
599will be substituted by the local host name (including any domain name),
600.Ql %h
601will be substituted by the target host name,
602.Ql %n
603will be substituted by the original target host name
604specified on the command line,
605.Ql %p
606the destination port,
607.Ql %r
608by the remote login username,
609.Ql %u
610by the username and
611.Ql %i
612by the numeric user ID (uid) of the user running
613.Xr ssh 1 ,
614and
615.Ql \&%C
616by a hash of the concatenation: %l%h%p%r.
617It is recommended that any
618.Cm ControlPath
619used for opportunistic connection sharing include
620at least %h, %p, and %r (or alternatively %C) and be placed in a directory
621that is not writable by other users.
622This ensures that shared connections are uniquely identified.
623.It Cm ControlPersist
624When used in conjunction with
625.Cm ControlMaster ,
626specifies that the master connection should remain open
627in the background (waiting for future client connections)
628after the initial client connection has been closed.
629If set to
630.Dq no ,
631then the master connection will not be placed into the background,
632and will close as soon as the initial client connection is closed.
633If set to
634.Dq yes
635or
636.Dq 0 ,
637then the master connection will remain in the background indefinitely
638(until killed or closed via a mechanism such as the
639.Xr ssh 1
640.Dq Fl O No exit
641option).
642If set to a time in seconds, or a time in any of the formats documented in
643.Xr sshd_config 5 ,
644then the backgrounded master connection will automatically terminate
645after it has remained idle (with no client connections) for the
646specified time.
647.It Cm DynamicForward
648Specifies that a TCP port on the local machine be forwarded
649over the secure channel, and the application
650protocol is then used to determine where to connect to from the
651remote machine.
652.Pp
653The argument must be
654.Sm off
655.Oo Ar bind_address : Oc Ar port .
656.Sm on
657IPv6 addresses can be specified by enclosing addresses in square brackets.
658By default, the local port is bound in accordance with the
659.Cm GatewayPorts
660setting.
661However, an explicit
662.Ar bind_address
663may be used to bind the connection to a specific address.
664The
665.Ar bind_address
666of
667.Dq localhost
668indicates that the listening port be bound for local use only, while an
669empty address or
670.Sq *
671indicates that the port should be available from all interfaces.
672.Pp
673Currently the SOCKS4 and SOCKS5 protocols are supported, and
674.Xr ssh 1
675will act as a SOCKS server.
676Multiple forwardings may be specified, and
677additional forwardings can be given on the command line.
678Only the superuser can forward privileged ports.
679.It Cm EnableSSHKeysign
680Setting this option to
681.Dq yes
682in the global client configuration file
683.Pa /etc/ssh/ssh_config
684enables the use of the helper program
685.Xr ssh-keysign 8
686during
687.Cm HostbasedAuthentication .
688The argument must be
689.Dq yes
690or
691.Dq no .
692The default is
693.Dq no .
694This option should be placed in the non-hostspecific section.
695See
696.Xr ssh-keysign 8
697for more information.
698.It Cm EscapeChar
699Sets the escape character (default:
700.Ql ~ ) .
701The escape character can also
702be set on the command line.
703The argument should be a single character,
704.Ql ^
705followed by a letter, or
706.Dq none
707to disable the escape
708character entirely (making the connection transparent for binary
709data).
710.It Cm ExitOnForwardFailure
711Specifies whether
712.Xr ssh 1
713should terminate the connection if it cannot set up all requested
714dynamic, tunnel, local, and remote port forwardings, (e.g.\&
715if either end is unable to bind and listen on a specified port).
716Note that
717.Cm ExitOnForwardFailure
718does not apply to connections made over port forwardings and will not,
719for example, cause
720.Xr ssh 1
721to exit if TCP connections to the ultimate forwarding destination fail.
722The argument must be
723.Dq yes
724or
725.Dq no .
726The default is
727.Dq no .
728.It Cm FingerprintHash
729Specifies the hash algorithm used when displaying key fingerprints.
730Valid options are:
731.Dq md5
732and
733.Dq sha256 .
734The default is
735.Dq sha256 .
736.It Cm ForwardAgent
737Specifies whether the connection to the authentication agent (if any)
738will be forwarded to the remote machine.
739The argument must be
740.Dq yes
741or
742.Dq no .
743The default is
744.Dq no .
745.Pp
746Agent forwarding should be enabled with caution.
747Users with the ability to bypass file permissions on the remote host
748(for the agent's Unix-domain socket)
749can access the local agent through the forwarded connection.
750An attacker cannot obtain key material from the agent,
751however they can perform operations on the keys that enable them to
752authenticate using the identities loaded into the agent.
753.It Cm ForwardX11
754Specifies whether X11 connections will be automatically redirected
755over the secure channel and
756.Ev DISPLAY
757set.
758The argument must be
759.Dq yes
760or
761.Dq no .
762The default is
763.Dq no .
764.Pp
765X11 forwarding should be enabled with caution.
766Users with the ability to bypass file permissions on the remote host
767(for the user's X11 authorization database)
768can access the local X11 display through the forwarded connection.
769An attacker may then be able to perform activities such as keystroke monitoring
770if the
771.Cm ForwardX11Trusted
772option is also enabled.
773.It Cm ForwardX11Timeout
774Specify a timeout for untrusted X11 forwarding
775using the format described in the
776TIME FORMATS section of
777.Xr sshd_config 5 .
778X11 connections received by
779.Xr ssh 1
780after this time will be refused.
781The default is to disable untrusted X11 forwarding after twenty minutes has
782elapsed.
783.It Cm ForwardX11Trusted
784If this option is set to
785.Dq yes ,
786remote X11 clients will have full access to the original X11 display.
787.Pp
788If this option is set to
789.Dq no ,
790remote X11 clients will be considered untrusted and prevented
791from stealing or tampering with data belonging to trusted X11
792clients.
793Furthermore, the
794.Xr xauth 1
795token used for the session will be set to expire after 20 minutes.
796Remote clients will be refused access after this time.
797.Pp
798The default is
799.Dq no .
800.Pp
801See the X11 SECURITY extension specification for full details on
802the restrictions imposed on untrusted clients.
803.It Cm GatewayPorts
804Specifies whether remote hosts are allowed to connect to local
805forwarded ports.
806By default,
807.Xr ssh 1
808binds local port forwardings to the loopback address.
809This prevents other remote hosts from connecting to forwarded ports.
810.Cm GatewayPorts
811can be used to specify that ssh
812should bind local port forwardings to the wildcard address,
813thus allowing remote hosts to connect to forwarded ports.
814The argument must be
815.Dq yes
816or
817.Dq no .
818The default is
819.Dq no .
820.It Cm GlobalKnownHostsFile
821Specifies one or more files to use for the global
822host key database, separated by whitespace.
823The default is
824.Pa /etc/ssh/ssh_known_hosts ,
825.Pa /etc/ssh/ssh_known_hosts2 .
826.It Cm GSSAPIAuthentication
827Specifies whether user authentication based on GSSAPI is allowed.
828The default is
829.Dq no .
830.It Cm GSSAPIDelegateCredentials
831Forward (delegate) credentials to the server.
832The default is
833.Dq no .
834.It Cm HashKnownHosts
835Indicates that
836.Xr ssh 1
837should hash host names and addresses when they are added to
838.Pa ~/.ssh/known_hosts .
839These hashed names may be used normally by
840.Xr ssh 1
841and
842.Xr sshd 8 ,
843but they do not reveal identifying information should the file's contents
844be disclosed.
845The default is
846.Dq no .
847Note that existing names and addresses in known hosts files
848will not be converted automatically,
849but may be manually hashed using
850.Xr ssh-keygen 1 .
851.It Cm HostbasedAuthentication
852Specifies whether to try rhosts based authentication with public key
853authentication.
854The argument must be
855.Dq yes
856or
857.Dq no .
858The default is
859.Dq no .
860.It Cm HostbasedKeyTypes
861Specifies the key types that will be used for hostbased authentication
862as a comma-separated pattern list.
863Alternately if the specified value begins with a
864.Sq +
865character, then the specified key types will be appended to the default set
866instead of replacing them.
867The default for this option is:
868.Bd -literal -offset 3n
869ecdsa-sha2-nistp256-cert-v01@openssh.com,
870ecdsa-sha2-nistp384-cert-v01@openssh.com,
871ecdsa-sha2-nistp521-cert-v01@openssh.com,
872ssh-ed25519-cert-v01@openssh.com,
873ssh-rsa-cert-v01@openssh.com,
874ssh-dss-cert-v01@openssh.com,
875ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,
876ecdsa-sha2-nistp521,ssh-ed25519,
877ssh-rsa,ssh-dss
878.Ed
879.Pp
880The
881.Fl Q
882option of
883.Xr ssh 1
884may be used to list supported key types.
885.It Cm HostKeyAlgorithms
886Specifies the host key algorithms
887that the client wants to use in order of preference.
888Alternately if the specified value begins with a
889.Sq +
890character, then the specified key types will be appended to the default set
891instead of replacing them.
892The default for this option is:
893.Bd -literal -offset 3n
894ecdsa-sha2-nistp256-cert-v01@openssh.com,
895ecdsa-sha2-nistp384-cert-v01@openssh.com,
896ecdsa-sha2-nistp521-cert-v01@openssh.com,
897ssh-ed25519-cert-v01@openssh.com,
898ssh-rsa-cert-v01@openssh.com,
899ssh-dss-cert-v01@openssh.com,
900ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,
901ecdsa-sha2-nistp521,ssh-ed25519,
902ssh-rsa,ssh-dss
903.Ed
904.Pp
905If hostkeys are known for the destination host then this default is modified
906to prefer their algorithms.
907.Pp
908The list of available key types may also be obtained using the
909.Fl Q
910option of
911.Xr ssh 1
912with an argument of
913.Dq key .
914.It Cm HostKeyAlias
915Specifies an alias that should be used instead of the
916real host name when looking up or saving the host key
917in the host key database files.
918This option is useful for tunneling SSH connections
919or for multiple servers running on a single host.
920.It Cm HostName
921Specifies the real host name to log into.
922This can be used to specify nicknames or abbreviations for hosts.
923If the hostname contains the character sequence
924.Ql %h ,
925then this will be replaced with the host name specified on the command line
926(this is useful for manipulating unqualified names).
927The character sequence
928.Ql %%
929will be replaced by a single
930.Ql %
931character, which may be used when specifying IPv6 link-local addresses.
932.Pp
933The default is the name given on the command line.
934Numeric IP addresses are also permitted (both on the command line and in
935.Cm HostName
936specifications).
937.It Cm IdentitiesOnly
938Specifies that
939.Xr ssh 1
940should only use the authentication identity and certificate files explicitly
941configured in the
942.Nm
943files
944or passed on the
945.Xr ssh 1
946command-line,
947even if
948.Xr ssh-agent 1
949or a
950.Cm PKCS11Provider
951offers more identities.
952The argument to this keyword must be
953.Dq yes
954or
955.Dq no .
956This option is intended for situations where ssh-agent
957offers many different identities.
958The default is
959.Dq no .
960.It Cm IdentityFile
961Specifies a file from which the user's DSA, ECDSA, Ed25519 or RSA authentication
962identity is read.
963The default is
964.Pa ~/.ssh/identity
965for protocol version 1, and
966.Pa ~/.ssh/id_dsa ,
967.Pa ~/.ssh/id_ecdsa ,
968.Pa ~/.ssh/id_ed25519
969and
970.Pa ~/.ssh/id_rsa
971for protocol version 2.
972Additionally, any identities represented by the authentication agent
973will be used for authentication unless
974.Cm IdentitiesOnly
975is set.
976If no certificates have been explicitly specified by
977.Cm CertificateFile ,
978.Xr ssh 1
979will try to load certificate information from the filename obtained by
980appending
981.Pa -cert.pub
982to the path of a specified
983.Cm IdentityFile .
984.Pp
985The file name may use the tilde
986syntax to refer to a user's home directory or one of the following
987escape characters:
988.Ql %d
989(local user's home directory),
990.Ql %u
991(local user name),
992.Ql %l
993(local host name),
994.Ql %h
995(remote host name) or
996.Ql %r
997(remote user name).
998.Pp
999It is possible to have
1000multiple identity files specified in configuration files; all these
1001identities will be tried in sequence.
1002Multiple
1003.Cm IdentityFile
1004directives will add to the list of identities tried (this behaviour
1005differs from that of other configuration directives).
1006.Pp
1007.Cm IdentityFile
1008may be used in conjunction with
1009.Cm IdentitiesOnly
1010to select which identities in an agent are offered during authentication.
1011.Cm IdentityFile
1012may also be used in conjunction with
1013.Cm CertificateFile
1014in order to provide any certificate also needed for authentication with
1015the identity.
1016.It Cm IgnoreUnknown
1017Specifies a pattern-list of unknown options to be ignored if they are
1018encountered in configuration parsing.
1019This may be used to suppress errors if
1020.Nm
1021contains options that are unrecognised by
1022.Xr ssh 1 .
1023It is recommended that
1024.Cm IgnoreUnknown
1025be listed early in the configuration file as it will not be applied
1026to unknown options that appear before it.
1027.It Cm IPQoS
1028Specifies the IPv4 type-of-service or DSCP class for connections.
1029Accepted values are
1030.Dq af11 ,
1031.Dq af12 ,
1032.Dq af13 ,
1033.Dq af21 ,
1034.Dq af22 ,
1035.Dq af23 ,
1036.Dq af31 ,
1037.Dq af32 ,
1038.Dq af33 ,
1039.Dq af41 ,
1040.Dq af42 ,
1041.Dq af43 ,
1042.Dq cs0 ,
1043.Dq cs1 ,
1044.Dq cs2 ,
1045.Dq cs3 ,
1046.Dq cs4 ,
1047.Dq cs5 ,
1048.Dq cs6 ,
1049.Dq cs7 ,
1050.Dq ef ,
1051.Dq lowdelay ,
1052.Dq throughput ,
1053.Dq reliability ,
1054or a numeric value.
1055This option may take one or two arguments, separated by whitespace.
1056If one argument is specified, it is used as the packet class unconditionally.
1057If two values are specified, the first is automatically selected for
1058interactive sessions and the second for non-interactive sessions.
1059The default is
1060.Dq lowdelay
1061for interactive sessions and
1062.Dq throughput
1063for non-interactive sessions.
1064.It Cm KbdInteractiveAuthentication
1065Specifies whether to use keyboard-interactive authentication.
1066The argument to this keyword must be
1067.Dq yes
1068or
1069.Dq no .
1070The default is
1071.Dq yes .
1072.It Cm KbdInteractiveDevices
1073Specifies the list of methods to use in keyboard-interactive authentication.
1074Multiple method names must be comma-separated.
1075The default is to use the server specified list.
1076The methods available vary depending on what the server supports.
1077For an OpenSSH server,
1078it may be zero or more of:
1079.Dq bsdauth ,
1080.Dq pam ,
1081and
1082.Dq skey .
1083.It Cm KexAlgorithms
1084Specifies the available KEX (Key Exchange) algorithms.
1085Multiple algorithms must be comma-separated.
1086Alternately if the specified value begins with a
1087.Sq +
1088character, then the specified methods will be appended to the default set
1089instead of replacing them.
1090The default is:
1091.Bd -literal -offset indent
1092curve25519-sha256@libssh.org,
1093ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,
1094diffie-hellman-group-exchange-sha256,
1095diffie-hellman-group-exchange-sha1,
1096diffie-hellman-group14-sha1
1097.Ed
1098.Pp
1099The list of available key exchange algorithms may also be obtained using the
1100.Fl Q
1101option of
1102.Xr ssh 1
1103with an argument of
1104.Dq kex .
1105.It Cm LocalCommand
1106Specifies a command to execute on the local machine after successfully
1107connecting to the server.
1108The command string extends to the end of the line, and is executed with
1109the user's shell.
1110The following escape character substitutions will be performed:
1111.Ql %d
1112(local user's home directory),
1113.Ql %h
1114(remote host name),
1115.Ql %l
1116(local host name),
1117.Ql %n
1118(host name as provided on the command line),
1119.Ql %p
1120(remote port),
1121.Ql %r
1122(remote user name) or
1123.Ql %u
1124(local user name) or
1125.Ql \&%C
1126by a hash of the concatenation: %l%h%p%r.
1127.Pp
1128The command is run synchronously and does not have access to the
1129session of the
1130.Xr ssh 1
1131that spawned it.
1132It should not be used for interactive commands.
1133.Pp
1134This directive is ignored unless
1135.Cm PermitLocalCommand
1136has been enabled.
1137.It Cm LocalForward
1138Specifies that a TCP port on the local machine be forwarded over
1139the secure channel to the specified host and port from the remote machine.
1140The first argument must be
1141.Sm off
1142.Oo Ar bind_address : Oc Ar port
1143.Sm on
1144and the second argument must be
1145.Ar host : Ns Ar hostport .
1146IPv6 addresses can be specified by enclosing addresses in square brackets.
1147Multiple forwardings may be specified, and additional forwardings can be
1148given on the command line.
1149Only the superuser can forward privileged ports.
1150By default, the local port is bound in accordance with the
1151.Cm GatewayPorts
1152setting.
1153However, an explicit
1154.Ar bind_address
1155may be used to bind the connection to a specific address.
1156The
1157.Ar bind_address
1158of
1159.Dq localhost
1160indicates that the listening port be bound for local use only, while an
1161empty address or
1162.Sq *
1163indicates that the port should be available from all interfaces.
1164.It Cm LogLevel
1165Gives the verbosity level that is used when logging messages from
1166.Xr ssh 1 .
1167The possible values are:
1168QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.
1169The default is INFO.
1170DEBUG and DEBUG1 are equivalent.
1171DEBUG2 and DEBUG3 each specify higher levels of verbose output.
1172.It Cm MACs
1173Specifies the MAC (message authentication code) algorithms
1174in order of preference.
1175The MAC algorithm is used for data integrity protection.
1176Multiple algorithms must be comma-separated.
1177If the specified value begins with a
1178.Sq +
1179character, then the specified algorithms will be appended to the default set
1180instead of replacing them.
1181.Pp
1182The algorithms that contain
1183.Dq -etm
1184calculate the MAC after encryption (encrypt-then-mac).
1185These are considered safer and their use recommended.
1186.Pp
1187The default is:
1188.Bd -literal -offset indent
1189umac-64-etm@openssh.com,umac-128-etm@openssh.com,
1190hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,
1191hmac-sha1-etm@openssh.com,
1192umac-64@openssh.com,umac-128@openssh.com,
1193hmac-sha2-256,hmac-sha2-512,hmac-sha1
1194.Ed
1195.Pp
1196The list of available MAC algorithms may also be obtained using the
1197.Fl Q
1198option of
1199.Xr ssh 1
1200with an argument of
1201.Dq mac .
1202.It Cm NoHostAuthenticationForLocalhost
1203This option can be used if the home directory is shared across machines.
1204In this case localhost will refer to a different machine on each of
1205the machines and the user will get many warnings about changed host keys.
1206However, this option disables host authentication for localhost.
1207The argument to this keyword must be
1208.Dq yes
1209or
1210.Dq no .
1211The default is to check the host key for localhost.
1212.It Cm NumberOfPasswordPrompts
1213Specifies the number of password prompts before giving up.
1214The argument to this keyword must be an integer.
1215The default is 3.
1216.It Cm PasswordAuthentication
1217Specifies whether to use password authentication.
1218The argument to this keyword must be
1219.Dq yes
1220or
1221.Dq no .
1222The default is
1223.Dq yes .
1224.It Cm PermitLocalCommand
1225Allow local command execution via the
1226.Ic LocalCommand
1227option or using the
1228.Ic !\& Ns Ar command
1229escape sequence in
1230.Xr ssh 1 .
1231The argument must be
1232.Dq yes
1233or
1234.Dq no .
1235The default is
1236.Dq no .
1237.It Cm PKCS11Provider
1238Specifies which PKCS#11 provider to use.
1239The argument to this keyword is the PKCS#11 shared library
1240.Xr ssh 1
1241should use to communicate with a PKCS#11 token providing the user's
1242private RSA key.
1243.It Cm Port
1244Specifies the port number to connect on the remote host.
1245The default is 22.
1246.It Cm PreferredAuthentications
1247Specifies the order in which the client should try authentication methods.
1248This allows a client to prefer one method (e.g.\&
1249.Cm keyboard-interactive )
1250over another method (e.g.\&
1251.Cm password ) .
1252The default is:
1253.Bd -literal -offset indent
1254gssapi-with-mic,hostbased,publickey,
1255keyboard-interactive,password
1256.Ed
1257.It Cm Protocol
1258Specifies the protocol versions
1259.Xr ssh 1
1260should support in order of preference.
1261The possible values are
1262.Sq 1
1263and
1264.Sq 2 .
1265Multiple versions must be comma-separated.
1266When this option is set to
1267.Dq 2,1
1268.Nm ssh
1269will try version 2 and fall back to version 1
1270if version 2 is not available.
1271The default is
1272.Sq 2 .
1273Protocol 1 suffers from a number of cryptographic weaknesses and should
1274not be used.
1275It is only offered to support legacy devices.
1276.It Cm ProxyCommand
1277Specifies the command to use to connect to the server.
1278The command
1279string extends to the end of the line, and is executed
1280using the user's shell
1281.Ql exec
1282directive to avoid a lingering shell process.
1283.Pp
1284In the command string, any occurrence of
1285.Ql %h
1286will be substituted by the host name to
1287connect,
1288.Ql %p
1289by the port, and
1290.Ql %r
1291by the remote user name.
1292The command can be basically anything,
1293and should read from its standard input and write to its standard output.
1294It should eventually connect an
1295.Xr sshd 8
1296server running on some machine, or execute
1297.Ic sshd -i
1298somewhere.
1299Host key management will be done using the
1300HostName of the host being connected (defaulting to the name typed by
1301the user).
1302Setting the command to
1303.Dq none
1304disables this option entirely.
1305Note that
1306.Cm CheckHostIP
1307is not available for connects with a proxy command.
1308.Pp
1309This directive is useful in conjunction with
1310.Xr nc 1
1311and its proxy support.
1312For example, the following directive would connect via an HTTP proxy at
1313192.0.2.0:
1314.Bd -literal -offset 3n
1315ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
1316.Ed
1317.It Cm ProxyUseFdpass
1318Specifies that
1319.Cm ProxyCommand
1320will pass a connected file descriptor back to
1321.Xr ssh 1
1322instead of continuing to execute and pass data.
1323The default is
1324.Dq no .
1325.It Cm PubkeyAcceptedKeyTypes
1326Specifies the key types that will be used for public key authentication
1327as a comma-separated pattern list.
1328Alternately if the specified value begins with a
1329.Sq +
1330character, then the key types after it will be appended to the default
1331instead of replacing it.
1332The default for this option is:
1333.Bd -literal -offset 3n
1334ecdsa-sha2-nistp256-cert-v01@openssh.com,
1335ecdsa-sha2-nistp384-cert-v01@openssh.com,
1336ecdsa-sha2-nistp521-cert-v01@openssh.com,
1337ssh-ed25519-cert-v01@openssh.com,
1338ssh-rsa-cert-v01@openssh.com,
1339ssh-dss-cert-v01@openssh.com,
1340ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,
1341ecdsa-sha2-nistp521,ssh-ed25519,
1342ssh-rsa,ssh-dss
1343.Ed
1344.Pp
1345The
1346.Fl Q
1347option of
1348.Xr ssh 1
1349may be used to list supported key types.
1350.It Cm PubkeyAuthentication
1351Specifies whether to try public key authentication.
1352The argument to this keyword must be
1353.Dq yes
1354or
1355.Dq no .
1356The default is
1357.Dq yes .
1358.It Cm RekeyLimit
1359Specifies the maximum amount of data that may be transmitted before the
1360session key is renegotiated, optionally followed a maximum amount of
1361time that may pass before the session key is renegotiated.
1362The first argument is specified in bytes and may have a suffix of
1363.Sq K ,
1364.Sq M ,
1365or
1366.Sq G
1367to indicate Kilobytes, Megabytes, or Gigabytes, respectively.
1368The default is between
1369.Sq 1G
1370and
1371.Sq 4G ,
1372depending on the cipher.
1373The optional second value is specified in seconds and may use any of the
1374units documented in the
1375TIME FORMATS section of
1376.Xr sshd_config 5 .
1377The default value for
1378.Cm RekeyLimit
1379is
1380.Dq default none ,
1381which means that rekeying is performed after the cipher's default amount
1382of data has been sent or received and no time based rekeying is done.
1383.It Cm RemoteForward
1384Specifies that a TCP port on the remote machine be forwarded over
1385the secure channel to the specified host and port from the local machine.
1386The first argument must be
1387.Sm off
1388.Oo Ar bind_address : Oc Ar port
1389.Sm on
1390and the second argument must be
1391.Ar host : Ns Ar hostport .
1392IPv6 addresses can be specified by enclosing addresses in square brackets.
1393Multiple forwardings may be specified, and additional
1394forwardings can be given on the command line.
1395Privileged ports can be forwarded only when
1396logging in as root on the remote machine.
1397.Pp
1398If the
1399.Ar port
1400argument is
1401.Ql 0 ,
1402the listen port will be dynamically allocated on the server and reported
1403to the client at run time.
1404.Pp
1405If the
1406.Ar bind_address
1407is not specified, the default is to only bind to loopback addresses.
1408If the
1409.Ar bind_address
1410is
1411.Ql *
1412or an empty string, then the forwarding is requested to listen on all
1413interfaces.
1414Specifying a remote
1415.Ar bind_address
1416will only succeed if the server's
1417.Cm GatewayPorts
1418option is enabled (see
1419.Xr sshd_config 5 ) .
1420.It Cm RequestTTY
1421Specifies whether to request a pseudo-tty for the session.
1422The argument may be one of:
1423.Dq no
1424(never request a TTY),
1425.Dq yes
1426(always request a TTY when standard input is a TTY),
1427.Dq force
1428(always request a TTY) or
1429.Dq auto
1430(request a TTY when opening a login session).
1431This option mirrors the
1432.Fl t
1433and
1434.Fl T
1435flags for
1436.Xr ssh 1 .
1437.It Cm RevokedHostKeys
1438Specifies revoked host public keys.
1439Keys listed in this file will be refused for host authentication.
1440Note that if this file does not exist or is not readable,
1441then host authentication will be refused for all hosts.
1442Keys may be specified as a text file, listing one public key per line, or as
1443an OpenSSH Key Revocation List (KRL) as generated by
1444.Xr ssh-keygen 1 .
1445For more information on KRLs, see the KEY REVOCATION LISTS section in
1446.Xr ssh-keygen 1 .
1447.It Cm RhostsRSAAuthentication
1448Specifies whether to try rhosts based authentication with RSA host
1449authentication.
1450The argument must be
1451.Dq yes
1452or
1453.Dq no .
1454The default is
1455.Dq no .
1456This option applies to protocol version 1 only and requires
1457.Xr ssh 1
1458to be setuid root.
1459.It Cm RSAAuthentication
1460Specifies whether to try RSA authentication.
1461The argument to this keyword must be
1462.Dq yes
1463or
1464.Dq no .
1465RSA authentication will only be
1466attempted if the identity file exists, or an authentication agent is
1467running.
1468The default is
1469.Dq yes .
1470Note that this option applies to protocol version 1 only.
1471.It Cm SendEnv
1472Specifies what variables from the local
1473.Xr environ 7
1474should be sent to the server.
1475The server must also support it, and the server must be configured to
1476accept these environment variables.
1477Note that the
1478.Ev TERM
1479environment variable is always sent whenever a
1480pseudo-terminal is requested as it is required by the protocol.
1481Refer to
1482.Cm AcceptEnv
1483in
1484.Xr sshd_config 5
1485for how to configure the server.
1486Variables are specified by name, which may contain wildcard characters.
1487Multiple environment variables may be separated by whitespace or spread
1488across multiple
1489.Cm SendEnv
1490directives.
1491The default is not to send any environment variables.
1492.Pp
1493See
1494.Sx PATTERNS
1495for more information on patterns.
1496.It Cm ServerAliveCountMax
1497Sets the number of server alive messages (see below) which may be
1498sent without
1499.Xr ssh 1
1500receiving any messages back from the server.
1501If this threshold is reached while server alive messages are being sent,
1502ssh will disconnect from the server, terminating the session.
1503It is important to note that the use of server alive messages is very
1504different from
1505.Cm TCPKeepAlive
1506(below).
1507The server alive messages are sent through the encrypted channel
1508and therefore will not be spoofable.
1509The TCP keepalive option enabled by
1510.Cm TCPKeepAlive
1511is spoofable.
1512The server alive mechanism is valuable when the client or
1513server depend on knowing when a connection has become inactive.
1514.Pp
1515The default value is 3.
1516If, for example,
1517.Cm ServerAliveInterval
1518(see below) is set to 15 and
1519.Cm ServerAliveCountMax
1520is left at the default, if the server becomes unresponsive,
1521ssh will disconnect after approximately 45 seconds.
1522.It Cm ServerAliveInterval
1523Sets a timeout interval in seconds after which if no data has been received
1524from the server,
1525.Xr ssh 1
1526will send a message through the encrypted
1527channel to request a response from the server.
1528The default
1529is 0, indicating that these messages will not be sent to the server.
1530.It Cm StreamLocalBindMask
1531Sets the octal file creation mode mask
1532.Pq umask
1533used when creating a Unix-domain socket file for local or remote
1534port forwarding.
1535This option is only used for port forwarding to a Unix-domain socket file.
1536.Pp
1537The default value is 0177, which creates a Unix-domain socket file that is
1538readable and writable only by the owner.
1539Note that not all operating systems honor the file mode on Unix-domain
1540socket files.
1541.It Cm StreamLocalBindUnlink
1542Specifies whether to remove an existing Unix-domain socket file for local
1543or remote port forwarding before creating a new one.
1544If the socket file already exists and
1545.Cm StreamLocalBindUnlink
1546is not enabled,
1547.Nm ssh
1548will be unable to forward the port to the Unix-domain socket file.
1549This option is only used for port forwarding to a Unix-domain socket file.
1550.Pp
1551The argument must be
1552.Dq yes
1553or
1554.Dq no .
1555The default is
1556.Dq no .
1557.It Cm StrictHostKeyChecking
1558If this flag is set to
1559.Dq yes ,
1560.Xr ssh 1
1561will never automatically add host keys to the
1562.Pa ~/.ssh/known_hosts
1563file, and refuses to connect to hosts whose host key has changed.
1564This provides maximum protection against trojan horse attacks,
1565though it can be annoying when the
1566.Pa /etc/ssh/ssh_known_hosts
1567file is poorly maintained or when connections to new hosts are
1568frequently made.
1569This option forces the user to manually
1570add all new hosts.
1571If this flag is set to
1572.Dq no ,
1573ssh will automatically add new host keys to the
1574user known hosts files.
1575If this flag is set to
1576.Dq ask ,
1577new host keys
1578will be added to the user known host files only after the user
1579has confirmed that is what they really want to do, and
1580ssh will refuse to connect to hosts whose host key has changed.
1581The host keys of
1582known hosts will be verified automatically in all cases.
1583The argument must be
1584.Dq yes ,
1585.Dq no ,
1586or
1587.Dq ask .
1588The default is
1589.Dq ask .
1590.It Cm TCPKeepAlive
1591Specifies whether the system should send TCP keepalive messages to the
1592other side.
1593If they are sent, death of the connection or crash of one
1594of the machines will be properly noticed.
1595However, this means that
1596connections will die if the route is down temporarily, and some people
1597find it annoying.
1598.Pp
1599The default is
1600.Dq yes
1601(to send TCP keepalive messages), and the client will notice
1602if the network goes down or the remote host dies.
1603This is important in scripts, and many users want it too.
1604.Pp
1605To disable TCP keepalive messages, the value should be set to
1606.Dq no .
1607.It Cm Tunnel
1608Request
1609.Xr tun 4
1610device forwarding between the client and the server.
1611The argument must be
1612.Dq yes ,
1613.Dq point-to-point
1614(layer 3),
1615.Dq ethernet
1616(layer 2),
1617or
1618.Dq no .
1619Specifying
1620.Dq yes
1621requests the default tunnel mode, which is
1622.Dq point-to-point .
1623The default is
1624.Dq no .
1625.It Cm TunnelDevice
1626Specifies the
1627.Xr tun 4
1628devices to open on the client
1629.Pq Ar local_tun
1630and the server
1631.Pq Ar remote_tun .
1632.Pp
1633The argument must be
1634.Sm off
1635.Ar local_tun Op : Ar remote_tun .
1636.Sm on
1637The devices may be specified by numerical ID or the keyword
1638.Dq any ,
1639which uses the next available tunnel device.
1640If
1641.Ar remote_tun
1642is not specified, it defaults to
1643.Dq any .
1644The default is
1645.Dq any:any .
1646.It Cm UpdateHostKeys
1647Specifies whether
1648.Xr ssh 1
1649should accept notifications of additional hostkeys from the server sent
1650after authentication has completed and add them to
1651.Cm UserKnownHostsFile .
1652The argument must be
1653.Dq yes ,
1654.Dq no
1655(the default) or
1656.Dq ask .
1657Enabling this option allows learning alternate hostkeys for a server
1658and supports graceful key rotation by allowing a server to send replacement
1659public keys before old ones are removed.
1660Additional hostkeys are only accepted if the key used to authenticate the
1661host was already trusted or explicitly accepted by the user.
1662If
1663.Cm UpdateHostKeys
1664is set to
1665.Dq ask ,
1666then the user is asked to confirm the modifications to the known_hosts file.
1667Confirmation is currently incompatible with
1668.Cm ControlPersist ,
1669and will be disabled if it is enabled.
1670.Pp
1671Presently, only
1672.Xr sshd 8
1673from OpenSSH 6.8 and greater support the
1674.Dq hostkeys@openssh.com
1675protocol extension used to inform the client of all the server's hostkeys.
1676.It Cm UsePrivilegedPort
1677Specifies whether to use a privileged port for outgoing connections.
1678The argument must be
1679.Dq yes
1680or
1681.Dq no .
1682The default is
1683.Dq no .
1684If set to
1685.Dq yes ,
1686.Xr ssh 1
1687must be setuid root.
1688Note that this option must be set to
1689.Dq yes
1690for
1691.Cm RhostsRSAAuthentication
1692with older servers.
1693.It Cm User
1694Specifies the user to log in as.
1695This can be useful when a different user name is used on different machines.
1696This saves the trouble of
1697having to remember to give the user name on the command line.
1698.It Cm UserKnownHostsFile
1699Specifies one or more files to use for the user
1700host key database, separated by whitespace.
1701The default is
1702.Pa ~/.ssh/known_hosts ,
1703.Pa ~/.ssh/known_hosts2 .
1704.It Cm VerifyHostKeyDNS
1705Specifies whether to verify the remote key using DNS and SSHFP resource
1706records.
1707If this option is set to
1708.Dq yes ,
1709the client will implicitly trust keys that match a secure fingerprint
1710from DNS.
1711Insecure fingerprints will be handled as if this option was set to
1712.Dq ask .
1713If this option is set to
1714.Dq ask ,
1715information on fingerprint match will be displayed, but the user will still
1716need to confirm new host keys according to the
1717.Cm StrictHostKeyChecking
1718option.
1719The argument must be
1720.Dq yes ,
1721.Dq no ,
1722or
1723.Dq ask .
1724The default is
1725.Dq yes
1726if compiled with LDNS and
1727.Dq no
1728otherwise.
1729.Pp
1730See also VERIFYING HOST KEYS in
1731.Xr ssh 1 .
1732.It Cm VersionAddendum
1733Specifies a string to append to the regular version string to identify
1734OS- or site-specific modifications.
1735The default is
1736.Dq FreeBSD-20160310 .
1737The value
1738.Dq none
1739may be used to disable this.
1740.It Cm VisualHostKey
1741If this flag is set to
1742.Dq yes ,
1743an ASCII art representation of the remote host key fingerprint is
1744printed in addition to the fingerprint string at login and
1745for unknown host keys.
1746If this flag is set to
1747.Dq no ,
1748no fingerprint strings are printed at login and
1749only the fingerprint string will be printed for unknown host keys.
1750The default is
1751.Dq no .
1752.It Cm XAuthLocation
1753Specifies the full pathname of the
1754.Xr xauth 1
1755program.
1756The default is
1757.Pa /usr/local/bin/xauth .
1758.El
1759.Sh PATTERNS
1760A
1761.Em pattern
1762consists of zero or more non-whitespace characters,
1763.Sq *
1764(a wildcard that matches zero or more characters),
1765or
1766.Sq ?\&
1767(a wildcard that matches exactly one character).
1768For example, to specify a set of declarations for any host in the
1769.Dq .co.uk
1770set of domains,
1771the following pattern could be used:
1772.Pp
1773.Dl Host *.co.uk
1774.Pp
1775The following pattern
1776would match any host in the 192.168.0.[0-9] network range:
1777.Pp
1778.Dl Host 192.168.0.?
1779.Pp
1780A
1781.Em pattern-list
1782is a comma-separated list of patterns.
1783Patterns within pattern-lists may be negated
1784by preceding them with an exclamation mark
1785.Pq Sq !\& .
1786For example,
1787to allow a key to be used from anywhere within an organization
1788except from the
1789.Dq dialup
1790pool,
1791the following entry (in authorized_keys) could be used:
1792.Pp
1793.Dl from=\&"!*.dialup.example.com,*.example.com\&"
1794.Sh FILES
1795.Bl -tag -width Ds
1796.It Pa ~/.ssh/config
1797This is the per-user configuration file.
1798The format of this file is described above.
1799This file is used by the SSH client.
1800Because of the potential for abuse, this file must have strict permissions:
1801read/write for the user, and not accessible by others.
1802.It Pa /etc/ssh/ssh_config
1803Systemwide configuration file.
1804This file provides defaults for those
1805values that are not specified in the user's configuration file, and
1806for those users who do not have a configuration file.
1807This file must be world-readable.
1808.El
1809.Sh SEE ALSO
1810.Xr ssh 1
1811.Sh AUTHORS
1812OpenSSH is a derivative of the original and free
1813ssh 1.2.12 release by Tatu Ylonen.
1814Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1815Theo de Raadt and Dug Song
1816removed many bugs, re-added newer features and
1817created OpenSSH.
1818Markus Friedl contributed the support for SSH
1819protocol versions 1.5 and 2.0.
1820