Annotation of src/usr.bin/ssh/ssh_config.5, Revision 1.110
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.110 ! jmc 37: .\" $OpenBSD: ssh_config.5,v 1.109 2008/06/12 16:35:31 dtucker Exp $
! 38: .Dd $Mdocdate: June 12 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 ,
1.110 ! jmc 165: a fingerprint and an ASCII art representation of the key are printed,
! 166: in addition to the host IP address check.
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.109 dtucker 608: The following escape character substitutions will be performed:
609: .Ql %d
610: (local user's home directory),
611: .Ql %h
612: (remote host name),
613: .Ql %l
614: (local host name),
615: .Ql %n
616: (host name as provided on the command line),
617: .Ql %p
618: (remote port),
619: .Ql %r
620: (remote user name) or
621: .Ql %u
622: (local user name).
1.65 reyk 623: This directive is ignored unless
624: .Cm PermitLocalCommand
625: has been enabled.
1.1 stevesk 626: .It Cm LocalForward
1.74 jmc 627: Specifies that a TCP port on the local machine be forwarded over
1.1 stevesk 628: the secure channel to the specified host and port from the remote machine.
1.49 jmc 629: The first argument must be
1.43 djm 630: .Sm off
1.49 jmc 631: .Oo Ar bind_address : Oc Ar port
1.43 djm 632: .Sm on
1.49 jmc 633: and the second argument must be
634: .Ar host : Ns Ar hostport .
1.46 jmc 635: IPv6 addresses can be specified by enclosing addresses in square brackets or
1.43 djm 636: by using an alternative syntax:
1.49 jmc 637: .Oo Ar bind_address Ns / Oc Ns Ar port
638: and
639: .Ar host Ns / Ns Ar hostport .
1.46 jmc 640: Multiple forwardings may be specified, and additional forwardings can be
1.43 djm 641: given on the command line.
1.1 stevesk 642: Only the superuser can forward privileged ports.
1.43 djm 643: By default, the local port is bound in accordance with the
644: .Cm GatewayPorts
645: setting.
646: However, an explicit
647: .Ar bind_address
648: may be used to bind the connection to a specific address.
649: The
650: .Ar bind_address
651: of
652: .Dq localhost
1.46 jmc 653: indicates that the listening port be bound for local use only, while an
654: empty address or
655: .Sq *
1.43 djm 656: indicates that the port should be available from all interfaces.
1.1 stevesk 657: .It Cm LogLevel
658: Gives the verbosity level that is used when logging messages from
1.84 jmc 659: .Xr ssh 1 .
1.1 stevesk 660: The possible values are:
1.84 jmc 661: QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2, and DEBUG3.
1.7 jmc 662: The default is INFO.
663: DEBUG and DEBUG1 are equivalent.
664: DEBUG2 and DEBUG3 each specify higher levels of verbose output.
1.1 stevesk 665: .It Cm MACs
666: Specifies the MAC (message authentication code) algorithms
667: in order of preference.
668: The MAC algorithm is used in protocol version 2
669: for data integrity protection.
670: Multiple algorithms must be comma-separated.
1.84 jmc 671: The default is:
1.101 jmc 672: .Bd -literal -offset indent
673: hmac-md5,hmac-sha1,umac-64@openssh.com,
674: hmac-ripemd160,hmac-sha1-96,hmac-md5-96
675: .Ed
1.1 stevesk 676: .It Cm NoHostAuthenticationForLocalhost
677: This option can be used if the home directory is shared across machines.
678: In this case localhost will refer to a different machine on each of
679: the machines and the user will get many warnings about changed host keys.
680: However, this option disables host authentication for localhost.
681: The argument to this keyword must be
682: .Dq yes
683: or
684: .Dq no .
685: The default is to check the host key for localhost.
686: .It Cm NumberOfPasswordPrompts
687: Specifies the number of password prompts before giving up.
688: The argument to this keyword must be an integer.
1.84 jmc 689: The default is 3.
1.1 stevesk 690: .It Cm PasswordAuthentication
691: Specifies whether to use password authentication.
692: The argument to this keyword must be
693: .Dq yes
694: or
695: .Dq no .
696: The default is
697: .Dq yes .
1.65 reyk 698: .It Cm PermitLocalCommand
699: Allow local command execution via the
700: .Ic LocalCommand
701: option or using the
1.66 jmc 702: .Ic !\& Ns Ar command
1.65 reyk 703: escape sequence in
704: .Xr ssh 1 .
705: The argument must be
706: .Dq yes
707: or
708: .Dq no .
709: The default is
710: .Dq no .
1.67 jmc 711: .It Cm Port
712: Specifies the port number to connect on the remote host.
1.84 jmc 713: The default is 22.
1.1 stevesk 714: .It Cm PreferredAuthentications
715: Specifies the order in which the client should try protocol 2
1.11 jmc 716: authentication methods.
1.48 jmc 717: This allows a client to prefer one method (e.g.\&
1.1 stevesk 718: .Cm keyboard-interactive )
1.48 jmc 719: over another method (e.g.\&
1.1 stevesk 720: .Cm password )
721: The default for this option is:
1.94 jmc 722: .Do gssapi-with-mic ,
723: hostbased,
724: publickey,
725: keyboard-interactive,
726: password
727: .Dc .
1.1 stevesk 728: .It Cm Protocol
729: Specifies the protocol versions
1.84 jmc 730: .Xr ssh 1
1.1 stevesk 731: should support in order of preference.
732: The possible values are
1.84 jmc 733: .Sq 1
1.1 stevesk 734: and
1.84 jmc 735: .Sq 2 .
1.1 stevesk 736: Multiple versions must be comma-separated.
737: The default is
738: .Dq 2,1 .
1.84 jmc 739: This means that ssh
1.1 stevesk 740: tries version 2 and falls back to version 1
741: if version 2 is not available.
742: .It Cm ProxyCommand
743: Specifies the command to use to connect to the server.
744: The command
745: string extends to the end of the line, and is executed with
1.105 jmc 746: the user's shell.
1.1 stevesk 747: In the command string,
748: .Ql %h
749: will be substituted by the host name to
750: connect and
751: .Ql %p
752: by the port.
753: The command can be basically anything,
754: and should read from its standard input and write to its standard output.
755: It should eventually connect an
756: .Xr sshd 8
757: server running on some machine, or execute
758: .Ic sshd -i
759: somewhere.
760: Host key management will be done using the
761: HostName of the host being connected (defaulting to the name typed by
762: the user).
1.7 jmc 763: Setting the command to
764: .Dq none
1.6 markus 765: disables this option entirely.
1.1 stevesk 766: Note that
767: .Cm CheckHostIP
768: is not available for connects with a proxy command.
1.52 djm 769: .Pp
770: This directive is useful in conjunction with
771: .Xr nc 1
772: and its proxy support.
1.53 jmc 773: For example, the following directive would connect via an HTTP proxy at
1.52 djm 774: 192.0.2.0:
775: .Bd -literal -offset 3n
776: ProxyCommand /usr/bin/nc -X connect -x 192.0.2.0:8080 %h %p
777: .Ed
1.1 stevesk 778: .It Cm PubkeyAuthentication
779: Specifies whether to try public key authentication.
780: The argument to this keyword must be
781: .Dq yes
782: or
783: .Dq no .
784: The default is
785: .Dq yes .
786: This option applies to protocol version 2 only.
1.75 dtucker 787: .It Cm RekeyLimit
788: Specifies the maximum amount of data that may be transmitted before the
1.76 jmc 789: session key is renegotiated.
1.75 dtucker 790: The argument is the number of bytes, with an optional suffix of
1.76 jmc 791: .Sq K ,
792: .Sq M ,
1.75 dtucker 793: or
1.76 jmc 794: .Sq G
1.75 dtucker 795: to indicate Kilobytes, Megabytes, or Gigabytes, respectively.
796: The default is between
1.84 jmc 797: .Sq 1G
1.75 dtucker 798: and
1.84 jmc 799: .Sq 4G ,
1.75 dtucker 800: depending on the cipher.
1.76 jmc 801: This option applies to protocol version 2 only.
1.1 stevesk 802: .It Cm RemoteForward
1.74 jmc 803: Specifies that a TCP port on the remote machine be forwarded over
1.1 stevesk 804: the secure channel to the specified host and port from the local machine.
1.49 jmc 805: The first argument must be
1.43 djm 806: .Sm off
1.49 jmc 807: .Oo Ar bind_address : Oc Ar port
1.43 djm 808: .Sm on
1.49 jmc 809: and the second argument must be
810: .Ar host : Ns Ar hostport .
811: IPv6 addresses can be specified by enclosing addresses in square brackets
812: or by using an alternative syntax:
813: .Oo Ar bind_address Ns / Oc Ns Ar port
814: and
815: .Ar host Ns / Ns Ar hostport .
1.1 stevesk 816: Multiple forwardings may be specified, and additional
817: forwardings can be given on the command line.
818: Only the superuser can forward privileged ports.
1.43 djm 819: .Pp
820: If the
821: .Ar bind_address
822: is not specified, the default is to only bind to loopback addresses.
823: If the
824: .Ar bind_address
825: is
826: .Ql *
827: or an empty string, then the forwarding is requested to listen on all
828: interfaces.
829: Specifying a remote
830: .Ar bind_address
1.46 jmc 831: will only succeed if the server's
832: .Cm GatewayPorts
1.43 djm 833: option is enabled (see
1.46 jmc 834: .Xr sshd_config 5 ) .
1.1 stevesk 835: .It Cm RhostsRSAAuthentication
836: Specifies whether to try rhosts based authentication with RSA host
837: authentication.
838: The argument must be
839: .Dq yes
840: or
841: .Dq no .
842: The default is
843: .Dq no .
844: This option applies to protocol version 1 only and requires
1.84 jmc 845: .Xr ssh 1
1.1 stevesk 846: to be setuid root.
847: .It Cm RSAAuthentication
848: Specifies whether to try RSA authentication.
849: The argument to this keyword must be
850: .Dq yes
851: or
852: .Dq no .
853: RSA authentication will only be
854: attempted if the identity file exists, or an authentication agent is
855: running.
856: The default is
857: .Dq yes .
858: Note that this option applies to protocol version 1 only.
1.32 djm 859: .It Cm SendEnv
860: Specifies what variables from the local
861: .Xr environ 7
862: should be sent to the server.
1.84 jmc 863: Note that environment passing is only supported for protocol 2.
864: The server must also support it, and the server must be configured to
1.33 djm 865: accept these environment variables.
1.32 djm 866: Refer to
867: .Cm AcceptEnv
868: in
869: .Xr sshd_config 5
870: for how to configure the server.
1.80 jmc 871: Variables are specified by name, which may contain wildcard characters.
1.33 djm 872: Multiple environment variables may be separated by whitespace or spread
1.32 djm 873: across multiple
874: .Cm SendEnv
875: directives.
876: The default is not to send any environment variables.
1.81 jmc 877: .Pp
878: See
879: .Sx PATTERNS
880: for more information on patterns.
1.28 markus 881: .It Cm ServerAliveCountMax
1.73 jmc 882: Sets the number of server alive messages (see below) which may be
1.28 markus 883: sent without
1.84 jmc 884: .Xr ssh 1
1.28 markus 885: receiving any messages back from the server.
886: If this threshold is reached while server alive messages are being sent,
1.84 jmc 887: ssh will disconnect from the server, terminating the session.
1.28 markus 888: It is important to note that the use of server alive messages is very
889: different from
890: .Cm TCPKeepAlive
891: (below).
892: The server alive messages are sent through the encrypted channel
893: and therefore will not be spoofable.
894: The TCP keepalive option enabled by
895: .Cm TCPKeepAlive
896: is spoofable.
897: The server alive mechanism is valuable when the client or
898: server depend on knowing when a connection has become inactive.
899: .Pp
900: The default value is 3.
901: If, for example,
902: .Cm ServerAliveInterval
1.84 jmc 903: (see below) is set to 15 and
1.28 markus 904: .Cm ServerAliveCountMax
1.84 jmc 905: is left at the default, if the server becomes unresponsive,
906: ssh will disconnect after approximately 45 seconds.
1.89 markus 907: This option applies to protocol version 2 only.
1.67 jmc 908: .It Cm ServerAliveInterval
909: Sets a timeout interval in seconds after which if no data has been received
910: from the server,
1.84 jmc 911: .Xr ssh 1
1.67 jmc 912: will send a message through the encrypted
913: channel to request a response from the server.
914: The default
915: is 0, indicating that these messages will not be sent to the server.
916: This option applies to protocol version 2 only.
1.1 stevesk 917: .It Cm SmartcardDevice
1.11 jmc 918: Specifies which smartcard device to use.
919: The argument to this keyword is the device
1.84 jmc 920: .Xr ssh 1
1.1 stevesk 921: should use to communicate with a smartcard used for storing the user's
1.11 jmc 922: private RSA key.
923: By default, no device is specified and smartcard support is not activated.
1.1 stevesk 924: .It Cm StrictHostKeyChecking
925: If this flag is set to
926: .Dq yes ,
1.84 jmc 927: .Xr ssh 1
1.1 stevesk 928: will never automatically add host keys to the
1.50 djm 929: .Pa ~/.ssh/known_hosts
1.1 stevesk 930: file, and refuses to connect to hosts whose host key has changed.
931: This provides maximum protection against trojan horse attacks,
1.84 jmc 932: though it can be annoying when the
1.1 stevesk 933: .Pa /etc/ssh/ssh_known_hosts
1.84 jmc 934: file is poorly maintained or when connections to new hosts are
1.1 stevesk 935: frequently made.
936: This option forces the user to manually
937: add all new hosts.
938: If this flag is set to
939: .Dq no ,
1.84 jmc 940: ssh will automatically add new host keys to the
1.1 stevesk 941: user known hosts files.
942: If this flag is set to
943: .Dq ask ,
944: new host keys
945: will be added to the user known host files only after the user
946: has confirmed that is what they really want to do, and
1.84 jmc 947: ssh will refuse to connect to hosts whose host key has changed.
1.1 stevesk 948: The host keys of
949: known hosts will be verified automatically in all cases.
950: The argument must be
951: .Dq yes ,
1.84 jmc 952: .Dq no ,
1.1 stevesk 953: or
954: .Dq ask .
955: The default is
956: .Dq ask .
1.26 markus 957: .It Cm TCPKeepAlive
958: Specifies whether the system should send TCP keepalive messages to the
959: other side.
960: If they are sent, death of the connection or crash of one
961: of the machines will be properly noticed.
962: However, this means that
963: connections will die if the route is down temporarily, and some people
964: find it annoying.
965: .Pp
966: The default is
967: .Dq yes
968: (to send TCP keepalive messages), and the client will notice
969: if the network goes down or the remote host dies.
970: This is important in scripts, and many users want it too.
971: .Pp
972: To disable TCP keepalive messages, the value should be set to
973: .Dq no .
1.65 reyk 974: .It Cm Tunnel
1.95 stevesk 975: Request
1.65 reyk 976: .Xr tun 4
1.69 jmc 977: device forwarding between the client and the server.
1.65 reyk 978: The argument must be
1.68 reyk 979: .Dq yes ,
1.95 stevesk 980: .Dq point-to-point
981: (layer 3),
982: .Dq ethernet
983: (layer 2),
1.65 reyk 984: or
985: .Dq no .
1.95 stevesk 986: Specifying
987: .Dq yes
988: requests the default tunnel mode, which is
989: .Dq point-to-point .
1.65 reyk 990: The default is
991: .Dq no .
992: .It Cm TunnelDevice
1.95 stevesk 993: Specifies the
1.65 reyk 994: .Xr tun 4
1.95 stevesk 995: devices to open on the client
996: .Pq Ar local_tun
997: and the server
998: .Pq Ar remote_tun .
999: .Pp
1000: The argument must be
1001: .Sm off
1002: .Ar local_tun Op : Ar remote_tun .
1003: .Sm on
1004: The devices may be specified by numerical ID or the keyword
1005: .Dq any ,
1006: which uses the next available tunnel device.
1007: If
1008: .Ar remote_tun
1009: is not specified, it defaults to
1010: .Dq any .
1011: The default is
1012: .Dq any:any .
1.72 jmc 1013: .It Cm UsePrivilegedPort
1014: Specifies whether to use a privileged port for outgoing connections.
1015: The argument must be
1016: .Dq yes
1017: or
1018: .Dq no .
1019: The default is
1020: .Dq no .
1021: If set to
1.84 jmc 1022: .Dq yes ,
1023: .Xr ssh 1
1.72 jmc 1024: must be setuid root.
1025: Note that this option must be set to
1026: .Dq yes
1027: for
1028: .Cm RhostsRSAAuthentication
1029: with older servers.
1.1 stevesk 1030: .It Cm User
1031: Specifies the user to log in as.
1032: This can be useful when a different user name is used on different machines.
1033: This saves the trouble of
1034: having to remember to give the user name on the command line.
1035: .It Cm UserKnownHostsFile
1036: Specifies a file to use for the user
1037: host key database instead of
1.50 djm 1038: .Pa ~/.ssh/known_hosts .
1.8 jakob 1039: .It Cm VerifyHostKeyDNS
1040: Specifies whether to verify the remote key using DNS and SSHFP resource
1041: records.
1.24 jakob 1042: If this option is set to
1043: .Dq yes ,
1.25 jmc 1044: the client will implicitly trust keys that match a secure fingerprint
1.24 jakob 1045: from DNS.
1046: Insecure fingerprints will be handled as if this option was set to
1047: .Dq ask .
1048: If this option is set to
1049: .Dq ask ,
1050: information on fingerprint match will be displayed, but the user will still
1051: need to confirm new host keys according to the
1052: .Cm StrictHostKeyChecking
1053: option.
1054: The argument must be
1055: .Dq yes ,
1.84 jmc 1056: .Dq no ,
1.25 jmc 1057: or
1058: .Dq ask .
1.8 jakob 1059: The default is
1060: .Dq no .
1.12 jakob 1061: Note that this option applies to protocol version 2 only.
1.84 jmc 1062: .Pp
1063: See also
1064: .Sx VERIFYING HOST KEYS
1065: in
1066: .Xr ssh 1 .
1.1 stevesk 1067: .It Cm XAuthLocation
1.5 stevesk 1068: Specifies the full pathname of the
1.1 stevesk 1069: .Xr xauth 1
1070: program.
1071: The default is
1072: .Pa /usr/X11R6/bin/xauth .
1073: .El
1.86 jmc 1074: .Sh PATTERNS
1075: A
1076: .Em pattern
1077: consists of zero or more non-whitespace characters,
1078: .Sq *
1079: (a wildcard that matches zero or more characters),
1080: or
1081: .Sq ?\&
1082: (a wildcard that matches exactly one character).
1083: For example, to specify a set of declarations for any host in the
1084: .Dq .co.uk
1085: set of domains,
1086: the following pattern could be used:
1087: .Pp
1088: .Dl Host *.co.uk
1089: .Pp
1090: The following pattern
1091: would match any host in the 192.168.0.[0-9] network range:
1092: .Pp
1093: .Dl Host 192.168.0.?
1094: .Pp
1095: A
1096: .Em pattern-list
1097: is a comma-separated list of patterns.
1098: Patterns within pattern-lists may be negated
1099: by preceding them with an exclamation mark
1100: .Pq Sq !\& .
1101: For example,
1102: to allow a key to be used from anywhere within an organisation
1103: except from the
1104: .Dq dialup
1105: pool,
1106: the following entry (in authorized_keys) could be used:
1107: .Pp
1108: .Dl from=\&"!*.dialup.example.com,*.example.com\&"
1.1 stevesk 1109: .Sh FILES
1110: .Bl -tag -width Ds
1.50 djm 1111: .It Pa ~/.ssh/config
1.1 stevesk 1112: This is the per-user configuration file.
1113: The format of this file is described above.
1.84 jmc 1114: This file is used by the SSH client.
1.30 djm 1115: Because of the potential for abuse, this file must have strict permissions:
1116: read/write for the user, and not accessible by others.
1.1 stevesk 1117: .It Pa /etc/ssh/ssh_config
1118: Systemwide configuration file.
1119: This file provides defaults for those
1120: values that are not specified in the user's configuration file, and
1121: for those users who do not have a configuration file.
1122: This file must be world-readable.
1123: .El
1.13 jmc 1124: .Sh SEE ALSO
1125: .Xr ssh 1
1.1 stevesk 1126: .Sh AUTHORS
1127: OpenSSH is a derivative of the original and free
1128: ssh 1.2.12 release by Tatu Ylonen.
1129: Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1130: Theo de Raadt and Dug Song
1131: removed many bugs, re-added newer features and
1132: created OpenSSH.
1133: Markus Friedl contributed the support for SSH
1134: protocol versions 1.5 and 2.0.