1SSH_CONFIG(5) BSD File Formats Manual SSH_CONFIG(5)
2
4 ssh_config — OpenSSH SSH client configuration files
5
7 ssh(1) obtains configuration data from the following sources in the fol‐
8 lowing order:
9 1. command-line options
11 2. user's configuration file (~/.ssh/config)
12 3. GSSAPI configuration file ($HOME/.ssh/config.gssapi)
13 4. Kerberos configuration file ($HOME/.ssh/config.krb)
14 5. system-wide configuration file (/etc/gsissh/ssh_config)
15 For each parameter, the first obtained value will be used. The configu‐
17 ration files contain sections separated by Host specifications, and that
18 section is only applied for hosts that match one of the patterns given in
19 the specification. The matched host name is usually the one given on the
20 command line (see the CanonicalizeHostname option for exceptions).
21 Since the first obtained value for each parameter is used, more host-spe‐
23 cific declarations should be given near the beginning of the file, and
24 general defaults at the end.
25 The file contains keyword-argument pairs, one per line. Lines starting
27 with ‘#’ and empty lines are interpreted as comments. Arguments may
28 optionally be enclosed in double quotes (") in order to represent argu‐
29 ments containing spaces. Configuration options may be separated by
30 whitespace or optional whitespace and exactly one ‘=’; the latter format
31 is useful to avoid the need to quote whitespace when specifying configu‐
32 ration options using the ssh, scp, and sftp -o option.
33 The possible keywords and their meanings are as follows (note that key‐
35 words are case-insensitive and arguments are case-sensitive):
36 Host Restricts the following declarations (up to the next Host or
38 Match keyword) to be only for those hosts that match one of the
39 patterns given after the keyword. If more than one pattern is
40 provided, they should be separated by whitespace. A single ‘*’
41 as a pattern can be used to provide global defaults for all
42 hosts. The host is usually the hostname argument given on the
43 command line (see the CanonicalizeHostname keyword for excep‐
44 tions).
45 A pattern entry may be negated by prefixing it with an exclama‐
47 tion mark (‘!’). If a negated entry is matched, then the Host
48 entry is ignored, regardless of whether any other patterns on the
49 line match. Negated matches are therefore useful to provide
50 exceptions for wildcard matches.
51 See PATTERNS for more information on patterns.
53 Match Restricts the following declarations (up to the next Host or
55 Match keyword) to be used only when the conditions following the
56 Match keyword are satisfied. Match conditions are specified
57 using one or more criteria or the single token all which always
58 matches. The available criteria keywords are: canonical, final,
59 exec, host, originalhost, user, and localuser. The all criteria
60 must appear alone or immediately after canonical or final. Other
61 criteria may be combined arbitrarily. All criteria but all
62 canonical and final require an argument. Criteria may be negated
63 by prepending an exclamation mark (‘!’).
64 The canonical keyword matches only when the configuration file is
66 being re-parsed after hostname canonicalization (see the
67 CanonicalizeHostname option.) This may be useful to specify con‐
68 ditions that work with canonical host names only.
69 The final keyword requests that the configuration be re-parsed
71 (regardless of whether CanonicalizeHostname is enabled), and
72 matches only during this final pass. If CanonicalizeHostname is
73 enabled, then canonical and final match during the same pass.
74 The exec keyword executes the specified command under the user's
76 shell. If the command returns a zero exit status then the condi‐
77 tion is considered true. Commands containing whitespace charac‐
78 ters must be quoted. Arguments to exec accept the tokens
79 described in the TOKENS section.
80 The other keywords' criteria must be single entries or comma-sep‐
82 arated lists and may use the wildcard and negation operators
83 described in the PATTERNS section. The criteria for the host
84 keyword are matched against the target hostname, after any sub‐
85 stitution by the Hostname or CanonicalizeHostname options. The
86 originalhost keyword matches against the hostname as it was spec‐
87 ified on the command-line. The user keyword matches against the
88 target username on the remote host. The localuser keyword
89 matches against the name of the local user running ssh(1) (this
90 keyword may be useful in system-wide ssh_config files).
91 AddKeysToAgent
93 Specifies whether keys should be automatically added to a running
94 ssh-agent(1). If this option is set to yes and a key is loaded
95 from a file, the key and its passphrase are added to the agent
96 with the default lifetime, as if by ssh-add(1). If this option
97 is set to ask, ssh(1) will require confirmation using the
98 SSH_ASKPASS program before adding a key (see ssh-add(1) for
99 details). If this option is set to confirm, each use of the key
100 must be confirmed, as if the -c option was specified to
101 ssh-add(1). If this option is set to no, no keys are added to
102 the agent. The argument must be yes, confirm, ask, or no (the
103 default).
104 AddressFamily
106 Specifies which address family to use when connecting. Valid
107 arguments are any (the default), inet (use IPv4 only), or inet6
108 (use IPv6 only).
109 BatchMode
111 If set to yes, passphrase/password querying will be disabled.
112 This option is useful in scripts and other batch jobs where no
113 user is present to supply the password. The argument must be yes
114 or no (the default).
115 BindAddress
117 Use the specified address on the local machine as the source
118 address of the connection. Only useful on systems with more than
119 one address.
120 BindInterface
122 Use the address of the specified interface on the local machine
123 as the source address of the connection.
124 CanonicalDomains
126 When CanonicalizeHostname is enabled, this option specifies the
127 list of domain suffixes in which to search for the specified des‐
128 tination host.
129 CanonicalizeFallbackLocal
131 Specifies whether to fail with an error when hostname canonical‐
132 ization fails. The default, yes, will attempt to look up the
133 unqualified hostname using the system resolver's search rules. A
134 value of no will cause ssh(1) to fail instantly if
135 CanonicalizeHostname is enabled and the target hostname cannot be
136 found in any of the domains specified by CanonicalDomains.
137 CanonicalizeHostname
139 Controls whether explicit hostname canonicalization is performed.
140 The default, no, is not to perform any name rewriting and let the
141 system resolver handle all hostname lookups. If set to yes then,
142 for connections that do not use a ProxyCommand or ProxyJump,
143 ssh(1) will attempt to canonicalize the hostname specified on the
144 command line using the CanonicalDomains suffixes and
145 CanonicalizePermittedCNAMEs rules. If CanonicalizeHostname is
146 set to always, then canonicalization is applied to proxied con‐
147 nections too.
148 If this option is enabled, then the configuration files are pro‐
150 cessed again using the new target name to pick up any new config‐
151 uration in matching Host and Match stanzas.
152 CanonicalizeMaxDots
154 Specifies the maximum number of dot characters in a hostname
155 before canonicalization is disabled. The default, 1, allows a
156 single dot (i.e. hostname.subdomain).
157 CanonicalizePermittedCNAMEs
159 Specifies rules to determine whether CNAMEs should be followed
160 when canonicalizing hostnames. The rules consist of one or more
161 arguments of source_domain_list:target_domain_list, where
162 source_domain_list is a pattern-list of domains that may follow
163 CNAMEs in canonicalization, and target_domain_list is a pattern-
164 list of domains that they may resolve to.
165 For example, "*.a.example.com:*.b.example.com,*.c.example.com"
167 will allow hostnames matching "*.a.example.com" to be canonical‐
168 ized to names in the "*.b.example.com" or "*.c.example.com"
169 domains.
170 CASignatureAlgorithms
172 Specifies which algorithms are allowed for signing of certifi‐
173 cates by certificate authorities (CAs). The default is:
174 ecdsa-sha2-nistp256.ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
176 ssh-ed25519,rsa-sha2-512,rsa-sha2-256,ssh-rsa
177 ssh(1) will not accept host certificates signed using algorithms
179 other than those specified.
180 CertificateFile
182 Specifies a file from which the user's certificate is read. A
183 corresponding private key must be provided separately in order to
184 use this certificate either from an IdentityFile directive or -i
185 flag to ssh(1), via ssh-agent(1), or via a PKCS11Provider.
186 Arguments to CertificateFile may use the tilde syntax to refer to
188 a user's home directory or the tokens described in the TOKENS
189 section.
190 It is possible to have multiple certificate files specified in
192 configuration files; these certificates will be tried in
193 sequence. Multiple CertificateFile directives will add to the
194 list of certificates used for authentication.
195 ChallengeResponseAuthentication
197 Specifies whether to use challenge-response authentication. The
198 argument to this keyword must be yes (the default) or no.
199 CheckHostIP
201 If set to yes (the default), ssh(1) will additionally check the
202 host IP address in the known_hosts file. This allows it to
203 detect if a host key changed due to DNS spoofing and will add
204 addresses of destination hosts to ~/.ssh/known_hosts in the
205 process, regardless of the setting of StrictHostKeyChecking. If
206 the option is set to no, the check will not be executed.
207 Ciphers
209 Specifies the ciphers allowed and their order of preference.
210 Multiple ciphers must be comma-separated. If the specified value
211 begins with a ‘+’ character, then the specified ciphers will be
212 appended to the default set instead of replacing them. If the
213 specified value begins with a ‘-’ character, then the specified
214 ciphers (including wildcards) will be removed from the default
215 set instead of replacing them.
216 The supported ciphers are:
218 3des-cbc
220 aes128-cbc
221 aes192-cbc
222 aes256-cbc
223 aes128-ctr
224 aes192-ctr
225 aes256-ctr
226 aes128-gcm@openssh.com
227 aes256-gcm@openssh.com
228 chacha20-poly1305@openssh.com
229 The default is:
231 chacha20-poly1305@openssh.com,
233 aes128-ctr,aes192-ctr,aes256-ctr,
234 aes128-gcm@openssh.com,aes256-gcm@openssh.com
235 The list of available ciphers may also be obtained using "ssh -Q
237 cipher".
238 ClearAllForwardings
240 Specifies that all local, remote, and dynamic port forwardings
241 specified in the configuration files or on the command line be
242 cleared. This option is primarily useful when used from the
243 ssh(1) command line to clear port forwardings set in configura‐
244 tion files, and is automatically set by scp(1) and sftp(1). The
245 argument must be yes or no (the default).
246 Compression
248 Specifies whether to use compression. The argument must be yes
249 or no (the default).
250 ConnectionAttempts
252 Specifies the number of tries (one per second) to make before
253 exiting. The argument must be an integer. This may be useful in
254 scripts if the connection sometimes fails. The default is 1.
255 ConnectTimeout
257 Specifies the timeout (in seconds) used when connecting to the
258 SSH server, instead of using the default system TCP timeout.
259 This value is used only when the target is down or really
260 unreachable, not when it refuses the connection.
261 ControlMaster
263 Enables the sharing of multiple sessions over a single network
264 connection. When set to yes, ssh(1) will listen for connections
265 on a control socket specified using the ControlPath argument.
266 Additional sessions can connect to this socket using the same
267 ControlPath with ControlMaster set to no (the default). These
268 sessions will try to reuse the master instance's network connec‐
269 tion rather than initiating new ones, but will fall back to con‐
270 necting normally if the control socket does not exist, or is not
271 listening.
272 Setting this to ask will cause ssh(1) to listen for control con‐
274 nections, but require confirmation using ssh-askpass(1). If the
275 ControlPath cannot be opened, ssh(1) will continue without con‐
276 necting to a master instance.
277 X11 and ssh-agent(1) forwarding is supported over these multi‐
279 plexed connections, however the display and agent forwarded will
280 be the one belonging to the master connection i.e. it is not pos‐
281 sible to forward multiple displays or agents.
282 Two additional options allow for opportunistic multiplexing: try
284 to use a master connection but fall back to creating a new one if
285 one does not already exist. These options are: auto and autoask.
286 The latter requires confirmation like the ask option.
287 ControlPath
289 Specify the path to the control socket used for connection shar‐
290 ing as described in the ControlMaster section above or the string
291 none to disable connection sharing. Arguments to ControlPath may
292 use the tilde syntax to refer to a user's home directory or the
293 tokens described in the TOKENS section. It is recommended that
294 any ControlPath used for opportunistic connection sharing include
295 at least %h, %p, and %r (or alternatively %C) and be placed in a
296 directory that is not writable by other users. This ensures that
297 shared connections are uniquely identified.
298 ControlPersist
300 When used in conjunction with ControlMaster, specifies that the
301 master connection should remain open in the background (waiting
302 for future client connections) after the initial client connec‐
303 tion has been closed. If set to no, then the master connection
304 will not be placed into the background, and will close as soon as
305 the initial client connection is closed. If set to yes or 0,
306 then the master connection will remain in the background indefi‐
307 nitely (until killed or closed via a mechanism such as the "ssh
308 -O exit"). If set to a time in seconds, or a time in any of the
309 formats documented in sshd_config(5), then the backgrounded mas‐
310 ter connection will automatically terminate after it has remained
311 idle (with no client connections) for the specified time.
312 DynamicForward
314 Specifies that a TCP port on the local machine be forwarded over
315 the secure channel, and the application protocol is then used to
316 determine where to connect to from the remote machine.
317 The argument must be [bind_address:]port. IPv6 addresses can be
319 specified by enclosing addresses in square brackets. By default,
320 the local port is bound in accordance with the GatewayPorts set‐
321 ting. However, an explicit bind_address may be used to bind the
322 connection to a specific address. The bind_address of localhost
323 indicates that the listening port be bound for local use only,
324 while an empty address or ‘*’ indicates that the port should be
325 available from all interfaces.
326 Currently the SOCKS4 and SOCKS5 protocols are supported, and
328 ssh(1) will act as a SOCKS server. Multiple forwardings may be
329 specified, and additional forwardings can be given on the command
330 line. Only the superuser can forward privileged ports.
331 EnableSSHKeysign
333 Setting this option to yes in the global client configuration
334 file /etc/gsissh/ssh_config enables the use of the helper program
335 ssh-keysign(8) during HostbasedAuthentication. The argument must
336 be yes or no (the default). This option should be placed in the
337 non-hostspecific section. See ssh-keysign(8) for more informa‐
338 tion.
339 EscapeChar
341 Sets the escape character (default: ‘~’). The escape character
342 can also be set on the command line. The argument should be a
343 single character, ‘^’ followed by a letter, or none to disable
344 the escape character entirely (making the connection transparent
345 for binary data).
346 ExitOnForwardFailure
348 Specifies whether ssh(1) should terminate the connection if it
349 cannot set up all requested dynamic, tunnel, local, and remote
350 port forwardings, (e.g. if either end is unable to bind and lis‐
351 ten on a specified port). Note that ExitOnForwardFailure does
352 not apply to connections made over port forwardings and will not,
353 for example, cause ssh(1) to exit if TCP connections to the ulti‐
354 mate forwarding destination fail. The argument must be yes or no
355 (the default).
356 FingerprintHash
358 Specifies the hash algorithm used when displaying key finger‐
359 prints. Valid options are: md5 and sha256 (the default).
360 ForwardAgent
362 Specifies whether the connection to the authentication agent (if
363 any) will be forwarded to the remote machine. The argument must
364 be yes or no (the default).
365 Agent forwarding should be enabled with caution. Users with the
367 ability to bypass file permissions on the remote host (for the
368 agent's Unix-domain socket) can access the local agent through
369 the forwarded connection. An attacker cannot obtain key material
370 from the agent, however they can perform operations on the keys
371 that enable them to authenticate using the identities loaded into
372 the agent.
373 ForwardX11
375 Specifies whether X11 connections will be automatically redi‐
376 rected over the secure channel and DISPLAY set. The argument
377 must be yes or no (the default).
378 X11 forwarding should be enabled with caution. Users with the
380 ability to bypass file permissions on the remote host (for the
381 user's X11 authorization database) can access the local X11 dis‐
382 play through the forwarded connection. An attacker may then be
383 able to perform activities such as keystroke monitoring if the
384 ForwardX11Trusted option is also enabled.
385 ForwardX11Timeout
387 Specify a timeout for untrusted X11 forwarding using the format
388 described in the TIME FORMATS section of sshd_config(5). X11
389 connections received by ssh(1) after this time will be refused.
390 Setting ForwardX11Timeout to zero will disable the timeout and
391 permit X11 forwarding for the life of the connection. The
392 default is to disable untrusted X11 forwarding after twenty min‐
393 utes has elapsed.
394 ForwardX11Trusted
396 If this option is set to yes, remote X11 clients will have full
397 access to the original X11 display.
398 If this option is set to no (the default), remote X11 clients
400 will be considered untrusted and prevented from stealing or tam‐
401 pering with data belonging to trusted X11 clients. Furthermore,
402 the xauth(1) token used for the session will be set to expire
403 after 20 minutes. Remote clients will be refused access after
404 this time.
405 See the X11 SECURITY extension specification for full details on
407 the restrictions imposed on untrusted clients.
408 GatewayPorts
410 Specifies whether remote hosts are allowed to connect to local
411 forwarded ports. By default, ssh(1) binds local port forwardings
412 to the loopback address. This prevents other remote hosts from
413 connecting to forwarded ports. GatewayPorts can be used to spec‐
414 ify that ssh should bind local port forwardings to the wildcard
415 address, thus allowing remote hosts to connect to forwarded
416 ports. The argument must be yes or no (the default).
417 GlobalKnownHostsFile
419 Specifies one or more files to use for the global host key data‐
420 base, separated by whitespace. The default is
421 /etc/gsissh/ssh_known_hosts, /etc/gsissh/ssh_known_hosts2.
422 GSSAPIAuthentication
424 Specifies whether user authentication based on GSSAPI is allowed.
425 The default is yes.
426 GSSAPIClientIdentity
428 If set, specifies the GSSAPI client identity that ssh should use
429 when connecting to the server. The default is unset, which means
430 that the default identity will be used.
431 GSSAPIDelegateCredentials
433 Forward (delegate) credentials to the server. The default is
434 yes.
435 GSSAPIKeyExchange
437 Specifies whether key exchange based on GSSAPI may be used. When
438 using GSSAPI key exchange the server need not have a host key.
439 The default is “yes”.
440 GSSAPIRenewalForcesRekey
442 If set to “yes” then renewal of the client's GSSAPI credentials
443 will force the rekeying of the ssh connection. With a compatible
444 server, this will delegate the renewed credentials to a session
445 on the server.
446 Checks are made to ensure that credentials are only propagated
448 when the new credentials match the old ones on the originating
449 client and where the receiving server still has the old set in
450 its cache.
451 The default is “no”.
453 For this to work GSSAPIKeyExchange needs to be enabled in the
455 server and also used by the client.
456 GSSAPIServerIdentity
458 If set, specifies the GSSAPI server identity that ssh should
459 expect when connecting to the server. The default is unset, which
460 means that the expected GSSAPI server identity will be determined
461 from the target hostname.
462 GSSAPITrustDns
464 Set to “yes” to indicate that the DNS is trusted to securely
465 canonicalize the name of the host being connected to. If “no”,
466 the hostname entered on the command line will be passed untouched
467 to the GSSAPI library. The default is “no”.
468 GSSAPIKexAlgorithms
470 The list of key exchange algorithms that are offered for GSSAPI
471 key exchange. Possible values are
472 gss-gex-sha1-,
474 gss-group1-sha1-,
475 gss-group14-sha1-,
476 gss-group14-sha256-,
477 gss-group16-sha512-,
478 gss-nistp256-sha256-,
479 gss-curve25519-sha256-
480 The default is “gss-gex-sha1-,gss-group14-sha1-”.
482 HashKnownHosts
484 Indicates that ssh(1) should hash host names and addresses when
485 they are added to ~/.ssh/known_hosts. These hashed names may be
486 used normally by ssh(1) and sshd(8), but they do not reveal iden‐
487 tifying information should the file's contents be disclosed. The
488 default is no. Note that existing names and addresses in known
489 hosts files will not be converted automatically, but may be manu‐
490 ally hashed using ssh-keygen(1).
491 HostbasedAuthentication
493 Specifies whether to try rhosts based authentication with public
494 key authentication. The argument must be yes or no (the
495 default).
496 HostbasedKeyTypes
498 Specifies the key types that will be used for hostbased authenti‐
499 cation as a comma-separated list of patterns. Alternately if the
500 specified value begins with a ‘+’ character, then the specified
501 key types will be appended to the default set instead of replac‐
502 ing them. If the specified value begins with a ‘-’ character,
503 then the specified key types (including wildcards) will be
504 removed from the default set instead of replacing them. The
505 default for this option is:
506 ecdsa-sha2-nistp256-cert-v01@openssh.com,
508 ecdsa-sha2-nistp384-cert-v01@openssh.com,
509 ecdsa-sha2-nistp521-cert-v01@openssh.com,
510 ssh-ed25519-cert-v01@openssh.com,
511 rsa-sha2-512-cert-v01@openssh.com,rsa-sha2-256-cert-v01@openssh.com,
512 ssh-rsa-cert-v01@openssh.com,
513 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
514 ssh-ed25519,rsa-sha2-512,rsa-sha2-256,ssh-rsa
515 The -Q option of ssh(1) may be used to list supported key types.
517 HostKeyAlgorithms
519 Specifies the host key algorithms that the client wants to use in
520 order of preference. Alternately if the specified value begins
521 with a ‘+’ character, then the specified key types will be
522 appended to the default set instead of replacing them. If the
523 specified value begins with a ‘-’ character, then the specified
524 key types (including wildcards) will be removed from the default
525 set instead of replacing them. The default for this option is:
526 ecdsa-sha2-nistp256-cert-v01@openssh.com,
528 ecdsa-sha2-nistp384-cert-v01@openssh.com,
529 ecdsa-sha2-nistp521-cert-v01@openssh.com,
530 ssh-ed25519-cert-v01@openssh.com,
531 rsa-sha2-512-cert-v01@openssh.com,rsa-sha2-256-cert-v01@openssh.com,
532 ssh-rsa-cert-v01@openssh.com,
533 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
534 ssh-ed25519,rsa-sha2-512,rsa-sha2-256,ssh-rsa
535 If hostkeys are known for the destination host then this default
537 is modified to prefer their algorithms.
538 The list of available key types may also be obtained using "ssh
540 -Q key".
541 HostKeyAlias
543 Specifies an alias that should be used instead of the real host
544 name when looking up or saving the host key in the host key data‐
545 base files and when validating host certificates. This option is
546 useful for tunneling SSH connections or for multiple servers run‐
547 ning on a single host.
548 HostName
550 Specifies the real host name to log into. This can be used to
551 specify nicknames or abbreviations for hosts. Arguments to
552 HostName accept the tokens described in the TOKENS section.
553 Numeric IP addresses are also permitted (both on the command line
554 and in HostName specifications). The default is the name given
555 on the command line.
556 IdentitiesOnly
558 Specifies that ssh(1) should only use the authentication identity
559 and certificate files explicitly configured in the ssh_config
560 files or passed on the ssh(1) command-line, even if ssh-agent(1)
561 or a PKCS11Provider offers more identities. The argument to this
562 keyword must be yes or no (the default). This option is intended
563 for situations where ssh-agent offers many different identities.
564 IdentityAgent
566 Specifies the UNIX-domain socket used to communicate with the
567 authentication agent.
568 This option overrides the SSH_AUTH_SOCK environment variable and
570 can be used to select a specific agent. Setting the socket name
571 to none disables the use of an authentication agent. If the
572 string "SSH_AUTH_SOCK" is specified, the location of the socket
573 will be read from the SSH_AUTH_SOCK environment variable. Other‐
574 wise if the specified value begins with a ‘$’ character, then it
575 will be treated as an environment variable containing the loca‐
576 tion of the socket.
577 Arguments to IdentityAgent may use the tilde syntax to refer to a
579 user's home directory or the tokens described in the TOKENS sec‐
580 tion.
581 IdentityFile
583 Specifies a file from which the user's DSA, ECDSA, Ed25519 or RSA
584 authentication identity is read. The default is ~/.ssh/id_dsa,
585 ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519 and ~/.ssh/id_rsa. Addition‐
586 ally, any identities represented by the authentication agent will
587 be used for authentication unless IdentitiesOnly is set. If no
588 certificates have been explicitly specified by CertificateFile,
589 ssh(1) will try to load certificate information from the filename
590 obtained by appending -cert.pub to the path of a specified
591 IdentityFile.
592 Arguments to IdentityFile may use the tilde syntax to refer to a
594 user's home directory or the tokens described in the TOKENS sec‐
595 tion.
596 It is possible to have multiple identity files specified in con‐
598 figuration files; all these identities will be tried in sequence.
599 Multiple IdentityFile directives will add to the list of identi‐
600 ties tried (this behaviour differs from that of other configura‐
601 tion directives).
602 IdentityFile may be used in conjunction with IdentitiesOnly to
604 select which identities in an agent are offered during authenti‐
605 cation. IdentityFile may also be used in conjunction with
606 CertificateFile in order to provide any certificate also needed
607 for authentication with the identity.
608 The authentication identity can be also specified in a form of
610 PKCS#11 URI starting with a string pkcs11:. There is supported a
611 subset of the PKCS#11 URI as defined in RFC 7512 (implemented
612 path arguments id, manufacturer, object, token and query argument
613 module-path ). The URI can not be in quotes.
614 IgnoreUnknown
616 Specifies a pattern-list of unknown options to be ignored if they
617 are encountered in configuration parsing. This may be used to
618 suppress errors if ssh_config contains options that are unrecog‐
619 nised by ssh(1). It is recommended that IgnoreUnknown be listed
620 early in the configuration file as it will not be applied to
621 unknown options that appear before it.
622 Include
624 Include the specified configuration file(s). Multiple pathnames
625 may be specified and each pathname may contain glob(7) wildcards
626 and, for user configurations, shell-like ‘~’ references to user
627 home directories. Files without absolute paths are assumed to be
628 in ~/.ssh if included in a user configuration file or /etc/ssh if
629 included from the system configuration file. Include directive
630 may appear inside a Match or Host block to perform conditional
631 inclusion.
632 IPQoS Specifies the IPv4 type-of-service or DSCP class for connections.
634 Accepted values are af11, af12, af13, af21, af22, af23, af31,
635 af32, af33, af41, af42, af43, cs0, cs1, cs2, cs3, cs4, cs5, cs6,
636 cs7, ef, lowdelay, throughput, reliability, a numeric value, or
637 none to use the operating system default. This option may take
638 one or two arguments, separated by whitespace. If one argument
639 is specified, it is used as the packet class unconditionally. If
640 two values are specified, the first is automatically selected for
641 interactive sessions and the second for non-interactive sessions.
642 The default is af21 (Low-Latency Data) for interactive sessions
643 and cs1 (Lower Effort) for non-interactive sessions.
644 KbdInteractiveAuthentication
646 Specifies whether to use keyboard-interactive authentication.
647 The argument to this keyword must be yes (the default) or no.
648 KbdInteractiveDevices
650 Specifies the list of methods to use in keyboard-interactive
651 authentication. Multiple method names must be comma-separated.
652 The default is to use the server specified list. The methods
653 available vary depending on what the server supports. For an
654 OpenSSH server, it may be zero or more of: bsdauth and pam.
655 KexAlgorithms
657 Specifies the available KEX (Key Exchange) algorithms. Multiple
658 algorithms must be comma-separated. Alternately if the specified
659 value begins with a ‘+’ character, then the specified methods
660 will be appended to the default set instead of replacing them.
661 If the specified value begins with a ‘-’ character, then the
662 specified methods (including wildcards) will be removed from the
663 default set instead of replacing them. The default is:
664 curve25519-sha256,curve25519-sha256@libssh.org,
666 ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,
667 diffie-hellman-group-exchange-sha256,
668 diffie-hellman-group16-sha512,
669 diffie-hellman-group18-sha512,
670 diffie-hellman-group-exchange-sha1,
671 diffie-hellman-group14-sha256,
672 diffie-hellman-group14-sha1
673 The list of available key exchange algorithms may also be
675 obtained using "ssh -Q kex".
676 LocalCommand
678 Specifies a command to execute on the local machine after suc‐
679 cessfully connecting to the server. The command string extends
680 to the end of the line, and is executed with the user's shell.
681 Arguments to LocalCommand accept the tokens described in the
682 TOKENS section.
683 The command is run synchronously and does not have access to the
685 session of the ssh(1) that spawned it. It should not be used for
686 interactive commands.
687 This directive is ignored unless PermitLocalCommand has been
689 enabled.
690 LocalForward
692 Specifies that a TCP port on the local machine be forwarded over
693 the secure channel to the specified host and port from the remote
694 machine. The first argument must be [bind_address:]port and the
695 second argument must be host:hostport. IPv6 addresses can be
696 specified by enclosing addresses in square brackets. Multiple
697 forwardings may be specified, and additional forwardings can be
698 given on the command line. Only the superuser can forward privi‐
699 leged ports. By default, the local port is bound in accordance
700 with the GatewayPorts setting. However, an explicit bind_address
701 may be used to bind the connection to a specific address. The
702 bind_address of localhost indicates that the listening port be
703 bound for local use only, while an empty address or ‘*’ indicates
704 that the port should be available from all interfaces.
705 LogLevel
707 Gives the verbosity level that is used when logging messages from
708 ssh(1). The possible values are: QUIET, FATAL, ERROR, INFO, VER‐
709 BOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3. The default is INFO.
710 DEBUG and DEBUG1 are equivalent. DEBUG2 and DEBUG3 each specify
711 higher levels of verbose output.
712 MACs Specifies the MAC (message authentication code) algorithms in
714 order of preference. The MAC algorithm is used for data
715 integrity protection. Multiple algorithms must be comma-sepa‐
716 rated. If the specified value begins with a ‘+’ character, then
717 the specified algorithms will be appended to the default set
718 instead of replacing them. If the specified value begins with a
719 ‘-’ character, then the specified algorithms (including wild‐
720 cards) will be removed from the default set instead of replacing
721 them.
722 The algorithms that contain "-etm" calculate the MAC after
724 encryption (encrypt-then-mac). These are considered safer and
725 their use recommended.
726 The default is:
728 umac-64-etm@openssh.com,umac-128-etm@openssh.com,
730 hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,
731 hmac-sha1-etm@openssh.com,
732 umac-64@openssh.com,umac-128@openssh.com,
733 hmac-sha2-256,hmac-sha2-512,hmac-sha1
734 The list of available MAC algorithms may also be obtained using
736 "ssh -Q mac".
737 NoHostAuthenticationForLocalhost
739 Disable host authentication for localhost (loopback addresses).
740 The argument to this keyword must be yes or no (the default).
741 NumberOfPasswordPrompts
743 Specifies the number of password prompts before giving up. The
744 argument to this keyword must be an integer. The default is 3.
745 PasswordAuthentication
747 Specifies whether to use password authentication. The argument
748 to this keyword must be yes (the default) or no.
749 PermitLocalCommand
751 Allow local command execution via the LocalCommand option or
752 using the !command escape sequence in ssh(1). The argument must
753 be yes or no (the default).
754 PKCS11Provider
756 Specifies which PKCS#11 provider to use. The argument to this
757 keyword is the PKCS#11 shared library ssh(1) should use to commu‐
758 nicate with a PKCS#11 token providing the user's private RSA key.
759 Port Specifies the port number to connect on the remote host. The
761 default is 22.
762 PreferredAuthentications
764 Specifies the order in which the client should try authentication
765 methods. This allows a client to prefer one method (e.g.
766 keyboard-interactive) over another method (e.g. password). The
767 default is:
768 gssapi-keyex,gssapi-with-mic,hostbased,publickey,
770 keyboard-interactive,password
771 ProxyCommand
773 Specifies the command to use to connect to the server. The com‐
774 mand string extends to the end of the line, and is executed using
775 the user's shell ‘exec’ directive to avoid a lingering shell
776 process.
777 Arguments to ProxyCommand accept the tokens described in the
779 TOKENS section. The command can be basically anything, and
780 should read from its standard input and write to its standard
781 output. It should eventually connect an sshd(8) server running
782 on some machine, or execute sshd -i somewhere. Host key manage‐
783 ment will be done using the HostName of the host being connected
784 (defaulting to the name typed by the user). Setting the command
785 to none disables this option entirely. Note that CheckHostIP is
786 not available for connects with a proxy command.
787 This directive is useful in conjunction with nc(1) and its proxy
789 support. For example, the following directive would connect via
790 an HTTP proxy at 192.0.2.0:
791 ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
793 ProxyJump
795 Specifies one or more jump proxies as either [user@]host[:port]
796 or an ssh URI. Multiple proxies may be separated by comma char‐
797 acters and will be visited sequentially. Setting this option
798 will cause ssh(1) to connect to the target host by first making a
799 ssh(1) connection to the specified ProxyJump host and then estab‐
800 lishing a TCP forwarding to the ultimate target from there.
801 Note that this option will compete with the ProxyCommand option -
803 whichever is specified first will prevent later instances of the
804 other from taking effect.
805 ProxyUseFdpass
807 Specifies that ProxyCommand will pass a connected file descriptor
808 back to ssh(1) instead of continuing to execute and pass data.
809 The default is no.
810 PubkeyAcceptedKeyTypes
812 Specifies the key types that will be used for public key authen‐
813 tication as a comma-separated list of patterns. Alternately if
814 the specified value begins with a ‘+’ character, then the key
815 types after it will be appended to the default instead of replac‐
816 ing it. If the specified value begins with a ‘-’ character, then
817 the specified key types (including wildcards) will be removed
818 from the default set instead of replacing them. The default for
819 this option is:
820 ecdsa-sha2-nistp256-cert-v01@openssh.com,
822 ecdsa-sha2-nistp384-cert-v01@openssh.com,
823 ecdsa-sha2-nistp521-cert-v01@openssh.com,
824 ssh-ed25519-cert-v01@openssh.com,
825 rsa-sha2-512-cert-v01@openssh.com,rsa-sha2-256-cert-v01@openssh.com,
826 ssh-rsa-cert-v01@openssh.com,
827 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
828 ssh-ed25519,rsa-sha2-512,rsa-sha2-256,ssh-rsa
829 The list of available key types may also be obtained using "ssh
831 -Q key".
832 PubkeyAuthentication
834 Specifies whether to try public key authentication. The argument
835 to this keyword must be yes (the default) or no.
836 RekeyLimit
838 Specifies the maximum amount of data that may be transmitted
839 before the session key is renegotiated, optionally followed a
840 maximum amount of time that may pass before the session key is
841 renegotiated. The first argument is specified in bytes and may
842 have a suffix of ‘K’, ‘M’, or ‘G’ to indicate Kilobytes,
843 Megabytes, or Gigabytes, respectively. The default is between
844 ‘1G’ and ‘4G’, depending on the cipher. The optional second
845 value is specified in seconds and may use any of the units docu‐
846 mented in the TIME FORMATS section of sshd_config(5). The
847 default value for RekeyLimit is default none, which means that
848 rekeying is performed after the cipher's default amount of data
849 has been sent or received and no time based rekeying is done.
850 RemoteCommand
852 Specifies a command to execute on the remote machine after suc‐
853 cessfully connecting to the server. The command string extends
854 to the end of the line, and is executed with the user's shell.
855 Arguments to RemoteCommand accept the tokens described in the
856 TOKENS section.
857 RemoteForward
859 Specifies that a TCP port on the remote machine be forwarded over
860 the secure channel. The remote port may either be forwarded to a
861 specified host and port from the local machine, or may act as a
862 SOCKS 4/5 proxy that allows a remote client to connect to arbi‐
863 trary destinations from the local machine. The first argument
864 must be [bind_address:]port If forwarding to a specific destina‐
865 tion then the second argument must be host:hostport, otherwise if
866 no destination argument is specified then the remote forwarding
867 will be established as a SOCKS proxy.
868 IPv6 addresses can be specified by enclosing addresses in square
870 brackets. Multiple forwardings may be specified, and additional
871 forwardings can be given on the command line. Privileged ports
872 can be forwarded only when logging in as root on the remote
873 machine.
874 If the port argument is 0, the listen port will be dynamically
876 allocated on the server and reported to the client at run time.
877 If the bind_address is not specified, the default is to only bind
879 to loopback addresses. If the bind_address is ‘*’ or an empty
880 string, then the forwarding is requested to listen on all inter‐
881 faces. Specifying a remote bind_address will only succeed if the
882 server's GatewayPorts option is enabled (see sshd_config(5)).
883 RequestTTY
885 Specifies whether to request a pseudo-tty for the session. The
886 argument may be one of: no (never request a TTY), yes (always
887 request a TTY when standard input is a TTY), force (always
888 request a TTY) or auto (request a TTY when opening a login ses‐
889 sion). This option mirrors the -t and -T flags for ssh(1).
890 RevokedHostKeys
892 Specifies revoked host public keys. Keys listed in this file
893 will be refused for host authentication. Note that if this file
894 does not exist or is not readable, then host authentication will
895 be refused for all hosts. Keys may be specified as a text file,
896 listing one public key per line, or as an OpenSSH Key Revocation
897 List (KRL) as generated by ssh-keygen(1). For more information
898 on KRLs, see the KEY REVOCATION LISTS section in ssh-keygen(1).
899 SendEnv
901 Specifies what variables from the local environ(7) should be sent
902 to the server. The server must also support it, and the server
903 must be configured to accept these environment variables. Note
904 that the TERM environment variable is always sent whenever a
905 pseudo-terminal is requested as it is required by the protocol.
906 Refer to AcceptEnv in sshd_config(5) for how to configure the
907 server. Variables are specified by name, which may contain wild‐
908 card characters. Multiple environment variables may be separated
909 by whitespace or spread across multiple SendEnv directives.
910 See PATTERNS for more information on patterns.
912 It is possible to clear previously set SendEnv variable names by
914 prefixing patterns with -. The default is not to send any envi‐
915 ronment variables.
916 ServerAliveCountMax
918 Sets the number of server alive messages (see below) which may be
919 sent without ssh(1) receiving any messages back from the server.
920 If this threshold is reached while server alive messages are
921 being sent, ssh will disconnect from the server, terminating the
922 session. It is important to note that the use of server alive
923 messages is very different from TCPKeepAlive (below). The server
924 alive messages are sent through the encrypted channel and there‐
925 fore will not be spoofable. The TCP keepalive option enabled by
926 TCPKeepAlive is spoofable. The server alive mechanism is valu‐
927 able when the client or server depend on knowing when a connec‐
928 tion has become inactive.
929 The default value is 3. If, for example, ServerAliveInterval
931 (see below) is set to 15 and ServerAliveCountMax is left at the
932 default, if the server becomes unresponsive, ssh will disconnect
933 after approximately 45 seconds.
934 ServerAliveInterval
936 Sets a timeout interval in seconds after which if no data has
937 been received from the server, ssh(1) will send a message through
938 the encrypted channel to request a response from the server. The
939 default is 0, indicating that these messages will not be sent to
940 the server.
941 SetEnv Directly specify one or more environment variables and their con‐
943 tents to be sent to the server. Similarly to SendEnv, the server
944 must be prepared to accept the environment variable.
945 StreamLocalBindMask
947 Sets the octal file creation mode mask (umask) used when creating
948 a Unix-domain socket file for local or remote port forwarding.
949 This option is only used for port forwarding to a Unix-domain
950 socket file.
951 The default value is 0177, which creates a Unix-domain socket
953 file that is readable and writable only by the owner. Note that
954 not all operating systems honor the file mode on Unix-domain
955 socket files.
956 StreamLocalBindUnlink
958 Specifies whether to remove an existing Unix-domain socket file
959 for local or remote port forwarding before creating a new one.
960 If the socket file already exists and StreamLocalBindUnlink is
961 not enabled, ssh will be unable to forward the port to the Unix-
962 domain socket file. This option is only used for port forwarding
963 to a Unix-domain socket file.
964 The argument must be yes or no (the default).
966 StrictHostKeyChecking
968 If this flag is set to yes, ssh(1) will never automatically add
969 host keys to the ~/.ssh/known_hosts file, and refuses to connect
970 to hosts whose host key has changed. This provides maximum pro‐
971 tection against man-in-the-middle (MITM) attacks, though it can
972 be annoying when the /etc/gsissh/ssh_known_hosts file is poorly
973 maintained or when connections to new hosts are frequently made.
974 This option forces the user to manually add all new hosts.
975 If this flag is set to “accept-new” then ssh will automatically
977 add new host keys to the user known hosts files, but will not
978 permit connections to hosts with changed host keys. If this flag
979 is set to “no” or “off”, ssh will automatically add new host keys
980 to the user known hosts files and allow connections to hosts with
981 changed hostkeys to proceed, subject to some restrictions. If
982 this flag is set to ask (the default), new host keys will be
983 added to the user known host files only after the user has con‐
984 firmed that is what they really want to do, and ssh will refuse
985 to connect to hosts whose host key has changed. The host keys of
986 known hosts will be verified automatically in all cases.
987 SyslogFacility
989 Gives the facility code that is used when logging messages from
990 ssh(1). The possible values are: DAEMON, USER, AUTH, LOCAL0,
991 LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7. The
992 default is USER.
993 TCPKeepAlive
995 Specifies whether the system should send TCP keepalive messages
996 to the other side. If they are sent, death of the connection or
997 crash of one of the machines will be properly noticed. However,
998 this means that connections will die if the route is down tempo‐
999 rarily, and some people find it annoying.
1000 The default is yes (to send TCP keepalive messages), and the
1002 client will notice if the network goes down or the remote host
1003 dies. This is important in scripts, and many users want it too.
1004 To disable TCP keepalive messages, the value should be set to no.
1006 See also ServerAliveInterval for protocol-level keepalives.
1007 Tunnel Request tun(4) device forwarding between the client and the
1009 server. The argument must be yes, point-to-point (layer 3),
1010 ethernet (layer 2), or no (the default). Specifying yes requests
1011 the default tunnel mode, which is point-to-point.
1012 TunnelDevice
1014 Specifies the tun(4) devices to open on the client (local_tun)
1015 and the server (remote_tun).
1016 The argument must be local_tun[:remote_tun]. The devices may be
1018 specified by numerical ID or the keyword any, which uses the next
1019 available tunnel device. If remote_tun is not specified, it
1020 defaults to any. The default is any:any.
1021 UpdateHostKeys
1023 Specifies whether ssh(1) should accept notifications of addi‐
1024 tional hostkeys from the server sent after authentication has
1025 completed and add them to UserKnownHostsFile. The argument must
1026 be yes, no (the default) or ask. Enabling this option allows
1027 learning alternate hostkeys for a server and supports graceful
1028 key rotation by allowing a server to send replacement public keys
1029 before old ones are removed. Additional hostkeys are only
1030 accepted if the key used to authenticate the host was already
1031 trusted or explicitly accepted by the user. If UpdateHostKeys is
1032 set to ask, then the user is asked to confirm the modifications
1033 to the known_hosts file. Confirmation is currently incompatible
1034 with ControlPersist, and will be disabled if it is enabled.
1035 Presently, only sshd(8) from OpenSSH 6.8 and greater support the
1037 "hostkeys@openssh.com" protocol extension used to inform the
1038 client of all the server's hostkeys.
1039 User Specifies the user to log in as. This can be useful when a dif‐
1041 ferent user name is used on different machines. This saves the
1042 trouble of having to remember to give the user name on the com‐
1043 mand line.
1044 UserKnownHostsFile
1046 Specifies one or more files to use for the user host key data‐
1047 base, separated by whitespace. The default is
1048 ~/.ssh/known_hosts, ~/.ssh/known_hosts2.
1049 VerifyHostKeyDNS
1051 Specifies whether to verify the remote key using DNS and SSHFP
1052 resource records. If this option is set to yes, the client will
1053 implicitly trust keys that match a secure fingerprint from DNS.
1054 Insecure fingerprints will be handled as if this option was set
1055 to ask. If this option is set to ask, information on fingerprint
1056 match will be displayed, but the user will still need to confirm
1057 new host keys according to the StrictHostKeyChecking option. The
1058 default is no.
1059 See also VERIFYING HOST KEYS in ssh(1).
1061 VisualHostKey
1063 If this flag is set to yes, an ASCII art representation of the
1064 remote host key fingerprint is printed in addition to the finger‐
1065 print string at login and for unknown host keys. If this flag is
1066 set to no (the default), no fingerprint strings are printed at
1067 login and only the fingerprint string will be printed for unknown
1068 host keys.
1069 XAuthLocation
1071 Specifies the full pathname of the xauth(1) program. The default
1072 is /usr/bin/xauth.
1073
1075 A pattern consists of zero or more non-whitespace characters, ‘*’ (a
1076 wildcard that matches zero or more characters), or ‘?’ (a wildcard that
1077 matches exactly one character). For example, to specify a set of decla‐
1078 rations for any host in the ".co.uk" set of domains, the following pat‐
1079 tern could be used:
1080 Host *.co.uk
1082 The following pattern would match any host in the 192.168.0.[0-9] network
1084 range:
1085 Host 192.168.0.?
1087 A pattern-list is a comma-separated list of patterns. Patterns within
1089 pattern-lists may be negated by preceding them with an exclamation mark
1090 (‘!’). For example, to allow a key to be used from anywhere within an
1091 organization except from the "dialup" pool, the following entry (in
1092 authorized_keys) could be used:
1093 from="!*.dialup.example.com,*.example.com"
1095 Note that a negated match will never produce a positive result by itself.
1097 For example, attempting to match "host3" against the following pattern-
1098 list will fail:
1099 from="!host1,!host2"
1101 The solution here is to include a term that will yield a positive match,
1103 such as a wildcard:
1104 from="!host1,!host2,*"
1106
1108 Arguments to some keywords can make use of tokens, which are expanded at
1109 runtime:
1110 %% A literal ‘%’.
1112 %C Hash of %l%h%p%r.
1113 %d Local user's home directory.
1114 %h The remote hostname.
1115 %i The local user ID.
1116 %L The local hostname.
1117 %l The local hostname, including the domain name.
1118 %n The original remote hostname, as given on the command line.
1119 %p The remote port.
1120 %r The remote username.
1121 %T The local tun(4) or tap(4) network interface assigned if tun‐
1122 nel forwarding was requested, or "NONE" otherwise.
1123 %u The local username.
1124 Match exec accepts the tokens %%, %h, %i, %L, %l, %n, %p, %r, and %u.
1126 CertificateFile accepts the tokens %%, %d, %h, %i, %l, %r, and %u.
1128 ControlPath accepts the tokens %%, %C, %h, %i, %L, %l, %n, %p, %r, and
1130 %u.
1131 HostName accepts the tokens %% and %h.
1133 IdentityAgent and IdentityFile accept the tokens %%, %d, %h, %i, %l, %r,
1135 and %u.
1136 LocalCommand accepts the tokens %%, %C, %d, %h, %i, %l, %n, %p, %r, %T,
1138 and %u.
1139 ProxyCommand accepts the tokens %%, %h, %p, and %r.
1141 RemoteCommand accepts the tokens %%, %C, %d, %h, %i, %l, %n, %p, %r, and
1143 %u.
1144
1146 ~/.ssh/config
1147 This is the per-user configuration file. The format of this file
1148 is described above. This file is used by the SSH client.
1149 Because of the potential for abuse, this file must have strict
1150 permissions: read/write for the user, and not accessible by oth‐
1151 ers.
1152 /etc/gsissh/ssh_config
1154 Systemwide configuration file. This file provides defaults for
1155 those values that are not specified in the user's configuration
1156 file, and for those users who do not have a configuration file.
1157 This file must be world-readable.
1158
1160 ssh(1)
1161
1163 OpenSSH is a derivative of the original and free ssh 1.2.12 release by
1164 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
1165 de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
1166 ated OpenSSH. Markus Friedl contributed the support for SSH protocol
1167 versions 1.5 and 2.0.
1168BSD June 20, 2019 BSD