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.\" -*- 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
| 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
| 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
|
198.Nm ssh
199command line to clear port forwardings set in
200configuration files, and is automatically set by
201.Xr scp 1
202and
203.Xr sftp 1 .
204The argument must be
205.Dq yes
206or
207.Dq no .
208The default is
209.Dq no .
210.It Cm Compression
211Specifies whether to use compression.
212The argument must be
213.Dq yes
214or
215.Dq no .
216The default is
217.Dq no .
218.It Cm CompressionLevel
219Specifies the compression level to use if compression is enabled.
220The argument must be an integer from 1 (fast) to 9 (slow, best).
221The default level is 6, which is good for most applications.
222The meaning of the values is the same as in
223.Xr gzip 1 .
224Note that this option applies to protocol version 1 only.
225.It Cm ConnectionAttempts
226Specifies the number of tries (one per second) to make before exiting.
227The argument must be an integer.
228This may be useful in scripts if the connection sometimes fails.
229The default is 1.
230.It Cm DynamicForward
231Specifies that a TCP/IP port on the local machine be forwarded
232over the secure channel, and the application
233protocol is then used to determine where to connect to 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.
|
235Currently the SOCKS4 protocol is supported, and
236.Nm ssh
237will act as a SOCKS4 server.
238Multiple forwardings may be specified, and
| 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.
|
241.It Cm EscapeChar
242Sets the escape character (default:
243.Ql ~ ) .
244The escape character can also
245be set on the command line.
246The argument should be a single character,
247.Ql ^
248followed by a letter, or
249.Dq none
250to disable the escape
251character entirely (making the connection transparent for binary
252data).
253.It Cm ForwardAgent
254Specifies whether the connection to the authentication agent (if any)
255will be forwarded to the remote machine.
256The argument must be
257.Dq yes
258or
259.Dq no .
260The default is
261.Dq no .
262.Pp
| 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,
|
267however they can perform operations on the keys that enable them to
268authenticate using the identities loaded into the agent.
269.It Cm ForwardX11
270Specifies whether X11 connections will be automatically redirected
271over the secure channel and
272.Ev DISPLAY
273set.
274The argument must be
275.Dq yes
276or
277.Dq no .
278The default is
279.Dq no .
280.Pp
| 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.
|
286.It Cm GatewayPorts
287Specifies whether remote hosts are allowed to connect to local
288forwarded ports.
289By default,
290.Nm ssh
| 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.
|
293.Cm GatewayPorts
294can be used to specify that
295.Nm ssh
296should bind local port forwardings to the wildcard address,
297thus allowing remote hosts to connect to forwarded ports.
298The argument must be
299.Dq yes
300or
301.Dq no .
302The default is
303.Dq no .
304.It Cm GlobalKnownHostsFile
305Specifies a file to use for the global
306host key database instead of
307.Pa /etc/ssh/ssh_known_hosts .
308.It Cm HostbasedAuthentication
309Specifies whether to try rhosts based authentication with public key
310authentication.
311The argument must be
312.Dq yes
313or
314.Dq no .
315The default is
316.Dq no .
317This option applies to protocol version 2 only and
318is similar to
319.Cm RhostsRSAAuthentication .
320.It Cm HostKeyAlgorithms
321Specifies the protocol version 2 host key algorithms
322that the client wants to use in order of preference.
323The default for this option is:
324.Dq ssh-rsa,ssh-dss .
325.It Cm HostKeyAlias
326Specifies an alias that should be used instead of the
327real host name when looking up or saving the host key
328in the host key database files.
329This option is useful for tunneling ssh connections
330or for multiple servers running on a single host.
331.It Cm HostName
332Specifies the real host name to log into.
333This can be used to specify nicknames or abbreviations for hosts.
334Default is the name given on the command line.
335Numeric IP addresses are also permitted (both on the command line and in
336.Cm HostName
337specifications).
338.It Cm IdentityFile
339Specifies a file from which the user's RSA or DSA authentication identity
340is read. The default is
341.Pa $HOME/.ssh/identity
342for protocol version 1, and
343.Pa $HOME/.ssh/id_rsa
344and
345.Pa $HOME/.ssh/id_dsa
346for protocol version 2.
347Additionally, any identities represented by the authentication agent
348will be used for authentication.
349The file name may use the tilde
350syntax to refer to a user's home directory.
351It is possible to have
352multiple identity files specified in configuration files; all these
353identities will be tried in sequence.
354.It Cm KeepAlive
355Specifies whether the system should send TCP keepalive messages to the
356other side.
357If they are sent, death of the connection or crash of one
358of the machines will be properly noticed.
359However, this means that
360connections will die if the route is down temporarily, and some people
361find it annoying.
362.Pp
363The default is
364.Dq yes
365(to send keepalives), and the client will notice
366if the network goes down or the remote host dies.
367This is important in scripts, and many users want it too.
368.Pp
369To disable keepalives, the value should be set to
370.Dq no .
371.It Cm KerberosAuthentication
372Specifies whether Kerberos authentication will be used.
373The argument to this keyword must be
374.Dq yes
375or
376.Dq no .
377.It Cm KerberosTgtPassing
378Specifies whether a Kerberos TGT will be forwarded to the server.
379This will only work if the Kerberos server is actually an AFS kaserver.
380The argument to this keyword must be
381.Dq yes
382or
383.Dq no .
384.It Cm LocalForward
385Specifies that a TCP/IP port on the local machine be forwarded over
386the secure channel to the specified host and port from the remote machine.
387The first argument must be a port number, and the second must be
388.Ar host:port .
389IPv6 addresses can be specified with an alternative syntax:
390.Ar host/port .
391Multiple forwardings may be specified, and additional
392forwardings can be given on the command line.
393Only the superuser can forward privileged ports.
394.It Cm LogLevel
395Gives the verbosity level that is used when logging messages from
396.Nm ssh .
397The possible values are:
398QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2 and DEBUG3.
| 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.
|
401.It Cm MACs
402Specifies the MAC (message authentication code) algorithms
403in order of preference.
404The MAC algorithm is used in protocol version 2
405for data integrity protection.
406Multiple algorithms must be comma-separated.
407The default is
408.Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 .
409.It Cm NoHostAuthenticationForLocalhost
410This option can be used if the home directory is shared across machines.
411In this case localhost will refer to a different machine on each of
412the machines and the user will get many warnings about changed host keys.
413However, this option disables host authentication for localhost.
414The argument to this keyword must be
415.Dq yes
416or
417.Dq no .
418The default is to check the host key for localhost.
419.It Cm NumberOfPasswordPrompts
420Specifies the number of password prompts before giving up.
421The argument to this keyword must be an integer.
422Default is 3.
423.It Cm PasswordAuthentication
424Specifies whether to use password authentication.
425The argument to this keyword must be
426.Dq yes
427or
428.Dq no .
429The default is
430.Dq yes .
431.It Cm Port
432Specifies the port number to connect on the remote host.
433Default is 22.
434.It Cm PreferredAuthentications
435Specifies the order in which the client should try protocol 2
436authentication methods. This allows a client to prefer one method (e.g.
437.Cm keyboard-interactive )
438over another method (e.g.
439.Cm password )
440The default for this option is:
441.Dq hostbased,publickey,keyboard-interactive,password .
442.It Cm Protocol
443Specifies the protocol versions
444.Nm ssh
445should support in order of preference.
446The possible values are
447.Dq 1
448and
449.Dq 2 .
450Multiple versions must be comma-separated.
451The default is
452.Dq 2,1 .
453This means that
454.Nm ssh
455tries version 2 and falls back to version 1
456if version 2 is not available.
457.It Cm ProxyCommand
458Specifies the command to use to connect to the server.
459The command
460string extends to the end of the line, and is executed with
461.Pa /bin/sh .
462In the command string,
463.Ql %h
464will be substituted by the host name to
465connect and
466.Ql %p
467by the port.
468The command can be basically anything,
469and should read from its standard input and write to its standard output.
470It should eventually connect an
471.Xr sshd 8
472server running on some machine, or execute
473.Ic sshd -i
474somewhere.
475Host key management will be done using the
476HostName of the host being connected (defaulting to the name typed by
477the user).
| 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.
|
478Note that
479.Cm CheckHostIP
480is not available for connects with a proxy command.
481.Pp
482.It Cm PubkeyAuthentication
483Specifies whether to try public key authentication.
484The argument to this keyword must be
485.Dq yes
486or
487.Dq no .
488The default is
489.Dq yes .
490This option applies to protocol version 2 only.
491.It Cm RemoteForward
492Specifies that a TCP/IP port on the remote machine be forwarded over
493the secure channel to the specified host and port from the local machine.
494The first argument must be a port number, and the second must be
495.Ar host:port .
496IPv6 addresses can be specified with an alternative syntax:
497.Ar host/port .
498Multiple forwardings may be specified, and additional
499forwardings can be given on the command line.
500Only the superuser can forward privileged ports.
501.It Cm RhostsAuthentication
502Specifies whether to try rhosts based authentication.
503Note that this
504declaration only affects the client side and has no effect whatsoever
505on security.
506Most servers do not permit RhostsAuthentication because it
507is not secure (see
508.Cm RhostsRSAAuthentication ) .
509The argument to this keyword must be
510.Dq yes
511or
512.Dq no .
513The default is
514.Dq no .
515This option applies to protocol version 1 only and requires
516.Nm ssh
517to be setuid root and
518.Cm UsePrivilegedPort
519to be set to
520.Dq yes .
521.It Cm RhostsRSAAuthentication
522Specifies whether to try rhosts based authentication with RSA host
523authentication.
524The argument must be
525.Dq yes
526or
527.Dq no .
528The default is
529.Dq no .
530This option applies to protocol version 1 only and requires
531.Nm ssh
532to be setuid root.
533.It Cm RSAAuthentication
534Specifies whether to try RSA authentication.
535The argument to this keyword must be
536.Dq yes
537or
538.Dq no .
539RSA authentication will only be
540attempted if the identity file exists, or an authentication agent is
541running.
542The default is
543.Dq yes .
544Note that this option applies to protocol version 1 only.
545.It Cm SmartcardDevice
546Specifies which smartcard device to use. The argument to this keyword is
547the device
548.Nm ssh
549should use to communicate with a smartcard used for storing the user's
550private RSA key. By default, no device is specified and smartcard support
551is not activated.
552.It Cm StrictHostKeyChecking
553If this flag is set to
554.Dq yes ,
555.Nm ssh
556will never automatically add host keys to the
557.Pa $HOME/.ssh/known_hosts
558file, and refuses to connect to hosts whose host key has changed.
559This provides maximum protection against trojan horse attacks,
560however, can be annoying when the
561.Pa /etc/ssh/ssh_known_hosts
562file is poorly maintained, or connections to new hosts are
563frequently made.
564This option forces the user to manually
565add all new hosts.
566If this flag is set to
567.Dq no ,
568.Nm ssh
569will automatically add new host keys to the
570user known hosts files.
571If this flag is set to
572.Dq ask ,
573new host keys
574will be added to the user known host files only after the user
575has confirmed that is what they really want to do, and
576.Nm ssh
577will refuse to connect to hosts whose host key has changed.
578The host keys of
579known hosts will be verified automatically in all cases.
580The argument must be
581.Dq yes ,
582.Dq no
583or
584.Dq ask .
585The default is
586.Dq ask .
587.It Cm UsePrivilegedPort
588Specifies whether to use a privileged port for outgoing connections.
589The argument must be
590.Dq yes
591or
592.Dq no .
593The default is
594.Dq no .
595If set to
596.Dq yes
597.Nm ssh
598must be setuid root.
599Note that this option must be set to
600.Dq yes
601if
602.Cm RhostsAuthentication
603and
604.Cm RhostsRSAAuthentication
605authentications are needed with older servers.
606.It Cm User
607Specifies the user to log in as.
608This can be useful when a different user name is used on different machines.
609This saves the trouble of
610having to remember to give the user name on the command line.
611.It Cm UserKnownHostsFile
612Specifies a file to use for the user
613host key database instead of
614.Pa $HOME/.ssh/known_hosts .
615.It Cm VersionAddendum
616Specifies a string to append to the regular version string to identify
617OS- or site-specific modifications.
618The default is
| 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 .
|
620.It Cm XAuthLocation
621Specifies the full pathname of the
622.Xr xauth 1
623program.
624The default is
625.Pa /usr/X11R6/bin/xauth .
626.El
627.Sh FILES
628.Bl -tag -width Ds
629.It Pa $HOME/.ssh/config
630This is the per-user configuration file.
631The format of this file is described above.
632This file is used by the
633.Nm ssh
634client.
635This file does not usually contain any sensitive information,
636but the recommended permissions are read/write for the user, and not
637accessible by others.
638.It Pa /etc/ssh/ssh_config
639Systemwide configuration file.
640This file provides defaults for those
641values that are not specified in the user's configuration file, and
642for those users who do not have a configuration file.
643This file must be world-readable.
644.El
645.Sh AUTHORS
646OpenSSH is a derivative of the original and free
647ssh 1.2.12 release by Tatu Ylonen.
648Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
649Theo de Raadt and Dug Song
650removed many bugs, re-added newer features and
651created OpenSSH.
652Markus Friedl contributed the support for SSH
653protocol versions 1.5 and 2.0.
654.Sh SEE ALSO
655.Xr ssh 1
| 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
|