Debian Codegraph @

upstream/fedora-44/man5/ssh_config.5

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