2 .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
3 .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
4 .\" All rights reserved
6 .\" As far as I am concerned, the code I have written for this software
7 .\" can be used freely for any purpose. Any derived versions of this
8 .\" software must be clearly marked as such, and if the derived work is
9 .\" incompatible with the protocol description in the RFC file, it must be
10 .\" called by a name other than "ssh" or "Secure Shell".
12 .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
13 .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
14 .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
16 .\" Redistribution and use in source and binary forms, with or without
17 .\" modification, are permitted provided that the following conditions
19 .\" 1. Redistributions of source code must retain the above copyright
20 .\" notice, this list of conditions and the following disclaimer.
21 .\" 2. Redistributions in binary form must reproduce the above copyright
22 .\" notice, this list of conditions and the following disclaimer in the
23 .\" documentation and/or other materials provided with the distribution.
25 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
27 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
28 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
29 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
30 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
31 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
32 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
34 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 .\" $OpenBSD: ssh_config.5,v 1.268 2018/02/23 07:38:09 jmc Exp $
37 .Dd $Mdocdate: February 23 2018 $
42 .Nd OpenSSH SSH client configuration files
45 obtains configuration data from the following sources in
48 .Bl -enum -offset indent -compact
52 user's configuration file
55 system-wide configuration file
56 .Pq Pa /etc/ssh/ssh_config
59 For each parameter, the first obtained value
61 The configuration files contain sections separated by
63 specifications, and that section is only applied for hosts that
64 match one of the patterns given in the specification.
65 The matched host name is usually the one given on the command line
67 .Cm CanonicalizeHostname
68 option for exceptions).
70 Since the first obtained value for each parameter is used, more
71 host-specific declarations should be given near the beginning of the
72 file, and general defaults at the end.
74 The file contains keyword-argument pairs, one per line.
77 and empty lines are interpreted as comments.
78 Arguments may optionally be enclosed in double quotes
80 in order to represent arguments containing spaces.
81 Configuration options may be separated by whitespace or
82 optional whitespace and exactly one
84 the latter format is useful to avoid the need to quote whitespace
85 when specifying configuration options using the
94 keywords and their meanings are as follows (note that
95 keywords are case-insensitive and arguments are case-sensitive):
98 Restricts the following declarations (up to the next
102 keyword) to be only for those hosts that match one of the patterns
103 given after the keyword.
104 If more than one pattern is provided, they should be separated by whitespace.
107 as a pattern can be used to provide global
108 defaults for all hosts.
109 The host is usually the
111 argument given on the command line
113 .Cm CanonicalizeHostname
114 keyword for exceptions).
116 A pattern entry may be negated by prefixing it with an exclamation mark
118 If a negated entry is matched, then the
120 entry is ignored, regardless of whether any other patterns on the line
122 Negated matches are therefore useful to provide exceptions for wildcard
127 for more information on patterns.
129 Restricts the following declarations (up to the next
133 keyword) to be used only when the conditions following the
135 keyword are satisfied.
136 Match conditions are specified using one or more criteria
139 which always matches.
140 The available criteria keywords are:
150 criteria must appear alone or immediately after
152 Other criteria may be combined arbitrarily.
158 Criteria may be negated by prepending an exclamation mark
163 keyword matches only when the configuration file is being re-parsed
164 after hostname canonicalization (see the
165 .Cm CanonicalizeHostname
167 This may be useful to specify conditions that work with canonical host
171 keyword executes the specified command under the user's shell.
172 If the command returns a zero exit status then the condition is considered true.
173 Commands containing whitespace characters must be quoted.
176 accept the tokens described in the
180 The other keywords' criteria must be single entries or comma-separated
181 lists and may use the wildcard and negation operators described in the
186 keyword are matched against the target hostname, after any substitution
190 .Cm CanonicalizeHostname
194 keyword matches against the hostname as it was specified on the command-line.
197 keyword matches against the target username on the remote host.
200 keyword matches against the name of the local user running
202 (this keyword may be useful in system-wide
205 .It Cm AddKeysToAgent
206 Specifies whether keys should be automatically added to a running
208 If this option is set to
210 and a key is loaded from a file, the key and its passphrase are added to
211 the agent with the default lifetime, as if by
213 If this option is set to
216 will require confirmation using the
218 program before adding a key (see
221 If this option is set to
223 each use of the key must be confirmed, as if the
225 option was specified to
227 If this option is set to
229 no keys are added to the agent.
238 Specifies which address family to use when connecting.
249 passphrase/password querying will be disabled.
250 This option is useful in scripts and other batch jobs where no user
251 is present to supply the password.
258 Use the specified address on the local machine as the source address of
260 Only useful on systems with more than one address.
261 Note that this option does not work if
262 .Cm UsePrivilegedPort
266 Use the address of the specified interface on the local machine as the
267 source address of the connection.
268 Note that this option does not work if
269 .Cm UsePrivilegedPort
272 .It Cm CanonicalDomains
274 .Cm CanonicalizeHostname
275 is enabled, this option specifies the list of domain suffixes in which to
276 search for the specified destination host.
277 .It Cm CanonicalizeFallbackLocal
278 Specifies whether to fail with an error when hostname canonicalization fails.
281 will attempt to look up the unqualified hostname using the system resolver's
288 .Cm CanonicalizeHostname
289 is enabled and the target hostname cannot be found in any of the domains
291 .Cm CanonicalDomains .
292 .It Cm CanonicalizeHostname
293 Controls whether explicit hostname canonicalization is performed.
296 is not to perform any name rewriting and let the system resolver handle all
300 then, for connections that do not use a
303 will attempt to canonicalize the hostname specified on the command line
307 .Cm CanonicalizePermittedCNAMEs
310 .Cm CanonicalizeHostname
313 then canonicalization is applied to proxied connections too.
315 If this option is enabled, then the configuration files are processed
316 again using the new target name to pick up any new configuration in matching
321 .It Cm CanonicalizeMaxDots
322 Specifies the maximum number of dot characters in a hostname before
323 canonicalization is disabled.
325 allows a single dot (i.e. hostname.subdomain).
326 .It Cm CanonicalizePermittedCNAMEs
327 Specifies rules to determine whether CNAMEs should be followed when
328 canonicalizing hostnames.
329 The rules consist of one or more arguments of
330 .Ar source_domain_list : Ns Ar target_domain_list ,
332 .Ar source_domain_list
333 is a pattern-list of domains that may follow CNAMEs in canonicalization,
335 .Ar target_domain_list
336 is a pattern-list of domains that they may resolve to.
339 .Qq *.a.example.com:*.b.example.com,*.c.example.com
340 will allow hostnames matching
342 to be canonicalized to names in the
347 .It Cm CertificateFile
348 Specifies a file from which the user's certificate is read.
349 A corresponding private key must be provided separately in order
350 to use this certificate either
364 may use the tilde syntax to refer to a user's home directory
365 or the tokens described in the
369 It is possible to have multiple certificate files specified in
370 configuration files; these certificates will be tried in sequence.
373 directives will add to the list of certificates used for
375 .It Cm ChallengeResponseAuthentication
376 Specifies whether to use challenge-response authentication.
377 The argument to this keyword must be
387 will additionally check the host IP address in the
390 This allows it to detect if a host key changed due to DNS spoofing
391 and will add addresses of destination hosts to
392 .Pa ~/.ssh/known_hosts
393 in the process, regardless of the setting of
394 .Cm StrictHostKeyChecking .
395 If the option is set to
397 the check will not be executed.
399 Specifies the ciphers allowed and their order of preference.
400 Multiple ciphers must be comma-separated.
401 If the specified value begins with a
403 character, then the specified ciphers will be appended to the default set
404 instead of replacing them.
405 If the specified value begins with a
407 character, then the specified ciphers (including wildcards) will be removed
408 from the default set instead of replacing them.
410 The supported ciphers are:
411 .Bd -literal -offset indent
419 aes128-gcm@openssh.com
420 aes256-gcm@openssh.com
421 chacha20-poly1305@openssh.com
425 .Bd -literal -offset indent
426 chacha20-poly1305@openssh.com,
427 aes128-ctr,aes192-ctr,aes256-ctr,
428 aes128-gcm@openssh.com,aes256-gcm@openssh.com,
429 aes128-cbc,aes192-cbc,aes256-cbc
432 The list of available ciphers may also be obtained using
434 .It Cm ClearAllForwardings
435 Specifies that all local, remote, and dynamic port forwardings
436 specified in the configuration files or on the command line be
438 This option is primarily useful when used from the
440 command line to clear port forwardings set in
441 configuration files, and is automatically set by
451 Specifies whether to use compression.
457 .It Cm ConnectionAttempts
458 Specifies the number of tries (one per second) to make before exiting.
459 The argument must be an integer.
460 This may be useful in scripts if the connection sometimes fails.
462 .It Cm ConnectTimeout
463 Specifies the timeout (in seconds) used when connecting to the
464 SSH server, instead of using the default system TCP timeout.
465 This value is used only when the target is down or really unreachable,
466 not when it refuses the connection.
468 Enables the sharing of multiple sessions over a single network connection.
472 will listen for connections on a control socket specified using the
475 Additional sessions can connect to this socket using the same
482 These sessions will try to reuse the master instance's network connection
483 rather than initiating new ones, but will fall back to connecting normally
484 if the control socket does not exist, or is not listening.
490 to listen for control connections, but require confirmation using
496 will continue without connecting to a master instance.
500 forwarding is supported over these multiplexed connections, however the
501 display and agent forwarded will be the one belonging to the master
502 connection i.e. it is not possible to forward multiple displays or agents.
504 Two additional options allow for opportunistic multiplexing: try to use a
505 master connection but fall back to creating a new one if one does not already
511 The latter requires confirmation like the
515 Specify the path to the control socket used for connection sharing as described
518 section above or the string
520 to disable connection sharing.
523 may use the tilde syntax to refer to a user's home directory
524 or the tokens described in the
527 It is recommended that any
529 used for opportunistic connection sharing include
530 at least %h, %p, and %r (or alternatively %C) and be placed in a directory
531 that is not writable by other users.
532 This ensures that shared connections are uniquely identified.
533 .It Cm ControlPersist
534 When used in conjunction with
536 specifies that the master connection should remain open
537 in the background (waiting for future client connections)
538 after the initial client connection has been closed.
541 then the master connection will not be placed into the background,
542 and will close as soon as the initial client connection is closed.
546 then the master connection will remain in the background indefinitely
547 (until killed or closed via a mechanism such as the
549 If set to a time in seconds, or a time in any of the formats documented in
551 then the backgrounded master connection will automatically terminate
552 after it has remained idle (with no client connections) for the
554 .It Cm DynamicForward
555 Specifies that a TCP port on the local machine be forwarded
556 over the secure channel, and the application
557 protocol is then used to determine where to connect to from the
562 .Oo Ar bind_address : Oc Ar port .
564 IPv6 addresses can be specified by enclosing addresses in square brackets.
565 By default, the local port is bound in accordance with the
570 may be used to bind the connection to a specific address.
575 indicates that the listening port be bound for local use only, while an
578 indicates that the port should be available from all interfaces.
580 Currently the SOCKS4 and SOCKS5 protocols are supported, and
582 will act as a SOCKS server.
583 Multiple forwardings may be specified, and
584 additional forwardings can be given on the command line.
585 Only the superuser can forward privileged ports.
586 .It Cm EnableSSHKeysign
587 Setting this option to
589 in the global client configuration file
590 .Pa /etc/ssh/ssh_config
591 enables the use of the helper program
594 .Cm HostbasedAuthentication .
600 This option should be placed in the non-hostspecific section.
603 for more information.
605 Sets the escape character (default:
607 The escape character can also
608 be set on the command line.
609 The argument should be a single character,
611 followed by a letter, or
613 to disable the escape
614 character entirely (making the connection transparent for binary
616 .It Cm ExitOnForwardFailure
619 should terminate the connection if it cannot set up all requested
620 dynamic, tunnel, local, and remote port forwardings, (e.g.\&
621 if either end is unable to bind and listen on a specified port).
623 .Cm ExitOnForwardFailure
624 does not apply to connections made over port forwardings and will not,
627 to exit if TCP connections to the ultimate forwarding destination fail.
633 .It Cm FingerprintHash
634 Specifies the hash algorithm used when displaying key fingerprints.
641 Specifies whether the connection to the authentication agent (if any)
642 will be forwarded to the remote machine.
649 Agent forwarding should be enabled with caution.
650 Users with the ability to bypass file permissions on the remote host
651 (for the agent's Unix-domain socket)
652 can access the local agent through the forwarded connection.
653 An attacker cannot obtain key material from the agent,
654 however they can perform operations on the keys that enable them to
655 authenticate using the identities loaded into the agent.
657 Specifies whether X11 connections will be automatically redirected
658 over the secure channel and
667 X11 forwarding should be enabled with caution.
668 Users with the ability to bypass file permissions on the remote host
669 (for the user's X11 authorization database)
670 can access the local X11 display through the forwarded connection.
671 An attacker may then be able to perform activities such as keystroke monitoring
673 .Cm ForwardX11Trusted
674 option is also enabled.
675 .It Cm ForwardX11Timeout
676 Specify a timeout for untrusted X11 forwarding
677 using the format described in the
681 X11 connections received by
683 after this time will be refused.
684 The default is to disable untrusted X11 forwarding after twenty minutes has
686 .It Cm ForwardX11Trusted
687 If this option is set to
689 remote X11 clients will have full access to the original X11 display.
691 If this option is set to
694 remote X11 clients will be considered untrusted and prevented
695 from stealing or tampering with data belonging to trusted X11
699 token used for the session will be set to expire after 20 minutes.
700 Remote clients will be refused access after this time.
702 See the X11 SECURITY extension specification for full details on
703 the restrictions imposed on untrusted clients.
705 Specifies whether remote hosts are allowed to connect to local
709 binds local port forwardings to the loopback address.
710 This prevents other remote hosts from connecting to forwarded ports.
712 can be used to specify that ssh
713 should bind local port forwardings to the wildcard address,
714 thus allowing remote hosts to connect to forwarded ports.
720 .It Cm GlobalKnownHostsFile
721 Specifies one or more files to use for the global
722 host key database, separated by whitespace.
724 .Pa /etc/ssh/ssh_known_hosts ,
725 .Pa /etc/ssh/ssh_known_hosts2 .
726 .It Cm GSSAPIAuthentication
727 Specifies whether user authentication based on GSSAPI is allowed.
730 .It Cm GSSAPIDelegateCredentials
731 Forward (delegate) credentials to the server.
734 .It Cm HashKnownHosts
737 should hash host names and addresses when they are added to
738 .Pa ~/.ssh/known_hosts .
739 These hashed names may be used normally by
743 but they do not reveal identifying information should the file's contents
747 Note that existing names and addresses in known hosts files
748 will not be converted automatically,
749 but may be manually hashed using
751 .It Cm HostbasedAuthentication
752 Specifies whether to try rhosts based authentication with public key
759 .It Cm HostbasedKeyTypes
760 Specifies the key types that will be used for hostbased authentication
761 as a comma-separated pattern list.
762 Alternately if the specified value begins with a
764 character, then the specified key types will be appended to the default set
765 instead of replacing them.
766 If the specified value begins with a
768 character, then the specified key types (including wildcards) will be removed
769 from the default set instead of replacing them.
770 The default for this option is:
771 .Bd -literal -offset 3n
772 ecdsa-sha2-nistp256-cert-v01@openssh.com,
773 ecdsa-sha2-nistp384-cert-v01@openssh.com,
774 ecdsa-sha2-nistp521-cert-v01@openssh.com,
775 ssh-ed25519-cert-v01@openssh.com,
776 ssh-rsa-cert-v01@openssh.com,
777 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
785 may be used to list supported key types.
786 .It Cm HostKeyAlgorithms
787 Specifies the host key algorithms
788 that the client wants to use in order of preference.
789 Alternately if the specified value begins with a
791 character, then the specified key types will be appended to the default set
792 instead of replacing them.
793 If the specified value begins with a
795 character, then the specified key types (including wildcards) will be removed
796 from the default set instead of replacing them.
797 The default for this option is:
798 .Bd -literal -offset 3n
799 ecdsa-sha2-nistp256-cert-v01@openssh.com,
800 ecdsa-sha2-nistp384-cert-v01@openssh.com,
801 ecdsa-sha2-nistp521-cert-v01@openssh.com,
802 ssh-ed25519-cert-v01@openssh.com,
803 ssh-rsa-cert-v01@openssh.com,
804 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
808 If hostkeys are known for the destination host then this default is modified
809 to prefer their algorithms.
811 The list of available key types may also be obtained using
814 Specifies an alias that should be used instead of the
815 real host name when looking up or saving the host key
816 in the host key database files and when validating host certificates.
817 This option is useful for tunneling SSH connections
818 or for multiple servers running on a single host.
820 Specifies the real host name to log into.
821 This can be used to specify nicknames or abbreviations for hosts.
824 accept the tokens described in the
827 Numeric IP addresses are also permitted (both on the command line and in
830 The default is the name given on the command line.
831 .It Cm IdentitiesOnly
834 should only use the authentication identity and certificate files explicitly
845 offers more identities.
846 The argument to this keyword must be
851 This option is intended for situations where ssh-agent
852 offers many different identities.
856 socket used to communicate with the authentication agent.
858 This option overrides the
860 environment variable and can be used to select a specific agent.
861 Setting the socket name to
863 disables the use of an authentication agent.
866 is specified, the location of the socket will be read from the
868 environment variable.
872 may use the tilde syntax to refer to a user's home directory
873 or the tokens described in the
877 Specifies a file from which the user's DSA, ECDSA, Ed25519 or RSA authentication
881 .Pa ~/.ssh/id_ecdsa ,
882 .Pa ~/.ssh/id_ed25519
885 Additionally, any identities represented by the authentication agent
886 will be used for authentication unless
889 If no certificates have been explicitly specified by
890 .Cm CertificateFile ,
892 will try to load certificate information from the filename obtained by
895 to the path of a specified
900 may use the tilde syntax to refer to a user's home directory
901 or the tokens described in the
905 It is possible to have
906 multiple identity files specified in configuration files; all these
907 identities will be tried in sequence.
910 directives will add to the list of identities tried (this behaviour
911 differs from that of other configuration directives).
914 may be used in conjunction with
916 to select which identities in an agent are offered during authentication.
918 may also be used in conjunction with
920 in order to provide any certificate also needed for authentication with
923 Specifies a pattern-list of unknown options to be ignored if they are
924 encountered in configuration parsing.
925 This may be used to suppress errors if
927 contains options that are unrecognised by
929 It is recommended that
931 be listed early in the configuration file as it will not be applied
932 to unknown options that appear before it.
934 Include the specified configuration file(s).
935 Multiple pathnames may be specified and each pathname may contain
937 wildcards and, for user configurations, shell-like
939 references to user home directories.
940 Files without absolute paths are assumed to be in
942 if included in a user configuration file or
944 if included from the system configuration file.
946 directive may appear inside a
951 to perform conditional inclusion.
953 Specifies the IPv4 type-of-service or DSCP class for connections.
981 to use the operating system default.
982 This option may take one or two arguments, separated by whitespace.
983 If one argument is specified, it is used as the packet class unconditionally.
984 If two values are specified, the first is automatically selected for
985 interactive sessions and the second for non-interactive sessions.
988 for interactive sessions and
990 for non-interactive sessions.
991 .It Cm KbdInteractiveAuthentication
992 Specifies whether to use keyboard-interactive authentication.
993 The argument to this keyword must be
998 .It Cm KbdInteractiveDevices
999 Specifies the list of methods to use in keyboard-interactive authentication.
1000 Multiple method names must be comma-separated.
1001 The default is to use the server specified list.
1002 The methods available vary depending on what the server supports.
1003 For an OpenSSH server,
1004 it may be zero or more of:
1009 .It Cm KexAlgorithms
1010 Specifies the available KEX (Key Exchange) algorithms.
1011 Multiple algorithms must be comma-separated.
1012 Alternately if the specified value begins with a
1014 character, then the specified methods will be appended to the default set
1015 instead of replacing them.
1016 If the specified value begins with a
1018 character, then the specified methods (including wildcards) will be removed
1019 from the default set instead of replacing them.
1021 .Bd -literal -offset indent
1022 curve25519-sha256,curve25519-sha256@libssh.org,
1023 ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,
1024 diffie-hellman-group-exchange-sha256,
1025 diffie-hellman-group16-sha512,
1026 diffie-hellman-group18-sha512,
1027 diffie-hellman-group-exchange-sha1,
1028 diffie-hellman-group14-sha256,
1029 diffie-hellman-group14-sha1
1032 The list of available key exchange algorithms may also be obtained using
1035 Specifies a command to execute on the local machine after successfully
1036 connecting to the server.
1037 The command string extends to the end of the line, and is executed with
1041 accept the tokens described in the
1045 The command is run synchronously and does not have access to the
1049 It should not be used for interactive commands.
1051 This directive is ignored unless
1052 .Cm PermitLocalCommand
1055 Specifies that a TCP port on the local machine be forwarded over
1056 the secure channel to the specified host and port from the remote machine.
1057 The first argument must be
1059 .Oo Ar bind_address : Oc Ar port
1061 and the second argument must be
1062 .Ar host : Ns Ar hostport .
1063 IPv6 addresses can be specified by enclosing addresses in square brackets.
1064 Multiple forwardings may be specified, and additional forwardings can be
1065 given on the command line.
1066 Only the superuser can forward privileged ports.
1067 By default, the local port is bound in accordance with the
1070 However, an explicit
1072 may be used to bind the connection to a specific address.
1077 indicates that the listening port be bound for local use only, while an
1080 indicates that the port should be available from all interfaces.
1082 Gives the verbosity level that is used when logging messages from
1084 The possible values are:
1085 QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.
1086 The default is INFO.
1087 DEBUG and DEBUG1 are equivalent.
1088 DEBUG2 and DEBUG3 each specify higher levels of verbose output.
1090 Specifies the MAC (message authentication code) algorithms
1091 in order of preference.
1092 The MAC algorithm is used for data integrity protection.
1093 Multiple algorithms must be comma-separated.
1094 If the specified value begins with a
1096 character, then the specified algorithms will be appended to the default set
1097 instead of replacing them.
1098 If the specified value begins with a
1100 character, then the specified algorithms (including wildcards) will be removed
1101 from the default set instead of replacing them.
1103 The algorithms that contain
1105 calculate the MAC after encryption (encrypt-then-mac).
1106 These are considered safer and their use recommended.
1109 .Bd -literal -offset indent
1110 umac-64-etm@openssh.com,umac-128-etm@openssh.com,
1111 hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,
1112 hmac-sha1-etm@openssh.com,
1113 umac-64@openssh.com,umac-128@openssh.com,
1114 hmac-sha2-256,hmac-sha2-512,hmac-sha1
1117 The list of available MAC algorithms may also be obtained using
1119 .It Cm NoHostAuthenticationForLocalhost
1120 Disable host authentication for localhost (loopback addresses).
1121 The argument to this keyword must be
1126 .It Cm NumberOfPasswordPrompts
1127 Specifies the number of password prompts before giving up.
1128 The argument to this keyword must be an integer.
1130 .It Cm PasswordAuthentication
1131 Specifies whether to use password authentication.
1132 The argument to this keyword must be
1137 .It Cm PermitLocalCommand
1138 Allow local command execution via the
1141 .Ic !\& Ns Ar command
1144 The argument must be
1149 .It Cm PKCS11Provider
1150 Specifies which PKCS#11 provider to use.
1151 The argument to this keyword is the PKCS#11 shared library
1153 should use to communicate with a PKCS#11 token providing the user's
1156 Specifies the port number to connect on the remote host.
1158 .It Cm PreferredAuthentications
1159 Specifies the order in which the client should try authentication methods.
1160 This allows a client to prefer one method (e.g.\&
1161 .Cm keyboard-interactive )
1162 over another method (e.g.\&
1165 .Bd -literal -offset indent
1166 gssapi-with-mic,hostbased,publickey,
1167 keyboard-interactive,password
1170 Specifies the command to use to connect to the server.
1172 string extends to the end of the line, and is executed
1173 using the user's shell
1175 directive to avoid a lingering shell process.
1179 accept the tokens described in the
1182 The command can be basically anything,
1183 and should read from its standard input and write to its standard output.
1184 It should eventually connect an
1186 server running on some machine, or execute
1189 Host key management will be done using the
1190 HostName of the host being connected (defaulting to the name typed by
1192 Setting the command to
1194 disables this option entirely.
1197 is not available for connects with a proxy command.
1199 This directive is useful in conjunction with
1201 and its proxy support.
1202 For example, the following directive would connect via an HTTP proxy at
1204 .Bd -literal -offset 3n
1205 ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
1208 Specifies one or more jump proxies as either
1217 Multiple proxies may be separated by comma characters and will be visited
1219 Setting this option will cause
1221 to connect to the target host by first making a
1223 connection to the specified
1225 host and then establishing a
1226 TCP forwarding to the ultimate target from there.
1228 Note that this option will compete with the
1230 option - whichever is specified first will prevent later instances of the
1231 other from taking effect.
1232 .It Cm ProxyUseFdpass
1235 will pass a connected file descriptor back to
1237 instead of continuing to execute and pass data.
1240 .It Cm PubkeyAcceptedKeyTypes
1241 Specifies the key types that will be used for public key authentication
1242 as a comma-separated pattern list.
1243 Alternately if the specified value begins with a
1245 character, then the key types after it will be appended to the default
1246 instead of replacing it.
1247 If the specified value begins with a
1249 character, then the specified key types (including wildcards) will be removed
1250 from the default set instead of replacing them.
1251 The default for this option is:
1252 .Bd -literal -offset 3n
1253 ecdsa-sha2-nistp256-cert-v01@openssh.com,
1254 ecdsa-sha2-nistp384-cert-v01@openssh.com,
1255 ecdsa-sha2-nistp521-cert-v01@openssh.com,
1256 ssh-ed25519-cert-v01@openssh.com,
1257 ssh-rsa-cert-v01@openssh.com,
1258 ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
1262 The list of available key types may also be obtained using
1264 .It Cm PubkeyAuthentication
1265 Specifies whether to try public key authentication.
1266 The argument to this keyword must be
1272 Specifies the maximum amount of data that may be transmitted before the
1273 session key is renegotiated, optionally followed a maximum amount of
1274 time that may pass before the session key is renegotiated.
1275 The first argument is specified in bytes and may have a suffix of
1280 to indicate Kilobytes, Megabytes, or Gigabytes, respectively.
1281 The default is between
1285 depending on the cipher.
1286 The optional second value is specified in seconds and may use any of the
1287 units documented in the
1291 The default value for
1295 which means that rekeying is performed after the cipher's default amount
1296 of data has been sent or received and no time based rekeying is done.
1297 .It Cm RemoteCommand
1298 Specifies a command to execute on the remote machine after successfully
1299 connecting to the server.
1300 The command string extends to the end of the line, and is executed with
1304 accept the tokens described in the
1307 .It Cm RemoteForward
1308 Specifies that a TCP port on the remote machine be forwarded over
1310 The remote port may either be fowarded to a specified host and port
1311 from the local machine, or may act as a SOCKS 4/5 proxy that allows a remote
1312 client to connect to arbitrary destinations from the local machine.
1313 The first argument must be
1315 .Oo Ar bind_address : Oc Ar port
1317 If forwarding to a specific destination then the second argument must be
1318 .Ar host : Ns Ar hostport ,
1319 otherwise if no destination argument is specified then the remote forwarding
1320 will be established as a SOCKS proxy.
1322 IPv6 addresses can be specified by enclosing addresses in square brackets.
1323 Multiple forwardings may be specified, and additional
1324 forwardings can be given on the command line.
1325 Privileged ports can be forwarded only when
1326 logging in as root on the remote machine.
1331 the listen port will be dynamically allocated on the server and reported
1332 to the client at run time.
1336 is not specified, the default is to only bind to loopback addresses.
1341 or an empty string, then the forwarding is requested to listen on all
1345 will only succeed if the server's
1347 option is enabled (see
1348 .Xr sshd_config 5 ) .
1350 Specifies whether to request a pseudo-tty for the session.
1351 The argument may be one of:
1353 (never request a TTY),
1355 (always request a TTY when standard input is a TTY),
1357 (always request a TTY) or
1359 (request a TTY when opening a login session).
1360 This option mirrors the
1366 .It Cm RevokedHostKeys
1367 Specifies revoked host public keys.
1368 Keys listed in this file will be refused for host authentication.
1369 Note that if this file does not exist or is not readable,
1370 then host authentication will be refused for all hosts.
1371 Keys may be specified as a text file, listing one public key per line, or as
1372 an OpenSSH Key Revocation List (KRL) as generated by
1374 For more information on KRLs, see the KEY REVOCATION LISTS section in
1377 Specifies what variables from the local
1379 should be sent to the server.
1380 The server must also support it, and the server must be configured to
1381 accept these environment variables.
1384 environment variable is always sent whenever a
1385 pseudo-terminal is requested as it is required by the protocol.
1390 for how to configure the server.
1391 Variables are specified by name, which may contain wildcard characters.
1392 Multiple environment variables may be separated by whitespace or spread
1396 The default is not to send any environment variables.
1400 for more information on patterns.
1401 .It Cm ServerAliveCountMax
1402 Sets the number of server alive messages (see below) which may be
1405 receiving any messages back from the server.
1406 If this threshold is reached while server alive messages are being sent,
1407 ssh will disconnect from the server, terminating the session.
1408 It is important to note that the use of server alive messages is very
1412 The server alive messages are sent through the encrypted channel
1413 and therefore will not be spoofable.
1414 The TCP keepalive option enabled by
1417 The server alive mechanism is valuable when the client or
1418 server depend on knowing when a connection has become inactive.
1420 The default value is 3.
1422 .Cm ServerAliveInterval
1423 (see below) is set to 15 and
1424 .Cm ServerAliveCountMax
1425 is left at the default, if the server becomes unresponsive,
1426 ssh will disconnect after approximately 45 seconds.
1427 .It Cm ServerAliveInterval
1428 Sets a timeout interval in seconds after which if no data has been received
1431 will send a message through the encrypted
1432 channel to request a response from the server.
1434 is 0, indicating that these messages will not be sent to the server.
1435 .It Cm StreamLocalBindMask
1436 Sets the octal file creation mode mask
1438 used when creating a Unix-domain socket file for local or remote
1440 This option is only used for port forwarding to a Unix-domain socket file.
1442 The default value is 0177, which creates a Unix-domain socket file that is
1443 readable and writable only by the owner.
1444 Note that not all operating systems honor the file mode on Unix-domain
1446 .It Cm StreamLocalBindUnlink
1447 Specifies whether to remove an existing Unix-domain socket file for local
1448 or remote port forwarding before creating a new one.
1449 If the socket file already exists and
1450 .Cm StreamLocalBindUnlink
1453 will be unable to forward the port to the Unix-domain socket file.
1454 This option is only used for port forwarding to a Unix-domain socket file.
1456 The argument must be
1461 .It Cm StrictHostKeyChecking
1462 If this flag is set to
1465 will never automatically add host keys to the
1466 .Pa ~/.ssh/known_hosts
1467 file, and refuses to connect to hosts whose host key has changed.
1468 This provides maximum protection against man-in-the-middle (MITM) attacks,
1469 though it can be annoying when the
1470 .Pa /etc/ssh/ssh_known_hosts
1471 file is poorly maintained or when connections to new hosts are
1473 This option forces the user to manually
1476 If this flag is set to
1478 then ssh will automatically add new host keys to the user
1479 known hosts files, but will not permit connections to hosts with
1481 If this flag is set to
1485 ssh will automatically add new host keys to the user known hosts files
1486 and allow connections to hosts with changed hostkeys to proceed,
1487 subject to some restrictions.
1488 If this flag is set to
1492 will be added to the user known host files only after the user
1493 has confirmed that is what they really want to do, and
1494 ssh will refuse to connect to hosts whose host key has changed.
1496 known hosts will be verified automatically in all cases.
1497 .It Cm SyslogFacility
1498 Gives the facility code that is used when logging messages from
1500 The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2,
1501 LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
1502 The default is USER.
1504 Specifies whether the system should send TCP keepalive messages to the
1506 If they are sent, death of the connection or crash of one
1507 of the machines will be properly noticed.
1508 However, this means that
1509 connections will die if the route is down temporarily, and some people
1514 (to send TCP keepalive messages), and the client will notice
1515 if the network goes down or the remote host dies.
1516 This is important in scripts, and many users want it too.
1518 To disable TCP keepalive messages, the value should be set to
1521 .Cm ServerAliveInterval
1522 for protocol-level keepalives.
1526 device forwarding between the client and the server.
1527 The argument must be
1538 requests the default tunnel mode, which is
1539 .Cm point-to-point .
1543 devices to open on the client
1548 The argument must be
1550 .Ar local_tun Op : Ar remote_tun .
1552 The devices may be specified by numerical ID or the keyword
1554 which uses the next available tunnel device.
1557 is not specified, it defaults to
1561 .It Cm UpdateHostKeys
1564 should accept notifications of additional hostkeys from the server sent
1565 after authentication has completed and add them to
1566 .Cm UserKnownHostsFile .
1567 The argument must be
1572 Enabling this option allows learning alternate hostkeys for a server
1573 and supports graceful key rotation by allowing a server to send replacement
1574 public keys before old ones are removed.
1575 Additional hostkeys are only accepted if the key used to authenticate the
1576 host was already trusted or explicitly accepted by the user.
1581 then the user is asked to confirm the modifications to the known_hosts file.
1582 Confirmation is currently incompatible with
1583 .Cm ControlPersist ,
1584 and will be disabled if it is enabled.
1588 from OpenSSH 6.8 and greater support the
1589 .Qq hostkeys@openssh.com
1590 protocol extension used to inform the client of all the server's hostkeys.
1591 .It Cm UsePrivilegedPort
1592 Specifies whether to use a privileged port for outgoing connections.
1593 The argument must be
1601 must be setuid root.
1603 Specifies the user to log in as.
1604 This can be useful when a different user name is used on different machines.
1605 This saves the trouble of
1606 having to remember to give the user name on the command line.
1607 .It Cm UserKnownHostsFile
1608 Specifies one or more files to use for the user
1609 host key database, separated by whitespace.
1611 .Pa ~/.ssh/known_hosts ,
1612 .Pa ~/.ssh/known_hosts2 .
1613 .It Cm VerifyHostKeyDNS
1614 Specifies whether to verify the remote key using DNS and SSHFP resource
1616 If this option is set to
1618 the client will implicitly trust keys that match a secure fingerprint
1620 Insecure fingerprints will be handled as if this option was set to
1622 If this option is set to
1624 information on fingerprint match will be displayed, but the user will still
1625 need to confirm new host keys according to the
1626 .Cm StrictHostKeyChecking
1632 .Sx VERIFYING HOST KEYS
1635 .It Cm VisualHostKey
1636 If this flag is set to
1638 an ASCII art representation of the remote host key fingerprint is
1639 printed in addition to the fingerprint string at login and
1640 for unknown host keys.
1641 If this flag is set to
1644 no fingerprint strings are printed at login and
1645 only the fingerprint string will be printed for unknown host keys.
1646 .It Cm XAuthLocation
1647 Specifies the full pathname of the
1651 .Pa /usr/X11R6/bin/xauth .
1656 consists of zero or more non-whitespace characters,
1658 (a wildcard that matches zero or more characters),
1661 (a wildcard that matches exactly one character).
1662 For example, to specify a set of declarations for any host in the
1665 the following pattern could be used:
1669 The following pattern
1670 would match any host in the 192.168.0.[0-9] network range:
1672 .Dl Host 192.168.0.?
1676 is a comma-separated list of patterns.
1677 Patterns within pattern-lists may be negated
1678 by preceding them with an exclamation mark
1681 to allow a key to be used from anywhere within an organization
1685 the following entry (in authorized_keys) could be used:
1687 .Dl from=\&"!*.dialup.example.com,*.example.com\&"
1689 Note that a negated match will never produce a positive result by itself.
1690 For example, attempting to match
1692 against the following pattern-list will fail:
1694 .Dl from=\&"!host1,!host2\&"
1696 The solution here is to include a term that will yield a positive match,
1699 .Dl from=\&"!host1,!host2,*\&"
1701 Arguments to some keywords can make use of tokens,
1702 which are expanded at runtime:
1704 .Bl -tag -width XXXX -offset indent -compact
1711 Local user's home directory.
1713 The remote hostname.
1719 The local hostname, including the domain name.
1721 The original remote hostname, as given on the command line.
1725 The remote username.
1731 network interface assigned if
1732 tunnel forwarding was requested, or
1740 accepts the tokens %%, %h, %L, %l, %n, %p, %r, and %u.
1743 accepts the tokens %%, %d, %h, %l, %r, and %u.
1746 accepts the tokens %%, %C, %h, %i, %L, %l, %n, %p, %r, and %u.
1749 accepts the tokens %% and %h.
1754 accept the tokens %%, %d, %h, %l, %r, and %u.
1757 accepts the tokens %%, %C, %d, %h, %l, %n, %p, %r, %T, and %u.
1760 accepts the tokens %%, %h, %p, and %r.
1763 accepts the tokens %%, %C, %d, %h, %l, %n, %p, %r, and %u.
1766 .It Pa ~/.ssh/config
1767 This is the per-user configuration file.
1768 The format of this file is described above.
1769 This file is used by the SSH client.
1770 Because of the potential for abuse, this file must have strict permissions:
1771 read/write for the user, and not accessible by others.
1772 .It Pa /etc/ssh/ssh_config
1773 Systemwide configuration file.
1774 This file provides defaults for those
1775 values that are not specified in the user's configuration file, and
1776 for those users who do not have a configuration file.
1777 This file must be world-readable.
1783 OpenSSH is a derivative of the original and free
1784 ssh 1.2.12 release by
1786 .An Aaron Campbell , Bob Beck , Markus Friedl ,
1787 .An Niels Provos , Theo de Raadt
1790 removed many bugs, re-added newer features and
1793 contributed the support for SSH protocol versions 1.5 and 2.0.
projects / platform / upstream / openssh.git / blob