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