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