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