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