Annotation of src/usr.bin/ssh/ssh_config.5, Revision 1.198
1.1 stevesk 1: .\"
2: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
3: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
4: .\" All rights reserved
5: .\"
6: .\" As far as I am concerned, the code I have written for this software
7: .\" can be used freely for any purpose. Any derived versions of this
8: .\" software must be clearly marked as such, and if the derived work is
9: .\" incompatible with the protocol description in the RFC file, it must be
10: .\" called by a name other than "ssh" or "Secure Shell".
11: .\"
12: .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
13: .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
14: .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
15: .\"
16: .\" Redistribution and use in source and binary forms, with or without
17: .\" modification, are permitted provided that the following conditions
18: .\" are met:
19: .\" 1. Redistributions of source code must retain the above copyright
20: .\" notice, this list of conditions and the following disclaimer.
21: .\" 2. Redistributions in binary form must reproduce the above copyright
22: .\" notice, this list of conditions and the following disclaimer in the
23: .\" documentation and/or other materials provided with the distribution.
24: .\"
25: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
26: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
27: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
28: .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
29: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
30: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
31: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
32: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
34: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35: .\"
1.198 ! djm 36: .\" $OpenBSD: ssh_config.5,v 1.197 2014/12/21 23:12:42 djm Exp $
! 37: .Dd $Mdocdate: December 21 2014 $
1.1 stevesk 38: .Dt SSH_CONFIG 5
39: .Os
40: .Sh NAME
41: .Nm ssh_config
42: .Nd OpenSSH SSH client configuration files
43: .Sh SYNOPSIS
1.98 jmc 44: .Nm ~/.ssh/config
45: .Nm /etc/ssh/ssh_config
1.1 stevesk 46: .Sh DESCRIPTION
1.84 jmc 47: .Xr ssh 1
1.1 stevesk 48: obtains configuration data from the following sources in
49: the following order:
1.79 jmc 50: .Pp
1.2 stevesk 51: .Bl -enum -offset indent -compact
52: .It
53: command-line options
54: .It
55: user's configuration file
1.50 djm 56: .Pq Pa ~/.ssh/config
1.2 stevesk 57: .It
58: system-wide configuration file
59: .Pq Pa /etc/ssh/ssh_config
60: .El
1.1 stevesk 61: .Pp
62: For each parameter, the first obtained value
63: will be used.
1.41 jmc 64: The configuration files contain sections separated by
1.1 stevesk 65: .Dq Host
66: specifications, and that section is only applied for hosts that
67: match one of the patterns given in the specification.
1.193 djm 68: The matched host name is usually the one given on the command line
69: (see the
70: .Cm CanonicalizeHostname
71: option for exceptions.)
1.1 stevesk 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.
1.80 jmc 76: .Pp
1.1 stevesk 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 ,
1.87 jmc 90: .Nm scp ,
1.1 stevesk 91: and
92: .Nm sftp
93: .Fl o
94: option.
1.88 dtucker 95: Arguments may optionally be enclosed in double quotes
96: .Pq \&"
97: in order to represent arguments containing spaces.
1.1 stevesk 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
1.169 djm 106: or
107: .Cm Match
1.1 stevesk 108: keyword) to be only for those hosts that match one of the patterns
109: given after the keyword.
1.112 krw 110: If more than one pattern is provided, they should be separated by whitespace.
1.1 stevesk 111: A single
1.83 jmc 112: .Ql *
1.1 stevesk 113: as a pattern can be used to provide global
114: defaults for all hosts.
1.193 djm 115: The host is usually the
1.1 stevesk 116: .Ar hostname
1.193 djm 117: argument given on the command line
118: (see the
119: .Cm CanonicalizeHostname
120: option for exceptions.)
1.148 djm 121: .Pp
122: A pattern entry may be negated by prefixing it with an exclamation mark
123: .Pq Sq !\& .
124: If a negated entry is matched, then the
125: .Cm Host
126: entry is ignored, regardless of whether any other patterns on the line
127: match.
128: Negated matches are therefore useful to provide exceptions for wildcard
129: matches.
1.81 jmc 130: .Pp
131: See
132: .Sx PATTERNS
133: for more information on patterns.
1.170 jmc 134: .It Cm Match
1.169 djm 135: Restricts the following declarations (up to the next
136: .Cm Host
137: or
138: .Cm Match
139: keyword) to be used only when the conditions following the
140: .Cm Match
141: keyword are satisfied.
1.193 djm 142: Match conditions are specified using one or more critera
1.178 dtucker 143: or the single token
144: .Cm all
1.193 djm 145: which always matches.
146: The available criteria keywords are:
147: .Cm canonical ,
1.176 djm 148: .Cm exec ,
1.169 djm 149: .Cm host ,
150: .Cm originalhost ,
151: .Cm user ,
152: and
153: .Cm localuser .
1.193 djm 154: The
155: .Cm all
156: criteria must appear alone or immediately after
1.194 jmc 157: .Cm canonical .
1.193 djm 158: Other criteria may be combined arbitrarily.
159: All criteria but
160: .Cm all
161: and
162: .Cm canonical
163: require an argument.
164: Criteria may be negated by prepending an exclamation mark
165: .Pq Sq !\& .
1.169 djm 166: .Pp
1.177 jmc 167: The
1.193 djm 168: .Cm canonical
169: keywork matches only when the configuration file is being re-parsed
170: after hostname canonicalization (see the
171: .Cm CanonicalizeHostname
172: option.)
173: This may be useful to specify conditions that work with canonical host
174: names only.
175: The
1.176 djm 176: .Cm exec
1.177 jmc 177: keyword executes the specified command under the user's shell.
1.169 djm 178: If the command returns a zero exit status then the condition is considered true.
179: Commands containing whitespace characters must be quoted.
1.175 djm 180: The following character sequences in the command will be expanded prior to
181: execution:
182: .Ql %L
183: will be substituted by the first component of the local host name,
184: .Ql %l
185: will be substituted by the local host name (including any domain name),
186: .Ql %h
187: will be substituted by the target host name,
188: .Ql %n
189: will be substituted by the original target host name
1.176 djm 190: specified on the command-line,
1.175 djm 191: .Ql %p
192: the destination port,
193: .Ql %r
194: by the remote login username, and
195: .Ql %u
196: by the username of the user running
197: .Xr ssh 1 .
1.169 djm 198: .Pp
199: The other keywords' criteria must be single entries or comma-separated
200: lists and may use the wildcard and negation operators described in the
201: .Sx PATTERNS
202: section.
203: The criteria for the
204: .Cm host
205: keyword are matched against the target hostname, after any substitution
206: by the
207: .Cm Hostname
1.193 djm 208: or
209: .Cm CanonicalizeHostname
210: options.
1.169 djm 211: The
212: .Cm originalhost
213: keyword matches against the hostname as it was specified on the command-line.
214: The
215: .Cm user
216: keyword matches against the target username on the remote host.
217: The
218: .Cm localuser
219: keyword matches against the name of the local user running
220: .Xr ssh 1
221: (this keyword may be useful in system-wide
222: .Nm
223: files).
1.10 djm 224: .It Cm AddressFamily
1.11 jmc 225: Specifies which address family to use when connecting.
226: Valid arguments are
1.10 djm 227: .Dq any ,
228: .Dq inet
1.84 jmc 229: (use IPv4 only), or
1.10 djm 230: .Dq inet6
1.40 jmc 231: (use IPv6 only).
1.1 stevesk 232: .It Cm BatchMode
233: If set to
234: .Dq yes ,
235: passphrase/password querying will be disabled.
236: This option is useful in scripts and other batch jobs where no user
237: is present to supply the password.
238: The argument must be
239: .Dq yes
240: or
241: .Dq no .
242: The default is
243: .Dq no .
244: .It Cm BindAddress
1.60 dtucker 245: Use the specified address on the local machine as the source address of
1.61 jmc 246: the connection.
247: Only useful on systems with more than one address.
1.1 stevesk 248: Note that this option does not work if
249: .Cm UsePrivilegedPort
250: is set to
251: .Dq yes .
1.171 djm 252: .It Cm CanonicalDomains
1.172 jmc 253: When
1.173 djm 254: .Cm CanonicalizeHostname
1.171 djm 255: is enabled, this option specifies the list of domain suffixes in which to
256: search for the specified destination host.
1.173 djm 257: .It Cm CanonicalizeFallbackLocal
1.174 djm 258: Specifies whether to fail with an error when hostname canonicalization fails.
1.172 jmc 259: The default,
1.184 djm 260: .Dq yes ,
1.172 jmc 261: will attempt to look up the unqualified hostname using the system resolver's
1.171 djm 262: search rules.
263: A value of
1.184 djm 264: .Dq no
1.171 djm 265: will cause
266: .Xr ssh 1
267: to fail instantly if
1.173 djm 268: .Cm CanonicalizeHostname
1.171 djm 269: is enabled and the target hostname cannot be found in any of the domains
270: specified by
271: .Cm CanonicalDomains .
1.173 djm 272: .It Cm CanonicalizeHostname
1.174 djm 273: Controls whether explicit hostname canonicalization is performed.
1.172 jmc 274: The default,
275: .Dq no ,
1.171 djm 276: is not to perform any name rewriting and let the system resolver handle all
277: hostname lookups.
278: If set to
279: .Dq yes
280: then, for connections that do not use a
281: .Cm ProxyCommand ,
282: .Xr ssh 1
1.173 djm 283: will attempt to canonicalize the hostname specified on the command line
1.171 djm 284: using the
285: .Cm CanonicalDomains
286: suffixes and
1.173 djm 287: .Cm CanonicalizePermittedCNAMEs
1.171 djm 288: rules.
289: If
1.173 djm 290: .Cm CanonicalizeHostname
1.171 djm 291: is set to
292: .Dq always ,
1.174 djm 293: then canonicalization is applied to proxied connections too.
1.185 djm 294: .Pp
1.193 djm 295: If this option is enabled, then the configuration files are processed
296: again using the new target name to pick up any new configuration in matching
1.185 djm 297: .Cm Host
1.193 djm 298: and
299: .Cm Match
1.185 djm 300: stanzas.
1.173 djm 301: .It Cm CanonicalizeMaxDots
1.172 jmc 302: Specifies the maximum number of dot characters in a hostname before
1.174 djm 303: canonicalization is disabled.
1.172 jmc 304: The default,
305: .Dq 1 ,
306: allows a single dot (i.e. hostname.subdomain).
1.173 djm 307: .It Cm CanonicalizePermittedCNAMEs
1.172 jmc 308: Specifies rules to determine whether CNAMEs should be followed when
1.173 djm 309: canonicalizing hostnames.
1.171 djm 310: The rules consist of one or more arguments of
1.172 jmc 311: .Ar source_domain_list : Ns Ar target_domain_list ,
1.171 djm 312: where
313: .Ar source_domain_list
1.174 djm 314: is a pattern-list of domains that may follow CNAMEs in canonicalization,
1.171 djm 315: and
316: .Ar target_domain_list
1.172 jmc 317: is a pattern-list of domains that they may resolve to.
1.171 djm 318: .Pp
319: For example,
320: .Dq *.a.example.com:*.b.example.com,*.c.example.com
321: will allow hostnames matching
322: .Dq *.a.example.com
1.173 djm 323: to be canonicalized to names in the
1.171 djm 324: .Dq *.b.example.com
325: or
326: .Dq *.c.example.com
327: domains.
1.1 stevesk 328: .It Cm ChallengeResponseAuthentication
1.82 jmc 329: Specifies whether to use challenge-response authentication.
1.1 stevesk 330: The argument to this keyword must be
331: .Dq yes
332: or
333: .Dq no .
334: The default is
335: .Dq yes .
336: .It Cm CheckHostIP
337: If this flag is set to
338: .Dq yes ,
1.84 jmc 339: .Xr ssh 1
340: will additionally check the host IP address in the
1.1 stevesk 341: .Pa known_hosts
342: file.
343: This allows ssh to detect if a host key changed due to DNS spoofing.
1.107 grunk 344: If the option is set to
1.1 stevesk 345: .Dq no ,
346: the check will not be executed.
347: The default is
348: .Dq yes .
349: .It Cm Cipher
350: Specifies the cipher to use for encrypting the session
351: in protocol version 1.
352: Currently,
353: .Dq blowfish ,
354: .Dq 3des ,
355: and
356: .Dq des
357: are supported.
358: .Ar des
359: is only supported in the
1.84 jmc 360: .Xr ssh 1
1.1 stevesk 361: client for interoperability with legacy protocol 1 implementations
362: that do not support the
363: .Ar 3des
1.7 jmc 364: cipher.
365: Its use is strongly discouraged due to cryptographic weaknesses.
1.1 stevesk 366: The default is
367: .Dq 3des .
368: .It Cm Ciphers
369: Specifies the ciphers allowed for protocol version 2
370: in order of preference.
371: Multiple ciphers must be comma-separated.
1.180 djm 372: The supported ciphers are:
373: .Pp
1.186 naddy 374: .Bl -item -compact -offset indent
375: .It
376: 3des-cbc
377: .It
378: aes128-cbc
379: .It
380: aes192-cbc
381: .It
382: aes256-cbc
383: .It
384: aes128-ctr
385: .It
386: aes192-ctr
387: .It
388: aes256-ctr
389: .It
390: aes128-gcm@openssh.com
391: .It
392: aes256-gcm@openssh.com
393: .It
394: arcfour
395: .It
396: arcfour128
397: .It
398: arcfour256
399: .It
400: blowfish-cbc
401: .It
402: cast128-cbc
403: .It
404: chacha20-poly1305@openssh.com
405: .El
1.180 djm 406: .Pp
1.84 jmc 407: The default is:
1.186 naddy 408: .Bd -literal -offset indent
409: aes128-ctr,aes192-ctr,aes256-ctr,
1.161 markus 410: aes128-gcm@openssh.com,aes256-gcm@openssh.com,
1.180 djm 411: chacha20-poly1305@openssh.com,
1.186 naddy 412: arcfour256,arcfour128,
413: aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,
414: aes192-cbc,aes256-cbc,arcfour
1.1 stevesk 415: .Ed
1.180 djm 416: .Pp
417: The list of available ciphers may also be obtained using the
418: .Fl Q
419: option of
1.198 ! djm 420: .Xr ssh 1
! 421: with an argument of
! 422: .Dq cipher .
1.1 stevesk 423: .It Cm ClearAllForwardings
1.84 jmc 424: Specifies that all local, remote, and dynamic port forwardings
1.1 stevesk 425: specified in the configuration files or on the command line be
1.7 jmc 426: cleared.
427: This option is primarily useful when used from the
1.84 jmc 428: .Xr ssh 1
1.1 stevesk 429: command line to clear port forwardings set in
430: configuration files, and is automatically set by
431: .Xr scp 1
432: and
433: .Xr sftp 1 .
434: The argument must be
435: .Dq yes
436: or
437: .Dq no .
438: The default is
439: .Dq no .
440: .It Cm Compression
441: Specifies whether to use compression.
442: The argument must be
443: .Dq yes
444: or
445: .Dq no .
446: The default is
447: .Dq no .
448: .It Cm CompressionLevel
449: Specifies the compression level to use if compression is enabled.
450: The argument must be an integer from 1 (fast) to 9 (slow, best).
451: The default level is 6, which is good for most applications.
452: The meaning of the values is the same as in
453: .Xr gzip 1 .
454: Note that this option applies to protocol version 1 only.
455: .It Cm ConnectionAttempts
456: Specifies the number of tries (one per second) to make before exiting.
457: The argument must be an integer.
458: This may be useful in scripts if the connection sometimes fails.
459: The default is 1.
1.9 djm 460: .It Cm ConnectTimeout
1.84 jmc 461: Specifies the timeout (in seconds) used when connecting to the
462: SSH server, instead of using the default system TCP timeout.
1.11 jmc 463: This value is used only when the target is down or really unreachable,
464: not when it refuses the connection.
1.36 djm 465: .It Cm ControlMaster
466: Enables the sharing of multiple sessions over a single network connection.
467: When set to
1.84 jmc 468: .Dq yes ,
469: .Xr ssh 1
1.36 djm 470: will listen for connections on a control socket specified using the
471: .Cm ControlPath
472: argument.
473: Additional sessions can connect to this socket using the same
474: .Cm ControlPath
475: with
476: .Cm ControlMaster
477: set to
478: .Dq no
1.38 jmc 479: (the default).
1.64 jmc 480: These sessions will try to reuse the master instance's network connection
1.63 djm 481: rather than initiating new ones, but will fall back to connecting normally
482: if the control socket does not exist, or is not listening.
483: .Pp
1.37 djm 484: Setting this to
485: .Dq ask
1.84 jmc 486: will cause ssh
1.37 djm 487: to listen for control connections, but require confirmation using the
488: .Ev SSH_ASKPASS
489: program before they are accepted (see
490: .Xr ssh-add 1
1.38 jmc 491: for details).
1.51 jakob 492: If the
493: .Cm ControlPath
1.84 jmc 494: cannot be opened,
495: ssh will continue without connecting to a master instance.
1.58 djm 496: .Pp
497: X11 and
1.59 jmc 498: .Xr ssh-agent 1
1.58 djm 499: forwarding is supported over these multiplexed connections, however the
1.70 stevesk 500: display and agent forwarded will be the one belonging to the master
1.59 jmc 501: connection i.e. it is not possible to forward multiple displays or agents.
1.56 djm 502: .Pp
503: Two additional options allow for opportunistic multiplexing: try to use a
504: master connection but fall back to creating a new one if one does not already
505: exist.
506: These options are:
507: .Dq auto
508: and
509: .Dq autoask .
510: The latter requires confirmation like the
511: .Dq ask
512: option.
1.36 djm 513: .It Cm ControlPath
1.55 djm 514: Specify the path to the control socket used for connection sharing as described
515: in the
1.36 djm 516: .Cm ControlMaster
1.57 djm 517: section above or the string
518: .Dq none
519: to disable connection sharing.
1.55 djm 520: In the path,
1.147 djm 521: .Ql %L
522: will be substituted by the first component of the local host name,
1.77 djm 523: .Ql %l
1.147 djm 524: will be substituted by the local host name (including any domain name),
1.55 djm 525: .Ql %h
526: will be substituted by the target host name,
1.150 jmc 527: .Ql %n
528: will be substituted by the original target host name
529: specified on the command line,
1.55 djm 530: .Ql %p
1.175 djm 531: the destination port,
1.55 djm 532: .Ql %r
1.188 djm 533: by the remote login username,
1.147 djm 534: .Ql %u
535: by the username of the user running
1.188 djm 536: .Xr ssh 1 , and
1.189 jmc 537: .Ql \&%C
1.188 djm 538: by a hash of the concatenation: %l%h%p%r.
1.56 djm 539: It is recommended that any
540: .Cm ControlPath
541: used for opportunistic connection sharing include
1.195 djm 542: at least %h, %p, and %r (or alternatively %C) and be placed in a directory
543: that is not writable by other users.
1.56 djm 544: This ensures that shared connections are uniquely identified.
1.137 djm 545: .It Cm ControlPersist
546: When used in conjunction with
547: .Cm ControlMaster ,
548: specifies that the master connection should remain open
549: in the background (waiting for future client connections)
550: after the initial client connection has been closed.
551: If set to
552: .Dq no ,
553: then the master connection will not be placed into the background,
554: and will close as soon as the initial client connection is closed.
555: If set to
1.195 djm 556: .Dq yes
557: or
558: .Dq 0 ,
1.137 djm 559: then the master connection will remain in the background indefinitely
560: (until killed or closed via a mechanism such as the
561: .Xr ssh 1
562: .Dq Fl O No exit
563: option).
564: If set to a time in seconds, or a time in any of the formats documented in
565: .Xr sshd_config 5 ,
566: then the backgrounded master connection will automatically terminate
567: after it has remained idle (with no client connections) for the
568: specified time.
1.38 jmc 569: .It Cm DynamicForward
1.74 jmc 570: Specifies that a TCP port on the local machine be forwarded
1.38 jmc 571: over the secure channel, and the application
572: protocol is then used to determine where to connect to from the
573: remote machine.
1.62 djm 574: .Pp
575: The argument must be
576: .Sm off
577: .Oo Ar bind_address : Oc Ar port .
578: .Sm on
1.138 djm 579: IPv6 addresses can be specified by enclosing addresses in square brackets.
1.62 djm 580: By default, the local port is bound in accordance with the
581: .Cm GatewayPorts
582: setting.
583: However, an explicit
584: .Ar bind_address
585: may be used to bind the connection to a specific address.
586: The
587: .Ar bind_address
588: of
589: .Dq localhost
590: indicates that the listening port be bound for local use only, while an
591: empty address or
592: .Sq *
593: indicates that the port should be available from all interfaces.
594: .Pp
1.38 jmc 595: Currently the SOCKS4 and SOCKS5 protocols are supported, and
1.84 jmc 596: .Xr ssh 1
1.38 jmc 597: will act as a SOCKS server.
598: Multiple forwardings may be specified, and
599: additional forwardings can be given on the command line.
600: Only the superuser can forward privileged ports.
1.14 markus 601: .It Cm EnableSSHKeysign
602: Setting this option to
603: .Dq yes
604: in the global client configuration file
605: .Pa /etc/ssh/ssh_config
606: enables the use of the helper program
607: .Xr ssh-keysign 8
608: during
609: .Cm HostbasedAuthentication .
610: The argument must be
611: .Dq yes
612: or
613: .Dq no .
614: The default is
615: .Dq no .
1.23 jmc 616: This option should be placed in the non-hostspecific section.
1.14 markus 617: See
618: .Xr ssh-keysign 8
619: for more information.
1.1 stevesk 620: .It Cm EscapeChar
621: Sets the escape character (default:
622: .Ql ~ ) .
623: The escape character can also
624: be set on the command line.
625: The argument should be a single character,
626: .Ql ^
627: followed by a letter, or
628: .Dq none
629: to disable the escape
630: character entirely (making the connection transparent for binary
631: data).
1.96 markus 632: .It Cm ExitOnForwardFailure
633: Specifies whether
634: .Xr ssh 1
635: should terminate the connection if it cannot set up all requested
1.102 stevesk 636: dynamic, tunnel, local, and remote port forwardings.
1.96 markus 637: The argument must be
638: .Dq yes
639: or
640: .Dq no .
641: The default is
642: .Dq no .
1.197 djm 643: .It Cm FingerprintHash
644: Specifies the hash algorithm used when displaying key fingerprints.
645: Valid options are:
646: .Dq md5
647: and
648: .Dq sha256 .
649: .Dq md5 ,
650: The default is
651: .Dq sha256 .
1.1 stevesk 652: .It Cm ForwardAgent
653: Specifies whether the connection to the authentication agent (if any)
654: will be forwarded to the remote machine.
655: The argument must be
656: .Dq yes
657: or
658: .Dq no .
659: The default is
660: .Dq no .
1.3 stevesk 661: .Pp
1.7 jmc 662: Agent forwarding should be enabled with caution.
663: Users with the ability to bypass file permissions on the remote host
664: (for the agent's Unix-domain socket)
665: can access the local agent through the forwarded connection.
666: An attacker cannot obtain key material from the agent,
1.3 stevesk 667: however they can perform operations on the keys that enable them to
668: authenticate using the identities loaded into the agent.
1.1 stevesk 669: .It Cm ForwardX11
670: Specifies whether X11 connections will be automatically redirected
671: over the secure channel and
672: .Ev DISPLAY
673: set.
674: The argument must be
675: .Dq yes
676: or
677: .Dq no .
678: The default is
679: .Dq no .
1.3 stevesk 680: .Pp
1.7 jmc 681: X11 forwarding should be enabled with caution.
682: Users with the ability to bypass file permissions on the remote host
1.22 markus 683: (for the user's X11 authorization database)
1.7 jmc 684: can access the local X11 display through the forwarded connection.
1.22 markus 685: An attacker may then be able to perform activities such as keystroke monitoring
686: if the
687: .Cm ForwardX11Trusted
688: option is also enabled.
1.134 djm 689: .It Cm ForwardX11Timeout
1.135 jmc 690: Specify a timeout for untrusted X11 forwarding
691: using the format described in the
1.166 jmc 692: TIME FORMATS section of
1.134 djm 693: .Xr sshd_config 5 .
694: X11 connections received by
695: .Xr ssh 1
696: after this time will be refused.
697: The default is to disable untrusted X11 forwarding after twenty minutes has
698: elapsed.
1.22 markus 699: .It Cm ForwardX11Trusted
1.34 jmc 700: If this option is set to
1.84 jmc 701: .Dq yes ,
702: remote X11 clients will have full access to the original X11 display.
1.42 djm 703: .Pp
1.22 markus 704: If this option is set to
1.84 jmc 705: .Dq no ,
706: remote X11 clients will be considered untrusted and prevented
1.22 markus 707: from stealing or tampering with data belonging to trusted X11
708: clients.
1.42 djm 709: Furthermore, the
710: .Xr xauth 1
711: token used for the session will be set to expire after 20 minutes.
712: Remote clients will be refused access after this time.
1.22 markus 713: .Pp
714: The default is
715: .Dq no .
716: .Pp
717: See the X11 SECURITY extension specification for full details on
718: the restrictions imposed on untrusted clients.
1.1 stevesk 719: .It Cm GatewayPorts
720: Specifies whether remote hosts are allowed to connect to local
721: forwarded ports.
722: By default,
1.84 jmc 723: .Xr ssh 1
1.7 jmc 724: binds local port forwardings to the loopback address.
725: This prevents other remote hosts from connecting to forwarded ports.
1.1 stevesk 726: .Cm GatewayPorts
1.84 jmc 727: can be used to specify that ssh
1.1 stevesk 728: should bind local port forwardings to the wildcard address,
729: thus allowing remote hosts to connect to forwarded ports.
730: The argument must be
731: .Dq yes
732: or
733: .Dq no .
734: The default is
735: .Dq no .
736: .It Cm GlobalKnownHostsFile
1.151 djm 737: Specifies one or more files to use for the global
738: host key database, separated by whitespace.
739: The default is
740: .Pa /etc/ssh/ssh_known_hosts ,
741: .Pa /etc/ssh/ssh_known_hosts2 .
1.18 markus 742: .It Cm GSSAPIAuthentication
1.27 markus 743: Specifies whether user authentication based on GSSAPI is allowed.
1.20 jmc 744: The default is
1.21 markus 745: .Dq no .
1.18 markus 746: Note that this option applies to protocol version 2 only.
747: .It Cm GSSAPIDelegateCredentials
748: Forward (delegate) credentials to the server.
749: The default is
750: .Dq no .
751: Note that this option applies to protocol version 2 only.
1.44 djm 752: .It Cm HashKnownHosts
753: Indicates that
1.84 jmc 754: .Xr ssh 1
1.44 djm 755: should hash host names and addresses when they are added to
1.50 djm 756: .Pa ~/.ssh/known_hosts .
1.44 djm 757: These hashed names may be used normally by
1.84 jmc 758: .Xr ssh 1
1.44 djm 759: and
1.84 jmc 760: .Xr sshd 8 ,
1.44 djm 761: but they do not reveal identifying information should the file's contents
762: be disclosed.
763: The default is
764: .Dq no .
1.97 jmc 765: Note that existing names and addresses in known hosts files
766: will not be converted automatically,
767: but may be manually hashed using
1.45 djm 768: .Xr ssh-keygen 1 .
1.1 stevesk 769: .It Cm HostbasedAuthentication
770: Specifies whether to try rhosts based authentication with public key
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 2 only and
779: is similar to
780: .Cm RhostsRSAAuthentication .
781: .It Cm HostKeyAlgorithms
782: Specifies the protocol version 2 host key algorithms
783: that the client wants to use in order of preference.
784: The default for this option is:
1.139 djm 785: .Bd -literal -offset 3n
786: ecdsa-sha2-nistp256-cert-v01@openssh.com,
787: ecdsa-sha2-nistp384-cert-v01@openssh.com,
788: ecdsa-sha2-nistp521-cert-v01@openssh.com,
1.183 naddy 789: ssh-ed25519-cert-v01@openssh.com,
1.139 djm 790: ssh-rsa-cert-v01@openssh.com,ssh-dss-cert-v01@openssh.com,
791: ssh-rsa-cert-v00@openssh.com,ssh-dss-cert-v00@openssh.com,
792: ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,
1.182 markus 793: ssh-ed25519,ssh-rsa,ssh-dss
1.139 djm 794: .Ed
1.145 djm 795: .Pp
796: If hostkeys are known for the destination host then this default is modified
797: to prefer their algorithms.
1.198 ! djm 798: .Pp
! 799: The list of available key types may also be obtained using the
! 800: .Fl Q
! 801: option of
! 802: .Xr ssh 1
! 803: with an argument of
! 804: .Dq key .
1.1 stevesk 805: .It Cm HostKeyAlias
806: Specifies an alias that should be used instead of the
807: real host name when looking up or saving the host key
808: in the host key database files.
1.84 jmc 809: This option is useful for tunneling SSH connections
1.1 stevesk 810: or for multiple servers running on a single host.
811: .It Cm HostName
812: Specifies the real host name to log into.
813: This can be used to specify nicknames or abbreviations for hosts.
1.136 djm 814: If the hostname contains the character sequence
815: .Ql %h ,
1.150 jmc 816: then this will be replaced with the host name specified on the command line
1.136 djm 817: (this is useful for manipulating unqualified names).
1.187 djm 818: The character sequence
819: .Ql %%
820: will be replaced by a single
821: .Ql %
822: character, which may be used when specifying IPv6 link-local addresses.
823: .Pp
1.84 jmc 824: The default is the name given on the command line.
1.1 stevesk 825: Numeric IP addresses are also permitted (both on the command line and in
826: .Cm HostName
827: specifications).
1.29 markus 828: .It Cm IdentitiesOnly
829: Specifies that
1.84 jmc 830: .Xr ssh 1
1.29 markus 831: should only use the authentication identity files configured in the
1.31 jmc 832: .Nm
1.29 markus 833: files,
1.84 jmc 834: even if
835: .Xr ssh-agent 1
1.159 djm 836: or a
837: .Cm PKCS11Provider
1.29 markus 838: offers more identities.
839: The argument to this keyword must be
840: .Dq yes
841: or
842: .Dq no .
1.84 jmc 843: This option is intended for situations where ssh-agent
1.29 markus 844: offers many different identities.
845: The default is
846: .Dq no .
1.67 jmc 847: .It Cm IdentityFile
1.192 sobrado 848: Specifies a file from which the user's DSA, ECDSA, Ed25519 or RSA authentication
1.139 djm 849: identity is read.
1.67 jmc 850: The default is
851: .Pa ~/.ssh/identity
852: for protocol version 1, and
1.139 djm 853: .Pa ~/.ssh/id_dsa ,
1.183 naddy 854: .Pa ~/.ssh/id_ecdsa ,
855: .Pa ~/.ssh/id_ed25519
1.139 djm 856: and
1.67 jmc 857: .Pa ~/.ssh/id_rsa
858: for protocol version 2.
859: Additionally, any identities represented by the authentication agent
1.165 djm 860: will be used for authentication unless
861: .Cm IdentitiesOnly
862: is set.
1.129 djm 863: .Xr ssh 1
864: will try to load certificate information from the filename obtained by
865: appending
866: .Pa -cert.pub
867: to the path of a specified
868: .Cm IdentityFile .
1.90 djm 869: .Pp
1.67 jmc 870: The file name may use the tilde
1.91 jmc 871: syntax to refer to a user's home directory or one of the following
1.90 djm 872: escape characters:
873: .Ql %d
874: (local user's home directory),
875: .Ql %u
876: (local user name),
877: .Ql %l
878: (local host name),
879: .Ql %h
880: (remote host name) or
1.92 djm 881: .Ql %r
1.90 djm 882: (remote user name).
883: .Pp
1.67 jmc 884: It is possible to have
885: multiple identity files specified in configuration files; all these
886: identities will be tried in sequence.
1.152 djm 887: Multiple
888: .Cm IdentityFile
889: directives will add to the list of identities tried (this behaviour
890: differs from that of other configuration directives).
1.165 djm 891: .Pp
892: .Cm IdentityFile
893: may be used in conjunction with
894: .Cm IdentitiesOnly
895: to select which identities in an agent are offered during authentication.
1.164 jmc 896: .It Cm IgnoreUnknown
897: Specifies a pattern-list of unknown options to be ignored if they are
898: encountered in configuration parsing.
899: This may be used to suppress errors if
900: .Nm
901: contains options that are unrecognised by
902: .Xr ssh 1 .
903: It is recommended that
904: .Cm IgnoreUnknown
905: be listed early in the configuration file as it will not be applied
906: to unknown options that appear before it.
1.143 djm 907: .It Cm IPQoS
908: Specifies the IPv4 type-of-service or DSCP class for connections.
909: Accepted values are
910: .Dq af11 ,
911: .Dq af12 ,
912: .Dq af13 ,
1.154 djm 913: .Dq af21 ,
1.143 djm 914: .Dq af22 ,
915: .Dq af23 ,
916: .Dq af31 ,
917: .Dq af32 ,
918: .Dq af33 ,
919: .Dq af41 ,
920: .Dq af42 ,
921: .Dq af43 ,
922: .Dq cs0 ,
923: .Dq cs1 ,
924: .Dq cs2 ,
925: .Dq cs3 ,
926: .Dq cs4 ,
927: .Dq cs5 ,
928: .Dq cs6 ,
929: .Dq cs7 ,
930: .Dq ef ,
931: .Dq lowdelay ,
932: .Dq throughput ,
933: .Dq reliability ,
934: or a numeric value.
1.146 djm 935: This option may take one or two arguments, separated by whitespace.
1.143 djm 936: If one argument is specified, it is used as the packet class unconditionally.
937: If two values are specified, the first is automatically selected for
938: interactive sessions and the second for non-interactive sessions.
939: The default is
940: .Dq lowdelay
941: for interactive sessions and
942: .Dq throughput
943: for non-interactive sessions.
1.103 djm 944: .It Cm KbdInteractiveAuthentication
945: Specifies whether to use keyboard-interactive authentication.
946: The argument to this keyword must be
947: .Dq yes
948: or
949: .Dq no .
950: The default is
951: .Dq yes .
1.39 djm 952: .It Cm KbdInteractiveDevices
953: Specifies the list of methods to use in keyboard-interactive authentication.
954: Multiple method names must be comma-separated.
955: The default is to use the server specified list.
1.85 jmc 956: The methods available vary depending on what the server supports.
957: For an OpenSSH server,
958: it may be zero or more of:
959: .Dq bsdauth ,
960: .Dq pam ,
961: and
962: .Dq skey .
1.140 djm 963: .It Cm KexAlgorithms
964: Specifies the available KEX (Key Exchange) algorithms.
965: Multiple algorithms must be comma-separated.
1.141 jmc 966: The default is:
967: .Bd -literal -offset indent
1.179 markus 968: curve25519-sha256@libssh.org,
1.141 jmc 969: ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,
970: diffie-hellman-group-exchange-sha256,
1.186 naddy 971: diffie-hellman-group14-sha1,
1.141 jmc 972: diffie-hellman-group-exchange-sha1,
973: diffie-hellman-group1-sha1
974: .Ed
1.198 ! djm 975: .Pp
! 976: The list of available key exchange algorithms may also be obtained using the
! 977: .Fl Q
! 978: option of
! 979: .Xr ssh 1
! 980: with an argument of
! 981: .Dq kex .
1.65 reyk 982: .It Cm LocalCommand
983: Specifies a command to execute on the local machine after successfully
984: connecting to the server.
985: The command string extends to the end of the line, and is executed with
1.105 jmc 986: the user's shell.
1.109 dtucker 987: The following escape character substitutions will be performed:
988: .Ql %d
989: (local user's home directory),
990: .Ql %h
991: (remote host name),
992: .Ql %l
993: (local host name),
994: .Ql %n
995: (host name as provided on the command line),
996: .Ql %p
997: (remote port),
998: .Ql %r
999: (remote user name) or
1000: .Ql %u
1.188 djm 1001: (local user name) or
1.189 jmc 1002: .Ql \&%C
1.188 djm 1003: by a hash of the concatenation: %l%h%p%r.
1.123 djm 1004: .Pp
1005: The command is run synchronously and does not have access to the
1006: session of the
1007: .Xr ssh 1
1008: that spawned it.
1009: It should not be used for interactive commands.
1010: .Pp
1.65 reyk 1011: This directive is ignored unless
1012: .Cm PermitLocalCommand
1013: has been enabled.
1.1 stevesk 1014: .It Cm LocalForward
1.74 jmc 1015: Specifies that a TCP port on the local machine be forwarded over
1.1 stevesk 1016: the secure channel to the specified host and port from the remote machine.
1.49 jmc 1017: The first argument must be
1.43 djm 1018: .Sm off
1.49 jmc 1019: .Oo Ar bind_address : Oc Ar port
1.43 djm 1020: .Sm on
1.49 jmc 1021: and the second argument must be
1022: .Ar host : Ns Ar hostport .
1.138 djm 1023: IPv6 addresses can be specified by enclosing addresses in square brackets.
1.46 jmc 1024: Multiple forwardings may be specified, and additional forwardings can be
1.43 djm 1025: given on the command line.
1.1 stevesk 1026: Only the superuser can forward privileged ports.
1.43 djm 1027: By default, the local port is bound in accordance with the
1028: .Cm GatewayPorts
1029: setting.
1030: However, an explicit
1031: .Ar bind_address
1032: may be used to bind the connection to a specific address.
1033: The
1034: .Ar bind_address
1035: of
1036: .Dq localhost
1.46 jmc 1037: indicates that the listening port be bound for local use only, while an
1038: empty address or
1039: .Sq *
1.43 djm 1040: indicates that the port should be available from all interfaces.
1.1 stevesk 1041: .It Cm LogLevel
1042: Gives the verbosity level that is used when logging messages from
1.84 jmc 1043: .Xr ssh 1 .
1.1 stevesk 1044: The possible values are:
1.84 jmc 1045: QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.
1.7 jmc 1046: The default is INFO.
1047: DEBUG and DEBUG1 are equivalent.
1048: DEBUG2 and DEBUG3 each specify higher levels of verbose output.
1.1 stevesk 1049: .It Cm MACs
1050: Specifies the MAC (message authentication code) algorithms
1051: in order of preference.
1052: The MAC algorithm is used in protocol version 2
1053: for data integrity protection.
1054: Multiple algorithms must be comma-separated.
1.160 markus 1055: The algorithms that contain
1056: .Dq -etm
1057: calculate the MAC after encryption (encrypt-then-mac).
1058: These are considered safer and their use recommended.
1.84 jmc 1059: The default is:
1.101 jmc 1060: .Bd -literal -offset indent
1.160 markus 1061: umac-64-etm@openssh.com,umac-128-etm@openssh.com,
1062: hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,
1.186 naddy 1063: umac-64@openssh.com,umac-128@openssh.com,
1064: hmac-sha2-256,hmac-sha2-512,
1065: hmac-md5-etm@openssh.com,hmac-sha1-etm@openssh.com,
1066: hmac-ripemd160-etm@openssh.com,
1067: hmac-sha1-96-etm@openssh.com,hmac-md5-96-etm@openssh.com,
1068: hmac-md5,hmac-sha1,hmac-ripemd160,
1.157 naddy 1069: hmac-sha1-96,hmac-md5-96
1.101 jmc 1070: .Ed
1.198 ! djm 1071: .Pp
! 1072: The list of available MAC algorithms may also be obtained using the
! 1073: .Fl Q
! 1074: option of
! 1075: .Xr ssh 1
! 1076: with an argument of
! 1077: .Dq mac .
1.1 stevesk 1078: .It Cm NoHostAuthenticationForLocalhost
1079: This option can be used if the home directory is shared across machines.
1080: In this case localhost will refer to a different machine on each of
1081: the machines and the user will get many warnings about changed host keys.
1082: However, this option disables host authentication for localhost.
1083: The argument to this keyword must be
1084: .Dq yes
1085: or
1086: .Dq no .
1087: The default is to check the host key for localhost.
1088: .It Cm NumberOfPasswordPrompts
1089: Specifies the number of password prompts before giving up.
1090: The argument to this keyword must be an integer.
1.84 jmc 1091: The default is 3.
1.1 stevesk 1092: .It Cm PasswordAuthentication
1093: Specifies whether to use password authentication.
1094: The argument to this keyword must be
1095: .Dq yes
1096: or
1097: .Dq no .
1098: The default is
1099: .Dq yes .
1.65 reyk 1100: .It Cm PermitLocalCommand
1101: Allow local command execution via the
1102: .Ic LocalCommand
1103: option or using the
1.66 jmc 1104: .Ic !\& Ns Ar command
1.65 reyk 1105: escape sequence in
1106: .Xr ssh 1 .
1107: The argument must be
1108: .Dq yes
1109: or
1110: .Dq no .
1111: The default is
1112: .Dq no .
1.127 markus 1113: .It Cm PKCS11Provider
1114: Specifies which PKCS#11 provider to use.
1.144 jmc 1115: The argument to this keyword is the PKCS#11 shared library
1.127 markus 1116: .Xr ssh 1
1.128 markus 1117: should use to communicate with a PKCS#11 token providing the user's
1.127 markus 1118: private RSA key.
1.67 jmc 1119: .It Cm Port
1120: Specifies the port number to connect on the remote host.
1.84 jmc 1121: The default is 22.
1.1 stevesk 1122: .It Cm PreferredAuthentications
1123: Specifies the order in which the client should try protocol 2
1.11 jmc 1124: authentication methods.
1.48 jmc 1125: This allows a client to prefer one method (e.g.\&
1.1 stevesk 1126: .Cm keyboard-interactive )
1.48 jmc 1127: over another method (e.g.\&
1.131 jmc 1128: .Cm password ) .
1129: The default is:
1130: .Bd -literal -offset indent
1131: gssapi-with-mic,hostbased,publickey,
1132: keyboard-interactive,password
1133: .Ed
1.1 stevesk 1134: .It Cm Protocol
1135: Specifies the protocol versions
1.84 jmc 1136: .Xr ssh 1
1.1 stevesk 1137: should support in order of preference.
1138: The possible values are
1.84 jmc 1139: .Sq 1
1.1 stevesk 1140: and
1.84 jmc 1141: .Sq 2 .
1.1 stevesk 1142: Multiple versions must be comma-separated.
1.120 markus 1143: When this option is set to
1.121 jmc 1144: .Dq 2,1
1.120 markus 1145: .Nm ssh
1146: will try version 2 and fall back to version 1
1147: if version 2 is not available.
1.1 stevesk 1148: The default is
1.121 jmc 1149: .Sq 2 .
1.1 stevesk 1150: .It Cm ProxyCommand
1151: Specifies the command to use to connect to the server.
1152: The command
1.190 djm 1153: string extends to the end of the line, and is executed
1154: using the user's shell
1155: .Ql exec
1156: directive to avoid a lingering shell process.
1157: .Pp
1.133 jmc 1158: In the command string, any occurrence of
1.1 stevesk 1159: .Ql %h
1160: will be substituted by the host name to
1.132 djm 1161: connect,
1.1 stevesk 1162: .Ql %p
1.133 jmc 1163: by the port, and
1164: .Ql %r
1.132 djm 1165: by the remote user name.
1.1 stevesk 1166: The command can be basically anything,
1167: and should read from its standard input and write to its standard output.
1168: It should eventually connect an
1169: .Xr sshd 8
1170: server running on some machine, or execute
1171: .Ic sshd -i
1172: somewhere.
1173: Host key management will be done using the
1174: HostName of the host being connected (defaulting to the name typed by
1175: the user).
1.7 jmc 1176: Setting the command to
1177: .Dq none
1.6 markus 1178: disables this option entirely.
1.1 stevesk 1179: Note that
1180: .Cm CheckHostIP
1181: is not available for connects with a proxy command.
1.52 djm 1182: .Pp
1183: This directive is useful in conjunction with
1184: .Xr nc 1
1185: and its proxy support.
1.53 jmc 1186: For example, the following directive would connect via an HTTP proxy at
1.52 djm 1187: 192.0.2.0:
1188: .Bd -literal -offset 3n
1189: ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
1190: .Ed
1.167 djm 1191: .It Cm ProxyUseFdpass
1.168 jmc 1192: Specifies that
1.167 djm 1193: .Cm ProxyCommand
1194: will pass a connected file descriptor back to
1.168 jmc 1195: .Xr ssh 1
1.167 djm 1196: instead of continuing to execute and pass data.
1197: The default is
1198: .Dq no .
1.1 stevesk 1199: .It Cm PubkeyAuthentication
1200: Specifies whether to try public key authentication.
1201: The argument to this keyword must be
1202: .Dq yes
1203: or
1204: .Dq no .
1205: The default is
1206: .Dq yes .
1207: This option applies to protocol version 2 only.
1.75 dtucker 1208: .It Cm RekeyLimit
1209: Specifies the maximum amount of data that may be transmitted before the
1.162 dtucker 1210: session key is renegotiated, optionally followed a maximum amount of
1211: time that may pass before the session key is renegotiated.
1212: The first argument is specified in bytes and may have a suffix of
1.76 jmc 1213: .Sq K ,
1214: .Sq M ,
1.75 dtucker 1215: or
1.76 jmc 1216: .Sq G
1.75 dtucker 1217: to indicate Kilobytes, Megabytes, or Gigabytes, respectively.
1218: The default is between
1.84 jmc 1219: .Sq 1G
1.75 dtucker 1220: and
1.84 jmc 1221: .Sq 4G ,
1.75 dtucker 1222: depending on the cipher.
1.162 dtucker 1223: The optional second value is specified in seconds and may use any of the
1224: units documented in the
1.166 jmc 1225: TIME FORMATS section of
1.162 dtucker 1226: .Xr sshd_config 5 .
1227: The default value for
1228: .Cm RekeyLimit
1229: is
1230: .Dq default none ,
1231: which means that rekeying is performed after the cipher's default amount
1232: of data has been sent or received and no time based rekeying is done.
1.76 jmc 1233: This option applies to protocol version 2 only.
1.1 stevesk 1234: .It Cm RemoteForward
1.74 jmc 1235: Specifies that a TCP port on the remote machine be forwarded over
1.1 stevesk 1236: the secure channel to the specified host and port from the local machine.
1.49 jmc 1237: The first argument must be
1.43 djm 1238: .Sm off
1.49 jmc 1239: .Oo Ar bind_address : Oc Ar port
1.43 djm 1240: .Sm on
1.49 jmc 1241: and the second argument must be
1242: .Ar host : Ns Ar hostport .
1.138 djm 1243: IPv6 addresses can be specified by enclosing addresses in square brackets.
1.1 stevesk 1244: Multiple forwardings may be specified, and additional
1245: forwardings can be given on the command line.
1.113 stevesk 1246: Privileged ports can be forwarded only when
1247: logging in as root on the remote machine.
1.118 jmc 1248: .Pp
1.117 djm 1249: If the
1250: .Ar port
1251: argument is
1252: .Ql 0 ,
1253: the listen port will be dynamically allocated on the server and reported
1254: to the client at run time.
1.43 djm 1255: .Pp
1256: If the
1257: .Ar bind_address
1258: is not specified, the default is to only bind to loopback addresses.
1259: If the
1260: .Ar bind_address
1261: is
1262: .Ql *
1263: or an empty string, then the forwarding is requested to listen on all
1264: interfaces.
1265: Specifying a remote
1266: .Ar bind_address
1.46 jmc 1267: will only succeed if the server's
1268: .Cm GatewayPorts
1.43 djm 1269: option is enabled (see
1.46 jmc 1270: .Xr sshd_config 5 ) .
1.149 djm 1271: .It Cm RequestTTY
1272: Specifies whether to request a pseudo-tty for the session.
1273: The argument may be one of:
1274: .Dq no
1275: (never request a TTY),
1276: .Dq yes
1277: (always request a TTY when standard input is a TTY),
1278: .Dq force
1279: (always request a TTY) or
1280: .Dq auto
1281: (request a TTY when opening a login session).
1282: This option mirrors the
1283: .Fl t
1284: and
1285: .Fl T
1286: flags for
1287: .Xr ssh 1 .
1.196 djm 1288: .It Cm RevokedHostKeys
1289: Specifies revoked host public keys.
1290: Keys listed in this file will be refused for host authentication.
1291: Note that if this file does not exist or is not readable,
1292: then host authentication will be refused for all hosts.
1293: Keys may be specified as a text file, listing one public key per line, or as
1294: an OpenSSH Key Revocation List (KRL) as generated by
1295: .Xr ssh-keygen 1 .
1296: For more information on KRLs, see the KEY REVOCATION LISTS section in
1297: .Xr ssh-keygen 1 .
1.1 stevesk 1298: .It Cm RhostsRSAAuthentication
1299: Specifies whether to try rhosts based authentication with RSA host
1300: authentication.
1301: The argument must be
1302: .Dq yes
1303: or
1304: .Dq no .
1305: The default is
1306: .Dq no .
1307: This option applies to protocol version 1 only and requires
1.84 jmc 1308: .Xr ssh 1
1.1 stevesk 1309: to be setuid root.
1310: .It Cm RSAAuthentication
1311: Specifies whether to try RSA authentication.
1312: The argument to this keyword must be
1313: .Dq yes
1314: or
1315: .Dq no .
1316: RSA authentication will only be
1317: attempted if the identity file exists, or an authentication agent is
1318: running.
1319: The default is
1320: .Dq yes .
1321: Note that this option applies to protocol version 1 only.
1.32 djm 1322: .It Cm SendEnv
1323: Specifies what variables from the local
1324: .Xr environ 7
1325: should be sent to the server.
1.84 jmc 1326: Note that environment passing is only supported for protocol 2.
1327: The server must also support it, and the server must be configured to
1.33 djm 1328: accept these environment variables.
1.32 djm 1329: Refer to
1330: .Cm AcceptEnv
1331: in
1332: .Xr sshd_config 5
1333: for how to configure the server.
1.80 jmc 1334: Variables are specified by name, which may contain wildcard characters.
1.33 djm 1335: Multiple environment variables may be separated by whitespace or spread
1.32 djm 1336: across multiple
1337: .Cm SendEnv
1338: directives.
1339: The default is not to send any environment variables.
1.81 jmc 1340: .Pp
1341: See
1342: .Sx PATTERNS
1343: for more information on patterns.
1.28 markus 1344: .It Cm ServerAliveCountMax
1.73 jmc 1345: Sets the number of server alive messages (see below) which may be
1.28 markus 1346: sent without
1.84 jmc 1347: .Xr ssh 1
1.28 markus 1348: receiving any messages back from the server.
1349: If this threshold is reached while server alive messages are being sent,
1.84 jmc 1350: ssh will disconnect from the server, terminating the session.
1.28 markus 1351: It is important to note that the use of server alive messages is very
1352: different from
1353: .Cm TCPKeepAlive
1354: (below).
1355: The server alive messages are sent through the encrypted channel
1356: and therefore will not be spoofable.
1357: The TCP keepalive option enabled by
1358: .Cm TCPKeepAlive
1359: is spoofable.
1360: The server alive mechanism is valuable when the client or
1361: server depend on knowing when a connection has become inactive.
1362: .Pp
1363: The default value is 3.
1364: If, for example,
1365: .Cm ServerAliveInterval
1.84 jmc 1366: (see below) is set to 15 and
1.28 markus 1367: .Cm ServerAliveCountMax
1.84 jmc 1368: is left at the default, if the server becomes unresponsive,
1369: ssh will disconnect after approximately 45 seconds.
1.89 markus 1370: This option applies to protocol version 2 only.
1.67 jmc 1371: .It Cm ServerAliveInterval
1372: Sets a timeout interval in seconds after which if no data has been received
1373: from the server,
1.84 jmc 1374: .Xr ssh 1
1.67 jmc 1375: will send a message through the encrypted
1376: channel to request a response from the server.
1377: The default
1378: is 0, indicating that these messages will not be sent to the server.
1379: This option applies to protocol version 2 only.
1.191 millert 1380: .It Cm StreamLocalBindMask
1381: Sets the octal file creation mode mask
1382: .Pq umask
1383: used when creating a Unix-domain socket file for local or remote
1384: port forwarding.
1385: This option is only used for port forwarding to a Unix-domain socket file.
1386: .Pp
1387: The default value is 0177, which creates a Unix-domain socket file that is
1388: readable and writable only by the owner.
1389: Note that not all operating systems honor the file mode on Unix-domain
1390: socket files.
1391: .It Cm StreamLocalBindUnlink
1392: Specifies whether to remove an existing Unix-domain socket file for local
1393: or remote port forwarding before creating a new one.
1394: If the socket file already exists and
1395: .Cm StreamLocalBindUnlink
1396: is not enabled,
1397: .Nm ssh
1398: will be unable to forward the port to the Unix-domain socket file.
1399: This option is only used for port forwarding to a Unix-domain socket file.
1400: .Pp
1401: The argument must be
1402: .Dq yes
1403: or
1404: .Dq no .
1405: The default is
1406: .Dq no .
1.1 stevesk 1407: .It Cm StrictHostKeyChecking
1408: If this flag is set to
1409: .Dq yes ,
1.84 jmc 1410: .Xr ssh 1
1.1 stevesk 1411: will never automatically add host keys to the
1.50 djm 1412: .Pa ~/.ssh/known_hosts
1.1 stevesk 1413: file, and refuses to connect to hosts whose host key has changed.
1414: This provides maximum protection against trojan horse attacks,
1.84 jmc 1415: though it can be annoying when the
1.1 stevesk 1416: .Pa /etc/ssh/ssh_known_hosts
1.84 jmc 1417: file is poorly maintained or when connections to new hosts are
1.1 stevesk 1418: frequently made.
1419: This option forces the user to manually
1420: add all new hosts.
1421: If this flag is set to
1422: .Dq no ,
1.84 jmc 1423: ssh will automatically add new host keys to the
1.1 stevesk 1424: user known hosts files.
1425: If this flag is set to
1426: .Dq ask ,
1427: new host keys
1428: will be added to the user known host files only after the user
1429: has confirmed that is what they really want to do, and
1.84 jmc 1430: ssh will refuse to connect to hosts whose host key has changed.
1.1 stevesk 1431: The host keys of
1432: known hosts will be verified automatically in all cases.
1433: The argument must be
1434: .Dq yes ,
1.84 jmc 1435: .Dq no ,
1.1 stevesk 1436: or
1437: .Dq ask .
1438: The default is
1439: .Dq ask .
1.26 markus 1440: .It Cm TCPKeepAlive
1441: Specifies whether the system should send TCP keepalive messages to the
1442: other side.
1443: If they are sent, death of the connection or crash of one
1444: of the machines will be properly noticed.
1445: However, this means that
1446: connections will die if the route is down temporarily, and some people
1447: find it annoying.
1448: .Pp
1449: The default is
1450: .Dq yes
1451: (to send TCP keepalive messages), and the client will notice
1452: if the network goes down or the remote host dies.
1453: This is important in scripts, and many users want it too.
1454: .Pp
1455: To disable TCP keepalive messages, the value should be set to
1456: .Dq no .
1.65 reyk 1457: .It Cm Tunnel
1.95 stevesk 1458: Request
1.65 reyk 1459: .Xr tun 4
1.69 jmc 1460: device forwarding between the client and the server.
1.65 reyk 1461: The argument must be
1.68 reyk 1462: .Dq yes ,
1.95 stevesk 1463: .Dq point-to-point
1464: (layer 3),
1465: .Dq ethernet
1466: (layer 2),
1.65 reyk 1467: or
1468: .Dq no .
1.95 stevesk 1469: Specifying
1470: .Dq yes
1471: requests the default tunnel mode, which is
1472: .Dq point-to-point .
1.65 reyk 1473: The default is
1474: .Dq no .
1475: .It Cm TunnelDevice
1.95 stevesk 1476: Specifies the
1.65 reyk 1477: .Xr tun 4
1.95 stevesk 1478: devices to open on the client
1479: .Pq Ar local_tun
1480: and the server
1481: .Pq Ar remote_tun .
1482: .Pp
1483: The argument must be
1484: .Sm off
1485: .Ar local_tun Op : Ar remote_tun .
1486: .Sm on
1487: The devices may be specified by numerical ID or the keyword
1488: .Dq any ,
1489: which uses the next available tunnel device.
1490: If
1491: .Ar remote_tun
1492: is not specified, it defaults to
1493: .Dq any .
1494: The default is
1495: .Dq any:any .
1.72 jmc 1496: .It Cm UsePrivilegedPort
1497: Specifies whether to use a privileged port for outgoing connections.
1498: The argument must be
1499: .Dq yes
1500: or
1501: .Dq no .
1502: The default is
1503: .Dq no .
1504: If set to
1.84 jmc 1505: .Dq yes ,
1506: .Xr ssh 1
1.72 jmc 1507: must be setuid root.
1508: Note that this option must be set to
1509: .Dq yes
1510: for
1511: .Cm RhostsRSAAuthentication
1512: with older servers.
1.1 stevesk 1513: .It Cm User
1514: Specifies the user to log in as.
1515: This can be useful when a different user name is used on different machines.
1516: This saves the trouble of
1517: having to remember to give the user name on the command line.
1518: .It Cm UserKnownHostsFile
1.151 djm 1519: Specifies one or more files to use for the user
1520: host key database, separated by whitespace.
1521: The default is
1522: .Pa ~/.ssh/known_hosts ,
1523: .Pa ~/.ssh/known_hosts2 .
1.8 jakob 1524: .It Cm VerifyHostKeyDNS
1525: Specifies whether to verify the remote key using DNS and SSHFP resource
1526: records.
1.24 jakob 1527: If this option is set to
1528: .Dq yes ,
1.25 jmc 1529: the client will implicitly trust keys that match a secure fingerprint
1.24 jakob 1530: from DNS.
1531: Insecure fingerprints will be handled as if this option was set to
1532: .Dq ask .
1533: If this option is set to
1534: .Dq ask ,
1535: information on fingerprint match will be displayed, but the user will still
1536: need to confirm new host keys according to the
1537: .Cm StrictHostKeyChecking
1538: option.
1539: The argument must be
1540: .Dq yes ,
1.84 jmc 1541: .Dq no ,
1.25 jmc 1542: or
1543: .Dq ask .
1.8 jakob 1544: The default is
1545: .Dq no .
1.12 jakob 1546: Note that this option applies to protocol version 2 only.
1.84 jmc 1547: .Pp
1.166 jmc 1548: See also VERIFYING HOST KEYS in
1.84 jmc 1549: .Xr ssh 1 .
1.111 grunk 1550: .It Cm VisualHostKey
1551: If this flag is set to
1552: .Dq yes ,
1553: an ASCII art representation of the remote host key fingerprint is
1.197 djm 1554: printed in addition to the fingerprint string at login and
1.114 stevesk 1555: for unknown host keys.
1.111 grunk 1556: If this flag is set to
1557: .Dq no ,
1.114 stevesk 1558: no fingerprint strings are printed at login and
1.197 djm 1559: only the fingerprint string will be printed for unknown host keys.
1.111 grunk 1560: The default is
1561: .Dq no .
1.1 stevesk 1562: .It Cm XAuthLocation
1.5 stevesk 1563: Specifies the full pathname of the
1.1 stevesk 1564: .Xr xauth 1
1565: program.
1566: The default is
1567: .Pa /usr/X11R6/bin/xauth .
1568: .El
1.86 jmc 1569: .Sh PATTERNS
1570: A
1571: .Em pattern
1572: consists of zero or more non-whitespace characters,
1573: .Sq *
1574: (a wildcard that matches zero or more characters),
1575: or
1576: .Sq ?\&
1577: (a wildcard that matches exactly one character).
1578: For example, to specify a set of declarations for any host in the
1579: .Dq .co.uk
1580: set of domains,
1581: the following pattern could be used:
1582: .Pp
1583: .Dl Host *.co.uk
1584: .Pp
1585: The following pattern
1586: would match any host in the 192.168.0.[0-9] network range:
1587: .Pp
1588: .Dl Host 192.168.0.?
1589: .Pp
1590: A
1591: .Em pattern-list
1592: is a comma-separated list of patterns.
1593: Patterns within pattern-lists may be negated
1594: by preceding them with an exclamation mark
1595: .Pq Sq !\& .
1596: For example,
1.174 djm 1597: to allow a key to be used from anywhere within an organization
1.86 jmc 1598: except from the
1599: .Dq dialup
1600: pool,
1601: the following entry (in authorized_keys) could be used:
1602: .Pp
1603: .Dl from=\&"!*.dialup.example.com,*.example.com\&"
1.1 stevesk 1604: .Sh FILES
1605: .Bl -tag -width Ds
1.50 djm 1606: .It Pa ~/.ssh/config
1.1 stevesk 1607: This is the per-user configuration file.
1608: The format of this file is described above.
1.84 jmc 1609: This file is used by the SSH client.
1.30 djm 1610: Because of the potential for abuse, this file must have strict permissions:
1611: read/write for the user, and not accessible by others.
1.1 stevesk 1612: .It Pa /etc/ssh/ssh_config
1613: Systemwide configuration file.
1614: This file provides defaults for those
1615: values that are not specified in the user's configuration file, and
1616: for those users who do not have a configuration file.
1617: This file must be world-readable.
1618: .El
1.13 jmc 1619: .Sh SEE ALSO
1620: .Xr ssh 1
1.1 stevesk 1621: .Sh AUTHORS
1622: OpenSSH is a derivative of the original and free
1623: ssh 1.2.12 release by Tatu Ylonen.
1624: Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1625: Theo de Raadt and Dug Song
1626: removed many bugs, re-added newer features and
1627: created OpenSSH.
1628: Markus Friedl contributed the support for SSH
1629: protocol versions 1.5 and 2.0.