Debian Codegraph @

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