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