1.\" -*- nroff -*- 2.\" 3.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 5.\" All rights reserved 6.\" 7.\" As far as I am concerned, the code I have written for this software 8.\" can be used freely for any purpose. Any derived versions of this 9.\" software must be clearly marked as such, and if the derived work is 10.\" incompatible with the protocol description in the RFC file, it must be 11.\" called by a name other than "ssh" or "Secure Shell". 12.\" 13.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. 14.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. 15.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. 16.\" 17.\" Redistribution and use in source and binary forms, with or without 18.\" modification, are permitted provided that the following conditions 19.\" are met: 20.\" 1. Redistributions of source code must retain the above copyright 21.\" notice, this list of conditions and the following disclaimer. 22.\" 2. Redistributions in binary form must reproduce the above copyright 23.\" notice, this list of conditions and the following disclaimer in the 24.\" documentation and/or other materials provided with the distribution. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 27.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 28.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 29.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 30.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 31.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 32.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 33.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 34.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 35.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 36.\" 37.\" $OpenBSD: ssh_config.5,v 1.25 2003/11/12 20:14:51 jmc Exp $ 38.Dd September 25, 1999 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.Bl -tag -width Ds -compact 46.It Pa $HOME/.ssh/config 47.It Pa /etc/ssh/ssh_config 48.El 49.Sh DESCRIPTION 50.Nm ssh 51obtains configuration data from the following sources in 52the following order: 53.Bl -enum -offset indent -compact 54.It 55command-line options 56.It 57user's configuration file 58.Pq Pa $HOME/.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 bracketed 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. 81.Pp 82Otherwise a line is of the format 83.Dq keyword arguments . 84Configuration options may be separated by whitespace or 85optional whitespace and exactly one 86.Ql = ; 87the latter format is useful to avoid the need to quote whitespace 88when specifying configuration options using the 89.Nm ssh , 90.Nm scp 91and 92.Nm sftp 93.Fl o 94option. 95.Pp 96The possible 97keywords and their meanings are as follows (note that 98keywords are case-insensitive and arguments are case-sensitive): 99.Bl -tag -width Ds 100.It Cm Host 101Restricts the following declarations (up to the next 102.Cm Host 103keyword) to be only for those hosts that match one of the patterns 104given after the keyword. 105.Ql \&* 106and 107.Ql \&? 108can be used as wildcards in the 109patterns. 110A single 111.Ql \&* 112as a pattern can be used to provide global 113defaults for all hosts. 114The host is the 115.Ar hostname 116argument given on the command line (i.e., the name is not converted to 117a canonicalized host name before matching). 118.It Cm AddressFamily 119Specifies which address family to use when connecting. 120Valid arguments are 121.Dq any , 122.Dq inet 123(Use IPv4 only) or 124.Dq inet6 125(Use IPv6 only.) 126.It Cm BatchMode 127If set to 128.Dq yes , 129passphrase/password querying will be disabled. 130This option is useful in scripts and other batch jobs where no user 131is present to supply the password. 132The argument must be 133.Dq yes 134or 135.Dq no . 136The default is 137.Dq no . 138.It Cm BindAddress 139Specify the interface to transmit from on machines with multiple 140interfaces or aliased addresses. 141Note that this option does not work if 142.Cm UsePrivilegedPort 143is set to 144.Dq yes . 145.It Cm ChallengeResponseAuthentication 146Specifies whether to use challenge response authentication. 147The argument to this keyword must be 148.Dq yes 149or 150.Dq no . 151The default is 152.Dq yes . 153.It Cm CheckHostIP 154If this flag is set to 155.Dq yes , 156ssh will additionally check the host IP address in the 157.Pa known_hosts 158file. 159This allows ssh to detect if a host key changed due to DNS spoofing. 160If the option is set to 161.Dq no , 162the check will not be executed. 163The default is 164.Dq yes . 165.It Cm Cipher 166Specifies the cipher to use for encrypting the session 167in protocol version 1. 168Currently, 169.Dq blowfish , 170.Dq 3des , 171and 172.Dq des 173are supported. 174.Ar des 175is only supported in the 176.Nm ssh 177client for interoperability with legacy protocol 1 implementations 178that do not support the 179.Ar 3des 180cipher. 181Its use is strongly discouraged due to cryptographic weaknesses. 182The default is 183.Dq 3des . 184.It Cm Ciphers 185Specifies the ciphers allowed for protocol version 2 186in order of preference. 187Multiple ciphers must be comma-separated. 188The default is 189.Bd -literal 190 ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour, 191 aes192-cbc,aes256-cbc'' 192.Ed 193.It Cm ClearAllForwardings 194Specifies that all local, remote and dynamic port forwardings 195specified in the configuration files or on the command line be 196cleared. 197This option is primarily useful when used from the 198.Nm ssh 199command line to clear port forwardings set in 200configuration files, and is automatically set by 201.Xr scp 1 202and 203.Xr sftp 1 . 204The argument must be 205.Dq yes 206or 207.Dq no . 208The default is 209.Dq no . 210.It Cm Compression 211Specifies whether to use compression. 212The argument must be 213.Dq yes 214or 215.Dq no . 216The default is 217.Dq no . 218.It Cm CompressionLevel 219Specifies the compression level to use if compression is enabled. 220The argument must be an integer from 1 (fast) to 9 (slow, best). 221The default level is 6, which is good for most applications. 222The meaning of the values is the same as in 223.Xr gzip 1 . 224Note that this option applies to protocol version 1 only. 225.It Cm ConnectionAttempts 226Specifies the number of tries (one per second) to make before exiting. 227The argument must be an integer. 228This may be useful in scripts if the connection sometimes fails. 229The default is 1. 230.It Cm ConnectTimeout 231Specifies the timeout (in seconds) used when connecting to the ssh 232server, instead of using the default system TCP timeout. 233This value is used only when the target is down or really unreachable, 234not when it refuses the connection. 235.It Cm DynamicForward 236Specifies that a TCP/IP port on the local machine be forwarded 237over the secure channel, and the application 238protocol is then used to determine where to connect to from the 239remote machine. 240The argument must be a port number. 241Currently the SOCKS4 and SOCKS5 protocols are supported, and 242.Nm ssh 243will act as a SOCKS server. 244Multiple forwardings may be specified, and 245additional forwardings can be given on the command line. 246Only the superuser can forward privileged ports. 247.It Cm EnableSSHKeysign 248Setting this option to 249.Dq yes 250in the global client configuration file 251.Pa /etc/ssh/ssh_config 252enables the use of the helper program 253.Xr ssh-keysign 8 254during 255.Cm HostbasedAuthentication . 256The argument must be 257.Dq yes 258or 259.Dq no . 260The default is 261.Dq no . 262This option should be placed in the non-hostspecific section. 263See 264.Xr ssh-keysign 8 265for more information. 266.It Cm EscapeChar 267Sets the escape character (default: 268.Ql ~ ) . 269The escape character can also 270be set on the command line. 271The argument should be a single character, 272.Ql ^ 273followed by a letter, or 274.Dq none 275to disable the escape 276character entirely (making the connection transparent for binary 277data). 278.It Cm ForwardAgent 279Specifies whether the connection to the authentication agent (if any) 280will be forwarded to the remote machine. 281The argument must be 282.Dq yes 283or 284.Dq no . 285The default is 286.Dq no . 287.Pp 288Agent forwarding should be enabled with caution. 289Users with the ability to bypass file permissions on the remote host 290(for the agent's Unix-domain socket) 291can access the local agent through the forwarded connection. 292An attacker cannot obtain key material from the agent, 293however they can perform operations on the keys that enable them to 294authenticate using the identities loaded into the agent. 295.It Cm ForwardX11 296Specifies whether X11 connections will be automatically redirected 297over the secure channel and 298.Ev DISPLAY 299set. 300The argument must be 301.Dq yes 302or 303.Dq no . 304The default is 305.Dq no . 306.Pp 307X11 forwarding should be enabled with caution. 308Users with the ability to bypass file permissions on the remote host 309(for the user's X11 authorization database) 310can access the local X11 display through the forwarded connection. 311An attacker may then be able to perform activities such as keystroke monitoring 312if the 313.Cm ForwardX11Trusted 314option is also enabled. 315.It Cm ForwardX11Trusted 316If the this option is set to 317.Dq yes 318then remote X11 clients will have full access to the original X11 display. 319If this option is set to 320.Dq no 321then remote X11 clients will be considered untrusted and prevented 322from stealing or tampering with data belonging to trusted X11 323clients. 324.Pp 325The default is 326.Dq no . 327.Pp 328See the X11 SECURITY extension specification for full details on 329the restrictions imposed on untrusted clients. 330.It Cm GatewayPorts 331Specifies whether remote hosts are allowed to connect to local 332forwarded ports. 333By default, 334.Nm ssh 335binds local port forwardings to the loopback address. 336This prevents other remote hosts from connecting to forwarded ports. 337.Cm GatewayPorts 338can be used to specify that 339.Nm ssh 340should bind local port forwardings to the wildcard address, 341thus allowing remote hosts to connect to forwarded ports. 342The argument must be 343.Dq yes 344or 345.Dq no . 346The default is 347.Dq no . 348.It Cm GlobalKnownHostsFile 349Specifies a file to use for the global 350host key database instead of 351.Pa /etc/ssh/ssh_known_hosts . 352.It Cm GSSAPIAuthentication 353Specifies whether authentication based on GSSAPI may be used, either using 354the result of a successful key exchange, or using GSSAPI user 355authentication. 356The default is 357.Dq no . 358Note that this option applies to protocol version 2 only. 359.It Cm GSSAPIDelegateCredentials 360Forward (delegate) credentials to the server. 361The default is 362.Dq no . 363Note that this option applies to protocol version 2 only. 364.It Cm HostbasedAuthentication 365Specifies whether to try rhosts based authentication with public key 366authentication. 367The argument must be 368.Dq yes 369or 370.Dq no . 371The default is 372.Dq no . 373This option applies to protocol version 2 only and 374is similar to 375.Cm RhostsRSAAuthentication . 376.It Cm HostKeyAlgorithms 377Specifies the protocol version 2 host key algorithms 378that the client wants to use in order of preference. 379The default for this option is: 380.Dq ssh-rsa,ssh-dss . 381.It Cm HostKeyAlias 382Specifies an alias that should be used instead of the 383real host name when looking up or saving the host key 384in the host key database files. 385This option is useful for tunneling ssh connections 386or for multiple servers running on a single host. 387.It Cm HostName 388Specifies the real host name to log into. 389This can be used to specify nicknames or abbreviations for hosts. 390Default is the name given on the command line. 391Numeric IP addresses are also permitted (both on the command line and in 392.Cm HostName 393specifications). 394.It Cm IdentityFile 395Specifies a file from which the user's RSA or DSA authentication identity 396is read. 397The default is 398.Pa $HOME/.ssh/identity 399for protocol version 1, and 400.Pa $HOME/.ssh/id_rsa 401and 402.Pa $HOME/.ssh/id_dsa 403for protocol version 2. 404Additionally, any identities represented by the authentication agent 405will be used for authentication. 406The file name may use the tilde 407syntax to refer to a user's home directory. 408It is possible to have 409multiple identity files specified in configuration files; all these 410identities will be tried in sequence. 411.It Cm KeepAlive 412Specifies whether the system should send TCP keepalive messages to the 413other side. 414If they are sent, death of the connection or crash of one 415of the machines will be properly noticed. 416However, this means that 417connections will die if the route is down temporarily, and some people 418find it annoying. 419.Pp 420The default is 421.Dq yes 422(to send keepalives), and the client will notice 423if the network goes down or the remote host dies. 424This is important in scripts, and many users want it too. 425.Pp 426To disable keepalives, the value should be set to 427.Dq no . 428.It Cm LocalForward 429Specifies that a TCP/IP port on the local machine be forwarded over 430the secure channel to the specified host and port from the remote machine. 431The first argument must be a port number, and the second must be 432.Ar host:port . 433IPv6 addresses can be specified with an alternative syntax: 434.Ar host/port . 435Multiple forwardings may be specified, and additional 436forwardings can be given on the command line. 437Only the superuser can forward privileged ports. 438.It Cm LogLevel 439Gives the verbosity level that is used when logging messages from 440.Nm ssh . 441The possible values are: 442QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2 and DEBUG3. 443The default is INFO. 444DEBUG and DEBUG1 are equivalent. 445DEBUG2 and DEBUG3 each specify higher levels of verbose output. 446.It Cm MACs 447Specifies the MAC (message authentication code) algorithms 448in order of preference. 449The MAC algorithm is used in protocol version 2 450for data integrity protection. 451Multiple algorithms must be comma-separated. 452The default is 453.Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 . 454.It Cm NoHostAuthenticationForLocalhost 455This option can be used if the home directory is shared across machines. 456In this case localhost will refer to a different machine on each of 457the machines and the user will get many warnings about changed host keys. 458However, this option disables host authentication for localhost. 459The argument to this keyword must be 460.Dq yes 461or 462.Dq no . 463The default is to check the host key for localhost. 464.It Cm NumberOfPasswordPrompts 465Specifies the number of password prompts before giving up. 466The argument to this keyword must be an integer. 467Default is 3. 468.It Cm PasswordAuthentication 469Specifies whether to use password authentication. 470The argument to this keyword must be 471.Dq yes 472or 473.Dq no . 474The default is 475.Dq yes . 476.It Cm Port 477Specifies the port number to connect on the remote host. 478Default is 22. 479.It Cm PreferredAuthentications 480Specifies the order in which the client should try protocol 2 481authentication methods. 482This allows a client to prefer one method (e.g. 483.Cm keyboard-interactive ) 484over another method (e.g. 485.Cm password ) 486The default for this option is: 487.Dq hostbased,publickey,keyboard-interactive,password . 488.It Cm Protocol 489Specifies the protocol versions 490.Nm ssh 491should support in order of preference. 492The possible values are 493.Dq 1 494and 495.Dq 2 . 496Multiple versions must be comma-separated. 497The default is 498.Dq 2,1 . 499This means that 500.Nm ssh 501tries version 2 and falls back to version 1 502if version 2 is not available. 503.It Cm ProxyCommand 504Specifies the command to use to connect to the server. 505The command 506string extends to the end of the line, and is executed with 507.Pa /bin/sh . 508In the command string, 509.Ql %h 510will be substituted by the host name to 511connect and 512.Ql %p 513by the port. 514The command can be basically anything, 515and should read from its standard input and write to its standard output. 516It should eventually connect an 517.Xr sshd 8 518server running on some machine, or execute 519.Ic sshd -i 520somewhere. 521Host key management will be done using the 522HostName of the host being connected (defaulting to the name typed by 523the user). 524Setting the command to 525.Dq none 526disables this option entirely. 527Note that 528.Cm CheckHostIP 529is not available for connects with a proxy command. 530.Pp 531.It Cm PubkeyAuthentication 532Specifies whether to try public key authentication. 533The argument to this keyword must be 534.Dq yes 535or 536.Dq no . 537The default is 538.Dq yes . 539This option applies to protocol version 2 only. 540.It Cm RemoteForward 541Specifies that a TCP/IP port on the remote machine be forwarded over 542the secure channel to the specified host and port from the local machine. 543The first argument must be a port number, and the second must be 544.Ar host:port . 545IPv6 addresses can be specified with an alternative syntax: 546.Ar host/port . 547Multiple forwardings may be specified, and additional 548forwardings can be given on the command line. 549Only the superuser can forward privileged ports. 550.It Cm RhostsRSAAuthentication 551Specifies whether to try rhosts based authentication with RSA host 552authentication. 553The argument must be 554.Dq yes 555or 556.Dq no . 557The default is 558.Dq no . 559This option applies to protocol version 1 only and requires 560.Nm ssh 561to be setuid root. 562.It Cm RSAAuthentication 563Specifies whether to try RSA authentication. 564The argument to this keyword must be 565.Dq yes 566or 567.Dq no . 568RSA authentication will only be 569attempted if the identity file exists, or an authentication agent is 570running. 571The default is 572.Dq yes . 573Note that this option applies to protocol version 1 only. 574.It Cm SmartcardDevice 575Specifies which smartcard device to use. 576The argument to this keyword is the device 577.Nm ssh 578should use to communicate with a smartcard used for storing the user's 579private RSA key. 580By default, no device is specified and smartcard support is not activated. 581.It Cm StrictHostKeyChecking 582If this flag is set to 583.Dq yes , 584.Nm ssh 585will never automatically add host keys to the 586.Pa $HOME/.ssh/known_hosts 587file, and refuses to connect to hosts whose host key has changed. 588This provides maximum protection against trojan horse attacks, 589however, can be annoying when the 590.Pa /etc/ssh/ssh_known_hosts 591file is poorly maintained, or connections to new hosts are 592frequently made. 593This option forces the user to manually 594add all new hosts. 595If this flag is set to 596.Dq no , 597.Nm ssh 598will automatically add new host keys to the 599user known hosts files. 600If this flag is set to 601.Dq ask , 602new host keys 603will be added to the user known host files only after the user 604has confirmed that is what they really want to do, and 605.Nm ssh 606will refuse to connect to hosts whose host key has changed. 607The host keys of 608known hosts will be verified automatically in all cases. 609The argument must be 610.Dq yes , 611.Dq no 612or 613.Dq ask . 614The default is 615.Dq ask . 616.It Cm UsePrivilegedPort 617Specifies whether to use a privileged port for outgoing connections. 618The argument must be 619.Dq yes 620or 621.Dq no . 622The default is 623.Dq no . 624If set to 625.Dq yes 626.Nm ssh 627must be setuid root. 628Note that this option must be set to 629.Dq yes 630for 631.Cm RhostsRSAAuthentication 632with older servers. 633.It Cm User 634Specifies the user to log in as. 635This can be useful when a different user name is used on different machines. 636This saves the trouble of 637having to remember to give the user name on the command line. 638.It Cm UserKnownHostsFile 639Specifies a file to use for the user 640host key database instead of 641.Pa $HOME/.ssh/known_hosts . 642.It Cm VerifyHostKeyDNS 643Specifies whether to verify the remote key using DNS and SSHFP resource 644records. 645If this option is set to 646.Dq yes , 647the client will implicitly trust keys that match a secure fingerprint 648from DNS. 649Insecure fingerprints will be handled as if this option was set to 650.Dq ask . 651If this option is set to 652.Dq ask , 653information on fingerprint match will be displayed, but the user will still 654need to confirm new host keys according to the 655.Cm StrictHostKeyChecking 656option. 657The argument must be 658.Dq yes , 659.Dq no 660or 661.Dq ask . 662The default is 663.Dq no . 664Note that this option applies to protocol version 2 only. 665.It Cm XAuthLocation 666Specifies the full pathname of the 667.Xr xauth 1 668program. 669The default is 670.Pa /usr/X11R6/bin/xauth . 671.El 672.Sh FILES 673.Bl -tag -width Ds 674.It Pa $HOME/.ssh/config 675This is the per-user configuration file. 676The format of this file is described above. 677This file is used by the 678.Nm ssh 679client. 680This file does not usually contain any sensitive information, 681but the recommended permissions are read/write for the user, and not 682accessible by others. 683.It Pa /etc/ssh/ssh_config 684Systemwide configuration file. 685This file provides defaults for those 686values that are not specified in the user's configuration file, and 687for those users who do not have a configuration file. 688This file must be world-readable. 689.El 690.Sh SEE ALSO 691.Xr ssh 1 692.Sh AUTHORS 693OpenSSH is a derivative of the original and free 694ssh 1.2.12 release by Tatu Ylonen. 695Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 696Theo de Raadt and Dug Song 697removed many bugs, re-added newer features and 698created OpenSSH. 699Markus Friedl contributed the support for SSH 700protocol versions 1.5 and 2.0. 701