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