Debian Codegraph @

upstream/mageia-cauldron/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.413 2025/03/03 06:53:09 dtucker Exp $
37 .Dd $Mdocdate: March 3 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 a
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 a
540 .Xr sshd 8
541 listening on behalf of a
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.
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 GSSAPIDelegateCredentials
974 Forward (delegate) credentials to the server.
975 The default is
976 .Cm no .
977 .It Cm HashKnownHosts
978 Indicates that
979 .Xr ssh 1
980 should hash host names and addresses when they are added to
981 .Pa ~/.ssh/known_hosts .
982 These hashed names may be used normally by
983 .Xr ssh 1
984 and
985 .Xr sshd 8 ,
986 but they do not visually reveal identifying information if the
987 file's contents are disclosed.
988 The default is
989 .Cm no .
990 Note that existing names and addresses in known hosts files
991 will not be converted automatically,
992 but may be manually hashed using
993 .Xr ssh-keygen 1 .
994 .It Cm HostbasedAcceptedAlgorithms
995 The default is handled system-wide by
996 .Xr crypto-policies 7 .
997 Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page
998 .Xr update-crypto-policies 8 .
999 .Pp
1000 Specifies the signature algorithms that will be used for hostbased
1001 authentication as a comma-separated list of patterns.
1002 Alternately if the specified list begins with a
1003 .Sq +
1004 character, then the specified signature algorithms will be appended
1005 to the built-in openssh default set instead of replacing them.
1006 If the specified list begins with a
1007 .Sq -
1008 character, then the specified signature algorithms (including wildcards)
1009 will be removed from the built-in openssh default set instead of replacing them.
1010 If the specified list begins with a
1011 .Sq ^
1012 character, then the specified signature algorithms will be placed
1013 at the head of the built-in openssh default set.
1014 .Pp
1015 The
1016 .Fl Q
1017 option of
1018 .Xr ssh 1
1019 may be used to list supported signature algorithms.
1020 This was formerly named HostbasedKeyTypes.
1021 .It Cm HostbasedAuthentication
1022 Specifies whether to try rhosts based authentication with public key
1023 authentication.
1024 The argument must be
1025 .Cm yes
1026 or
1027 .Cm no
1028 (the default).
1029 .It Cm HostKeyAlgorithms
1030 Specifies the host key signature algorithms
1031 that the client wants to use in order of preference.
1032 Alternately if the specified list begins with a
1033 .Sq +
1034 character, then the specified signature algorithms will be appended to
1035 the default set instead of replacing them.
1036 If the specified list begins with a
1037 .Sq -
1038 character, then the specified signature algorithms (including wildcards)
1039 will be removed from the default set instead of replacing them.
1040 If the specified list begins with a
1041 .Sq ^
1042 character, then the specified signature algorithms will be placed
1043 at the head of the default set.
1044 The default for this option is:
1045 .Bd -literal -offset 3n
1046 [email protected],
1047 [email protected],
1048 [email protected],
1049 [email protected],
1050 [email protected],
1051 [email protected],
1052 [email protected],
1053 [email protected],
1054 ssh-ed25519,
1055 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
1056 [email protected],
1057 [email protected],
1058 rsa-sha2-512,rsa-sha2-256
1059 .Ed
1060 .Pp
1061 If hostkeys are known for the destination host then this default is modified
1062 to prefer their algorithms.
1063 .Pp
1064 The list of available signature algorithms may also be obtained using
1065 .Qq ssh -Q HostKeyAlgorithms .
1066 .Pp
1067 The proposed
1068 .Cm HostKeyAlgorithms
1069 during KEX are limited to the set of algorithms that is defined in
1070 .Cm PubkeyAcceptedAlgorithms
1071 and therefore they are indirectly affected by system-wide
1072 .Xr crypto_policies 7 .
1073 .Xr crypto_policies 7 can not handle the list of host key algorithms directly as doing so
1074 would break the order given by the
1075 .Pa known_hosts
1076 file.
1077 .It Cm HostKeyAlias
1078 Specifies an alias that should be used instead of the
1079 real host name when looking up or saving the host key
1080 in the host key database files and when validating host certificates.
1081 This option is useful for tunneling SSH connections
1082 or for multiple servers running on a single host.
1083 .It Cm Hostname
1084 Specifies the real host name to log into.
1085 This can be used to specify nicknames or abbreviations for hosts.
1086 Arguments to
1087 .Cm Hostname
1088 accept the tokens described in the
1089 .Sx TOKENS
1090 section.
1091 Numeric IP addresses are also permitted (both on the command line and in
1092 .Cm Hostname
1093 specifications).
1094 The default is the name given on the command line.
1095 .It Cm IdentitiesOnly
1096 Specifies that
1097 .Xr ssh 1
1098 should only use the configured authentication identity and certificate files
1099 (either the default files, or those explicitly configured in the
1100 .Nm
1101 files
1102 or passed on the
1103 .Xr ssh 1
1104 command-line),
1105 even if
1106 .Xr ssh-agent 1
1107 or a
1108 .Cm PKCS11Provider
1109 or
1110 .Cm SecurityKeyProvider
1111 offers more identities.
1112 The argument to this keyword must be
1113 .Cm yes
1114 or
1115 .Cm no
1116 (the default).
1117 This option is intended for situations where ssh-agent
1118 offers many different identities.
1119 .It Cm IdentityAgent
1120 Specifies the
1121 .Ux Ns -domain
1122 socket used to communicate with the authentication agent.
1123 .Pp
1124 This option overrides the
1125 .Ev SSH_AUTH_SOCK
1126 environment variable and can be used to select a specific agent.
1127 Setting the socket name to
1128 .Cm none
1129 disables the use of an authentication agent.
1130 If the string
1131 .Qq SSH_AUTH_SOCK
1132 is specified, the location of the socket will be read from the
1133 .Ev SSH_AUTH_SOCK
1134 environment variable.
1135 Otherwise if the specified value begins with a
1136 .Sq $
1137 character, then it will be treated as an environment variable containing
1138 the location of the socket.
1139 .Pp
1140 Arguments to
1141 .Cm IdentityAgent
1142 may use the tilde syntax to refer to a user's home directory,
1143 the tokens described in the
1144 .Sx TOKENS
1145 section and environment variables as described in the
1146 .Sx ENVIRONMENT VARIABLES
1147 section.
1148 .It Cm IdentityFile
1149 Specifies a file from which the user's ECDSA, authenticator-hosted ECDSA,
1150 Ed25519, authenticator-hosted Ed25519 or RSA authentication identity is read.
1151 You can also specify a public key file to use the corresponding
1152 private key that is loaded in
1153 .Xr ssh-agent 1
1154 when the private key file is not present locally.
1155 The default is
1156 .Pa ~/.ssh/id_rsa ,
1157 .Pa ~/.ssh/id_ecdsa ,
1158 .Pa ~/.ssh/id_ecdsa_sk ,
1159 .Pa ~/.ssh/id_ed25519
1160 and
1161 .Pa ~/.ssh/id_ed25519_sk .
1162 Additionally, any identities represented by the authentication agent
1163 will be used for authentication unless
1164 .Cm IdentitiesOnly
1165 is set.
1166 If no certificates have been explicitly specified by
1167 .Cm CertificateFile ,
1168 .Xr ssh 1
1169 will try to load certificate information from the filename obtained by
1170 appending
1171 .Pa -cert.pub
1172 to the path of a specified
1173 .Cm IdentityFile .
1174 .Pp
1175 Arguments to
1176 .Cm IdentityFile
1177 may use the tilde syntax to refer to a user's home directory
1178 or the tokens described in the
1179 .Sx TOKENS
1180 section.
1181 Alternately an argument of
1182 .Cm none
1183 may be used to indicate no identity files should be loaded.
1184 .Pp
1185 It is possible to have
1186 multiple identity files specified in configuration files; all these
1187 identities will be tried in sequence.
1188 Multiple
1189 .Cm IdentityFile
1190 directives will add to the list of identities tried (this behaviour
1191 differs from that of other configuration directives).
1192 .Pp
1193 .Cm IdentityFile
1194 may be used in conjunction with
1195 .Cm IdentitiesOnly
1196 to select which identities in an agent are offered during authentication.
1197 .Cm IdentityFile
1198 may also be used in conjunction with
1199 .Cm CertificateFile
1200 in order to provide any certificate also needed for authentication with
1201 the identity.
1202 .Pp
1203 The authentication identity can be also specified in a form of PKCS#11 URI
1204 starting with a string
1205 .Cm pkcs11: .
1206 There is supported a subset of the PKCS#11 URI as defined
1207 in RFC 7512 (implemented path arguments
1208 .Cm id ,
1209 .Cm manufacturer ,
1210 .Cm object ,
1211 .Cm token
1212 and query arguments
1213 .Cm module-path
1214 and
1215 .Cm pin-value
1216 ). The URI can not be in quotes.
1217 .It Cm IgnoreUnknown
1218 Specifies a pattern-list of unknown options to be ignored if they are
1219 encountered in configuration parsing.
1220 This may be used to suppress errors if
1221 .Nm
1222 contains options that are unrecognised by
1223 .Xr ssh 1 .
1224 It is recommended that
1225 .Cm IgnoreUnknown
1226 be listed early in the configuration file as it will not be applied
1227 to unknown options that appear before it.
1228 .It Cm Include
1229 Include the specified configuration file(s).
1230 Multiple pathnames may be specified and each pathname may contain
1231 .Xr glob 7
1232 wildcards,
1233 tokens as described in the
1234 .Sx TOKENS
1235 section, environment variables as described in the
1236 .Sx ENVIRONMENT VARIABLES
1237 section and, for user configurations, shell-like
1238 .Sq ~
1239 references to user home directories.
1240 Wildcards will be expanded and processed in lexical order.
1241 Files without absolute paths are assumed to be in
1242 .Pa ~/.ssh
1243 if included in a user configuration file or
1244 .Pa /etc/ssh
1245 if included from the system configuration file.
1246 .Cm Include
1247 directive may appear inside a
1248 .Cm Match
1249 or
1250 .Cm Host
1251 block
1252 to perform conditional inclusion.
1253 .It Cm IPQoS
1254 Specifies the IPv4 type-of-service or DSCP class for connections.
1255 Accepted values are
1256 .Cm af11 ,
1257 .Cm af12 ,
1258 .Cm af13 ,
1259 .Cm af21 ,
1260 .Cm af22 ,
1261 .Cm af23 ,
1262 .Cm af31 ,
1263 .Cm af32 ,
1264 .Cm af33 ,
1265 .Cm af41 ,
1266 .Cm af42 ,
1267 .Cm af43 ,
1268 .Cm cs0 ,
1269 .Cm cs1 ,
1270 .Cm cs2 ,
1271 .Cm cs3 ,
1272 .Cm cs4 ,
1273 .Cm cs5 ,
1274 .Cm cs6 ,
1275 .Cm cs7 ,
1276 .Cm ef ,
1277 .Cm le ,
1278 .Cm lowdelay ,
1279 .Cm throughput ,
1280 .Cm reliability ,
1281 a numeric value, or
1282 .Cm none
1283 to use the operating system default.
1284 This option may take one or two arguments, separated by whitespace.
1285 If one argument is specified, it is used as the packet class unconditionally.
1286 If two values are specified, the first is automatically selected for
1287 interactive sessions and the second for non-interactive sessions.
1288 The default is
1289 .Cm af21
1290 (Low-Latency Data)
1291 for interactive sessions and
1292 .Cm cs1
1293 (Lower Effort)
1294 for non-interactive sessions.
1295 .It Cm KbdInteractiveAuthentication
1296 Specifies whether to use keyboard-interactive authentication.
1297 The argument to this keyword must be
1298 .Cm yes
1299 (the default)
1300 or
1301 .Cm no .
1302 .Cm ChallengeResponseAuthentication
1303 is a deprecated alias for this.
1304 .It Cm KbdInteractiveDevices
1305 Specifies the list of methods to use in keyboard-interactive authentication.
1306 Multiple method names must be comma-separated.
1307 The default is to use the server specified list.
1308 The methods available vary depending on what the server supports.
1309 For an OpenSSH server,
1310 it may be zero or more of:
1311 .Cm bsdauth
1312 and
1313 .Cm pam .
1314 .It Cm KexAlgorithms
1315 The default is handled system-wide by
1316 .Xr crypto-policies 7 .
1317 Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page
1318 .Xr update-crypto-policies 8 .
1319 .Pp
1320 Specifies the permitted KEX (Key Exchange) algorithms that will be used and
1321 their preference order.
1322 The selected algorithm will be the first algorithm in this list that
1323 the server also supports.
1324 Multiple algorithms must be comma-separated.
1325 .Pp
1326 If the specified list begins with a
1327 .Sq +
1328 character, then the specified methods will be appended to the built-in
1329 openssh default set instead of replacing them.
1330 If the specified list begins with a
1331 .Sq -
1332 character, then the specified algorithms (including wildcards) will be removed
1333 from the built-in openssh default set instead of replacing them.
1334 If the specified list begins with a
1335 .Sq ^
1336 character, then the specified algorithms will be placed at the head of the
1337 .Pp
1338 built-in openssh default set.
1339 The list of supported key exchange algorithms may also be obtained using
1340 .Qq ssh -Q kex .
1341 .It Cm KnownHostsCommand
1342 Specifies a command to use to obtain a list of host keys, in addition to
1343 those listed in
1344 .Cm UserKnownHostsFile
1345 and
1346 .Cm GlobalKnownHostsFile .
1347 This command is executed after the files have been read.
1348 It may write host key lines to standard output in identical format to the
1349 usual files (described in the
1350 .Sx VERIFYING HOST KEYS
1351 section in
1352 .Xr ssh 1 ) .
1353 Arguments to
1354 .Cm KnownHostsCommand
1355 accept the tokens described in the
1356 .Sx TOKENS
1357 section.
1358 The command may be invoked multiple times per connection: once when preparing
1359 the preference list of host key algorithms to use, again to obtain the
1360 host key for the requested host name and, if
1361 .Cm CheckHostIP
1362 is enabled, one more time to obtain the host key matching the server's
1363 address.
1364 If the command exits abnormally or returns a non-zero exit status then the
1365 connection is terminated.
1366 .It Cm LocalCommand
1367 Specifies a command to execute on the local machine after successfully
1368 connecting to the server.
1369 The command string extends to the end of the line, and is executed with
1370 the user's shell.
1371 Arguments to
1372 .Cm LocalCommand
1373 accept the tokens described in the
1374 .Sx TOKENS
1375 section.
1376 .Pp
1377 The command is run synchronously and does not have access to the
1378 session of the
1379 .Xr ssh 1
1380 that spawned it.
1381 It should not be used for interactive commands.
1382 .Pp
1383 This directive is ignored unless
1384 .Cm PermitLocalCommand
1385 has been enabled.
1386 .It Cm LocalForward
1387 Specifies that a TCP port or Unix-domain socket on the local machine
1388 be forwarded over
1389 the secure channel to the specified host and port (or Unix-domain socket)
1390 from the remote machine.
1391 For a TCP port, the first argument must be
1392 .Sm off
1393 .Oo Ar bind_address : Oc Ar port
1394 .Sm on
1395 or a Unix domain socket path.
1396 The second argument is the destination and may be
1397 .Ar host : Ns Ar hostport
1398 or a Unix domain socket path if the remote host supports it.
1399 .Pp
1400 IPv6 addresses can be specified by enclosing addresses in square brackets.
1401 .Pp
1402 If either argument contains a '/' in it, that argument will be
1403 interpreted as a Unix-domain socket (on the corresponding host) rather
1404 than a TCP port.
1405 .Pp
1406 Multiple forwardings may be specified, and additional forwardings can be
1407 given on the command line.
1408 Only the superuser can forward privileged ports.
1409 By default, the local port is bound in accordance with the
1410 .Cm GatewayPorts
1411 setting.
1412 However, an explicit
1413 .Ar bind_address
1414 may be used to bind the connection to a specific address.
1415 The
1416 .Ar bind_address
1417 of
1418 .Cm localhost
1419 indicates that the listening port be bound for local use only, while an
1420 empty address or
1421 .Sq *
1422 indicates that the port should be available from all interfaces.
1423 Unix domain socket paths may use the tokens described in the
1424 .Sx TOKENS
1425 section and environment variables as described in the
1426 .Sx ENVIRONMENT VARIABLES
1427 section.
1428 .It Cm LogLevel
1429 Gives the verbosity level that is used when logging messages from
1430 .Xr ssh 1 .
1431 The possible values are:
1432 QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.
1433 The default is INFO.
1434 DEBUG and DEBUG1 are equivalent.
1435 DEBUG2 and DEBUG3 each specify higher levels of verbose output.
1436 .It Cm LogVerbose
1437 Specify one or more overrides to LogLevel.
1438 An override consists of one or more pattern lists that matches the
1439 source file, function and line number to force detailed logging for.
1440 For example, an override pattern of:
1441 .Bd -literal -offset indent
1442 kex.c:*:1000,*:kex_exchange_identification():*,packet.c:*
1443 .Ed
1444 .Pp
1445 would enable detailed logging for line 1000 of
1446 .Pa kex.c ,
1447 everything in the
1448 .Fn kex_exchange_identification
1449 function, and all code in the
1450 .Pa packet.c
1451 file.
1452 This option is intended for debugging and no overrides are enabled by default.
1453 .It Cm MACs
1454 The default is handled system-wide by
1455 .Xr crypto-policies 7 .
1456 Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page
1457 .Xr update-crypto-policies 8 .
1458 .Pp
1459 Specifies the MAC (message authentication code) algorithms
1460 in order of preference.
1461 The MAC algorithm is used for data integrity protection.
1462 Multiple algorithms must be comma-separated.
1463 If the specified list begins with a
1464 .Sq +
1465 character, then the specified algorithms will be appended to the built-in
1466 openssh default set instead of replacing them.
1467 If the specified list begins with a
1468 .Sq -
1469 character, then the specified algorithms (including wildcards) will be removed
1470 from the built-in openssh default set instead of replacing them.
1471 If the specified list begins with a
1472 .Sq ^
1473 character, then the specified algorithms will be placed at the head of the
1474 built-in openssh default set.
1475 .Pp
1476 The algorithms that contain
1477 .Qq -etm
1478 calculate the MAC after encryption (encrypt-then-mac).
1479 These are considered safer and their use recommended.
1480 .Pp
1481 The list of available MAC algorithms may also be obtained using
1482 .Qq ssh -Q mac .
1483 .It Cm NoHostAuthenticationForLocalhost
1484 Disable host authentication for localhost (loopback addresses).
1485 The argument to this keyword must be
1486 .Cm yes
1487 or
1488 .Cm no
1489 (the default).
1490 .It Cm NumberOfPasswordPrompts
1491 Specifies the number of password prompts before giving up.
1492 The argument to this keyword must be an integer.
1493 The default is 3.
1494 .It Cm ObscureKeystrokeTiming
1495 Specifies whether
1496 .Xr ssh 1
1497 should try to obscure inter-keystroke timings from passive observers of
1498 network traffic.
1499 If enabled, then for interactive sessions,
1500 .Xr ssh 1
1501 will send keystrokes at fixed intervals of a few tens of milliseconds
1502 and will send fake keystroke packets for some time after typing ceases.
1503 The argument to this keyword must be
1504 .Cm yes ,
1505 .Cm no
1506 or an interval specifier of the form
1507 .Cm interval:milliseconds
1508 (e.g.\&
1509 .Cm interval:80
1510 for 80 milliseconds).
1511 The default is to obscure keystrokes using a 20ms packet interval.
1512 Note that smaller intervals will result in higher fake keystroke packet rates.
1513 .It Cm PasswordAuthentication
1514 Specifies whether to use password authentication.
1515 The argument to this keyword must be
1516 .Cm yes
1517 (the default)
1518 or
1519 .Cm no .
1520 .It Cm PermitLocalCommand
1521 Allow local command execution via the
1522 .Ic LocalCommand
1523 option or using the
1524 .Ic !\& Ns Ar command
1525 escape sequence in
1526 .Xr ssh 1 .
1527 The argument must be
1528 .Cm yes
1529 or
1530 .Cm no
1531 (the default).
1532 .It Cm PermitRemoteOpen
1533 Specifies the destinations to which remote TCP port forwarding is permitted when
1534 .Cm RemoteForward
1535 is used as a SOCKS proxy.
1536 The forwarding specification must be one of the following forms:
1537 .Pp
1538 .Bl -item -offset indent -compact
1539 .It
1540 .Cm PermitRemoteOpen
1541 .Sm off
1542 .Ar host : port
1543 .Sm on
1544 .It
1545 .Cm PermitRemoteOpen
1546 .Sm off
1547 .Ar IPv4_addr : port
1548 .Sm on
1549 .It
1550 .Cm PermitRemoteOpen
1551 .Sm off
1552 .Ar \&[ IPv6_addr \&] : port
1553 .Sm on
1554 .El
1555 .Pp
1556 Multiple forwards may be specified by separating them with whitespace.
1557 An argument of
1558 .Cm any
1559 can be used to remove all restrictions and permit any forwarding requests.
1560 An argument of
1561 .Cm none
1562 can be used to prohibit all forwarding requests.
1563 The wildcard
1564 .Sq *
1565 can be used for host or port to allow all hosts or ports respectively.
1566 Otherwise, no pattern matching or address lookups are performed on supplied
1567 names.
1568 .It Cm PKCS11Provider
1569 Specifies which PKCS#11 provider to use or
1570 .Cm none
1571 to indicate that no provider should be used (the default).
1572 The argument to this keyword is a path to the PKCS#11 shared library
1573 .Xr ssh 1
1574 should use to communicate with a PKCS#11 token providing keys for user
1575 authentication.
1576 .It Cm Port
1577 Specifies the port number to connect on the remote host.
1578 The default is 22.
1579 .It Cm PreferredAuthentications
1580 Specifies the order in which the client should try authentication methods.
1581 This allows a client to prefer one method (e.g.\&
1582 .Cm keyboard-interactive )
1583 over another method (e.g.\&
1584 .Cm password ) .
1585 The default is:
1586 .Bd -literal -offset indent
1587 gssapi-with-mic,hostbased,publickey,
1588 keyboard-interactive,password
1589 .Ed
1590 .It Cm ProxyCommand
1591 Specifies the command to use to connect to the server.
1592 The command
1593 string extends to the end of the line, and is executed
1594 using the user's shell
1595 .Ql exec
1596 directive to avoid a lingering shell process.
1597 .Pp
1598 Arguments to
1599 .Cm ProxyCommand
1600 accept the tokens described in the
1601 .Sx TOKENS
1602 section.
1603 The command can be basically anything,
1604 and should read from its standard input and write to its standard output.
1605 It should eventually connect an
1606 .Xr sshd 8
1607 server running on some machine, or execute
1608 .Ic sshd -i
1609 somewhere.
1610 Host key management will be done using the
1611 .Cm Hostname
1612 of the host being connected (defaulting to the name typed by the user).
1613 Setting the command to
1614 .Cm none
1615 disables this option entirely.
1616 Note that
1617 .Cm CheckHostIP
1618 is not available for connects with a proxy command.
1619 .Pp
1620 This directive is useful in conjunction with
1621 .Xr nc 1
1622 and its proxy support.
1623 For example, the following directive would connect via an HTTP proxy at
1624 192.0.2.0:
1625 .Bd -literal -offset 3n
1626 ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
1627 .Ed
1628 .It Cm ProxyJump
1629 Specifies one or more jump proxies as either
1630 .Sm off
1631 .Op Ar user No @
1632 .Ar host
1633 .Op : Ns Ar port
1634 .Sm on
1635 or an ssh URI.
1636 Multiple proxies may be separated by comma characters and will be visited
1637 sequentially.
1638 Setting this option will cause
1639 .Xr ssh 1
1640 to connect to the target host by first making a
1641 .Xr ssh 1
1642 connection to the specified
1643 .Cm ProxyJump
1644 host and then establishing a
1645 TCP forwarding to the ultimate target from there.
1646 Setting the host to
1647 .Cm none
1648 disables this option entirely.
1649 .Pp
1650 Note that this option will compete with the
1651 .Cm ProxyCommand
1652 option - whichever is specified first will prevent later instances of the
1653 other from taking effect.
1654 .Pp
1655 Note also that the configuration for the destination host (either supplied
1656 via the command-line or the configuration file) is not generally applied
1657 to jump hosts.
1658 .Pa ~/.ssh/config
1659 should be used if specific configuration is required for jump hosts.
1660 .It Cm ProxyUseFdpass
1661 Specifies that
1662 .Cm ProxyCommand
1663 will pass a connected file descriptor back to
1664 .Xr ssh 1
1665 instead of continuing to execute and pass data.
1666 The default is
1667 .Cm no .
1668 .It Cm PubkeyAcceptedAlgorithms
1669 The default is handled system-wide by
1670 .Xr crypto-policies 7 .
1671 Information about defaults, how to modify the defaults and how to customize existing policies with sub-policies are present in manual page
1672 .Xr update-crypto-policies 8 .
1673 .Pp
1674 Specifies the signature algorithms that will be used for public key
1675 authentication as a comma-separated list of patterns.
1676 If the specified list begins with a
1677 .Sq +
1678 character, then the algorithms after it will be appended to the built-in
1679 openssh default instead of replacing it.
1680 If the specified list begins with a
1681 .Sq -
1682 character, then the specified algorithms (including wildcards) will be removed
1683 from the built-in openssh default set instead of replacing them.
1684 If the specified list begins with a
1685 .Sq ^
1686 character, then the specified algorithms will be placed at the head of the
1687 built-in openssh default set.
1688 .Pp
1689 The list of available signature algorithms may also be obtained using
1690 .Qq ssh -Q PubkeyAcceptedAlgorithms .
1691 .Pp
1692 This option affects also
1693 .Cm HostKeyAlgorithms
1694 .It Cm PubkeyAuthentication
1695 Specifies whether to try public key authentication.
1696 The argument to this keyword must be
1697 .Cm yes
1698 (the default),
1699 .Cm no ,
1700 .Cm unbound
1701 or
1702 .Cm host-bound .
1703 The final two options enable public key authentication while respectively
1704 disabling or enabling the OpenSSH host-bound authentication protocol
1705 extension required for restricted
1706 .Xr ssh-agent 1
1707 forwarding.
1708 .It Cm RekeyLimit
1709 Specifies the maximum amount of data that may be transmitted or received
1710 before the session key is renegotiated, optionally followed by a maximum
1711 amount of time that may pass before the session key is renegotiated.
1712 The first argument is specified in bytes and may have a suffix of
1713 .Sq K ,
1714 .Sq M ,
1715 or
1716 .Sq G
1717 to indicate Kilobytes, Megabytes, or Gigabytes, respectively.
1718 The default is between
1719 .Sq 1G
1720 and
1721 .Sq 4G ,
1722 depending on the cipher.
1723 The optional second value is specified in seconds and may use any of the
1724 units documented in the TIME FORMATS section of
1725 .Xr sshd_config 5 .
1726 The default value for
1727 .Cm RekeyLimit
1728 is
1729 .Cm default none ,
1730 which means that rekeying is performed after the cipher's default amount
1731 of data has been sent or received and no time based rekeying is done.
1732 .It Cm RemoteCommand
1733 Specifies a command to execute on the remote machine after successfully
1734 connecting to the server.
1735 The command string extends to the end of the line, and is executed with
1736 the user's shell.
1737 Arguments to
1738 .Cm RemoteCommand
1739 accept the tokens described in the
1740 .Sx TOKENS
1741 section.
1742 .It Cm RemoteForward
1743 Specifies that a TCP port or Unix-domain socket on the remote machine
1744 be forwarded over the secure channel.
1745 The remote port may either be forwarded to a specified host and port
1746 or Unix-domain socket
1747 from the local machine, or may act as a SOCKS 4/5 proxy that allows a remote
1748 client to connect to arbitrary destinations from the local machine.
1749 The first argument is the listening specification and may be
1750 .Sm off
1751 .Oo Ar bind_address : Oc Ar port
1752 .Sm on
1753 or, if the remote host supports it, a Unix domain socket path.
1754 If forwarding to a specific destination then the second argument must be
1755 .Ar host : Ns Ar hostport
1756 or a Unix domain socket path,
1757 otherwise if no destination argument is specified then the remote forwarding
1758 will be established as a SOCKS proxy.
1759 When acting as a SOCKS proxy, the destination of the connection can be
1760 restricted by
1761 .Cm PermitRemoteOpen .
1762 .Pp
1763 IPv6 addresses can be specified by enclosing addresses in square brackets.
1764 .Pp
1765 If either argument contains a '/' in it, that argument will be
1766 interpreted as a Unix-domain socket (on the corresponding host) rather
1767 than a TCP port.
1768 .Pp
1769 Multiple forwardings may be specified, and additional
1770 forwardings can be given on the command line.
1771 Privileged ports can be forwarded only when
1772 logging in as root on the remote machine.
1773 Unix domain socket paths may use the tokens described in the
1774 .Sx TOKENS
1775 section and environment variables as described in the
1776 .Sx ENVIRONMENT VARIABLES
1777 section.
1778 .Pp
1779 If the
1780 .Ar port
1781 argument is 0,
1782 the listen port will be dynamically allocated on the server and reported
1783 to the client at run time.
1784 .Pp
1785 If the
1786 .Ar bind_address
1787 is not specified, the default is to only bind to loopback addresses.
1788 If the
1789 .Ar bind_address
1790 is
1791 .Ql *
1792 or an empty string, then the forwarding is requested to listen on all
1793 interfaces.
1794 Specifying a remote
1795 .Ar bind_address
1796 will only succeed if the server's
1797 .Cm GatewayPorts
1798 option is enabled (see
1799 .Xr sshd_config 5 ) .
1800 .It Cm RequestTTY
1801 Specifies whether to request a pseudo-tty for the session.
1802 The argument may be one of:
1803 .Cm no
1804 (never request a TTY),
1805 .Cm yes
1806 (always request a TTY when standard input is a TTY),
1807 .Cm force
1808 (always request a TTY) or
1809 .Cm auto
1810 (request a TTY when opening a login session).
1811 This option mirrors the
1812 .Fl t
1813 and
1814 .Fl T
1815 flags for
1816 .Xr ssh 1 .
1817 .It Cm RequiredRSASize
1818 Specifies the minimum RSA key size (in bits) that
1819 .Xr ssh 1
1820 will accept.
1821 User authentication keys smaller than this limit will be ignored.
1822 Servers that present host keys smaller than this limit will cause the
1823 connection to be terminated.
1824 The default is
1825 .Cm 1024
1826 bits.
1827 Note that this limit may only be raised from the default.
1828 .It Cm RevokedHostKeys
1829 Specifies revoked host public keys.
1830 Keys listed in this file will be refused for host authentication.
1831 Note that if this file does not exist or is not readable,
1832 then host authentication will be refused for all hosts.
1833 Keys may be specified as a text file, listing one public key per line, or as
1834 an OpenSSH Key Revocation List (KRL) as generated by
1835 .Xr ssh-keygen 1 .
1836 For more information on KRLs, see the KEY REVOCATION LISTS section in
1837 .Xr ssh-keygen 1 .
1838 Arguments to
1839 .Cm RevokedHostKeys
1840 may use the tilde syntax to refer to a user's home directory,
1841 the tokens described in the
1842 .Sx TOKENS
1843 section and environment variables as described in the
1844 .Sx ENVIRONMENT VARIABLES
1845 section.
1846 .It Cm SecurityKeyProvider
1847 Specifies a path to a library that will be used when loading any
1848 FIDO authenticator-hosted keys, overriding the default of using
1849 the built-in USB HID support.
1850 .Pp
1851 If the specified value begins with a
1852 .Sq $
1853 character, then it will be treated as an environment variable containing
1854 the path to the library.
1855 .It Cm SendEnv
1856 Specifies what variables from the local
1857 .Xr environ 7
1858 should be sent to the server.
1859 The server must also support it, and the server must be configured to
1860 accept these environment variables.
1861 Note that the
1862 .Ev TERM
1863 environment variable is always sent whenever a
1864 pseudo-terminal is requested as it is required by the protocol.
1865 Refer to
1866 .Cm AcceptEnv
1867 in
1868 .Xr sshd_config 5
1869 for how to configure the server.
1870 Variables are specified by name, which may contain wildcard characters.
1871 Multiple environment variables may be separated by whitespace or spread
1872 across multiple
1873 .Cm SendEnv
1874 directives.
1875 .Pp
1876 See
1877 .Sx PATTERNS
1878 for more information on patterns.
1879 .Pp
1880 It is possible to clear previously set
1881 .Cm SendEnv
1882 variable names by prefixing patterns with
1883 .Pa - .
1884 The default is not to send any environment variables.
1885 .It Cm ServerAliveCountMax
1886 Sets the number of server alive messages (see below) which may be
1887 sent without
1888 .Xr ssh 1
1889 receiving any messages back from the server.
1890 If this threshold is reached while server alive messages are being sent,
1891 ssh will disconnect from the server, terminating the session.
1892 It is important to note that the use of server alive messages is very
1893 different from
1894 .Cm TCPKeepAlive
1895 (below).
1896 The server alive messages are sent through the encrypted channel
1897 and therefore will not be spoofable.
1898 The TCP keepalive option enabled by
1899 .Cm TCPKeepAlive
1900 is spoofable.
1901 The server alive mechanism is valuable when the client or
1902 server depend on knowing when a connection has become unresponsive.
1903 .Pp
1904 The default value is 3.
1905 If, for example,
1906 .Cm ServerAliveInterval
1907 (see below) is set to 15 and
1908 .Cm ServerAliveCountMax
1909 is left at the default, if the server becomes unresponsive,
1910 ssh will disconnect after approximately 45 seconds.
1911 .It Cm ServerAliveInterval
1912 Sets a timeout interval in seconds after which if no data has been received
1913 from the server,
1914 .Xr ssh 1
1915 will send a message through the encrypted
1916 channel to request a response from the server.
1917 The default
1918 is 0, indicating that these messages will not be sent to the server.
1919 .It Cm SessionType
1920 May be used to either request invocation of a subsystem on the remote system,
1921 or to prevent the execution of a remote command at all.
1922 The latter is useful for just forwarding ports.
1923 The argument to this keyword must be
1924 .Cm none
1925 (same as the
1926 .Fl N
1927 option),
1928 .Cm subsystem
1929 (same as the
1930 .Fl s
1931 option) or
1932 .Cm default
1933 (shell or command execution).
1934 .It Cm SetEnv
1935 Directly specify one or more environment variables and their contents to
1936 be sent to the server in the form
1937 .Dq NAME=VALUE .
1938 Similarly to
1939 .Cm SendEnv ,
1940 with the exception of the
1941 .Ev TERM
1942 variable, the server must be prepared to accept the environment variable.
1943 .Pp
1944 The
1945 .Dq VALUE
1946 may use the tokens described in the
1947 .Sx TOKENS
1948 section and environment variables as described in the
1949 .Sx ENVIRONMENT VARIABLES
1950 section.
1951 .It Cm StdinNull
1952 Redirects stdin from
1953 .Pa /dev/null
1954 (actually, prevents reading from stdin).
1955 Either this or the equivalent
1956 .Fl n
1957 option must be used when
1958 .Nm ssh
1959 is run in the background.
1960 The argument to this keyword must be
1961 .Cm yes
1962 (same as the
1963 .Fl n
1964 option) or
1965 .Cm no
1966 (the default).
1967 .It Cm StreamLocalBindMask
1968 Sets the octal file creation mode mask
1969 .Pq umask
1970 used when creating a Unix-domain socket file for local or remote
1971 port forwarding.
1972 This option is only used for port forwarding to a Unix-domain socket file.
1973 .Pp
1974 The default value is 0177, which creates a Unix-domain socket file that is
1975 readable and writable only by the owner.
1976 Note that not all operating systems honor the file mode on Unix-domain
1977 socket files.
1978 .It Cm StreamLocalBindUnlink
1979 Specifies whether to remove an existing Unix-domain socket file for local
1980 or remote port forwarding before creating a new one.
1981 If the socket file already exists and
1982 .Cm StreamLocalBindUnlink
1983 is not enabled,
1984 .Nm ssh
1985 will be unable to forward the port to the Unix-domain socket file.
1986 This option is only used for port forwarding to a Unix-domain socket file.
1987 .Pp
1988 The argument must be
1989 .Cm yes
1990 or
1991 .Cm no
1992 (the default).
1993 .It Cm StrictHostKeyChecking
1994 If this flag is set to
1995 .Cm yes ,
1996 .Xr ssh 1
1997 will never automatically add host keys to the
1998 .Pa ~/.ssh/known_hosts
1999 file, and refuses to connect to hosts whose host key has changed.
2000 This provides maximum protection against man-in-the-middle (MITM) attacks,
2001 though it can be annoying when the
2002 .Pa /etc/ssh/ssh_known_hosts
2003 file is poorly maintained or when connections to new hosts are
2004 frequently made.
2005 This option forces the user to manually
2006 add all new hosts.
2007 .Pp
2008 If this flag is set to
2009 .Cm accept-new
2010 then ssh will automatically add new host keys to the user's
2011 .Pa known_hosts
2012 file, but will not permit connections to hosts with
2013 changed host keys.
2014 If this flag is set to
2015 .Cm no
2016 or
2017 .Cm off ,
2018 ssh will automatically add new host keys to the user known hosts files
2019 and allow connections to hosts with changed hostkeys to proceed,
2020 subject to some restrictions.
2021 If this flag is set to
2022 .Cm ask
2023 (the default),
2024 new host keys
2025 will be added to the user known host files only after the user
2026 has confirmed that is what they really want to do, and
2027 ssh will refuse to connect to hosts whose host key has changed.
2028 The host keys of
2029 known hosts will be verified automatically in all cases.
2030 .It Cm SyslogFacility
2031 Gives the facility code that is used when logging messages from
2032 .Xr ssh 1 .
2033 The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2,
2034 LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
2035 The default is USER.
2036 .It Cm TCPKeepAlive
2037 Specifies whether the system should send TCP keepalive messages to the
2038 other side.
2039 If they are sent, death of the connection or crash of one
2040 of the machines will be properly noticed.
2041 However, this means that
2042 connections will die if the route is down temporarily, and some people
2043 find it annoying.
2044 .Pp
2045 The default is
2046 .Cm yes
2047 (to send TCP keepalive messages), and the client will notice
2048 if the network goes down or the remote host dies.
2049 This is important in scripts, and many users want it too.
2050 .Pp
2051 To disable TCP keepalive messages, the value should be set to
2052 .Cm no .
2053 See also
2054 .Cm ServerAliveInterval
2055 for protocol-level keepalives.
2056 .It Cm Tag
2057 Specify a configuration tag name that may be later used by a
2058 .Cm Match
2059 directive to select a block of configuration.
2060 .It Cm Tunnel
2061 Request
2062 .Xr tun 4
2063 device forwarding between the client and the server.
2064 The argument must be
2065 .Cm yes ,
2066 .Cm point-to-point
2067 (layer 3),
2068 .Cm ethernet
2069 (layer 2),
2070 or
2071 .Cm no
2072 (the default).
2073 Specifying
2074 .Cm yes
2075 requests the default tunnel mode, which is
2076 .Cm point-to-point .
2077 .It Cm TunnelDevice
2078 Specifies the
2079 .Xr tun 4
2080 devices to open on the client
2081 .Pq Ar local_tun
2082 and the server
2083 .Pq Ar remote_tun .
2084 .Pp
2085 The argument must be
2086 .Sm off
2087 .Ar local_tun Op : Ar remote_tun .
2088 .Sm on
2089 The devices may be specified by numerical ID or the keyword
2090 .Cm any ,
2091 which uses the next available tunnel device.
2092 If
2093 .Ar remote_tun
2094 is not specified, it defaults to
2095 .Cm any .
2096 The default is
2097 .Cm any:any .
2098 .It Cm UpdateHostKeys
2099 Specifies whether
2100 .Xr ssh 1
2101 should accept notifications of additional hostkeys from the server sent
2102 after authentication has completed and add them to
2103 .Cm UserKnownHostsFile .
2104 The argument must be
2105 .Cm yes ,
2106 .Cm no
2107 or
2108 .Cm ask .
2109 This option allows learning alternate hostkeys for a server
2110 and supports graceful key rotation by allowing a server to send replacement
2111 public keys before old ones are removed.
2112 .Pp
2113 Additional hostkeys are only accepted if the key used to authenticate the
2114 host was already trusted or explicitly accepted by the user, the host was
2115 authenticated via
2116 .Cm UserKnownHostsFile
2117 (i.e. not
2118 .Cm GlobalKnownHostsFile )
2119 and the host was authenticated using a plain key and not a certificate.
2120 .Pp
2121 .Cm UpdateHostKeys
2122 is enabled by default if the user has not overridden the default
2123 .Cm UserKnownHostsFile
2124 setting and has not enabled
2125 .Cm VerifyHostKeyDNS ,
2126 otherwise
2127 .Cm UpdateHostKeys
2128 will be set to
2129 .Cm no .
2130 .Pp
2131 If
2132 .Cm UpdateHostKeys
2133 is set to
2134 .Cm ask ,
2135 then the user is asked to confirm the modifications to the known_hosts file.
2136 Confirmation is currently incompatible with
2137 .Cm ControlPersist ,
2138 and will be disabled if it is enabled.
2139 .Pp
2140 Presently, only
2141 .Xr sshd 8
2142 from OpenSSH 6.8 and greater support the
2143 .Qq [email protected]
2144 protocol extension used to inform the client of all the server's hostkeys.
2145 .It Cm User
2146 Specifies the user to log in as.
2147 This can be useful when a different user name is used on different machines.
2148 This saves the trouble of
2149 having to remember to give the user name on the command line.
2150 Arguments to
2151 .Cm User
2152 may use the tokens described in the
2153 .Sx TOKENS
2154 section
2155 (with the exception of %r and %C)
2156 and environment variables as described in the
2157 .Sx ENVIRONMENT VARIABLES
2158 section.
2159 .It Cm UserKnownHostsFile
2160 Specifies one or more files to use for the user
2161 host key database, separated by whitespace.
2162 Each filename may use tilde notation to refer to the user's home directory,
2163 the tokens described in the
2164 .Sx TOKENS
2165 section and environment variables as described in the
2166 .Sx ENVIRONMENT VARIABLES
2167 section.
2168 A value of
2169 .Cm none
2170 causes
2171 .Xr ssh 1
2172 to ignore any user-specific known hosts files.
2173 The default is
2174 .Pa ~/.ssh/known_hosts ,
2175 .Pa ~/.ssh/known_hosts2 .
2176 .It Cm VerifyHostKeyDNS
2177 Specifies whether to verify the remote key using DNS and SSHFP resource
2178 records.
2179 If this option is set to
2180 .Cm yes ,
2181 the client will implicitly trust keys that match a secure fingerprint
2182 from DNS.
2183 Insecure fingerprints will be handled as if this option was set to
2184 .Cm ask .
2185 If this option is set to
2186 .Cm ask ,
2187 information on fingerprint match will be displayed, but the user will still
2188 need to confirm new host keys according to the
2189 .Cm StrictHostKeyChecking
2190 option.
2191 The default is
2192 .Cm no .
2193 .Pp
2194 See also
2195 .Sx VERIFYING HOST KEYS
2196 in
2197 .Xr ssh 1 .
2198 .It Cm VersionAddendum
2199 Optionally specifies additional text to append to the SSH protocol banner
2200 sent by the client upon connection.
2201 The default is
2202 .Cm none .
2203 .It Cm VisualHostKey
2204 If this flag is set to
2205 .Cm yes ,
2206 an ASCII art representation of the remote host key fingerprint is
2207 printed in addition to the fingerprint string at login and
2208 for unknown host keys.
2209 If this flag is set to
2210 .Cm no
2211 (the default),
2212 no fingerprint strings are printed at login and
2213 only the fingerprint string will be printed for unknown host keys.
2214 .It Cm XAuthLocation
2215 Specifies the full pathname of the
2216 .Xr xauth 1
2217 program.
2218 The default is
2219 .Pa /usr/bin/xauth .
2220 .El
2221 .Sh PATTERNS
2222 A
2223 .Em pattern
2224 consists of zero or more non-whitespace characters,
2225 .Sq *
2226 (a wildcard that matches zero or more characters),
2227 or
2228 .Sq ?\&
2229 (a wildcard that matches exactly one character).
2230 For example, to specify a set of declarations for any host in the
2231 .Qq .co.uk
2232 set of domains,
2233 the following pattern could be used:
2234 .Pp
2235 .Dl Host *.co.uk
2236 .Pp
2237 The following pattern
2238 would match any host in the 192.168.0.[0-9] network range:
2239 .Pp
2240 .Dl Host 192.168.0.?
2241 .Pp
2242 A
2243 .Em pattern-list
2244 is a comma-separated list of patterns.
2245 Patterns within pattern-lists may be negated
2246 by preceding them with an exclamation mark
2247 .Pq Sq !\& .
2248 For example,
2249 to allow a key to be used from anywhere within an organization
2250 except from the
2251 .Qq dialup
2252 pool,
2253 the following entry (in authorized_keys) could be used:
2254 .Pp
2255 .Dl from=\&"!*.dialup.example.com,*.example.com\&"
2256 .Pp
2257 Note that a negated match will never produce a positive result by itself.
2258 For example, attempting to match
2259 .Qq host3
2260 against the following pattern-list will fail:
2261 .Pp
2262 .Dl from=\&"!host1,!host2\&"
2263 .Pp
2264 The solution here is to include a term that will yield a positive match,
2265 such as a wildcard:
2266 .Pp
2267 .Dl from=\&"!host1,!host2,*\&"
2268 .Sh TOKENS
2269 Arguments to some keywords can make use of tokens,
2270 which are expanded at runtime:
2271 .Pp
2272 .Bl -tag -width XXXX -offset indent -compact
2273 .It %%
2274 A literal
2275 .Sq % .
2276 .It \&%C
2277 Hash of %l%h%p%r%j.
2278 .It %d
2279 Local user's home directory.
2280 .It %f
2281 The fingerprint of the server's host key.
2282 .It %H
2283 The
2284 .Pa known_hosts
2285 hostname or address that is being searched for.
2286 .It %h
2287 The remote hostname.
2288 .It \%%I
2289 A string describing the reason for a
2290 .Cm KnownHostsCommand
2291 execution: either
2292 .Cm ADDRESS
2293 when looking up a host by address (only when
2294 .Cm CheckHostIP
2295 is enabled),
2296 .Cm HOSTNAME
2297 when searching by hostname, or
2298 .Cm ORDER
2299 when preparing the host key algorithm preference list to use for the
2300 destination host.
2301 .It %i
2302 The local user ID.
2303 .It %j
2304 The contents of the ProxyJump option, or the empty string if this
2305 option is unset.
2306 .It %K
2307 The base64 encoded host key.
2308 .It %k
2309 The host key alias if specified, otherwise the original remote hostname given
2310 on the command line.
2311 .It %L
2312 The local hostname.
2313 .It %l
2314 The local hostname, including the domain name.
2315 .It %n
2316 The original remote hostname, as given on the command line.
2317 .It %p
2318 The remote port.
2319 .It %r
2320 The remote username.
2321 .It \&%T
2322 The local
2323 .Xr tun 4
2324 or
2325 .Xr tap 4
2326 network interface assigned if
2327 tunnel forwarding was requested, or
2328 .Qq NONE
2329 otherwise.
2330 .It %t
2331 The type of the server host key, e.g.
2332 .Cm ssh-ed25519 .
2333 .It %u
2334 The local username.
2335 .El
2336 .Pp
2337 .Cm CertificateFile ,
2338 .Cm ControlPath ,
2339 .Cm IdentityAgent ,
2340 .Cm IdentityFile ,
2341 .Cm Include ,
2342 .Cm KnownHostsCommand ,
2343 .Cm LocalForward ,
2344 .Cm Match exec ,
2345 .Cm RemoteCommand ,
2346 .Cm RemoteForward ,
2347 .Cm RevokedHostKeys ,
2348 .Cm UserKnownHostsFile
2349 and
2350 .Cm VersionAddendum
2351 accept the tokens %%, %C, %d, %h, %i, %j, %k, %L, %l, %n, %p, %r, and %u.
2352 .Pp
2353 .Cm KnownHostsCommand
2354 additionally accepts the tokens %f, %H, %I, %K and %t.
2355 .Pp
2356 .Cm Hostname
2357 accepts the tokens %% and %h.
2358 .Pp
2359 .Cm LocalCommand
2360 accepts all tokens.
2361 .Pp
2362 .Cm ProxyCommand
2363 and
2364 .Cm ProxyJump
2365 accept the tokens %%, %h, %n, %p, and %r.
2366 .Pp
2367 Note that some of these directives build commands for execution via the shell.
2368 Because
2369 .Xr ssh 1
2370 performs no filtering or escaping of characters that have special meaning in
2371 shell commands (e.g. quotes), it is the user's responsibility to ensure that
2372 the arguments passed to
2373 .Xr ssh 1
2374 do not contain such characters and that tokens are appropriately quoted
2375 when used.
2376 .Sh ENVIRONMENT VARIABLES
2377 Arguments to some keywords can be expanded at runtime from environment
2378 variables on the client by enclosing them in
2379 .Ic ${} ,
2380 for example
2381 .Ic ${HOME}/.ssh
2382 would refer to the user's .ssh directory.
2383 If a specified environment variable does not exist then an error will be
2384 returned and the setting for that keyword will be ignored.
2385 .Pp
2386 The keywords
2387 .Cm CertificateFile ,
2388 .Cm ControlPath ,
2389 .Cm IdentityAgent ,
2390 .Cm IdentityFile ,
2391 .Cm Include ,
2392 .Cm KnownHostsCommand ,
2393 and
2394 .Cm UserKnownHostsFile
2395 support environment variables.
2396 The keywords
2397 .Cm LocalForward
2398 and
2399 .Cm RemoteForward
2400 support environment variables only for Unix domain socket paths.
2401 .Sh FILES
2402 .Bl -tag -width Ds
2403 .It Pa ~/.ssh/config
2404 This is the per-user configuration file.
2405 The format of this file is described above.
2406 This file is used by the SSH client.
2407 Because of the potential for abuse, this file must have strict permissions:
2408 read/write for the user, and not writable by others.
2409 .It Pa /etc/ssh/ssh_config
2410 Systemwide configuration file.
2411 This file provides defaults for those
2412 values that are not specified in the user's configuration file, and
2413 for those users who do not have a configuration file.
2414 This file must be world-readable.
2415 .El
2416 .Sh SEE ALSO
2417 .Xr ssh 1 ,
2418 .Xr crypto-policies 7 ,
2419 .Xr update-crypto-policies 8
2420 .Sh AUTHORS
2421 .An -nosplit
2422 OpenSSH is a derivative of the original and free
2423 ssh 1.2.12 release by
2424 .An Tatu Ylonen .
2425 .An Aaron Campbell , Bob Beck , Markus Friedl ,
2426 .An Niels Provos , Theo de Raadt
2427 and
2428 .An Dug Song
2429 removed many bugs, re-added newer features and
2430 created OpenSSH.
2431 .An Markus Friedl
2432 contributed the support for SSH protocol versions 1.5 and 2.0.