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