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