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