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