ssh_config.5

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