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