ssh_config.5

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