1SSH_CONFIG(5) BSD File Formats Manual SSH_CONFIG(5)
2
4 ssh_config — OpenSSH SSH client configuration files
5
7 ~/.ssh/config
8 /etc/ssh/ssh_config
9
11 ssh(1) obtains configuration data from the following sources in the fol‐
12 lowing order:
13 1. command-line options
15 2. user's configuration file (~/.ssh/config)
16 3. system-wide configuration file (/etc/ssh/ssh_config)
17 For each parameter, the first obtained value will be used. The configu‐
19 ration files contain sections separated by Host specifications, and that
20 section is only applied for hosts that match one of the patterns given in
21 the specification. The matched host name is usually the one given on the
22 command line (see the CanonicalizeHostname option for exceptions).
23 Since the first obtained value for each parameter is used, more host-spe‐
25 cific declarations should be given near the beginning of the file, and
26 general defaults at the end.
27 The file contains keyword-argument pairs, one per line. Lines starting
29 with ‘#’ and empty lines are interpreted as comments. Arguments may
30 optionally be enclosed in double quotes (") in order to represent argu‐
31 ments containing spaces. Configuration options may be separated by
32 whitespace or optional whitespace and exactly one ‘=’; the latter format
33 is useful to avoid the need to quote whitespace when specifying configu‐
34 ration options using the ssh, scp, and sftp -o option.
35 The possible keywords and their meanings are as follows (note that key‐
37 words are case-insensitive and arguments are case-sensitive):
38 Host Restricts the following declarations (up to the next Host or
40 Match keyword) to be only for those hosts that match one of the
41 patterns given after the keyword. If more than one pattern is
42 provided, they should be separated by whitespace. A single ‘*’
43 as a pattern can be used to provide global defaults for all
44 hosts. The host is usually the hostname argument given on the
45 command line (see the CanonicalizeHostname keyword for excep‐
46 tions).
47 A pattern entry may be negated by prefixing it with an exclama‐
49 tion mark (‘!’). If a negated entry is matched, then the Host
50 entry is ignored, regardless of whether any other patterns on the
51 line match. Negated matches are therefore useful to provide
52 exceptions for wildcard matches.
53 See PATTERNS for more information on patterns.
55 Match Restricts the following declarations (up to the next Host or
57 Match keyword) to be used only when the conditions following the
58 Match keyword are satisfied. Match conditions are specified
59 using one or more criteria or the single token all which always
60 matches. The available criteria keywords are: canonical, exec,
61 host, originalhost, user, and localuser. The all criteria must
62 appear alone or immediately after canonical. Other criteria may
63 be combined arbitrarily. All criteria but all and canonical
64 require an argument. Criteria may be negated by prepending an
65 exclamation mark (‘!’).
66 The canonical keyword matches only when the configuration file is
68 being re-parsed after hostname canonicalization (see the
69 CanonicalizeHostname option.) This may be useful to specify con‐
70 ditions that work with canonical host names only. The exec key‐
71 word executes the specified command under the user's shell. If
72 the command returns a zero exit status then the condition is con‐
73 sidered true. Commands containing whitespace characters must be
74 quoted. Arguments to exec accept the tokens described in the
75 TOKENS section.
76 The other keywords' criteria must be single entries or comma-sep‐
78 arated lists and may use the wildcard and negation operators
79 described in the PATTERNS section. The criteria for the host
80 keyword are matched against the target hostname, after any sub‐
81 stitution by the Hostname or CanonicalizeHostname options. The
82 originalhost keyword matches against the hostname as it was spec‐
83 ified on the command-line. The user keyword matches against the
84 target username on the remote host. The localuser keyword
85 matches against the name of the local user running ssh(1) (this
86 keyword may be useful in system-wide ssh_config files).
87 AddKeysToAgent
89 Specifies whether keys should be automatically added to a running
90 ssh-agent(1). If this option is set to yes and a key is loaded
91 from a file, the key and its passphrase are added to the agent
92 with the default lifetime, as if by ssh-add(1). If this option
93 is set to ask, ssh(1) will require confirmation using the
94 SSH_ASKPASS program before adding a key (see ssh-add(1) for
95 details). If this option is set to confirm, each use of the key
96 must be confirmed, as if the -c option was specified to
97 ssh-add(1). If this option is set to no, no keys are added to
98 the agent. The argument must be yes, confirm, ask, or no (the
99 default).
100 AddressFamily
102 Specifies which address family to use when connecting. Valid
103 arguments are any (the default), inet (use IPv4 only), or inet6
104 (use IPv6 only).
105 BatchMode
107 If set to yes, passphrase/password querying will be disabled.
108 This option is useful in scripts and other batch jobs where no
109 user is present to supply the password. The argument must be yes
110 or no (the default).
111 BindAddress
113 Use the specified address on the local machine as the source
114 address of the connection. Only useful on systems with more than
115 one address. Note that this option does not work if
116 UsePrivilegedPort is set to yes.
117 CanonicalDomains
119 When CanonicalizeHostname is enabled, this option specifies the
120 list of domain suffixes in which to search for the specified des‐
121 tination host.
122 CanonicalizeFallbackLocal
124 Specifies whether to fail with an error when hostname canonical‐
125 ization fails. The default, yes, will attempt to look up the
126 unqualified hostname using the system resolver's search rules. A
127 value of no will cause ssh(1) to fail instantly if
128 CanonicalizeHostname is enabled and the target hostname cannot be
129 found in any of the domains specified by CanonicalDomains.
130 CanonicalizeHostname
132 Controls whether explicit hostname canonicalization is performed.
133 The default, no, is not to perform any name rewriting and let the
134 system resolver handle all hostname lookups. If set to yes then,
135 for connections that do not use a ProxyCommand, ssh(1) will
136 attempt to canonicalize the hostname specified on the command
137 line using the CanonicalDomains suffixes and
138 CanonicalizePermittedCNAMEs rules. If CanonicalizeHostname is
139 set to always, then canonicalization is applied to proxied con‐
140 nections too.
141 If this option is enabled, then the configuration files are pro‐
143 cessed again using the new target name to pick up any new config‐
144 uration in matching Host and Match stanzas.
145 CanonicalizeMaxDots
147 Specifies the maximum number of dot characters in a hostname
148 before canonicalization is disabled. The default, 1, allows a
149 single dot (i.e. hostname.subdomain).
150 CanonicalizePermittedCNAMEs
152 Specifies rules to determine whether CNAMEs should be followed
153 when canonicalizing hostnames. The rules consist of one or more
154 arguments of source_domain_list:target_domain_list, where
155 source_domain_list is a pattern-list of domains that may follow
156 CNAMEs in canonicalization, and target_domain_list is a pattern-
157 list of domains that they may resolve to.
158 For example, "*.a.example.com:*.b.example.com,*.c.example.com"
160 will allow hostnames matching "*.a.example.com" to be canonical‐
161 ized to names in the "*.b.example.com" or "*.c.example.com"
162 domains.
163 CertificateFile
165 Specifies a file from which the user's certificate is read. A
166 corresponding private key must be provided separately in order to
167 use this certificate either from an IdentityFile directive or -i
168 flag to ssh(1), via ssh-agent(1), or via a PKCS11Provider.
169 Arguments to CertificateFile may use the tilde syntax to refer to
171 a user's home directory or the tokens described in the TOKENS
172 section.
173 It is possible to have multiple certificate files specified in
175 configuration files; these certificates will be tried in
176 sequence. Multiple CertificateFile directives will add to the
177 list of certificates used for authentication.
178 ChallengeResponseAuthentication
180 Specifies whether to use challenge-response authentication. The
181 argument to this keyword must be yes (the default) or no.
182 CheckHostIP
184 If set to yes (the default), ssh(1) will additionally check the
185 host IP address in the known_hosts file. This allows it to
186 detect if a host key changed due to DNS spoofing and will add
187 addresses of destination hosts to ~/.ssh/known_hosts in the
188 process, regardless of the setting of StrictHostKeyChecking. If
189 the option is set to no, the check will not be executed.
190 Cipher Specifies the cipher to use for encrypting the session in proto‐
192 col version 1. Currently, blowfish, 3des (the default), and des
193 are supported, though des is only supported in the ssh(1) client
194 for interoperability with legacy protocol 1 implementations; its
195 use is strongly discouraged due to cryptographic weaknesses.
196 Ciphers
198 Specifies the ciphers allowed for protocol version 2 in order of
199 preference. Multiple ciphers must be comma-separated. If the
200 specified value begins with a ‘+’ character, then the specified
201 ciphers will be appended to the default set instead of replacing
202 them.
203 The supported ciphers are:
205 3des-cbc
207 aes128-cbc
208 aes192-cbc
209 aes256-cbc
210 aes128-ctr
211 aes192-ctr
212 aes256-ctr
213 aes128-gcm@openssh.com
214 aes256-gcm@openssh.com
215 arcfour
216 arcfour128
217 arcfour256
218 blowfish-cbc
219 cast128-cbc
220 chacha20-poly1305@openssh.com
221 The default is:
223 chacha20-poly1305@openssh.com,
225 aes128-ctr,aes192-ctr,aes256-ctr,
226 aes128-gcm@openssh.com,aes256-gcm@openssh.com,
227 aes128-cbc,aes192-cbc,aes256-cbc
228 The list of available ciphers may also be obtained using "ssh -Q
230 cipher".
231 ClearAllForwardings
233 Specifies that all local, remote, and dynamic port forwardings
234 specified in the configuration files or on the command line be
235 cleared. This option is primarily useful when used from the
236 ssh(1) command line to clear port forwardings set in configura‐
237 tion files, and is automatically set by scp(1) and sftp(1). The
238 argument must be yes or no (the default).
239 Compression
241 Specifies whether to use compression. The argument must be yes
242 or no (the default).
243 CompressionLevel
245 Specifies the compression level to use if compression is enabled.
246 The argument must be an integer from 1 (fast) to 9 (slow, best).
247 The default level is 6, which is good for most applications. The
248 meaning of the values is the same as in gzip(1). Note that this
249 option applies to protocol version 1 only.
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/ssh/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 algorithms used when displaying key finger‐
359 prints. Valid options are: md5 and sha256. The default is
360 sha256 md5.
361 ForwardAgent
363 Specifies whether the connection to the authentication agent (if
364 any) will be forwarded to the remote machine. The argument must
365 be yes or no (the default).
366 Agent forwarding should be enabled with caution. Users with the
368 ability to bypass file permissions on the remote host (for the
369 agent's Unix-domain socket) can access the local agent through
370 the forwarded connection. An attacker cannot obtain key material
371 from the agent, however they can perform operations on the keys
372 that enable them to authenticate using the identities loaded into
373 the agent.
374 ForwardX11
376 Specifies whether X11 connections will be automatically redi‐
377 rected over the secure channel and DISPLAY set. The argument
378 must be yes or no (the default).
379 X11 forwarding should be enabled with caution. Users with the
381 ability to bypass file permissions on the remote host (for the
382 user's X11 authorization database) can access the local X11 dis‐
383 play through the forwarded connection. An attacker may then be
384 able to perform activities such as keystroke monitoring if the
385 ForwardX11Trusted option is also enabled.
386 ForwardX11Timeout
388 Specify a timeout for untrusted X11 forwarding using the format
389 described in the TIME FORMATS section of sshd_config(5). X11
390 connections received by ssh(1) after this time will be refused.
391 The default is to disable untrusted X11 forwarding after twenty
392 minutes has elapsed.
393 ForwardX11Trusted
395 If this option is set to yes, remote X11 clients will have full
396 access to the original X11 display.
397 If this option is set to no (the default), remote X11 clients
399 will be considered untrusted and prevented from stealing or tam‐
400 pering with data belonging to trusted X11 clients. Furthermore,
401 the xauth(1) token used for the session will be set to expire
402 after 20 minutes. Remote clients will be refused access after
403 this time.
404 See the X11 SECURITY extension specification for full details on
406 the restrictions imposed on untrusted clients.
407 GatewayPorts
409 Specifies whether remote hosts are allowed to connect to local
410 forwarded ports. By default, ssh(1) binds local port forwardings
411 to the loopback address. This prevents other remote hosts from
412 connecting to forwarded ports. GatewayPorts can be used to spec‐
413 ify that ssh should bind local port forwardings to the wildcard
414 address, thus allowing remote hosts to connect to forwarded
415 ports. The argument must be yes or no (the default).
416 GlobalKnownHostsFile
418 Specifies one or more files to use for the global host key data‐
419 base, separated by whitespace. The default is
420 /etc/ssh/ssh_known_hosts, /etc/ssh/ssh_known_hosts2.
421 GSSAPIAuthentication
423 Specifies whether user authentication based on GSSAPI is allowed.
424 The default is no.
425 GSSAPIClientIdentity
427 If set, specifies the GSSAPI client identity that ssh should use
428 when connecting to the server. The default is unset, which means
429 that the default identity will be used.
430 GSSAPIDelegateCredentials
432 Forward (delegate) credentials to the server. The default is no.
433 GSSAPIKeyExchange
435 Specifies whether key exchange based on GSSAPI may be used. When
436 using GSSAPI key exchange the server need not have a host key.
437 The default is “no”.
438 GSSAPIRenewalForcesRekey
440 If set to “yes” then renewal of the client's GSSAPI credentials
441 will force the rekeying of the ssh connection. With a compatible
442 server, this can delegate the renewed credentials to a session on
443 the server. The default is “no”.
444 GSSAPIServerIdentity
446 If set, specifies the GSSAPI server identity that ssh should
447 expect when connecting to the server. The default is unset, which
448 means that the expected GSSAPI server identity will be determined
449 from the target hostname.
450 GSSAPITrustDns
452 Set to “yes to indicate that the DNS is trusted to securely
453 canonicalize” the name of the host being connected to. If “no,
454 the hostname entered on the” command line will be passed
455 untouched to the GSSAPI library. The default is “no”.
456 GSSAPIKexAlgorithms
458 The list of key exchange algorithms that are offered for GSSAPI
459 key exchange. Possible values are
460 gss-gex-sha1-,
462 gss-group1-sha1-,
463 gss-group14-sha1-
464 The default is
466 “gss-gex-sha1-,gss-group1-sha1-,gss-group14-sha1-”. This option
467 only applies to protocol version 2 connections using GSSAPI.
468 HashKnownHosts
470 Indicates that ssh(1) should hash host names and addresses when
471 they are added to ~/.ssh/known_hosts. These hashed names may be
472 used normally by ssh(1) and sshd(8), but they do not reveal iden‐
473 tifying information should the file's contents be disclosed. The
474 default is no. Note that existing names and addresses in known
475 hosts files will not be converted automatically, but may be manu‐
476 ally hashed using ssh-keygen(1).
477 HostbasedAuthentication
479 Specifies whether to try rhosts based authentication with public
480 key authentication. The argument must be yes or no (the
481 default).
482 HostbasedKeyTypes
484 Specifies the key types that will be used for hostbased authenti‐
485 cation as a comma-separated pattern list. Alternately if the
486 specified value begins with a ‘+’ character, then the specified
487 key types will be appended to the default set instead of replac‐
488 ing them. The default for this option is:
489 ecdsa-sha2-nistp256-cert-v01@openssh.com,
491 ecdsa-sha2-nistp384-cert-v01@openssh.com,
492 ecdsa-sha2-nistp521-cert-v01@openssh.com,
493 ssh-ed25519-cert-v01@openssh.com,
494 ssh-rsa-cert-v01@openssh.com,
495 ssh-dss-cert-v01@openssh.com,
496 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
497 ssh-ed25519,ssh-rsa,ssh-dss
498 The -Q option of ssh(1) may be used to list supported key types.
500 HostKeyAlgorithms
502 Specifies the host key algorithms that the client wants to use in
503 order of preference. Alternately if the specified value begins
504 with a ‘+’ character, then the specified key types will be
505 appended to the default set instead of replacing them. The
506 default for this option is:
507 ecdsa-sha2-nistp256-cert-v01@openssh.com,
509 ecdsa-sha2-nistp384-cert-v01@openssh.com,
510 ecdsa-sha2-nistp521-cert-v01@openssh.com,
511 ssh-ed25519-cert-v01@openssh.com,
512 ssh-rsa-cert-v01@openssh.com,
513 ssh-dss-cert-v01@openssh.com,
514 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
515 ssh-ed25519,ssh-rsa,ssh-dss
516 If hostkeys are known for the destination host then this default
518 is modified to prefer their algorithms.
519 The list of available key types may also be obtained using "ssh
521 -Q key".
522 HostKeyAlias
524 Specifies an alias that should be used instead of the real host
525 name when looking up or saving the host key in the host key data‐
526 base files. This option is useful for tunneling SSH connections
527 or for multiple servers running on a single host.
528 HostName
530 Specifies the real host name to log into. This can be used to
531 specify nicknames or abbreviations for hosts. Arguments to
532 HostName accept the tokens described in the TOKENS section.
533 Numeric IP addresses are also permitted (both on the command line
534 and in HostName specifications). The default is the name given
535 on the command line.
536 IdentitiesOnly
538 Specifies that ssh(1) should only use the authentication identity
539 and certificate files explicitly configured in the ssh_config
540 files or passed on the ssh(1) command-line, even if ssh-agent(1)
541 or a PKCS11Provider offers more identities. The argument to this
542 keyword must be yes or no (the default). This option is intended
543 for situations where ssh-agent offers many different identities.
544 IdentityAgent
546 Specifies the UNIX-domain socket used to communicate with the
547 authentication agent.
548 This option overrides the SSH_AUTH_SOCK environment variable and
550 can be used to select a specific agent. Setting the socket name
551 to none disables the use of an authentication agent. If the
552 string "SSH_AUTH_SOCK" is specified, the location of the socket
553 will be read from the SSH_AUTH_SOCK environment variable.
554 Arguments to IdentityAgent may use the tilde syntax to refer to a
556 user's home directory or the tokens described in the TOKENS sec‐
557 tion.
558 IdentityFile
560 Specifies a file from which the user's DSA, ECDSA, Ed25519 or RSA
561 authentication identity is read. The default is ~/.ssh/identity
562 for protocol version 1, and ~/.ssh/id_dsa, ~/.ssh/id_ecdsa,
563 ~/.ssh/id_ed25519 and ~/.ssh/id_rsa for protocol version 2.
564 Additionally, any identities represented by the authentication
565 agent will be used for authentication unless IdentitiesOnly is
566 set. If no certificates have been explicitly specified by
567 CertificateFile, ssh(1) will try to load certificate information
568 from the filename obtained by appending -cert.pub to the path of
569 a specified IdentityFile.
570 Arguments to IdentityFile may use the tilde syntax to refer to a
572 user's home directory or the tokens described in the TOKENS sec‐
573 tion.
574 It is possible to have multiple identity files specified in con‐
576 figuration files; all these identities will be tried in sequence.
577 Multiple IdentityFile directives will add to the list of identi‐
578 ties tried (this behaviour differs from that of other configura‐
579 tion directives).
580 IdentityFile may be used in conjunction with IdentitiesOnly to
582 select which identities in an agent are offered during authenti‐
583 cation. IdentityFile may also be used in conjunction with
584 CertificateFile in order to provide any certificate also needed
585 for authentication with the identity.
586 IgnoreUnknown
588 Specifies a pattern-list of unknown options to be ignored if they
589 are encountered in configuration parsing. This may be used to
590 suppress errors if ssh_config contains options that are unrecog‐
591 nised by ssh(1). It is recommended that IgnoreUnknown be listed
592 early in the configuration file as it will not be applied to
593 unknown options that appear before it.
594 Include
596 Include the specified configuration file(s). Multiple pathnames
597 may be specified and each pathname may contain glob(3) wildcards
598 and, for user configurations, shell-like ‘~’ references to user
599 home directories. Files without absolute paths are assumed to be
600 in ~/.ssh if included in a user configuration file or /etc/ssh if
601 included from the system configuration file. Include directive
602 may appear inside a Match or Host block to perform conditional
603 inclusion.
604 IPQoS Specifies the IPv4 type-of-service or DSCP class for connections.
606 Accepted values are af11, af12, af13, af21, af22, af23, af31,
607 af32, af33, af41, af42, af43, cs0, cs1, cs2, cs3, cs4, cs5, cs6,
608 cs7, ef, lowdelay, throughput, reliability, or a numeric value.
609 This option may take one or two arguments, separated by white‐
610 space. If one argument is specified, it is used as the packet
611 class unconditionally. If two values are specified, the first is
612 automatically selected for interactive sessions and the second
613 for non-interactive sessions. The default is lowdelay for inter‐
614 active sessions and throughput for non-interactive sessions.
615 KbdInteractiveAuthentication
617 Specifies whether to use keyboard-interactive authentication.
618 The argument to this keyword must be yes (the default) or no.
619 KbdInteractiveDevices
621 Specifies the list of methods to use in keyboard-interactive
622 authentication. Multiple method names must be comma-separated.
623 The default is to use the server specified list. The methods
624 available vary depending on what the server supports. For an
625 OpenSSH server, it may be zero or more of: bsdauth, pam, and
626 skey.
627 KexAlgorithms
629 Specifies the available KEX (Key Exchange) algorithms. Multiple
630 algorithms must be comma-separated. Alternately if the specified
631 value begins with a ‘+’ character, then the specified methods
632 will be appended to the default set instead of replacing them.
633 The default is:
634 curve25519-sha256,curve25519-sha256@libssh.org,
636 ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,
637 diffie-hellman-group-exchange-sha256,
638 diffie-hellman-group-exchange-sha1,
639 diffie-hellman-group14-sha1,
640 diffie-hellman-group1-sha1
641 The list of available key exchange algorithms may also be
643 obtained using "ssh -Q kex".
644 LocalCommand
646 Specifies a command to execute on the local machine after suc‐
647 cessfully connecting to the server. The command string extends
648 to the end of the line, and is executed with the user's shell.
649 Arguments to LocalCommand accept the tokens described in the
650 TOKENS section.
651 The command is run synchronously and does not have access to the
653 session of the ssh(1) that spawned it. It should not be used for
654 interactive commands.
655 This directive is ignored unless PermitLocalCommand has been
657 enabled.
658 LocalForward
660 Specifies that a TCP port on the local machine be forwarded over
661 the secure channel to the specified host and port from the remote
662 machine. The first argument must be [bind_address:]port and the
663 second argument must be host:hostport. IPv6 addresses can be
664 specified by enclosing addresses in square brackets. Multiple
665 forwardings may be specified, and additional forwardings can be
666 given on the command line. Only the superuser can forward privi‐
667 leged ports. By default, the local port is bound in accordance
668 with the GatewayPorts setting. However, an explicit bind_address
669 may be used to bind the connection to a specific address. The
670 bind_address of localhost indicates that the listening port be
671 bound for local use only, while an empty address or ‘*’ indicates
672 that the port should be available from all interfaces.
673 LogLevel
675 Gives the verbosity level that is used when logging messages from
676 ssh(1). The possible values are: QUIET, FATAL, ERROR, INFO, VER‐
677 BOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3. The default is INFO.
678 DEBUG and DEBUG1 are equivalent. DEBUG2 and DEBUG3 each specify
679 higher levels of verbose output.
680 MACs Specifies the MAC (message authentication code) algorithms in
682 order of preference. The MAC algorithm is used for data
683 integrity protection. Multiple algorithms must be comma-sepa‐
684 rated. If the specified value begins with a ‘+’ character, then
685 the specified algorithms will be appended to the default set
686 instead of replacing them.
687 The algorithms that contain "-etm" calculate the MAC after
689 encryption (encrypt-then-mac). These are considered safer and
690 their use recommended.
691 The default is:
693 umac-64-etm@openssh.com,umac-128-etm@openssh.com,
695 hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,
696 hmac-sha1-etm@openssh.com,
697 umac-64@openssh.com,umac-128@openssh.com,
698 hmac-sha2-256,hmac-sha2-512,hmac-sha1
699 The list of available MAC algorithms may also be obtained using
701 "ssh -Q mac".
702 NoHostAuthenticationForLocalhost
704 This option can be used if the home directory is shared across
705 machines. In this case localhost will refer to a different
706 machine on each of the machines and the user will get many warn‐
707 ings about changed host keys. However, this option disables host
708 authentication for localhost. The argument to this keyword must
709 be yes or no. (the default).
710 NumberOfPasswordPrompts
712 Specifies the number of password prompts before giving up. The
713 argument to this keyword must be an integer. The default is 3.
714 PasswordAuthentication
716 Specifies whether to use password authentication. The argument
717 to this keyword must be yes (the default) or no.
718 PermitLocalCommand
720 Allow local command execution via the LocalCommand option or
721 using the !command escape sequence in ssh(1). The argument must
722 be yes or no (the default).
723 PKCS11Provider
725 Specifies which PKCS#11 provider to use. The argument to this
726 keyword is the PKCS#11 shared library ssh(1) should use to commu‐
727 nicate with a PKCS#11 token providing the user's private RSA key.
728 Port Specifies the port number to connect on the remote host. The
730 default is 22.
731 PreferredAuthentications
733 Specifies the order in which the client should try authentication
734 methods. This allows a client to prefer one method (e.g.
735 keyboard-interactive) over another method (e.g. password). The
736 default is:
737 gssapi-with-mic,hostbased,publickey,
739 keyboard-interactive,password
740 Protocol
742 Specifies the protocol versions ssh(1) should support in order of
743 preference. The possible values are 1 and 2. Multiple versions
744 must be comma-separated. When this option is set to 2,1 ssh will
745 try version 2 and fall back to version 1 if version 2 is not
746 available. The default is version 2. Protocol 1 suffers from a
747 number of cryptographic weaknesses and should not be used. It is
748 only offered to support legacy devices.
749 ProxyCommand
751 Specifies the command to use to connect to the server. The com‐
752 mand string extends to the end of the line, and is executed using
753 the user's shell ‘exec’ directive to avoid a lingering shell
754 process.
755 Arguments to ProxyCommand accept the tokens described in the
757 TOKENS section. The command can be basically anything, and
758 should read from its standard input and write to its standard
759 output. It should eventually connect an sshd(8) server running
760 on some machine, or execute sshd -i somewhere. Host key manage‐
761 ment will be done using the HostName of the host being connected
762 (defaulting to the name typed by the user). Setting the command
763 to none disables this option entirely. Note that CheckHostIP is
764 not available for connects with a proxy command.
765 This directive is useful in conjunction with nc(1) and its proxy
767 support. For example, the following directive would connect via
768 an HTTP proxy at 192.0.2.0:
769 ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
771 ProxyJump
773 Specifies one or more jump proxies as [user@]host[:port]. Multi‐
774 ple proxies may be separated by comma characters and will be vis‐
775 ited sequentially. Setting this option will cause ssh(1) to con‐
776 nect to the target host by first making a ssh(1) connection to
777 the specified ProxyJump host and then establishing a TCP forward‐
778 ing to the ultimate target from there.
779 Note that this option will compete with the ProxyCommand option -
781 whichever is specified first will prevent later instances of the
782 other from taking effect.
783 ProxyUseFdpass
785 Specifies that ProxyCommand will pass a connected file descriptor
786 back to ssh(1) instead of continuing to execute and pass data.
787 The default is no.
788 PubkeyAcceptedKeyTypes
790 Specifies the key types that will be used for public key authen‐
791 tication as a comma-separated pattern list. Alternately if the
792 specified value begins with a ‘+’ character, then the key types
793 after it will be appended to the default instead of replacing it.
794 The default for this option is:
795 ecdsa-sha2-nistp256-cert-v01@openssh.com,
797 ecdsa-sha2-nistp384-cert-v01@openssh.com,
798 ecdsa-sha2-nistp521-cert-v01@openssh.com,
799 ssh-ed25519-cert-v01@openssh.com,
800 ssh-rsa-cert-v01@openssh.com,
801 ssh-dss-cert-v01@openssh.com,
802 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
803 ssh-ed25519,ssh-rsa,ssh-dsa
804 The list of available key types may also be obtained using "ssh
806 -Q key".
807 PubkeyAuthentication
809 Specifies whether to try public key authentication. The argument
810 to this keyword must be yes (the default) or no.
811 RekeyLimit
813 Specifies the maximum amount of data that may be transmitted
814 before the session key is renegotiated, optionally followed a
815 maximum amount of time that may pass before the session key is
816 renegotiated. The first argument is specified in bytes and may
817 have a suffix of ‘K’, ‘M’, or ‘G’ to indicate Kilobytes,
818 Megabytes, or Gigabytes, respectively. The default is between
819 ‘1G’ and ‘4G’, depending on the cipher. The optional second
820 value is specified in seconds and may use any of the units docu‐
821 mented in the TIME FORMATS section of sshd_config(5). The
822 default value for RekeyLimit is default none, which means that
823 rekeying is performed after the cipher's default amount of data
824 has been sent or received and no time based rekeying is done.
825 RemoteForward
827 Specifies that a TCP port on the remote machine be forwarded over
828 the secure channel to the specified host and port from the local
829 machine. The first argument must be [bind_address:]port and the
830 second argument must be host:hostport. IPv6 addresses can be
831 specified by enclosing addresses in square brackets. Multiple
832 forwardings may be specified, and additional forwardings can be
833 given on the command line. Privileged ports can be forwarded
834 only when logging in as root on the remote machine.
835 If the port argument is 0, the listen port will be dynamically
837 allocated on the server and reported to the client at run time.
838 If the bind_address is not specified, the default is to only bind
840 to loopback addresses. If the bind_address is ‘*’ or an empty
841 string, then the forwarding is requested to listen on all inter‐
842 faces. Specifying a remote bind_address will only succeed if the
843 server's GatewayPorts option is enabled (see sshd_config(5)).
844 RequestTTY
846 Specifies whether to request a pseudo-tty for the session. The
847 argument may be one of: no (never request a TTY), yes (always
848 request a TTY when standard input is a TTY), force (always
849 request a TTY) or auto (request a TTY when opening a login ses‐
850 sion). This option mirrors the -t and -T flags for ssh(1).
851 RevokedHostKeys
853 Specifies revoked host public keys. Keys listed in this file
854 will be refused for host authentication. Note that if this file
855 does not exist or is not readable, then host authentication will
856 be refused for all hosts. Keys may be specified as a text file,
857 listing one public key per line, or as an OpenSSH Key Revocation
858 List (KRL) as generated by ssh-keygen(1). For more information
859 on KRLs, see the KEY REVOCATION LISTS section in ssh-keygen(1).
860 RhostsRSAAuthentication
862 Specifies whether to try rhosts based authentication with RSA
863 host authentication. The argument must be yes or no (the
864 default). This option applies to protocol version 1 only and
865 requires ssh(1) to be setuid root.
866 RSAAuthentication
868 Specifies whether to try RSA authentication. The argument to
869 this keyword must be yes (the default) or no. RSA authentication
870 will only be attempted if the identity file exists, or an authen‐
871 tication agent is running. Note that this option applies to pro‐
872 tocol version 1 only.
873 SendEnv
875 Specifies what variables from the local environ(7) should be sent
876 to the server. The server must also support it, and the server
877 must be configured to accept these environment variables. Note
878 that the TERM environment variable is always sent whenever a
879 pseudo-terminal is requested as it is required by the protocol.
880 Refer to AcceptEnv in sshd_config(5) for how to configure the
881 server. Variables are specified by name, which may contain wild‐
882 card characters. Multiple environment variables may be separated
883 by whitespace or spread across multiple SendEnv directives. The
884 default is not to send any environment variables.
885 See PATTERNS for more information on patterns.
887 ServerAliveCountMax
889 Sets the number of server alive messages (see below) which may be
890 sent without ssh(1) receiving any messages back from the server.
891 If this threshold is reached while server alive messages are
892 being sent, ssh will disconnect from the server, terminating the
893 session. It is important to note that the use of server alive
894 messages is very different from TCPKeepAlive (below). The server
895 alive messages are sent through the encrypted channel and there‐
896 fore will not be spoofable. The TCP keepalive option enabled by
897 TCPKeepAlive is spoofable. The server alive mechanism is valu‐
898 able when the client or server depend on knowing when a connec‐
899 tion has become inactive.
900 The default value is 3. If, for example, ServerAliveInterval
902 (see below) is set to 15 and ServerAliveCountMax is left at the
903 default, if the server becomes unresponsive, ssh will disconnect
904 after approximately 45 seconds.
905 ServerAliveInterval
907 Sets a timeout interval in seconds after which if no data has
908 been received from the server, ssh(1) will send a message through
909 the encrypted channel to request a response from the server. The
910 default is 0, indicating that these messages will not be sent to
911 the server.
912 StreamLocalBindMask
914 Sets the octal file creation mode mask (umask) used when creating
915 a Unix-domain socket file for local or remote port forwarding.
916 This option is only used for port forwarding to a Unix-domain
917 socket file.
918 The default value is 0177, which creates a Unix-domain socket
920 file that is readable and writable only by the owner. Note that
921 not all operating systems honor the file mode on Unix-domain
922 socket files.
923 StreamLocalBindUnlink
925 Specifies whether to remove an existing Unix-domain socket file
926 for local or remote port forwarding before creating a new one.
927 If the socket file already exists and StreamLocalBindUnlink is
928 not enabled, ssh will be unable to forward the port to the Unix-
929 domain socket file. This option is only used for port forwarding
930 to a Unix-domain socket file.
931 The argument must be yes or no (the default).
933 StrictHostKeyChecking
935 If this flag is set to yes, ssh(1) will never automatically add
936 host keys to the ~/.ssh/known_hosts file, and refuses to connect
937 to hosts whose host key has changed. This provides maximum pro‐
938 tection against trojan horse attacks, though it can be annoying
939 when the /etc/ssh/ssh_known_hosts file is poorly maintained or
940 when connections to new hosts are frequently made. This option
941 forces the user to manually add all new hosts. If this flag is
942 set to no, ssh will automatically add new host keys to the user
943 known hosts files. If this flag is set to ask (the default), new
944 host keys will be added to the user known host files only after
945 the user has confirmed that is what they really want to do, and
946 ssh will refuse to connect to hosts whose host key has changed.
947 The host keys of known hosts will be verified automatically in
948 all cases.
949 TCPKeepAlive
951 Specifies whether the system should send TCP keepalive messages
952 to the other side. If they are sent, death of the connection or
953 crash of one of the machines will be properly noticed. However,
954 this means that connections will die if the route is down tempo‐
955 rarily, and some people find it annoying.
956 The default is yes (to send TCP keepalive messages), and the
958 client will notice if the network goes down or the remote host
959 dies. This is important in scripts, and many users want it too.
960 To disable TCP keepalive messages, the value should be set to no.
962 Tunnel Request tun(4) device forwarding between the client and the
964 server. The argument must be yes, point-to-point (layer 3),
965 ethernet (layer 2), or no (the default). Specifying yes requests
966 the default tunnel mode, which is point-to-point.
967 TunnelDevice
969 Specifies the tun(4) devices to open on the client (local_tun)
970 and the server (remote_tun).
971 The argument must be local_tun[:remote_tun]. The devices may be
973 specified by numerical ID or the keyword any, which uses the next
974 available tunnel device. If remote_tun is not specified, it
975 defaults to any. The default is any:any.
976 UpdateHostKeys
978 Specifies whether ssh(1) should accept notifications of addi‐
979 tional hostkeys from the server sent after authentication has
980 completed and add them to UserKnownHostsFile. The argument must
981 be yes, no (the default) or ask. Enabling this option allows
982 learning alternate hostkeys for a server and supports graceful
983 key rotation by allowing a server to send replacement public keys
984 before old ones are removed. Additional hostkeys are only
985 accepted if the key used to authenticate the host was already
986 trusted or explicitly accepted by the user. If UpdateHostKeys is
987 set to ask, then the user is asked to confirm the modifications
988 to the known_hosts file. Confirmation is currently incompatible
989 with ControlPersist, and will be disabled if it is enabled.
990 Presently, only sshd(8) from OpenSSH 6.8 and greater support the
992 "hostkeys@openssh.com" protocol extension used to inform the
993 client of all the server's hostkeys.
994 UsePrivilegedPort
996 Specifies whether to use a privileged port for outgoing connec‐
997 tions. The argument must be yes or no (the default). If set to
998 yes, ssh(1) must be setuid root. Note that this option must be
999 set to yes for RhostsRSAAuthentication with older servers.
1000 User Specifies the user to log in as. This can be useful when a dif‐
1002 ferent user name is used on different machines. This saves the
1003 trouble of having to remember to give the user name on the com‐
1004 mand line.
1005 UserKnownHostsFile
1007 Specifies one or more files to use for the user host key data‐
1008 base, separated by whitespace. The default is
1009 ~/.ssh/known_hosts, ~/.ssh/known_hosts2.
1010 VerifyHostKeyDNS
1012 Specifies whether to verify the remote key using DNS and SSHFP
1013 resource records. If this option is set to yes, the client will
1014 implicitly trust keys that match a secure fingerprint from DNS.
1015 Insecure fingerprints will be handled as if this option was set
1016 to ask. If this option is set to ask, information on fingerprint
1017 match will be displayed, but the user will still need to confirm
1018 new host keys according to the StrictHostKeyChecking option. The
1019 default is no.
1020 See also VERIFYING HOST KEYS in ssh(1).
1022 VisualHostKey
1024 If this flag is set to yes, an ASCII art representation of the
1025 remote host key fingerprint is printed in addition to the finger‐
1026 print string at login and for unknown host keys. If this flag is
1027 set to no (the default), no fingerprint strings are printed at
1028 login and only the fingerprint string will be printed for unknown
1029 host keys.
1030 XAuthLocation
1032 Specifies the full pathname of the xauth(1) program. The default
1033 is /usr/bin/xauth.
1034
1036 A pattern consists of zero or more non-whitespace characters, ‘*’ (a
1037 wildcard that matches zero or more characters), or ‘?’ (a wildcard that
1038 matches exactly one character). For example, to specify a set of decla‐
1039 rations for any host in the ".co.uk" set of domains, the following pat‐
1040 tern could be used:
1041 Host *.co.uk
1043 The following pattern would match any host in the 192.168.0.[0-9] network
1045 range:
1046 Host 192.168.0.?
1048 A pattern-list is a comma-separated list of patterns. Patterns within
1050 pattern-lists may be negated by preceding them with an exclamation mark
1051 (‘!’). For example, to allow a key to be used from anywhere within an
1052 organization except from the "dialup" pool, the following entry (in
1053 authorized_keys) could be used:
1054 from="!*.dialup.example.com,*.example.com"
1056
1058 Arguments to some keywords can make use of tokens, which are expanded at
1059 runtime:
1060 %% A literal ‘%’.
1062 %C Shorthand for %l%h%p%r.
1063 %d Local user's home directory.
1064 %h The remote hostname.
1065 %i The local user ID.
1066 %L The local hostname.
1067 %l The local hostname, including the domain name.
1068 %n The original remote hostname, as given on the command line.
1069 %p The remote port.
1070 %r The remote username.
1071 %u The local username.
1072 Match exec accepts the tokens %%, %h, %L, %l, %n, %p, %r, and %u.
1074 CertificateFile accepts the tokens %%, %d, %h, %l, %r, and %u.
1076 ControlPath accepts the tokens %%, %C, %h, %i, %L, %l, %n, %p, %r, and
1078 %u.
1079 HostName accepts the tokens %% and %h.
1081 IdentityAgent and IdentityFile accept the tokens %%, %d, %h, %l, %r, and
1083 %u.
1084 LocalCommand accepts the tokens %%, %C, %d, %h, %l, %n, %p, %r, and %u.
1086 ProxyCommand accepts the tokens %%, %h, %p, and %r.
1088
1090 ~/.ssh/config
1091 This is the per-user configuration file. The format of this file
1092 is described above. This file is used by the SSH client.
1093 Because of the potential for abuse, this file must have strict
1094 permissions: read/write for the user, and not accessible by oth‐
1095 ers.
1096 /etc/ssh/ssh_config
1098 Systemwide configuration file. This file provides defaults for
1099 those values that are not specified in the user's configuration
1100 file, and for those users who do not have a configuration file.
1101 This file must be world-readable.
1102
1104 ssh(1)
1105
1107 OpenSSH is a derivative of the original and free ssh 1.2.12 release by
1108 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo
1109 de Raadt and Dug Song removed many bugs, re-added newer features and cre‐
1110 ated OpenSSH. Markus Friedl contributed the support for SSH protocol
1111 versions 1.5 and 2.0.
1112BSD June 21, 2019 BSD