1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
1 |
SSH(1) OpenBSD Reference Manual SSH(1) |
2 |
||
3 |
NAME
|
|
4 |
ssh - OpenSSH SSH client (remote login program) |
|
5 |
||
6 |
SYNOPSIS
|
|
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
7 |
ssh [-1246AaCfgkMNnqsTtVvXxY] [-b bind_address] [-c cipher_spec] |
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
8 |
[-D [bind_address:]port] [-e escape_char] [-F configfile] |
9 |
[-i identity_file] [-L [bind_address:]port:host:hostport] |
|
10 |
[-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port] |
|
11 |
[-R [bind_address:]port:host:hostport] [-S ctl_path] |
|
12 |
[-w tunnel:tunnel] [user@]hostname [command] |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
13 |
|
14 |
DESCRIPTION
|
|
15 |
ssh (SSH client) is a program for logging into a remote machine and for |
|
16 |
executing commands on a remote machine. It is intended to replace rlogin |
|
17 |
and rsh, and provide secure encrypted communications between two untrust- |
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
18 |
ed hosts over an insecure network. X11 connections and arbitrary TCP |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
19 |
ports can also be forwarded over the secure channel. |
20 |
||
21 |
ssh connects and logs into the specified hostname (with optional user |
|
22 |
name). The user must prove his/her identity to the remote machine using |
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
23 |
one of several methods depending on the protocol version used (see be- |
24 |
low). |
|
25 |
||
26 |
If command is specified, it is executed on the remote host instead of a |
|
27 |
login shell. |
|
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
28 |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
29 |
The options are as follows: |
30 |
||
31 |
-1 Forces ssh to try protocol version 1 only. |
|
32 |
||
33 |
-2 Forces ssh to try protocol version 2 only. |
|
34 |
||
35 |
-4 Forces ssh to use IPv4 addresses only. |
|
36 |
||
37 |
-6 Forces ssh to use IPv6 addresses only. |
|
38 |
||
39 |
-A Enables forwarding of the authentication agent connection. This |
|
40 |
can also be specified on a per-host basis in a configuration |
|
41 |
file. |
|
42 |
||
43 |
Agent forwarding should be enabled with caution. Users with the |
|
44 |
ability to bypass file permissions on the remote host (for the |
|
45 |
agent's Unix-domain socket) can access the local agent through |
|
46 |
the forwarded connection. An attacker cannot obtain key material
|
|
47 |
from the agent, however they can perform operations on the keys
|
|
48 |
that enable them to authenticate using the identities loaded into
|
|
49 |
the agent.
|
|
50 |
||
51 |
-a Disables forwarding of the authentication agent connection.
|
|
52 |
||
53 |
-b bind_address
|
|
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
54 |
Use bind_address on the local machine as the source address of
|
55 |
the connection. Only useful on systems with more than one ad-
|
|
56 |
dress.
|
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
57 |
|
58 |
-C Requests compression of all data (including stdin, stdout,
|
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
59 |
stderr, and data for forwarded X11 and TCP connections). The
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
60 |
compression algorithm is the same used by gzip(1), and the
|
61 |
``level'' can be controlled by the CompressionLevel option for
|
|
62 |
protocol version 1. Compression is desirable on modem lines and
|
|
63 |
other slow connections, but will only slow down things on fast
|
|
64 |
networks. The default value can be set on a host-by-host basis
|
|
65 |
in the configuration files; see the Compression option.
|
|
66 |
||
67 |
-c cipher_spec
|
|
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
68 |
Selects the cipher specification for encrypting the session.
|
69 |
||
70 |
Protocol version 1 allows specification of a single cipher. The
|
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
71 |
supported values are ``3des'', ``blowfish'', and ``des''. 3des
|
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
72 |
(triple-des) is an encrypt-decrypt-encrypt triple with three dif-
|
73 |
ferent keys. It is believed to be secure. blowfish is a fast
|
|
74 |
block cipher; it appears very secure and is much faster than
|
|
75 |
3des. des is only supported in the ssh client for interoperabil-
|
|
76 |
ity with legacy protocol 1 implementations that do not support
|
|
77 |
the 3des cipher. Its use is strongly discouraged due to crypto-
|
|
78 |
graphic weaknesses. The default is ``3des''.
|
|
79 |
||
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
80 |
For protocol version 2, cipher_spec is a comma-separated list of
|
81 |
ciphers listed in order of preference. The supported ciphers
|
|
82 |
are: 3des-cbc, aes128-cbc, aes192-cbc, aes256-cbc, aes128-ctr,
|
|
83 |
aes192-ctr, aes256-ctr, arcfour128, arcfour256, arcfour, blow-
|
|
84 |
fish-cbc, and cast128-cbc. The default is:
|
|
85 |
||
86 |
aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128,
|
|
87 |
arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr,
|
|
88 |
aes192-ctr,aes256-ctr
|
|
89 |
||
90 |
-D [bind_address:]port
|
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
91 |
Specifies a local ``dynamic'' application-level port forwarding.
|
92 |
This works by allocating a socket to listen to port on the local
|
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
93 |
side, optionally bound to the specified bind_address. Whenever a
|
94 |
connection is made to this port, the connection is forwarded over
|
|
95 |
the secure channel, and the application protocol is then used to
|
|
96 |
determine where to connect to from the remote machine. Currently
|
|
97 |
the SOCKS4 and SOCKS5 protocols are supported, and ssh will act
|
|
98 |
as a SOCKS server. Only root can forward privileged ports. Dy-
|
|
99 |
namic port forwardings can also be specified in the configuration
|
|
100 |
file.
|
|
101 |
||
102 |
IPv6 addresses can be specified with an alternative syntax:
|
|
103 |
[bind_address/]port or by enclosing the address in square brack-
|
|
104 |
ets. Only the superuser can forward privileged ports. By de-
|
|
105 |
fault, the local port is bound in accordance with the
|
|
106 |
GatewayPorts setting. However, an explicit bind_address may be
|
|
107 |
used to bind the connection to a specific address. The
|
|
108 |
bind_address of ``localhost'' indicates that the listening port
|
|
109 |
be bound for local use only, while an empty address or `*' indi- |
|
110 |
cates that the port should be available from all interfaces. |
|
111 |
||
112 |
-e escape_char |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
113 |
Sets the escape character for sessions with a pty (default: `~'). |
114 |
The escape character is only recognized at the beginning of a
|
|
115 |
line. The escape character followed by a dot (`.') closes the |
|
116 |
connection; followed by control-Z suspends the connection; and |
|
117 |
followed by itself sends the escape character once. Setting the |
|
118 |
character to ``none'' disables any escapes and makes the session |
|
119 |
fully transparent. |
|
120 |
||
121 |
-F configfile |
|
122 |
Specifies an alternative per-user configuration file. If a con- |
|
123 |
figuration file is given on the command line, the system-wide |
|
124 |
configuration file (/etc/ssh/ssh_config) will be ignored. The |
|
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
125 |
default for the per-user configuration file is ~/.ssh/config. |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
126 |
|
127 |
-f Requests ssh to go to background just before command execution. |
|
128 |
This is useful if ssh is going to ask for passwords or passphras- |
|
129 |
es, but the user wants it in the background. This implies -n. |
|
130 |
The recommended way to start X11 programs at a remote site is |
|
131 |
with something like ssh -f host xterm. |
|
132 |
||
133 |
-g Allows remote hosts to connect to local forwarded ports. |
|
134 |
||
135 |
-I smartcard_device |
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
136 |
Specify the device ssh should use to communicate with a smartcard |
137 |
used for storing the user's private RSA key. This option is only |
|
138 |
available if support for smartcard devices is compiled in (de-
|
|
139 |
fault is no support).
|
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
140 |
|
141 |
-i identity_file
|
|
142 |
Selects a file from which the identity (private key) for RSA or
|
|
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
143 |
DSA authentication is read. The default is ~/.ssh/identity for
|
144 |
protocol version 1, and ~/.ssh/id_rsa and ~/.ssh/id_dsa for pro-
|
|
145 |
tocol version 2. Identity files may also be specified on a per-
|
|
146 |
host basis in the configuration file. It is possible to have
|
|
147 |
multiple -i options (and multiple identities specified in config-
|
|
148 |
uration files).
|
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
149 |
|
150 |
-k Disables forwarding (delegation) of GSSAPI credentials to the
|
|
151 |
server.
|
|
152 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
153 |
-L [bind_address:]port:host:hostport
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
154 |
Specifies that the given port on the local (client) host is to be
|
155 |
forwarded to the given host and port on the remote side. This
|
|
156 |
works by allocating a socket to listen to port on the local side,
|
|
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
157 |
optionally bound to the specified bind_address. Whenever a con-
|
158 |
nection is made to this port, the connection is forwarded over
|
|
159 |
the secure channel, and a connection is made to host port
|
|
160 |
hostport from the remote machine. Port forwardings can also be
|
|
161 |
specified in the configuration file. IPv6 addresses can be spec-
|
|
162 |
ified with an alternative syntax: [bind_address/]port/host/host-
|
|
163 |
port or by enclosing the address in square brackets. Only the
|
|
164 |
superuser can forward privileged ports. By default, the local
|
|
165 |
port is bound in accordance with the GatewayPorts setting. How-
|
|
166 |
ever, an explicit bind_address may be used to bind the connection
|
|
167 |
to a specific address. The bind_address of ``localhost'' indi-
|
|
168 |
cates that the listening port be bound for local use only, while
|
|
169 |
an empty address or `*' indicates that the port should be avail- |
|
170 |
able from all interfaces. |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
171 |
|
172 |
-l login_name |
|
173 |
Specifies the user to log in as on the remote machine. This also |
|
174 |
may be specified on a per-host basis in the configuration file. |
|
175 |
||
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
176 |
-M Places the ssh client into ``master'' mode for connection shar- |
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
177 |
ing. Multiple -M options places ssh into ``master'' mode with |
178 |
confirmation required before slave connections are accepted. Re- |
|
179 |
fer to the description of ControlMaster in ssh_config(5) for de- |
|
180 |
tails. |
|
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
181 |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
182 |
-m mac_spec |
183 |
Additionally, for protocol version 2 a comma-separated list of |
|
184 |
MAC (message authentication code) algorithms can be specified in |
|
185 |
order of preference. See the MACs keyword for more information. |
|
186 |
||
187 |
-N Do not execute a remote command. This is useful for just for- |
|
188 |
warding ports (protocol version 2 only). |
|
189 |
||
190 |
-n Redirects stdin from /dev/null (actually, prevents reading from |
|
191 |
stdin). This must be used when ssh is run in the background. A |
|
192 |
common trick is to use this to run X11 programs on a remote ma- |
|
193 |
chine. For example, ssh -n shadows.cs.hut.fi emacs & will start |
|
194 |
an emacs on shadows.cs.hut.fi, and the X11 connection will be au- |
|
195 |
tomatically forwarded over an encrypted channel. The ssh program |
|
196 |
will be put in the background. (This does not work if ssh needs |
|
197 |
to ask for a password or passphrase; see also the -f option.) |
|
198 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
199 |
-O ctl_cmd |
200 |
Control an active connection multiplexing master process. When |
|
201 |
the -O option is specified, the ctl_cmd argument is interpreted |
|
202 |
and passed to the master process. Valid commands are: ``check'' |
|
203 |
(check that the master process is running) and ``exit'' (request |
|
204 |
the master to exit). |
|
205 |
||
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
206 |
-o option |
207 |
Can be used to give options in the format used in the configura- |
|
208 |
tion file. This is useful for specifying options for which there |
|
209 |
is no separate command-line flag. For full details of the op- |
|
210 |
tions listed below, and their possible values, see ssh_config(5). |
|
211 |
||
212 |
AddressFamily |
|
213 |
BatchMode |
|
214 |
BindAddress |
|
215 |
ChallengeResponseAuthentication |
|
216 |
CheckHostIP |
|
217 |
Cipher |
|
218 |
Ciphers |
|
219 |
ClearAllForwardings |
|
220 |
Compression |
|
221 |
CompressionLevel |
|
222 |
ConnectionAttempts |
|
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
223 |
ConnectTimeout |
224 |
ControlMaster |
|
225 |
ControlPath |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
226 |
DynamicForward |
227 |
EscapeChar |
|
228 |
ForwardAgent |
|
229 |
ForwardX11 |
|
230 |
ForwardX11Trusted |
|
231 |
GatewayPorts |
|
232 |
GlobalKnownHostsFile |
|
233 |
GSSAPIAuthentication |
|
234 |
GSSAPIDelegateCredentials |
|
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
235 |
HashKnownHosts |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
236 |
Host |
237 |
HostbasedAuthentication |
|
238 |
HostKeyAlgorithms |
|
239 |
HostKeyAlias |
|
240 |
HostName |
|
241 |
IdentityFile |
|
242 |
IdentitiesOnly |
|
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
243 |
KbdInteractiveDevices |
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
244 |
LocalCommand |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
245 |
LocalForward |
246 |
LogLevel |
|
247 |
MACs |
|
248 |
NoHostAuthenticationForLocalhost |
|
249 |
NumberOfPasswordPrompts |
|
250 |
PasswordAuthentication |
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
251 |
PermitLocalCommand |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
252 |
Port |
253 |
PreferredAuthentications |
|
254 |
Protocol |
|
255 |
ProxyCommand |
|
256 |
PubkeyAuthentication |
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
257 |
RekeyLimit |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
258 |
RemoteForward |
259 |
RhostsRSAAuthentication |
|
260 |
RSAAuthentication |
|
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
261 |
SendEnv |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
262 |
ServerAliveInterval |
263 |
ServerAliveCountMax |
|
264 |
SmartcardDevice |
|
265 |
StrictHostKeyChecking |
|
266 |
TCPKeepAlive |
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
267 |
Tunnel |
268 |
TunnelDevice |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
269 |
UsePrivilegedPort |
270 |
User |
|
271 |
UserKnownHostsFile |
|
272 |
VerifyHostKeyDNS |
|
273 |
XAuthLocation |
|
274 |
||
275 |
-p port |
|
276 |
Port to connect to on the remote host. This can be specified on |
|
277 |
a per-host basis in the configuration file. |
|
278 |
||
279 |
-q Quiet mode. Causes all warning and diagnostic messages to be |
|
280 |
suppressed. |
|
281 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
282 |
-R [bind_address:]port:host:hostport |
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
283 |
Specifies that the given port on the remote (server) host is to |
284 |
be forwarded to the given host and port on the local side. This |
|
285 |
works by allocating a socket to listen to port on the remote |
|
286 |
side, and whenever a connection is made to this port, the connec- |
|
287 |
tion is forwarded over the secure channel, and a connection is |
|
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
288 |
made to host port hostport from the local machine. |
289 |
||
290 |
Port forwardings can also be specified in the configuration file. |
|
291 |
Privileged ports can be forwarded only when logging in as root on |
|
292 |
the remote machine. IPv6 addresses can be specified by enclosing |
|
293 |
the address in square braces or using an alternative syntax: |
|
294 |
[bind_address/]host/port/hostport. |
|
295 |
||
296 |
By default, the listening socket on the server will be bound to |
|
297 |
the loopback interface only. This may be overriden by specifying |
|
298 |
a bind_address. An empty bind_address, or the address `*', indi- |
|
299 |
cates that the remote socket should listen on all interfaces.
|
|
300 |
Specifying a remote bind_address will only succeed if the serv-
|
|
301 |
er's GatewayPorts option is enabled (see sshd_config(5)). |
|
302 |
||
303 |
-S ctl_path |
|
304 |
Specifies the location of a control socket for connection shar- |
|
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
305 |
ing. Refer to the description of ControlPath and ControlMaster |
306 |
in ssh_config(5) for details. |
|
307 |
||
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
308 |
-s May be used to request invocation of a subsystem on the remote |
309 |
system. Subsystems are a feature of the SSH2 protocol which fa- |
|
310 |
cilitate the use of SSH as a secure transport for other applica- |
|
311 |
tions (eg. sftp(1)). The subsystem is specified as the remote |
|
312 |
command. |
|
313 |
||
314 |
-T Disable pseudo-tty allocation. |
|
315 |
||
316 |
-t Force pseudo-tty allocation. This can be used to execute arbi- |
|
317 |
trary screen-based programs on a remote machine, which can be |
|
318 |
very useful, e.g., when implementing menu services. Multiple -t |
|
319 |
options force tty allocation, even if ssh has no local tty. |
|
320 |
||
321 |
-V Display the version number and exit. |
|
322 |
||
323 |
-v Verbose mode. Causes ssh to print debugging messages about its |
|
324 |
progress. This is helpful in debugging connection, authentica- |
|
325 |
tion, and configuration problems. Multiple -v options increase |
|
326 |
the verbosity. The maximum is 3. |
|
327 |
||
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
328 |
-w tunnel:tunnel |
329 |
Requests a tun(4) device on the client (first tunnel arg) and |
|
330 |
server (second tunnel arg). The devices may be specified by nu- |
|
331 |
merical ID or the keyword ``any'', which uses the next available |
|
332 |
tunnel device. See also the Tunnel directive in ssh_config(5). |
|
333 |
||
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
334 |
-X Enables X11 forwarding. This can also be specified on a per-host |
335 |
basis in a configuration file. |
|
336 |
||
337 |
X11 forwarding should be enabled with caution. Users with the |
|
338 |
ability to bypass file permissions on the remote host (for the |
|
339 |
user's X authorization database) can access the local X11 display |
|
340 |
through the forwarded connection. An attacker may then be able
|
|
341 |
to perform activities such as keystroke monitoring.
|
|
342 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
343 |
For this reason, X11 forwarding is subjected to X11 SECURITY ex-
|
344 |
tension restrictions by default. Please refer to the ssh -Y op-
|
|
345 |
tion and the ForwardX11Trusted directive in ssh_config(5) for
|
|
346 |
more information.
|
|
347 |
||
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
348 |
-x Disables X11 forwarding.
|
349 |
||
1.1.2
by Colin Watson
Import upstream version 4.1p1 |
350 |
-Y Enables trusted X11 forwarding. Trusted X11 forwardings are not
|
351 |
subjected to the X11 SECURITY extension controls.
|
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
352 |
|
353 |
ssh may additionally obtain configuration data from a per-user configura-
|
|
354 |
tion file and a system-wide configuration file. The file format and con-
|
|
355 |
figuration options are described in ssh_config(5).
|
|
356 |
||
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
357 |
ssh exits with the exit status of the remote command or with 255 if an
|
358 |
error occurred.
|
|
359 |
||
360 |
AUTHENTICATION
|
|
361 |
The OpenSSH SSH client supports SSH protocols 1 and 2. Protocol 2 is the
|
|
362 |
default, with ssh falling back to protocol 1 if it detects protocol 2 is
|
|
363 |
unsupported. These settings may be altered using the Protocol option in
|
|
364 |
ssh_config(5), or enforced using the -1 and -2 options (see above). Both
|
|
365 |
protocols support similar authentication methods, but protocol 2 is pre-
|
|
366 |
ferred since it provides additional mechanisms for confidentiality (the
|
|
367 |
traffic is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour) and
|
|
368 |
integrity (hmac-md5, hmac-sha1, hmac-ripemd160). Protocol 1 lacks a
|
|
369 |
strong mechanism for ensuring the integrity of the connection.
|
|
370 |
||
371 |
The methods available for authentication are: host-based authentication,
|
|
372 |
public key authentication, challenge-response authentication, and pass-
|
|
373 |
word authentication. Authentication methods are tried in the order spec-
|
|
374 |
ified above, though protocol 2 has a configuration option to change the
|
|
375 |
default order: PreferredAuthentications.
|
|
376 |
||
377 |
Host-based authentication works as follows: If the machine the user logs
|
|
378 |
in from is listed in /etc/hosts.equiv or /etc/shosts.equiv on the remote
|
|
379 |
machine, and the user names are the same on both sides, or if the files
|
|
380 |
~/.rhosts or ~/.shosts exist in the user's home directory on the remote |
|
381 |
machine and contain a line containing the name of the client machine and |
|
382 |
the name of the user on that machine, the user is considered for login. |
|
383 |
Additionally, the server must be able to verify the client's host key |
|
384 |
(see the description of /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts,
|
|
385 |
below) for login to be permitted. This authentication method closes se-
|
|
386 |
curity holes due to IP spoofing, DNS spoofing, and routing spoofing.
|
|
387 |
[Note to the administrator: /etc/hosts.equiv, ~/.rhosts, and the
|
|
388 |
rlogin/rsh protocol in general, are inherently insecure and should be
|
|
389 |
disabled if security is desired.]
|
|
390 |
||
391 |
Public key authentication works as follows: The scheme is based on pub-
|
|
392 |
lic-key cryptography, using cryptosystems where encryption and decryption
|
|
393 |
are done using separate keys, and it is unfeasible to derive the decryp-
|
|
394 |
tion key from the encryption key. The idea is that each user creates a
|
|
395 |
public/private key pair for authentication purposes. The server knows
|
|
396 |
the public key, and only the user knows the private key. ssh implements
|
|
397 |
public key authentication protocol automatically, using either the RSA or
|
|
398 |
DSA algorithms. Protocol 1 is restricted to using only RSA keys, but
|
|
399 |
protocol 2 may use either. The HISTORY section of ssl(8) contains a
|
|
400 |
brief discussion of the two algorithms.
|
|
401 |
||
402 |
The file ~/.ssh/authorized_keys lists the public keys that are permitted
|
|
403 |
for logging in. When the user logs in, the ssh program tells the server
|
|
404 |
which key pair it would like to use for authentication. The client
|
|
405 |
proves that it has access to the private key and the server checks that
|
|
406 |
the corresponding public key is authorized to accept the account.
|
|
407 |
||
408 |
The user creates his/her key pair by running ssh-keygen(1). This stores
|
|
409 |
the private key in ~/.ssh/identity (protocol 1), ~/.ssh/id_dsa (protocol
|
|
410 |
2 DSA), or ~/.ssh/id_rsa (protocol 2 RSA) and stores the public key in
|
|
411 |
~/.ssh/identity.pub (protocol 1), ~/.ssh/id_dsa.pub (protocol 2 DSA), or
|
|
412 |
~/.ssh/id_rsa.pub (protocol 2 RSA) in the user's home directory. The us- |
|
413 |
er should then copy the public key to ~/.ssh/authorized_keys in his/her |
|
414 |
home directory on the remote machine. The authorized_keys file corre- |
|
415 |
sponds to the conventional ~/.rhosts file, and has one key per line, |
|
416 |
though the lines can be very long. After this, the user can log in with- |
|
417 |
out giving the password. |
|
418 |
||
419 |
The most convenient way to use public key authentication may be with an |
|
420 |
authentication agent. See ssh-agent(1) for more information. |
|
421 |
||
422 |
Challenge-response authentication works as follows: The server sends an |
|
423 |
arbitrary "challenge" text, and prompts for a response. Protocol 2 al- |
|
424 |
lows multiple challenges and responses; protocol 1 is restricted to just |
|
425 |
one challenge/response. Examples of challenge-response authentication |
|
426 |
include BSD Authentication (see login.conf(5)) and PAM (some non-OpenBSD |
|
427 |
systems). |
|
428 |
||
429 |
Finally, if other authentication methods fail, ssh prompts the user for a |
|
430 |
password. The password is sent to the remote host for checking; however, |
|
431 |
since all communications are encrypted, the password cannot be seen by |
|
432 |
someone listening on the network. |
|
433 |
||
434 |
ssh automatically maintains and checks a database containing identifica- |
|
435 |
tion for all hosts it has ever been used with. Host keys are stored in |
|
436 |
~/.ssh/known_hosts in the user's home directory. Additionally, the file |
|
437 |
/etc/ssh/ssh_known_hosts is automatically checked for known hosts. Any
|
|
438 |
new hosts are automatically added to the user's file. If a host's iden- |
|
439 |
tification ever changes, ssh warns about this and disables password au-
|
|
440 |
thentication to prevent server spoofing or man-in-the-middle attacks,
|
|
441 |
which could otherwise be used to circumvent the encryption. The
|
|
442 |
StrictHostKeyChecking option can be used to control logins to machines
|
|
443 |
whose host key is not known or has changed.
|
|
444 |
||
445 |
When the user's identity has been accepted by the server, the server ei- |
|
446 |
ther executes the given command, or logs into the machine and gives the |
|
447 |
user a normal shell on the remote machine. All communication with the |
|
448 |
remote command or shell will be automatically encrypted. |
|
449 |
||
450 |
If a pseudo-terminal has been allocated (normal login session), the user |
|
451 |
may use the escape characters noted below. |
|
452 |
||
453 |
If no pseudo-tty has been allocated, the session is transparent and can |
|
454 |
be used to reliably transfer binary data. On most systems, setting the |
|
455 |
escape character to ``none'' will also make the session transparent even |
|
456 |
if a tty is used. |
|
457 |
||
458 |
The session terminates when the command or shell on the remote machine |
|
459 |
exits and all X11 and TCP connections have been closed. |
|
460 |
||
461 |
ESCAPE CHARACTERS |
|
462 |
When a pseudo-terminal has been requested, ssh supports a number of func- |
|
463 |
tions through the use of an escape character. |
|
464 |
||
465 |
A single tilde character can be sent as ~~ or by following the tilde by a |
|
466 |
character other than those described below. The escape character must |
|
467 |
always follow a newline to be interpreted as special. The escape charac- |
|
468 |
ter can be changed in configuration files using the EscapeChar configura- |
|
469 |
tion directive or on the command line by the -e option. |
|
470 |
||
471 |
The supported escapes (assuming the default `~') are: |
|
472 |
||
473 |
~. Disconnect.
|
|
474 |
||
475 |
~^Z Background ssh.
|
|
476 |
||
477 |
~# List forwarded connections.
|
|
478 |
||
479 |
~& Background ssh at logout when waiting for forwarded connection /
|
|
480 |
X11 sessions to terminate.
|
|
481 |
||
482 |
~? Display a list of escape characters.
|
|
483 |
||
484 |
~B Send a BREAK to the remote system (only useful for SSH protocol
|
|
485 |
version 2 and if the peer supports it).
|
|
486 |
||
487 |
~C Open command line. Currently this allows the addition of port
|
|
488 |
forwardings using the -L and -R options (see above). It also al-
|
|
489 |
lows the cancellation of existing remote port-forwardings using
|
|
490 |
-KR hostport. !command allows the user to execute a local com-
|
|
491 |
mand if the PermitLocalCommand option is enabled in
|
|
492 |
ssh_config(5). Basic help is available, using the -h option.
|
|
493 |
||
494 |
~R Request rekeying of the connection (only useful for SSH protocol
|
|
495 |
version 2 and if the peer supports it).
|
|
496 |
||
497 |
TCP FORWARDING
|
|
498 |
Forwarding of arbitrary TCP connections over the secure channel can be
|
|
499 |
specified either on the command line or in a configuration file. One
|
|
500 |
possible application of TCP forwarding is a secure connection to a mail
|
|
501 |
server; another is going through firewalls.
|
|
502 |
||
503 |
In the example below, we look at encrypting communication between an IRC
|
|
504 |
client and server, even though the IRC server does not directly support
|
|
505 |
encrypted communications. This works as follows: the user connects to
|
|
506 |
the remote host using ssh, specifying a port to be used to forward con-
|
|
507 |
nections to the remote server. After that it is possible to start the
|
|
508 |
service which is to be encrypted on the client machine, connecting to the
|
|
509 |
same local port, and ssh will encrypt and forward the connection.
|
|
510 |
||
511 |
The following example tunnels an IRC session from client machine
|
|
512 |
``127.0.0.1'' (localhost) to remote server ``server.example.com'':
|
|
513 |
||
514 |
$ ssh -f -L 1234:localhost:6667 server.example.com sleep 10
|
|
515 |
$ irc -c '#users' -p 1234 pinky 127.0.0.1 |
|
516 |
||
517 |
This tunnels a connection to IRC server ``server.example.com'', joining
|
|
518 |
channel ``#users'', nickname ``pinky'', using port 1234. It doesn't mat- |
|
519 |
ter which port is used, as long as it's greater than 1023 (remember, only |
|
520 |
root can open sockets on privileged ports) and doesn't conflict with any |
|
521 |
ports already in use. The connection is forwarded to port 6667 on the |
|
522 |
remote server, since that's the standard port for IRC services. |
|
523 |
||
524 |
The -f option backgrounds ssh and the remote command ``sleep 10'' is
|
|
525 |
specified to allow an amount of time (10 seconds, in the example) to
|
|
526 |
start the service which is to be tunnelled. If no connections are made
|
|
527 |
within the time specified, ssh will exit.
|
|
528 |
||
529 |
X11 FORWARDING
|
|
530 |
If the ForwardX11 variable is set to ``yes'' (or see the description of
|
|
531 |
the -X, -x, and -Y options above) and the user is using X11 (the DISPLAY
|
|
532 |
environment variable is set), the connection to the X11 display is auto-
|
|
533 |
matically forwarded to the remote side in such a way that any X11 pro-
|
|
534 |
grams started from the shell (or command) will go through the encrypted
|
|
535 |
channel, and the connection to the real X server will be made from the
|
|
536 |
local machine. The user should not manually set DISPLAY. Forwarding of
|
|
537 |
X11 connections can be configured on the command line or in configuration
|
|
538 |
files.
|
|
539 |
||
540 |
The DISPLAY value set by ssh will point to the server machine, but with a
|
|
541 |
display number greater than zero. This is normal, and happens because
|
|
542 |
ssh creates a ``proxy'' X server on the server machine for forwarding the
|
|
543 |
connections over the encrypted channel.
|
|
544 |
||
545 |
ssh will also automatically set up Xauthority data on the server machine.
|
|
546 |
For this purpose, it will generate a random authorization cookie, store
|
|
547 |
it in Xauthority on the server, and verify that any forwarded connections
|
|
548 |
carry this cookie and replace it by the real cookie when the connection
|
|
549 |
is opened. The real authentication cookie is never sent to the server
|
|
550 |
machine (and no cookies are sent in the plain).
|
|
551 |
||
552 |
If the ForwardAgent variable is set to ``yes'' (or see the description of
|
|
553 |
the -A and -a options above) and the user is using an authentication
|
|
554 |
agent, the connection to the agent is automatically forwarded to the re-
|
|
555 |
mote side.
|
|
556 |
||
557 |
VERIFYING HOST KEYS
|
|
558 |
When connecting to a server for the first time, a fingerprint of the
|
|
559 |
server's public key is presented to the user (unless the option |
|
560 |
StrictHostKeyChecking has been disabled). Fingerprints can be determined |
|
561 |
using ssh-keygen(1): |
|
562 |
||
563 |
$ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key |
|
564 |
||
565 |
If the fingerprint is already known, it can be matched and verified, and |
|
566 |
the key can be accepted. If the fingerprint is unknown, an alternative |
|
567 |
method of verification is available: SSH fingerprints verified by DNS. |
|
568 |
An additional resource record (RR), SSHFP, is added to a zonefile and the |
|
569 |
connecting client is able to match the fingerprint with that of the key |
|
570 |
presented. |
|
571 |
||
572 |
In this example, we are connecting a client to a server, |
|
573 |
``host.example.com''. The SSHFP resource records should first be added |
|
574 |
to the zonefile for host.example.com: |
|
575 |
||
576 |
$ ssh-keygen -f /etc/ssh/ssh_host_rsa_key.pub -r host.example.com. |
|
577 |
$ ssh-keygen -f /etc/ssh/ssh_host_dsa_key.pub -r host.example.com. |
|
578 |
||
579 |
The output lines will have to be added to the zonefile. To check that |
|
580 |
the zone is answering fingerprint queries: |
|
581 |
||
582 |
$ dig -t SSHFP host.example.com |
|
583 |
||
584 |
Finally the client connects: |
|
585 |
||
586 |
$ ssh -o "VerifyHostKeyDNS ask" host.example.com |
|
587 |
[...] |
|
588 |
Matching host key fingerprint found in DNS. |
|
589 |
Are you sure you want to continue connecting (yes/no)? |
|
590 |
||
591 |
See the VerifyHostKeyDNS option in ssh_config(5) for more information. |
|
592 |
||
593 |
SSH-BASED VIRTUAL PRIVATE NETWORKS |
|
594 |
ssh contains support for Virtual Private Network (VPN) tunnelling using |
|
595 |
the tun(4) network pseudo-device, allowing two networks to be joined se- |
|
596 |
curely. The sshd_config(5) configuration option PermitTunnel controls |
|
597 |
whether the server supports this, and at what level (layer 2 or 3 traf- |
|
598 |
fic). |
|
599 |
||
600 |
The following example would connect client network 10.0.50.0/24 with re- |
|
601 |
mote network 10.0.99.0/24, provided that the SSH server running on the |
|
602 |
gateway to the remote network, at 192.168.1.15, allows it: |
|
603 |
||
604 |
# ssh -f -w 0:1 192.168.1.15 true |
|
605 |
# ifconfig tun0 10.0.50.1 10.0.99.1 netmask 255.255.255.252 |
|
606 |
||
607 |
Client access may be more finely tuned via the /root/.ssh/authorized_keys |
|
608 |
file (see below) and the PermitRootLogin server option. The following |
|
609 |
entry would permit connections on the first tun(4) device from user |
|
610 |
``jane'' and on the second device from user ``john'', if PermitRootLogin |
|
611 |
is set to ``forced-commands-only'': |
|
612 |
||
613 |
tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane |
|
614 |
tunnel="2",command="sh /etc/netstart tun1" ssh-rsa ... john |
|
615 |
||
616 |
Since a SSH-based setup entails a fair amount of overhead, it may be more |
|
617 |
suited to temporary setups, such as for wireless VPNs. More permanent |
|
618 |
VPNs are better provided by tools such as ipsecctl(8) and isakmpd(8). |
|
619 |
||
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
620 |
ENVIRONMENT
|
621 |
ssh will normally set the following environment variables: |
|
622 |
||
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
623 |
DISPLAY The DISPLAY variable indicates the location of the |
624 |
X11 server. It is automatically set by ssh to |
|
625 |
point to a value of the form ``hostname:n'', where |
|
626 |
``hostname'' indicates the host where the shell |
|
627 |
runs, and `n' is an integer >= 1. ssh uses this |
|
628 |
special value to forward X11 connections over the
|
|
629 |
secure channel. The user should normally not set
|
|
630 |
DISPLAY explicitly, as that will render the X11
|
|
631 |
connection insecure (and will require the user to
|
|
632 |
manually copy any required authorization cookies).
|
|
633 |
||
634 |
HOME Set to the path of the user's home directory. |
|
635 |
||
636 |
LOGNAME Synonym for USER; set for compatibility with sys- |
|
637 |
tems that use this variable. |
|
638 |
||
639 |
MAIL Set to the path of the user's mailbox. |
|
640 |
||
641 |
PATH Set to the default PATH, as specified when compil-
|
|
642 |
ing ssh.
|
|
643 |
||
644 |
SSH_ASKPASS If ssh needs a passphrase, it will read the
|
|
645 |
passphrase from the current terminal if it was run
|
|
646 |
from a terminal. If ssh does not have a terminal
|
|
647 |
associated with it but DISPLAY and SSH_ASKPASS are
|
|
648 |
set, it will execute the program specified by
|
|
649 |
SSH_ASKPASS and open an X11 window to read the
|
|
650 |
passphrase. This is particularly useful when call-
|
|
651 |
ing ssh from a .xsession or related script. (Note
|
|
652 |
that on some machines it may be necessary to redi-
|
|
653 |
rect the input from /dev/null to make this work.)
|
|
654 |
||
655 |
SSH_AUTH_SOCK Identifies the path of a UNIX-domain socket used to
|
|
656 |
communicate with the agent.
|
|
657 |
||
658 |
SSH_CONNECTION Identifies the client and server ends of the con-
|
|
659 |
nection. The variable contains four space-separat-
|
|
660 |
ed values: client IP address, client port number,
|
|
661 |
server IP address, and server port number.
|
|
662 |
||
663 |
SSH_ORIGINAL_COMMAND This variable contains the original command line if
|
|
664 |
a forced command is executed. It can be used to
|
|
665 |
extract the original arguments.
|
|
666 |
||
667 |
SSH_TTY This is set to the name of the tty (path to the de-
|
|
668 |
vice) associated with the current shell or command.
|
|
669 |
If the current session has no tty, this variable is
|
|
670 |
not set.
|
|
671 |
||
672 |
TZ This variable is set to indicate the present time
|
|
673 |
zone if it was set when the daemon was started
|
|
674 |
(i.e., the daemon passes the value on to new con-
|
|
675 |
nections).
|
|
676 |
||
677 |
USER Set to the name of the user logging in.
|
|
678 |
||
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
679 |
Additionally, ssh reads ~/.ssh/environment, and adds lines of the format
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
680 |
``VARNAME=value'' to the environment if the file exists and users are al-
|
681 |
lowed to change their environment. For more information, see the
|
|
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
682 |
PermitUserEnvironment option in sshd_config(5).
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
683 |
|
684 |
FILES
|
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
685 |
~/.rhosts
|
686 |
This file is used for host-based authentication (see above). On
|
|
687 |
some machines this file may need to be world-readable if the us-
|
|
688 |
er's home directory is on an NFS partition, because sshd(8) reads |
|
689 |
it as root. Additionally, this file must be owned by the user, |
|
690 |
and must not have write permissions for anyone else. The recom- |
|
691 |
mended permission for most machines is read/write for the user, |
|
692 |
and not accessible by others. |
|
693 |
||
694 |
~/.shosts |
|
695 |
This file is used in exactly the same way as .rhosts, but allows |
|
696 |
host-based authentication without permitting login with |
|
697 |
rlogin/rsh. |
|
698 |
||
699 |
~/.ssh/authorized_keys |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
700 |
Lists the public keys (RSA/DSA) that can be used for logging in |
701 |
as this user. The format of this file is described in the |
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
702 |
sshd(8) manual page. This file is not highly sensitive, but the |
703 |
recommended permissions are read/write for the user, and not ac- |
|
704 |
cessible by others. |
|
705 |
||
1.1.3
by Colin Watson
Import upstream version 4.2p1 |
706 |
~/.ssh/config |
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
707 |
This is the per-user configuration file. The file format and |
1.1.1
by Colin Watson
Import upstream version 3.9p1 |
708 |
configuration options are described in ssh_config(5). Because of |
709 |
the potential for abuse, this file must have strict permissions: |
|
710 |
read/write for the user, and not accessible by others. |
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
711 |
|
712 |
~/.ssh/environment |
|
713 |
Contains additional definitions for environment variables; see |
|
714 |
ENVIRONMENT, above. |
|
715 |
||
716 |
~/.ssh/identity |
|
717 |
~/.ssh/id_dsa |
|
718 |
~/.ssh/id_rsa |
|
719 |
Contains the private key for authentication. These files contain |
|
720 |
sensitive data and should be readable by the user but not acces- |
|
721 |
sible by others (read/write/execute). ssh will simply ignore a |
|
722 |
private key file if it is accessible by others. It is possible |
|
723 |
to specify a passphrase when generating the key which will be |
|
724 |
used to encrypt the sensitive part of this file using 3DES. |
|
725 |
||
726 |
~/.ssh/identity.pub |
|
727 |
~/.ssh/id_dsa.pub |
|
728 |
~/.ssh/id_rsa.pub |
|
729 |
Contains the public key for authentication. These files are not |
|
730 |
sensitive and can (but need not) be readable by anyone. |
|
731 |
||
732 |
~/.ssh/known_hosts |
|
733 |
Contains a list of host keys for all hosts the user has logged |
|
734 |
into that are not already in the systemwide list of known host |
|
735 |
keys. See sshd(8) for further details of the format of this |
|
736 |
file. |
|
737 |
||
738 |
~/.ssh/rc |
|
739 |
Commands in this file are executed by ssh when the user logs in, |
|
740 |
just before the user's shell (or command) is started. See the |
|
741 |
sshd(8) manual page for more information.
|
|
742 |
||
743 |
/etc/hosts.equiv
|
|
744 |
This file is for host-based authentication (see above). It
|
|
745 |
should only be writable by root.
|
|
746 |
||
747 |
/etc/shosts.equiv
|
|
748 |
This file is used in exactly the same way as hosts.equiv, but al-
|
|
749 |
lows host-based authentication without permitting login with
|
|
750 |
rlogin/rsh.
|
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
751 |
|
752 |
/etc/ssh/ssh_config
|
|
753 |
Systemwide configuration file. The file format and configuration
|
|
754 |
options are described in ssh_config(5).
|
|
755 |
||
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
756 |
/etc/ssh/ssh_host_key
|
757 |
/etc/ssh/ssh_host_dsa_key
|
|
758 |
/etc/ssh/ssh_host_rsa_key
|
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
759 |
These three files contain the private parts of the host keys and
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
760 |
are used for host-based authentication. If protocol version 1 is
|
761 |
used, ssh must be setuid root, since the host key is readable on-
|
|
762 |
ly by root. For protocol version 2, ssh uses ssh-keysign(8) to
|
|
763 |
access the host keys, eliminating the requirement that ssh be se-
|
|
764 |
tuid root when host-based authentication is used. By default ssh
|
|
765 |
is not setuid root.
|
|
766 |
||
767 |
/etc/ssh/ssh_known_hosts
|
|
768 |
Systemwide list of known host keys. This file should be prepared
|
|
769 |
by the system administrator to contain the public host keys of
|
|
770 |
all machines in the organization. It should be world-readable.
|
|
771 |
See sshd(8) for further details of the format of this file.
|
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
772 |
|
773 |
/etc/ssh/sshrc
|
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
774 |
Commands in this file are executed by ssh when the user logs in,
|
775 |
just before the user's shell (or command) is started. See the |
|
776 |
sshd(8) manual page for more information. |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
777 |
|
778 |
SEE ALSO |
|
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
779 |
scp(1), sftp(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), ssh-keyscan(1), |
780 |
tun(4), hosts.equiv(5), ssh_config(5), ssh-keysign(8), sshd(8) |
|
1
by Noah Meyerhans
Import upstream version 3.8.1p1 |
781 |
|
782 |
T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne, and S. Lehtinen, SSH |
|
783 |
Protocol Architecture, draft-ietf-secsh-architecture-12.txt, January |
|
784 |
2002, work in progress material. |
|
785 |
||
786 |
AUTHORS
|
|
787 |
OpenSSH is a derivative of the original and free ssh 1.2.12 release by |
|
788 |
Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo |
|
789 |
de Raadt and Dug Song removed many bugs, re-added newer features and |
|
790 |
created OpenSSH. Markus Friedl contributed the support for SSH protocol |
|
791 |
versions 1.5 and 2.0. |
|
792 |
||
1.6.1
by Colin Watson
Import upstream version 4.3p2 |
793 |
OpenBSD 3.9 September 25, 1999 12 |