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