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