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.1 2002/06/20 19:56:07 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 $HOME/.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 command line options, user's configuration file
  54 .Pq Pa $HOME/.ssh/config ,
  55 and system-wide configuration file
  56 .Pq Pa /etc/ssh/ssh_config .
  57 .Pp
  58 For each parameter, the first obtained value
  59 will be used.
  60 The configuration files contain sections bracketed by
  61 .Dq Host
  62 specifications, and that section is only applied for hosts that
  63 match one of the patterns given in the specification.
  64 The matched host name is the one given on the command line.
  65 .Pp
  66 Since the first obtained value for each parameter is used, more
  67 host-specific declarations should be given near the beginning of the
  68 file, and general defaults at the end.
  69 .Pp
  70 The configuration file has the following format:
  71 .Pp
  72 Empty lines and lines starting with
  73 .Ql #
  74 are comments.
  75 .Pp
  76 Otherwise a line is of the format
  77 .Dq keyword arguments .
  78 Configuration options may be separated by whitespace or
  79 optional whitespace and exactly one
  80 .Ql = ;
  81 the latter format is useful to avoid the need to quote whitespace
  82 when specifying configuration options using the
  83 .Nm ssh ,
  84 .Nm scp
  85 and
  86 .Nm sftp
  87 .Fl o
  88 option.
  89 .Pp
  90 The possible
  91 keywords and their meanings are as follows (note that
  92 keywords are case-insensitive and arguments are case-sensitive):
  93 .Bl -tag -width Ds
  94 .It Cm Host
  95 Restricts the following declarations (up to the next
  96 .Cm Host
  97 keyword) to be only for those hosts that match one of the patterns
  98 given after the keyword.
  99 .Ql \&*
 100 and
 101 .Ql ?
 102 can be used as wildcards in the
 103 patterns.
 104 A single
 105 .Ql \&*
 106 as a pattern can be used to provide global
 107 defaults for all hosts.
 108 The host is the
 109 .Ar hostname
 110 argument given on the command line (i.e., the name is not converted to
 111 a canonicalized host name before matching).
 112 .It Cm AFSTokenPassing
 113 Specifies whether to pass AFS tokens to remote host.
 114 The argument to this keyword must be
 115 .Dq yes
 116 or
 117 .Dq no .
 118 This option applies to protocol version 1 only.
 119 .It Cm BatchMode
 120 If set to
 121 .Dq yes ,
 122 passphrase/password querying will be disabled.
 123 This option is useful in scripts and other batch jobs where no user
 124 is present to supply the password.
 125 The argument must be
 126 .Dq yes
 127 or
 128 .Dq no .
 129 The default is
 130 .Dq no .
 131 .It Cm BindAddress
 132 Specify the interface to transmit from on machines with multiple
 133 interfaces or aliased addresses.
 134 Note that this option does not work if
 135 .Cm UsePrivilegedPort
 136 is set to
 137 .Dq yes .
 138 .It Cm ChallengeResponseAuthentication
 139 Specifies whether to use challenge response authentication.
 140 The argument to this keyword must be
 141 .Dq yes
 142 or
 143 .Dq no .
 144 The default is
 145 .Dq yes .
 146 .It Cm CheckHostIP
 147 If this flag is set to
 148 .Dq yes ,
 149 ssh will additionally check the host IP address in the
 150 .Pa known_hosts
 151 file.
 152 This allows ssh to detect if a host key changed due to DNS spoofing.
 153 If the option is set to
 154 .Dq no ,
 155 the check will not be executed.
 156 The default is
 157 .Dq yes .
 158 .It Cm Cipher
 159 Specifies the cipher to use for encrypting the session
 160 in protocol version 1.
 161 Currently,
 162 .Dq blowfish ,
 163 .Dq 3des ,
 164 and
 165 .Dq des
 166 are supported.
 167 .Ar des
 168 is only supported in the
 169 .Nm ssh
 170 client for interoperability with legacy protocol 1 implementations
 171 that do not support the
 172 .Ar 3des
 173 cipher.  Its use is strongly discouraged due to cryptographic
 174 weaknesses.
 175 The default is
 176 .Dq 3des .
 177 .It Cm Ciphers
 178 Specifies the ciphers allowed for protocol version 2
 179 in order of preference.
 180 Multiple ciphers must be comma-separated.
 181 The default is
 182 .Pp
 183 .Bd -literal
 184   ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,
 185     aes192-cbc,aes256-cbc''
 186 .Ed
 187 .It Cm ClearAllForwardings
 188 Specifies that all local, remote and dynamic port forwardings
 189 specified in the configuration files or on the command line be
 190 cleared.  This option is primarily useful when used from the
 191 .Nm ssh
 192 command line to clear port forwardings set in
 193 configuration files, and is automatically set by
 194 .Xr scp 1
 195 and
 196 .Xr sftp 1 .
 197 The argument must be
 198 .Dq yes
 199 or
 200 .Dq no .
 201 The default is
 202 .Dq no .
 203 .It Cm Compression
 204 Specifies whether to use compression.
 205 The argument must be
 206 .Dq yes
 207 or
 208 .Dq no .
 209 The default is
 210 .Dq no .
 211 .It Cm CompressionLevel
 212 Specifies the compression level to use if compression is enabled.
 213 The argument must be an integer from 1 (fast) to 9 (slow, best).
 214 The default level is 6, which is good for most applications.
 215 The meaning of the values is the same as in
 216 .Xr gzip 1 .
 217 Note that this option applies to protocol version 1 only.
 218 .It Cm ConnectionAttempts
 219 Specifies the number of tries (one per second) to make before exiting.
 220 The argument must be an integer.
 221 This may be useful in scripts if the connection sometimes fails.
 222 The default is 1.
 223 .It Cm DynamicForward
 224 Specifies that a TCP/IP port on the local machine be forwarded
 225 over the secure channel, and the application
 226 protocol is then used to determine where to connect to from the
 227 remote machine.  The argument must be a port number.
 228 Currently the SOCKS4 protocol is supported, and
 229 .Nm ssh
 230 will act as a SOCKS4 server.
 231 Multiple forwardings may be specified, and
 232 additional forwardings can be given on the command line.  Only
 233 the superuser can forward privileged ports.
 234 .It Cm EscapeChar
 235 Sets the escape character (default:
 236 .Ql ~ ) .
 237 The escape character can also
 238 be set on the command line.
 239 The argument should be a single character,
 240 .Ql ^
 241 followed by a letter, or
 242 .Dq none
 243 to disable the escape
 244 character entirely (making the connection transparent for binary
 245 data).
 246 .It Cm ForwardAgent
 247 Specifies whether the connection to the authentication agent (if any)
 248 will be forwarded to the remote machine.
 249 The argument must be
 250 .Dq yes
 251 or
 252 .Dq no .
 253 The default is
 254 .Dq no .
 255 .It Cm ForwardX11
 256 Specifies whether X11 connections will be automatically redirected
 257 over the secure channel and
 258 .Ev DISPLAY
 259 set.
 260 The argument must be
 261 .Dq yes
 262 or
 263 .Dq no .
 264 The default is
 265 .Dq no .
 266 .It Cm GatewayPorts
 267 Specifies whether remote hosts are allowed to connect to local
 268 forwarded ports.
 269 By default,
 270 .Nm ssh
 271 binds local port forwardings to the loopback address.  This
 272 prevents other remote hosts from connecting to forwarded ports.
 273 .Cm GatewayPorts
 274 can be used to specify that
 275 .Nm ssh
 276 should bind local port forwardings to the wildcard address,
 277 thus allowing remote hosts to connect to forwarded ports.
 278 The argument must be
 279 .Dq yes
 280 or
 281 .Dq no .
 282 The default is
 283 .Dq no .
 284 .It Cm GlobalKnownHostsFile
 285 Specifies a file to use for the global
 286 host key database instead of
 287 .Pa /etc/ssh/ssh_known_hosts .
 288 .It Cm HostbasedAuthentication
 289 Specifies whether to try rhosts based authentication with public key
 290 authentication.
 291 The argument must be
 292 .Dq yes
 293 or
 294 .Dq no .
 295 The default is
 296 .Dq no .
 297 This option applies to protocol version 2 only and
 298 is similar to
 299 .Cm RhostsRSAAuthentication .
 300 .It Cm HostKeyAlgorithms
 301 Specifies the protocol version 2 host key algorithms
 302 that the client wants to use in order of preference.
 303 The default for this option is:
 304 .Dq ssh-rsa,ssh-dss .
 305 .It Cm HostKeyAlias
 306 Specifies an alias that should be used instead of the
 307 real host name when looking up or saving the host key
 308 in the host key database files.
 309 This option is useful for tunneling ssh connections
 310 or for multiple servers running on a single host.
 311 .It Cm HostName
 312 Specifies the real host name to log into.
 313 This can be used to specify nicknames or abbreviations for hosts.
 314 Default is the name given on the command line.
 315 Numeric IP addresses are also permitted (both on the command line and in
 316 .Cm HostName
 317 specifications).
 318 .It Cm IdentityFile
 319 Specifies a file from which the user's RSA or DSA authentication identity
 320 is read. The default is
 321 .Pa $HOME/.ssh/identity
 322 for protocol version 1, and
 323 .Pa $HOME/.ssh/id_rsa
 324 and
 325 .Pa $HOME/.ssh/id_dsa
 326 for protocol version 2.
 327 Additionally, any identities represented by the authentication agent
 328 will be used for authentication.
 329 The file name may use the tilde
 330 syntax to refer to a user's home directory.
 331 It is possible to have
 332 multiple identity files specified in configuration files; all these
 333 identities will be tried in sequence.
 334 .It Cm KeepAlive
 335 Specifies whether the system should send TCP keepalive messages to the
 336 other side.
 337 If they are sent, death of the connection or crash of one
 338 of the machines will be properly noticed.
 339 However, this means that
 340 connections will die if the route is down temporarily, and some people
 341 find it annoying.
 342 .Pp
 343 The default is
 344 .Dq yes
 345 (to send keepalives), and the client will notice
 346 if the network goes down or the remote host dies.
 347 This is important in scripts, and many users want it too.
 348 .Pp
 349 To disable keepalives, the value should be set to
 350 .Dq no .
 351 .It Cm KerberosAuthentication
 352 Specifies whether Kerberos authentication will be used.
 353 The argument to this keyword must be
 354 .Dq yes
 355 or
 356 .Dq no .
 357 .It Cm KerberosTgtPassing
 358 Specifies whether a Kerberos TGT will be forwarded to the server.
 359 This will only work if the Kerberos server is actually an AFS kaserver.
 360 The argument to this keyword must be
 361 .Dq yes
 362 or
 363 .Dq no .
 364 .It Cm LocalForward
 365 Specifies that a TCP/IP port on the local machine be forwarded over
 366 the secure channel to the specified host and port from the remote machine.
 367 The first argument must be a port number, and the second must be
 368 .Ar host:port .
 369 IPv6 addresses can be specified with an alternative syntax:
 370 .Ar host/port .
 371 Multiple forwardings may be specified, and additional
 372 forwardings can be given on the command line.
 373 Only the superuser can forward privileged ports.
 374 .It Cm LogLevel
 375 Gives the verbosity level that is used when logging messages from
 376 .Nm ssh .
 377 The possible values are:
 378 QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2 and DEBUG3.
 379 The default is INFO.  DEBUG and DEBUG1 are equivalent.  DEBUG2
 380 and DEBUG3 each specify higher levels of verbose output.
 381 .It Cm MACs
 382 Specifies the MAC (message authentication code) algorithms
 383 in order of preference.
 384 The MAC algorithm is used in protocol version 2
 385 for data integrity protection.
 386 Multiple algorithms must be comma-separated.
 387 The default is
 388 .Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 .
 389 .It Cm NoHostAuthenticationForLocalhost
 390 This option can be used if the home directory is shared across machines.
 391 In this case localhost will refer to a different machine on each of
 392 the machines and the user will get many warnings about changed host keys.
 393 However, this option disables host authentication for localhost.
 394 The argument to this keyword must be
 395 .Dq yes
 396 or
 397 .Dq no .
 398 The default is to check the host key for localhost.
 399 .It Cm NumberOfPasswordPrompts
 400 Specifies the number of password prompts before giving up.
 401 The argument to this keyword must be an integer.
 402 Default is 3.
 403 .It Cm PasswordAuthentication
 404 Specifies whether to use password authentication.
 405 The argument to this keyword must be
 406 .Dq yes
 407 or
 408 .Dq no .
 409 The default is
 410 .Dq yes .
 411 .It Cm Port
 412 Specifies the port number to connect on the remote host.
 413 Default is 22.
 414 .It Cm PreferredAuthentications
 415 Specifies the order in which the client should try protocol 2
 416 authentication methods. This allows a client to prefer one method (e.g.
 417 .Cm keyboard-interactive )
 418 over another method (e.g.
 419 .Cm password )
 420 The default for this option is:
 421 .Dq hostbased,publickey,keyboard-interactive,password .
 422 .It Cm Protocol
 423 Specifies the protocol versions
 424 .Nm ssh
 425 should support in order of preference.
 426 The possible values are
 427 .Dq 1
 428 and
 429 .Dq 2 .
 430 Multiple versions must be comma-separated.
 431 The default is
 432 .Dq 2,1 .
 433 This means that
 434 .Nm ssh
 435 tries version 2 and falls back to version 1
 436 if version 2 is not available.
 437 .It Cm ProxyCommand
 438 Specifies the command to use to connect to the server.
 439 The command
 440 string extends to the end of the line, and is executed with
 441 .Pa /bin/sh .
 442 In the command string,
 443 .Ql %h
 444 will be substituted by the host name to
 445 connect and
 446 .Ql %p
 447 by the port.
 448 The command can be basically anything,
 449 and should read from its standard input and write to its standard output.
 450 It should eventually connect an
 451 .Xr sshd 8
 452 server running on some machine, or execute
 453 .Ic sshd -i
 454 somewhere.
 455 Host key management will be done using the
 456 HostName of the host being connected (defaulting to the name typed by
 457 the user).
 458 Note that
 459 .Cm CheckHostIP
 460 is not available for connects with a proxy command.
 461 .Pp
 462 .It Cm PubkeyAuthentication
 463 Specifies whether to try public key authentication.
 464 The argument to this keyword must be
 465 .Dq yes
 466 or
 467 .Dq no .
 468 The default is
 469 .Dq yes .
 470 This option applies to protocol version 2 only.
 471 .It Cm RemoteForward
 472 Specifies that a TCP/IP port on the remote machine be forwarded over
 473 the secure channel to the specified host and port from the local machine.
 474 The first argument must be a port number, and the second must be
 475 .Ar host:port .
 476 IPv6 addresses can be specified with an alternative syntax:
 477 .Ar host/port .
 478 Multiple forwardings may be specified, and additional
 479 forwardings can be given on the command line.
 480 Only the superuser can forward privileged ports.
 481 .It Cm RhostsAuthentication
 482 Specifies whether to try rhosts based authentication.
 483 Note that this
 484 declaration only affects the client side and has no effect whatsoever
 485 on security.
 486 Most servers do not permit RhostsAuthentication because it
 487 is not secure (see
 488 .Cm RhostsRSAAuthentication ) .
 489 The argument to this keyword must be
 490 .Dq yes
 491 or
 492 .Dq no .
 493 The default is
 494 .Dq no .
 495 This option applies to protocol version 1 only.
 496 .It Cm RhostsRSAAuthentication
 497 Specifies whether to try rhosts based authentication with RSA host
 498 authentication.
 499 The argument must be
 500 .Dq yes
 501 or
 502 .Dq no .
 503 The default is
 504 .Dq no .
 505 This option applies to protocol version 1 only and requires
 506 .Nm ssh
 507 to be setuid root.
 508 .It Cm RSAAuthentication
 509 Specifies whether to try RSA authentication.
 510 The argument to this keyword must be
 511 .Dq yes
 512 or
 513 .Dq no .
 514 RSA authentication will only be
 515 attempted if the identity file exists, or an authentication agent is
 516 running.
 517 The default is
 518 .Dq yes .
 519 Note that this option applies to protocol version 1 only.
 520 .It Cm SmartcardDevice
 521 Specifies which smartcard device to use. The argument to this keyword is
 522 the device
 523 .Nm ssh
 524 should use to communicate with a smartcard used for storing the user's
 525 private RSA key. By default, no device is specified and smartcard support
 526 is not activated.
 527 .It Cm StrictHostKeyChecking
 528 If this flag is set to
 529 .Dq yes ,
 530 .Nm ssh
 531 will never automatically add host keys to the
 532 .Pa $HOME/.ssh/known_hosts
 533 file, and refuses to connect to hosts whose host key has changed.
 534 This provides maximum protection against trojan horse attacks,
 535 however, can be annoying when the
 536 .Pa /etc/ssh/ssh_known_hosts
 537 file is poorly maintained, or connections to new hosts are
 538 frequently made.
 539 This option forces the user to manually
 540 add all new hosts.
 541 If this flag is set to
 542 .Dq no ,
 543 .Nm ssh
 544 will automatically add new host keys to the
 545 user known hosts files.
 546 If this flag is set to
 547 .Dq ask ,
 548 new host keys
 549 will be added to the user known host files only after the user
 550 has confirmed that is what they really want to do, and
 551 .Nm ssh
 552 will refuse to connect to hosts whose host key has changed.
 553 The host keys of
 554 known hosts will be verified automatically in all cases.
 555 The argument must be
 556 .Dq yes ,
 557 .Dq no
 558 or
 559 .Dq ask .
 560 The default is
 561 .Dq ask .
 562 .It Cm UsePrivilegedPort
 563 Specifies whether to use a privileged port for outgoing connections.
 564 The argument must be
 565 .Dq yes
 566 or
 567 .Dq no .
 568 The default is
 569 .Dq no .
 570 Note that this option must be set to
 571 .Dq yes
 572 if
 573 .Cm RhostsAuthentication
 574 and
 575 .Cm RhostsRSAAuthentication
 576 authentications are needed with older servers.
 577 .It Cm User
 578 Specifies the user to log in as.
 579 This can be useful when a different user name is used on different machines.
 580 This saves the trouble of
 581 having to remember to give the user name on the command line.
 582 .It Cm UserKnownHostsFile
 583 Specifies a file to use for the user
 584 host key database instead of
 585 .Pa $HOME/.ssh/known_hosts .
 586 .It Cm XAuthLocation
 587 Specifies the location of the
 588 .Xr xauth 1
 589 program.
 590 The default is
 591 .Pa /usr/X11R6/bin/xauth .
 592 .El
 593 .Sh FILES
 594 .Bl -tag -width Ds
 595 .It Pa $HOME/.ssh/config
 596 This is the per-user configuration file.
 597 The format of this file is described above.
 598 This file is used by the
 599 .Nm ssh
 600 client.
 601 This file does not usually contain any sensitive information,
 602 but the recommended permissions are read/write for the user, and not
 603 accessible by others.
 604 .It Pa /etc/ssh/ssh_config
 605 Systemwide configuration file.
 606 This file provides defaults for those
 607 values that are not specified in the user's configuration file, and
 608 for those users who do not have a configuration file.
 609 This file must be world-readable.
 610 .El
 611 .Sh AUTHORS
 612 OpenSSH is a derivative of the original and free
 613 ssh 1.2.12 release by Tatu Ylonen.
 614 Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
 615 Theo de Raadt and Dug Song
 616 removed many bugs, re-added newer features and
 617 created OpenSSH.
 618 Markus Friedl contributed the support for SSH
 619 protocol versions 1.5 and 2.0.
 620 .Sh SEE ALSO
 621 .Xr ssh 1