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