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