1.\" 2.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 3.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 4.\" All rights reserved 5.\" 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". 11.\" 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. 15.\" 16.\" Redistribution and use in source and binary forms, with or without 17.\" modification, are permitted provided that the following conditions 18.\" are met: 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. 24.\" 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. 35.\" 36.\" $OpenBSD: ssh_config.5,v 1.184 2014/01/19 04:48:08 djm Exp $ 37.\" $FreeBSD$ 38.Dd January 19, 2014 39.Dt SSH_CONFIG 5 40.Os 41.Sh NAME 42.Nm ssh_config 43.Nd OpenSSH SSH client configuration files 44.Sh SYNOPSIS 45.Nm ~/.ssh/config 46.Nm /etc/ssh/ssh_config 47.Sh DESCRIPTION 48.Xr ssh 1 49obtains configuration data from the following sources in 50the following order: 51.Pp 52.Bl -enum -offset indent -compact 53.It 54command-line options 55.It 56user's configuration file 57.Pq Pa ~/.ssh/config 58.It 59system-wide configuration file 60.Pq Pa /etc/ssh/ssh_config 61.El 62.Pp 63For each parameter, the first obtained value 64will be used. 65The configuration files contain sections separated by 66.Dq Host 67specifications, and that section is only applied for hosts that 68match one of the patterns given in the specification. 69The matched host name is the one given on the command line. 70.Pp 71Since the first obtained value for each parameter is used, more 72host-specific declarations should be given near the beginning of the 73file, and general defaults at the end. 74.Pp 75The configuration file has the following format: 76.Pp 77Empty lines and lines starting with 78.Ql # 79are comments. 80Otherwise a line is of the format 81.Dq keyword arguments . 82Configuration options may be separated by whitespace or 83optional whitespace and exactly one 84.Ql = ; 85the latter format is useful to avoid the need to quote whitespace 86when specifying configuration options using the 87.Nm ssh , 88.Nm scp , 89and 90.Nm sftp 91.Fl o 92option. 93Arguments may optionally be enclosed in double quotes 94.Pq \&" 95in order to represent arguments containing spaces. 96.Pp 97The possible 98keywords and their meanings are as follows (note that 99keywords are case-insensitive and arguments are case-sensitive): 100.Bl -tag -width Ds 101.It Cm Host 102Restricts the following declarations (up to the next 103.Cm Host 104or 105.Cm Match 106keyword) to be only for those hosts that match one of the patterns 107given after the keyword. 108If more than one pattern is provided, they should be separated by whitespace. 109A single 110.Ql * 111as a pattern can be used to provide global 112defaults for all hosts. 113The host is the 114.Ar hostname 115argument given on the command line (i.e. the name is not converted to 116a canonicalized host name before matching). 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 keyword/criteria pairs 139or the single token 140.Cm all 141which matches all criteria. 142The available keywords are: 143.Cm exec , 144.Cm host , 145.Cm originalhost , 146.Cm user , 147and 148.Cm localuser . 149.Pp 150The 151.Cm exec 152keyword executes the specified command under the user's shell. 153If the command returns a zero exit status then the condition is considered true. 154Commands containing whitespace characters must be quoted. 155The following character sequences in the command will be expanded prior to 156execution: 157.Ql %L 158will be substituted by the first component of the local host name, 159.Ql %l 160will be substituted by the local host name (including any domain name), 161.Ql %h 162will be substituted by the target host name, 163.Ql %n 164will be substituted by the original target host name 165specified on the command-line, 166.Ql %p 167the destination port, 168.Ql %r 169by the remote login username, and 170.Ql %u 171by the username of the user running 172.Xr ssh 1 . 173.Pp 174The other keywords' criteria must be single entries or comma-separated 175lists and may use the wildcard and negation operators described in the 176.Sx PATTERNS 177section. 178The criteria for the 179.Cm host 180keyword are matched against the target hostname, after any substitution 181by the 182.Cm Hostname 183option. 184The 185.Cm originalhost 186keyword matches against the hostname as it was specified on the command-line. 187The 188.Cm user 189keyword matches against the target username on the remote host. 190The 191.Cm localuser 192keyword matches against the name of the local user running 193.Xr ssh 1 194(this keyword may be useful in system-wide 195.Nm 196files). 197.It Cm AddressFamily 198Specifies which address family to use when connecting. 199Valid arguments are 200.Dq any , 201.Dq inet 202(use IPv4 only), or 203.Dq inet6 204(use IPv6 only). 205.It Cm BatchMode 206If set to 207.Dq yes , 208passphrase/password querying will be disabled. 209This option is useful in scripts and other batch jobs where no user 210is present to supply the password. 211The argument must be 212.Dq yes 213or 214.Dq no . 215The default is 216.Dq no . 217.It Cm BindAddress 218Use the specified address on the local machine as the source address of 219the connection. 220Only useful on systems with more than one address. 221Note that this option does not work if 222.Cm UsePrivilegedPort 223is set to 224.Dq yes . 225.It Cm CanonicalDomains 226When 227.Cm CanonicalizeHostname 228is enabled, this option specifies the list of domain suffixes in which to 229search for the specified destination host. 230.It Cm CanonicalizeFallbackLocal 231Specifies whether to fail with an error when hostname canonicalization fails. 232The default, 233.Dq yes , 234will attempt to look up the unqualified hostname using the system resolver's 235search rules. 236A value of 237.Dq no 238will cause 239.Xr ssh 1 240to fail instantly if 241.Cm CanonicalizeHostname 242is enabled and the target hostname cannot be found in any of the domains 243specified by 244.Cm CanonicalDomains . 245.It Cm CanonicalizeHostname 246Controls whether explicit hostname canonicalization is performed. 247The default, 248.Dq no , 249is not to perform any name rewriting and let the system resolver handle all 250hostname lookups. 251If set to 252.Dq yes 253then, for connections that do not use a 254.Cm ProxyCommand , 255.Xr ssh 1 256will attempt to canonicalize the hostname specified on the command line 257using the 258.Cm CanonicalDomains 259suffixes and 260.Cm CanonicalizePermittedCNAMEs 261rules. 262If 263.Cm CanonicalizeHostname 264is set to 265.Dq always , 266then canonicalization is applied to proxied connections too. 267.It Cm CanonicalizeMaxDots 268Specifies the maximum number of dot characters in a hostname before 269canonicalization is disabled. 270The default, 271.Dq 1 , 272allows a single dot (i.e. hostname.subdomain). 273.It Cm CanonicalizePermittedCNAMEs 274Specifies rules to determine whether CNAMEs should be followed when 275canonicalizing hostnames. 276The rules consist of one or more arguments of 277.Ar source_domain_list : Ns Ar target_domain_list , 278where 279.Ar source_domain_list 280is a pattern-list of domains that may follow CNAMEs in canonicalization, 281and 282.Ar target_domain_list 283is a pattern-list of domains that they may resolve to. 284.Pp 285For example, 286.Dq *.a.example.com:*.b.example.com,*.c.example.com 287will allow hostnames matching 288.Dq *.a.example.com 289to be canonicalized to names in the 290.Dq *.b.example.com 291or 292.Dq *.c.example.com 293domains. 294.It Cm ChallengeResponseAuthentication 295Specifies whether to use challenge-response authentication. 296The argument to this keyword must be 297.Dq yes 298or 299.Dq no . 300The default is 301.Dq yes . 302.It Cm CheckHostIP 303If this flag is set to 304.Dq yes , 305.Xr ssh 1 306will additionally check the host IP address in the 307.Pa known_hosts 308file. 309This allows ssh to detect if a host key changed due to DNS spoofing. 310If the option is set to 311.Dq no , 312the check will not be executed. 313The default is 314.Dq no . 315.It Cm Cipher 316Specifies the cipher to use for encrypting the session 317in protocol version 1. 318Currently, 319.Dq blowfish , 320.Dq 3des , 321and 322.Dq des 323are supported. 324.Ar des 325is only supported in the 326.Xr ssh 1 327client for interoperability with legacy protocol 1 implementations 328that do not support the 329.Ar 3des 330cipher. 331Its use is strongly discouraged due to cryptographic weaknesses. 332The default is 333.Dq 3des . 334.It Cm Ciphers 335Specifies the ciphers allowed for protocol version 2 336in order of preference. 337Multiple ciphers must be comma-separated. 338The supported ciphers are: 339.Pp 340.Dq 3des-cbc , 341.Dq aes128-cbc , 342.Dq aes192-cbc , 343.Dq aes256-cbc , 344.Dq aes128-ctr , 345.Dq aes192-ctr , 346.Dq aes256-ctr , 347.Dq aes128-gcm@openssh.com , 348.Dq aes256-gcm@openssh.com , 349.Dq arcfour128 , 350.Dq arcfour256 , 351.Dq arcfour , 352.Dq blowfish-cbc , 353.Dq cast128-cbc , 354and 355.Dq chacha20-poly1305@openssh.com . 356.Pp 357The default is: 358.Bd -literal -offset 3n 359aes128-ctr,aes192-ctr,aes256-ctr,arcfour256,arcfour128, 360aes128-gcm@openssh.com,aes256-gcm@openssh.com, 361chacha20-poly1305@openssh.com, 362aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,aes192-cbc, 363aes256-cbc,arcfour 364.Ed 365.Pp 366The list of available ciphers may also be obtained using the 367.Fl Q 368option of 369.Xr ssh 1 . 370.It Cm ClearAllForwardings 371Specifies that all local, remote, and dynamic port forwardings 372specified in the configuration files or on the command line be 373cleared. 374This option is primarily useful when used from the 375.Xr ssh 1 376command line to clear port forwardings set in 377configuration files, and is automatically set by 378.Xr scp 1 379and 380.Xr sftp 1 . 381The argument must be 382.Dq yes 383or 384.Dq no . 385The default is 386.Dq no . 387.It Cm Compression 388Specifies whether to use compression. 389The argument must be 390.Dq yes 391or 392.Dq no . 393The default is 394.Dq no . 395.It Cm CompressionLevel 396Specifies the compression level to use if compression is enabled. 397The argument must be an integer from 1 (fast) to 9 (slow, best). 398The default level is 6, which is good for most applications. 399The meaning of the values is the same as in 400.Xr gzip 1 . 401Note that this option applies to protocol version 1 only. 402.It Cm ConnectionAttempts 403Specifies the number of tries (one per second) to make before exiting. 404The argument must be an integer. 405This may be useful in scripts if the connection sometimes fails. 406The default is 1. 407.It Cm ConnectTimeout 408Specifies the timeout (in seconds) used when connecting to the 409SSH server, instead of using the default system TCP timeout. 410This value is used only when the target is down or really unreachable, 411not when it refuses the connection. 412.It Cm ControlMaster 413Enables the sharing of multiple sessions over a single network connection. 414When set to 415.Dq yes , 416.Xr ssh 1 417will listen for connections on a control socket specified using the 418.Cm ControlPath 419argument. 420Additional sessions can connect to this socket using the same 421.Cm ControlPath 422with 423.Cm ControlMaster 424set to 425.Dq no 426(the default). 427These sessions will try to reuse the master instance's network connection 428rather than initiating new ones, but will fall back to connecting normally 429if the control socket does not exist, or is not listening. 430.Pp 431Setting this to 432.Dq ask 433will cause ssh 434to listen for control connections, but require confirmation using the 435.Ev SSH_ASKPASS 436program before they are accepted (see 437.Xr ssh-add 1 438for details). 439If the 440.Cm ControlPath 441cannot be opened, 442ssh will continue without connecting to a master instance. 443.Pp 444X11 and 445.Xr ssh-agent 1 446forwarding is supported over these multiplexed connections, however the 447display and agent forwarded will be the one belonging to the master 448connection i.e. it is not possible to forward multiple displays or agents. 449.Pp 450Two additional options allow for opportunistic multiplexing: try to use a 451master connection but fall back to creating a new one if one does not already 452exist. 453These options are: 454.Dq auto 455and 456.Dq autoask . 457The latter requires confirmation like the 458.Dq ask 459option. 460.It Cm ControlPath 461Specify the path to the control socket used for connection sharing as described 462in the 463.Cm ControlMaster 464section above or the string 465.Dq none 466to disable connection sharing. 467In the path, 468.Ql %L 469will be substituted by the first component of the local host name, 470.Ql %l 471will be substituted by the local host name (including any domain name), 472.Ql %h 473will be substituted by the target host name, 474.Ql %n 475will be substituted by the original target host name 476specified on the command line, 477.Ql %p 478the destination port, 479.Ql %r 480by the remote login username, and 481.Ql %u 482by the username of the user running 483.Xr ssh 1 . 484It is recommended that any 485.Cm ControlPath 486used for opportunistic connection sharing include 487at least %h, %p, and %r. 488This ensures that shared connections are uniquely identified. 489.It Cm ControlPersist 490When used in conjunction with 491.Cm ControlMaster , 492specifies that the master connection should remain open 493in the background (waiting for future client connections) 494after the initial client connection has been closed. 495If set to 496.Dq no , 497then the master connection will not be placed into the background, 498and will close as soon as the initial client connection is closed. 499If set to 500.Dq yes , 501then the master connection will remain in the background indefinitely 502(until killed or closed via a mechanism such as the 503.Xr ssh 1 504.Dq Fl O No exit 505option). 506If set to a time in seconds, or a time in any of the formats documented in 507.Xr sshd_config 5 , 508then the backgrounded master connection will automatically terminate 509after it has remained idle (with no client connections) for the 510specified time. 511.It Cm DynamicForward 512Specifies that a TCP port on the local machine be forwarded 513over the secure channel, and the application 514protocol is then used to determine where to connect to from the 515remote machine. 516.Pp 517The argument must be 518.Sm off 519.Oo Ar bind_address : Oc Ar port . 520.Sm on 521IPv6 addresses can be specified by enclosing addresses in square brackets. 522By default, the local port is bound in accordance with the 523.Cm GatewayPorts 524setting. 525However, an explicit 526.Ar bind_address 527may be used to bind the connection to a specific address. 528The 529.Ar bind_address 530of 531.Dq localhost 532indicates that the listening port be bound for local use only, while an 533empty address or 534.Sq * 535indicates that the port should be available from all interfaces. 536.Pp 537Currently the SOCKS4 and SOCKS5 protocols are supported, and 538.Xr ssh 1 539will act as a SOCKS server. 540Multiple forwardings may be specified, and 541additional forwardings can be given on the command line. 542Only the superuser can forward privileged ports. 543.It Cm EnableSSHKeysign 544Setting this option to 545.Dq yes 546in the global client configuration file 547.Pa /etc/ssh/ssh_config 548enables the use of the helper program 549.Xr ssh-keysign 8 550during 551.Cm HostbasedAuthentication . 552The argument must be 553.Dq yes 554or 555.Dq no . 556The default is 557.Dq no . 558This option should be placed in the non-hostspecific section. 559See 560.Xr ssh-keysign 8 561for more information. 562.It Cm EscapeChar 563Sets the escape character (default: 564.Ql ~ ) . 565The escape character can also 566be set on the command line. 567The argument should be a single character, 568.Ql ^ 569followed by a letter, or 570.Dq none 571to disable the escape 572character entirely (making the connection transparent for binary 573data). 574.It Cm ExitOnForwardFailure 575Specifies whether 576.Xr ssh 1 577should terminate the connection if it cannot set up all requested 578dynamic, tunnel, local, and remote port forwardings. 579The argument must be 580.Dq yes 581or 582.Dq no . 583The default is 584.Dq no . 585.It Cm ForwardAgent 586Specifies whether the connection to the authentication agent (if any) 587will be forwarded to the remote machine. 588The argument must be 589.Dq yes 590or 591.Dq no . 592The default is 593.Dq no . 594.Pp 595Agent forwarding should be enabled with caution. 596Users with the ability to bypass file permissions on the remote host 597(for the agent's Unix-domain socket) 598can access the local agent through the forwarded connection. 599An attacker cannot obtain key material from the agent, 600however they can perform operations on the keys that enable them to 601authenticate using the identities loaded into the agent. 602.It Cm ForwardX11 603Specifies whether X11 connections will be automatically redirected 604over the secure channel and 605.Ev DISPLAY 606set. 607The argument must be 608.Dq yes 609or 610.Dq no . 611The default is 612.Dq no . 613.Pp 614X11 forwarding should be enabled with caution. 615Users with the ability to bypass file permissions on the remote host 616(for the user's X11 authorization database) 617can access the local X11 display through the forwarded connection. 618An attacker may then be able to perform activities such as keystroke monitoring 619if the 620.Cm ForwardX11Trusted 621option is also enabled. 622.It Cm ForwardX11Timeout 623Specify a timeout for untrusted X11 forwarding 624using the format described in the 625TIME FORMATS section of 626.Xr sshd_config 5 . 627X11 connections received by 628.Xr ssh 1 629after this time will be refused. 630The default is to disable untrusted X11 forwarding after twenty minutes has 631elapsed. 632.It Cm ForwardX11Trusted 633If this option is set to 634.Dq yes , 635remote X11 clients will have full access to the original X11 display. 636.Pp 637If this option is set to 638.Dq no , 639remote X11 clients will be considered untrusted and prevented 640from stealing or tampering with data belonging to trusted X11 641clients. 642Furthermore, the 643.Xr xauth 1 644token used for the session will be set to expire after 20 minutes. 645Remote clients will be refused access after this time. 646.Pp 647The default is 648.Dq no . 649.Pp 650See the X11 SECURITY extension specification for full details on 651the restrictions imposed on untrusted clients. 652.It Cm GatewayPorts 653Specifies whether remote hosts are allowed to connect to local 654forwarded ports. 655By default, 656.Xr ssh 1 657binds local port forwardings to the loopback address. 658This prevents other remote hosts from connecting to forwarded ports. 659.Cm GatewayPorts 660can be used to specify that ssh 661should bind local port forwardings to the wildcard address, 662thus allowing remote hosts to connect to forwarded ports. 663The argument must be 664.Dq yes 665or 666.Dq no . 667The default is 668.Dq no . 669.It Cm GlobalKnownHostsFile 670Specifies one or more files to use for the global 671host key database, separated by whitespace. 672The default is 673.Pa /etc/ssh/ssh_known_hosts , 674.Pa /etc/ssh/ssh_known_hosts2 . 675.It Cm GSSAPIAuthentication 676Specifies whether user authentication based on GSSAPI is allowed. 677The default is 678.Dq no . 679Note that this option applies to protocol version 2 only. 680.It Cm GSSAPIDelegateCredentials 681Forward (delegate) credentials to the server. 682The default is 683.Dq no . 684Note that this option applies to protocol version 2 only. 685.It Cm HashKnownHosts 686Indicates that 687.Xr ssh 1 688should hash host names and addresses when they are added to 689.Pa ~/.ssh/known_hosts . 690These hashed names may be used normally by 691.Xr ssh 1 692and 693.Xr sshd 8 , 694but they do not reveal identifying information should the file's contents 695be disclosed. 696The default is 697.Dq no . 698Note that existing names and addresses in known hosts files 699will not be converted automatically, 700but may be manually hashed using 701.Xr ssh-keygen 1 . 702.It Cm HostbasedAuthentication 703Specifies whether to try rhosts based authentication with public key 704authentication. 705The argument must be 706.Dq yes 707or 708.Dq no . 709The default is 710.Dq no . 711This option applies to protocol version 2 only and 712is similar to 713.Cm RhostsRSAAuthentication . 714.It Cm HostKeyAlgorithms 715Specifies the protocol version 2 host key algorithms 716that the client wants to use in order of preference. 717The default for this option is: 718.Bd -literal -offset 3n 719ecdsa-sha2-nistp256-cert-v01@openssh.com, 720ecdsa-sha2-nistp384-cert-v01@openssh.com, 721ecdsa-sha2-nistp521-cert-v01@openssh.com, 722ssh-ed25519-cert-v01@openssh.com, 723ssh-rsa-cert-v01@openssh.com,ssh-dss-cert-v01@openssh.com, 724ssh-rsa-cert-v00@openssh.com,ssh-dss-cert-v00@openssh.com, 725ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521, 726ssh-ed25519,ssh-rsa,ssh-dss 727.Ed 728.Pp 729If hostkeys are known for the destination host then this default is modified 730to prefer their algorithms. 731.It Cm HostKeyAlias 732Specifies an alias that should be used instead of the 733real host name when looking up or saving the host key 734in the host key database files. 735This option is useful for tunneling SSH connections 736or for multiple servers running on a single host. 737.It Cm HostName 738Specifies the real host name to log into. 739This can be used to specify nicknames or abbreviations for hosts. 740If the hostname contains the character sequence 741.Ql %h , 742then this will be replaced with the host name specified on the command line 743(this is useful for manipulating unqualified names). 744The default is the name given on the command line. 745Numeric IP addresses are also permitted (both on the command line and in 746.Cm HostName 747specifications). 748.It Cm IdentitiesOnly 749Specifies that 750.Xr ssh 1 751should only use the authentication identity files configured in the 752.Nm 753files, 754even if 755.Xr ssh-agent 1 756or a 757.Cm PKCS11Provider 758offers more identities. 759The argument to this keyword must be 760.Dq yes 761or 762.Dq no . 763This option is intended for situations where ssh-agent 764offers many different identities. 765The default is 766.Dq no . 767.It Cm IdentityFile 768Specifies a file from which the user's DSA, ECDSA, ED25519 or RSA authentication 769identity is read. 770The default is 771.Pa ~/.ssh/identity 772for protocol version 1, and 773.Pa ~/.ssh/id_dsa , 774.Pa ~/.ssh/id_ecdsa , 775.Pa ~/.ssh/id_ed25519 776and 777.Pa ~/.ssh/id_rsa 778for protocol version 2. 779Additionally, any identities represented by the authentication agent 780will be used for authentication unless 781.Cm IdentitiesOnly 782is set. 783.Xr ssh 1 784will try to load certificate information from the filename obtained by 785appending 786.Pa -cert.pub 787to the path of a specified 788.Cm IdentityFile . 789.Pp 790The file name may use the tilde 791syntax to refer to a user's home directory or one of the following 792escape characters: 793.Ql %d 794(local user's home directory), 795.Ql %u 796(local user name), 797.Ql %l 798(local host name), 799.Ql %h 800(remote host name) or 801.Ql %r 802(remote user name). 803.Pp 804It is possible to have 805multiple identity files specified in configuration files; all these 806identities will be tried in sequence. 807Multiple 808.Cm IdentityFile 809directives will add to the list of identities tried (this behaviour 810differs from that of other configuration directives). 811.Pp 812.Cm IdentityFile 813may be used in conjunction with 814.Cm IdentitiesOnly 815to select which identities in an agent are offered during authentication. 816.It Cm IgnoreUnknown 817Specifies a pattern-list of unknown options to be ignored if they are 818encountered in configuration parsing. 819This may be used to suppress errors if 820.Nm 821contains options that are unrecognised by 822.Xr ssh 1 . 823It is recommended that 824.Cm IgnoreUnknown 825be listed early in the configuration file as it will not be applied 826to unknown options that appear before it. 827.It Cm IPQoS 828Specifies the IPv4 type-of-service or DSCP class for connections. 829Accepted values are 830.Dq af11 , 831.Dq af12 , 832.Dq af13 , 833.Dq af21 , 834.Dq af22 , 835.Dq af23 , 836.Dq af31 , 837.Dq af32 , 838.Dq af33 , 839.Dq af41 , 840.Dq af42 , 841.Dq af43 , 842.Dq cs0 , 843.Dq cs1 , 844.Dq cs2 , 845.Dq cs3 , 846.Dq cs4 , 847.Dq cs5 , 848.Dq cs6 , 849.Dq cs7 , 850.Dq ef , 851.Dq lowdelay , 852.Dq throughput , 853.Dq reliability , 854or a numeric value. 855This option may take one or two arguments, separated by whitespace. 856If one argument is specified, it is used as the packet class unconditionally. 857If two values are specified, the first is automatically selected for 858interactive sessions and the second for non-interactive sessions. 859The default is 860.Dq lowdelay 861for interactive sessions and 862.Dq throughput 863for non-interactive sessions. 864.It Cm KbdInteractiveAuthentication 865Specifies whether to use keyboard-interactive authentication. 866The argument to this keyword must be 867.Dq yes 868or 869.Dq no . 870The default is 871.Dq yes . 872.It Cm KbdInteractiveDevices 873Specifies the list of methods to use in keyboard-interactive authentication. 874Multiple method names must be comma-separated. 875The default is to use the server specified list. 876The methods available vary depending on what the server supports. 877For an OpenSSH server, 878it may be zero or more of: 879.Dq bsdauth , 880.Dq pam , 881and 882.Dq skey . 883.It Cm KexAlgorithms 884Specifies the available KEX (Key Exchange) algorithms. 885Multiple algorithms must be comma-separated. 886The default is: 887.Bd -literal -offset indent 888curve25519-sha256@libssh.org, 889ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521, 890diffie-hellman-group-exchange-sha256, 891diffie-hellman-group-exchange-sha1, 892diffie-hellman-group14-sha1, 893diffie-hellman-group1-sha1 894.Ed 895.It Cm LocalCommand 896Specifies a command to execute on the local machine after successfully 897connecting to the server. 898The command string extends to the end of the line, and is executed with 899the user's shell. 900The following escape character substitutions will be performed: 901.Ql %d 902(local user's home directory), 903.Ql %h 904(remote host name), 905.Ql %l 906(local host name), 907.Ql %n 908(host name as provided on the command line), 909.Ql %p 910(remote port), 911.Ql %r 912(remote user name) or 913.Ql %u 914(local user name). 915.Pp 916The command is run synchronously and does not have access to the 917session of the 918.Xr ssh 1 919that spawned it. 920It should not be used for interactive commands. 921.Pp 922This directive is ignored unless 923.Cm PermitLocalCommand 924has been enabled. 925.It Cm LocalForward 926Specifies that a TCP port on the local machine be forwarded over 927the secure channel to the specified host and port from the remote machine. 928The first argument must be 929.Sm off 930.Oo Ar bind_address : Oc Ar port 931.Sm on 932and the second argument must be 933.Ar host : Ns Ar hostport . 934IPv6 addresses can be specified by enclosing addresses in square brackets. 935Multiple forwardings may be specified, and additional forwardings can be 936given on the command line. 937Only the superuser can forward privileged ports. 938By default, the local port is bound in accordance with the 939.Cm GatewayPorts 940setting. 941However, an explicit 942.Ar bind_address 943may be used to bind the connection to a specific address. 944The 945.Ar bind_address 946of 947.Dq localhost 948indicates that the listening port be bound for local use only, while an 949empty address or 950.Sq * 951indicates that the port should be available from all interfaces. 952.It Cm LogLevel 953Gives the verbosity level that is used when logging messages from 954.Xr ssh 1 . 955The possible values are: 956QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3. 957The default is INFO. 958DEBUG and DEBUG1 are equivalent. 959DEBUG2 and DEBUG3 each specify higher levels of verbose output. 960.It Cm MACs 961Specifies the MAC (message authentication code) algorithms 962in order of preference. 963The MAC algorithm is used in protocol version 2 964for data integrity protection. 965Multiple algorithms must be comma-separated. 966The algorithms that contain 967.Dq -etm 968calculate the MAC after encryption (encrypt-then-mac). 969These are considered safer and their use recommended. 970The default is: 971.Bd -literal -offset indent 972hmac-md5-etm@openssh.com,hmac-sha1-etm@openssh.com, 973umac-64-etm@openssh.com,umac-128-etm@openssh.com, 974hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com, 975hmac-ripemd160-etm@openssh.com,hmac-sha1-96-etm@openssh.com, 976hmac-md5-96-etm@openssh.com, 977hmac-md5,hmac-sha1,umac-64@openssh.com,umac-128@openssh.com, 978hmac-sha2-256,hmac-sha2-512,hmac-ripemd160, 979hmac-sha1-96,hmac-md5-96 980.Ed 981.It Cm NoHostAuthenticationForLocalhost 982This option can be used if the home directory is shared across machines. 983In this case localhost will refer to a different machine on each of 984the machines and the user will get many warnings about changed host keys. 985However, this option disables host authentication for localhost. 986The argument to this keyword must be 987.Dq yes 988or 989.Dq no . 990The default is to check the host key for localhost. 991.It Cm NumberOfPasswordPrompts 992Specifies the number of password prompts before giving up. 993The argument to this keyword must be an integer. 994The default is 3. 995.It Cm PasswordAuthentication 996Specifies whether to use password authentication. 997The argument to this keyword must be 998.Dq yes 999or 1000.Dq no . 1001The default is 1002.Dq yes . 1003.It Cm PermitLocalCommand 1004Allow local command execution via the 1005.Ic LocalCommand 1006option or using the 1007.Ic !\& Ns Ar command 1008escape sequence in 1009.Xr ssh 1 . 1010The argument must be 1011.Dq yes 1012or 1013.Dq no . 1014The default is 1015.Dq no . 1016.It Cm PKCS11Provider 1017Specifies which PKCS#11 provider to use. 1018The argument to this keyword is the PKCS#11 shared library 1019.Xr ssh 1 1020should use to communicate with a PKCS#11 token providing the user's 1021private RSA key. 1022.It Cm Port 1023Specifies the port number to connect on the remote host. 1024The default is 22. 1025.It Cm PreferredAuthentications 1026Specifies the order in which the client should try protocol 2 1027authentication methods. 1028This allows a client to prefer one method (e.g.\& 1029.Cm keyboard-interactive ) 1030over another method (e.g.\& 1031.Cm password ) . 1032The default is: 1033.Bd -literal -offset indent 1034gssapi-with-mic,hostbased,publickey, 1035keyboard-interactive,password 1036.Ed 1037.It Cm Protocol 1038Specifies the protocol versions 1039.Xr ssh 1 1040should support in order of preference. 1041The possible values are 1042.Sq 1 1043and 1044.Sq 2 . 1045Multiple versions must be comma-separated. 1046When this option is set to 1047.Dq 2,1 1048.Nm ssh 1049will try version 2 and fall back to version 1 1050if version 2 is not available. 1051The default is 1052.Sq 2 . 1053.It Cm ProxyCommand 1054Specifies the command to use to connect to the server. 1055The command 1056string extends to the end of the line, and is executed with 1057the user's shell. 1058In the command string, any occurrence of 1059.Ql %h 1060will be substituted by the host name to 1061connect, 1062.Ql %p 1063by the port, and 1064.Ql %r 1065by the remote user name. 1066The command can be basically anything, 1067and should read from its standard input and write to its standard output. 1068It should eventually connect an 1069.Xr sshd 8 1070server running on some machine, or execute 1071.Ic sshd -i 1072somewhere. 1073Host key management will be done using the 1074HostName of the host being connected (defaulting to the name typed by 1075the user). 1076Setting the command to 1077.Dq none 1078disables this option entirely. 1079Note that 1080.Cm CheckHostIP 1081is not available for connects with a proxy command. 1082.Pp 1083This directive is useful in conjunction with 1084.Xr nc 1 1085and its proxy support. 1086For example, the following directive would connect via an HTTP proxy at 1087192.0.2.0: 1088.Bd -literal -offset 3n 1089ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p 1090.Ed 1091.It Cm ProxyUseFdpass 1092Specifies that 1093.Cm ProxyCommand 1094will pass a connected file descriptor back to 1095.Xr ssh 1 1096instead of continuing to execute and pass data. 1097The default is 1098.Dq no . 1099.It Cm PubkeyAuthentication 1100Specifies whether to try public key authentication. 1101The argument to this keyword must be 1102.Dq yes 1103or 1104.Dq no . 1105The default is 1106.Dq yes . 1107This option applies to protocol version 2 only. 1108.It Cm RekeyLimit 1109Specifies the maximum amount of data that may be transmitted before the 1110session key is renegotiated, optionally followed a maximum amount of 1111time that may pass before the session key is renegotiated. 1112The first argument is specified in bytes and may have a suffix of 1113.Sq K , 1114.Sq M , 1115or 1116.Sq G 1117to indicate Kilobytes, Megabytes, or Gigabytes, respectively. 1118The default is between 1119.Sq 1G 1120and 1121.Sq 4G , 1122depending on the cipher. 1123The optional second value is specified in seconds and may use any of the 1124units documented in the 1125TIME FORMATS section of 1126.Xr sshd_config 5 . 1127The default value for 1128.Cm RekeyLimit 1129is 1130.Dq default none , 1131which means that rekeying is performed after the cipher's default amount 1132of data has been sent or received and no time based rekeying is done. 1133This option applies to protocol version 2 only. 1134.It Cm RemoteForward 1135Specifies that a TCP port on the remote machine be forwarded over 1136the secure channel to the specified host and port from the local machine. 1137The first argument must be 1138.Sm off 1139.Oo Ar bind_address : Oc Ar port 1140.Sm on 1141and the second argument must be 1142.Ar host : Ns Ar hostport . 1143IPv6 addresses can be specified by enclosing addresses in square brackets. 1144Multiple forwardings may be specified, and additional 1145forwardings can be given on the command line. 1146Privileged ports can be forwarded only when 1147logging in as root on the remote machine. 1148.Pp 1149If the 1150.Ar port 1151argument is 1152.Ql 0 , 1153the listen port will be dynamically allocated on the server and reported 1154to the client at run time. 1155.Pp 1156If the 1157.Ar bind_address 1158is not specified, the default is to only bind to loopback addresses. 1159If the 1160.Ar bind_address 1161is 1162.Ql * 1163or an empty string, then the forwarding is requested to listen on all 1164interfaces. 1165Specifying a remote 1166.Ar bind_address 1167will only succeed if the server's 1168.Cm GatewayPorts 1169option is enabled (see 1170.Xr sshd_config 5 ) . 1171.It Cm RequestTTY 1172Specifies whether to request a pseudo-tty for the session. 1173The argument may be one of: 1174.Dq no 1175(never request a TTY), 1176.Dq yes 1177(always request a TTY when standard input is a TTY), 1178.Dq force 1179(always request a TTY) or 1180.Dq auto 1181(request a TTY when opening a login session). 1182This option mirrors the 1183.Fl t 1184and 1185.Fl T 1186flags for 1187.Xr ssh 1 . 1188.It Cm RhostsRSAAuthentication 1189Specifies whether to try rhosts based authentication with RSA host 1190authentication. 1191The argument must be 1192.Dq yes 1193or 1194.Dq no . 1195The default is 1196.Dq no . 1197This option applies to protocol version 1 only and requires 1198.Xr ssh 1 1199to be setuid root. 1200.It Cm RSAAuthentication 1201Specifies whether to try RSA authentication. 1202The argument to this keyword must be 1203.Dq yes 1204or 1205.Dq no . 1206RSA authentication will only be 1207attempted if the identity file exists, or an authentication agent is 1208running. 1209The default is 1210.Dq yes . 1211Note that this option applies to protocol version 1 only. 1212.It Cm SendEnv 1213Specifies what variables from the local 1214.Xr environ 7 1215should be sent to the server. 1216Note that environment passing is only supported for protocol 2. 1217The server must also support it, and the server must be configured to 1218accept these environment variables. 1219Refer to 1220.Cm AcceptEnv 1221in 1222.Xr sshd_config 5 1223for how to configure the server. 1224Variables are specified by name, which may contain wildcard characters. 1225Multiple environment variables may be separated by whitespace or spread 1226across multiple 1227.Cm SendEnv 1228directives. 1229The default is not to send any environment variables. 1230.Pp 1231See 1232.Sx PATTERNS 1233for more information on patterns. 1234.It Cm ServerAliveCountMax 1235Sets the number of server alive messages (see below) which may be 1236sent without 1237.Xr ssh 1 1238receiving any messages back from the server. 1239If this threshold is reached while server alive messages are being sent, 1240ssh will disconnect from the server, terminating the session. 1241It is important to note that the use of server alive messages is very 1242different from 1243.Cm TCPKeepAlive 1244(below). 1245The server alive messages are sent through the encrypted channel 1246and therefore will not be spoofable. 1247The TCP keepalive option enabled by 1248.Cm TCPKeepAlive 1249is spoofable. 1250The server alive mechanism is valuable when the client or 1251server depend on knowing when a connection has become inactive. 1252.Pp 1253The default value is 3. 1254If, for example, 1255.Cm ServerAliveInterval 1256(see below) is set to 15 and 1257.Cm ServerAliveCountMax 1258is left at the default, if the server becomes unresponsive, 1259ssh will disconnect after approximately 45 seconds. 1260This option applies to protocol version 2 only. 1261.It Cm ServerAliveInterval 1262Sets a timeout interval in seconds after which if no data has been received 1263from the server, 1264.Xr ssh 1 1265will send a message through the encrypted 1266channel to request a response from the server. 1267The default 1268is 0, indicating that these messages will not be sent to the server. 1269This option applies to protocol version 2 only. 1270.It Cm StrictHostKeyChecking 1271If this flag is set to 1272.Dq yes , 1273.Xr ssh 1 1274will never automatically add host keys to the 1275.Pa ~/.ssh/known_hosts 1276file, and refuses to connect to hosts whose host key has changed. 1277This provides maximum protection against trojan horse attacks, 1278though it can be annoying when the 1279.Pa /etc/ssh/ssh_known_hosts 1280file is poorly maintained or when connections to new hosts are 1281frequently made. 1282This option forces the user to manually 1283add all new hosts. 1284If this flag is set to 1285.Dq no , 1286ssh will automatically add new host keys to the 1287user known hosts files. 1288If this flag is set to 1289.Dq ask , 1290new host keys 1291will be added to the user known host files only after the user 1292has confirmed that is what they really want to do, and 1293ssh will refuse to connect to hosts whose host key has changed. 1294The host keys of 1295known hosts will be verified automatically in all cases. 1296The argument must be 1297.Dq yes , 1298.Dq no , 1299or 1300.Dq ask . 1301The default is 1302.Dq ask . 1303.It Cm TCPKeepAlive 1304Specifies whether the system should send TCP keepalive messages to the 1305other side. 1306If they are sent, death of the connection or crash of one 1307of the machines will be properly noticed. 1308However, this means that 1309connections will die if the route is down temporarily, and some people 1310find it annoying. 1311.Pp 1312The default is 1313.Dq yes 1314(to send TCP keepalive messages), and the client will notice 1315if the network goes down or the remote host dies. 1316This is important in scripts, and many users want it too. 1317.Pp 1318To disable TCP keepalive messages, the value should be set to 1319.Dq no . 1320.It Cm Tunnel 1321Request 1322.Xr tun 4 1323device forwarding between the client and the server. 1324The argument must be 1325.Dq yes , 1326.Dq point-to-point 1327(layer 3), 1328.Dq ethernet 1329(layer 2), 1330or 1331.Dq no . 1332Specifying 1333.Dq yes 1334requests the default tunnel mode, which is 1335.Dq point-to-point . 1336The default is 1337.Dq no . 1338.It Cm TunnelDevice 1339Specifies the 1340.Xr tun 4 1341devices to open on the client 1342.Pq Ar local_tun 1343and the server 1344.Pq Ar remote_tun . 1345.Pp 1346The argument must be 1347.Sm off 1348.Ar local_tun Op : Ar remote_tun . 1349.Sm on 1350The devices may be specified by numerical ID or the keyword 1351.Dq any , 1352which uses the next available tunnel device. 1353If 1354.Ar remote_tun 1355is not specified, it defaults to 1356.Dq any . 1357The default is 1358.Dq any:any . 1359.It Cm UsePrivilegedPort 1360Specifies whether to use a privileged port for outgoing connections. 1361The argument must be 1362.Dq yes 1363or 1364.Dq no . 1365The default is 1366.Dq no . 1367If set to 1368.Dq yes , 1369.Xr ssh 1 1370must be setuid root. 1371Note that this option must be set to 1372.Dq yes 1373for 1374.Cm RhostsRSAAuthentication 1375with older servers. 1376.It Cm User 1377Specifies the user to log in as. 1378This can be useful when a different user name is used on different machines. 1379This saves the trouble of 1380having to remember to give the user name on the command line. 1381.It Cm UserKnownHostsFile 1382Specifies one or more files to use for the user 1383host key database, separated by whitespace. 1384The default is 1385.Pa ~/.ssh/known_hosts , 1386.Pa ~/.ssh/known_hosts2 . 1387.It Cm VerifyHostKeyDNS 1388Specifies whether to verify the remote key using DNS and SSHFP resource 1389records. 1390If this option is set to 1391.Dq yes , 1392the client will implicitly trust keys that match a secure fingerprint 1393from DNS. 1394Insecure fingerprints will be handled as if this option was set to 1395.Dq ask . 1396If this option is set to 1397.Dq ask , 1398information on fingerprint match will be displayed, but the user will still 1399need to confirm new host keys according to the 1400.Cm StrictHostKeyChecking 1401option. 1402The argument must be 1403.Dq yes , 1404.Dq no , 1405or 1406.Dq ask . 1407The default is 1408.Dq yes 1409if compiled with LDNS and 1410.Dq no 1411otherwise. 1412Note that this option applies to protocol version 2 only. 1413.Pp 1414See also VERIFYING HOST KEYS in 1415.Xr ssh 1 . 1416.It Cm VersionAddendum 1417Specifies a string to append to the regular version string to identify 1418OS- or site-specific modifications. 1419The default is 1420.Dq FreeBSD-20140130 . 1421.It Cm VisualHostKey 1422If this flag is set to 1423.Dq yes , 1424an ASCII art representation of the remote host key fingerprint is 1425printed in addition to the hex fingerprint string at login and 1426for unknown host keys. 1427If this flag is set to 1428.Dq no , 1429no fingerprint strings are printed at login and 1430only the hex fingerprint string will be printed for unknown host keys. 1431The default is 1432.Dq no . 1433.It Cm XAuthLocation 1434Specifies the full pathname of the 1435.Xr xauth 1 1436program. 1437The default is 1438.Pa /usr/local/bin/xauth . 1439.El 1440.Sh PATTERNS 1441A 1442.Em pattern 1443consists of zero or more non-whitespace characters, 1444.Sq * 1445(a wildcard that matches zero or more characters), 1446or 1447.Sq ?\& 1448(a wildcard that matches exactly one character). 1449For example, to specify a set of declarations for any host in the 1450.Dq .co.uk 1451set of domains, 1452the following pattern could be used: 1453.Pp 1454.Dl Host *.co.uk 1455.Pp 1456The following pattern 1457would match any host in the 192.168.0.[0-9] network range: 1458.Pp 1459.Dl Host 192.168.0.? 1460.Pp 1461A 1462.Em pattern-list 1463is a comma-separated list of patterns. 1464Patterns within pattern-lists may be negated 1465by preceding them with an exclamation mark 1466.Pq Sq !\& . 1467For example, 1468to allow a key to be used from anywhere within an organization 1469except from the 1470.Dq dialup 1471pool, 1472the following entry (in authorized_keys) could be used: 1473.Pp 1474.Dl from=\&"!*.dialup.example.com,*.example.com\&" 1475.Sh FILES 1476.Bl -tag -width Ds 1477.It Pa ~/.ssh/config 1478This is the per-user configuration file. 1479The format of this file is described above. 1480This file is used by the SSH client. 1481Because of the potential for abuse, this file must have strict permissions: 1482read/write for the user, and not accessible by others. 1483.It Pa /etc/ssh/ssh_config 1484Systemwide configuration file. 1485This file provides defaults for those 1486values that are not specified in the user's configuration file, and 1487for those users who do not have a configuration file. 1488This file must be world-readable. 1489.El 1490.Sh SEE ALSO 1491.Xr ssh 1 1492.Sh AUTHORS 1493OpenSSH is a derivative of the original and free 1494ssh 1.2.12 release by Tatu Ylonen. 1495Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 1496Theo de Raadt and Dug Song 1497removed many bugs, re-added newer features and 1498created OpenSSH. 1499Markus Friedl contributed the support for SSH 1500protocol versions 1.5 and 2.0. 1501