removed
[ikiwiki.git] / docs / handbook / handbook-openssh.mdwn
CommitLineData
c19defb7 1
2----
3
4
5
6## 10.10 OpenSSH
7
8
9
10***Contributed by Chern Lee. ***
11
12
13
14 **OpenSSH** is a set of network connectivity tools used to access remote machines securely. It can be used as a direct replacement for `rlogin`, `rsh`, `rcp`, and `telnet`. Additionally, any other TCP/IP connections can be tunneled/forwarded securely through SSH. **OpenSSH** encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and other network-level attacks.
15
16
17
18 **OpenSSH** is maintained by the OpenBSD project, and is based upon SSH v1.2.12 with all the recent bug fixes and updates. It is compatible with both SSH protocols 1 and 2.
19
20
21
22### 10.10.1 Advantages of Using OpenSSH
23
24
25
26Normally, when using [telnet(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#telnet&section1) or [rlogin(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=rlogin&section=1), data is sent over the network in an clear, un-encrypted form. Network sniffers anywhere in between the client and server can steal your user/password information or data transferred in your session. **OpenSSH** offers a variety of authentication and encryption methods to prevent this from happening.
27
28
29
30### 10.10.2 Enabling sshd
31
32
33
34Be sure to make the following addition to your `rc.conf` file:
35
36
37
38
39
40 sshd_enable="YES"
41
42
43
44
45
46This will load [sshd(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#sshd&section8&manpath=OpenBSD+3.3), the daemon program for **OpenSSH** , the next time your system initializes. Alternatively, you can simply run directly the **sshd** daemon by typing `rcstart sshd` on the command line.
47
48
49
50### 10.10.3 SSH Client
51
52
53
54The [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh&section1&manpath=OpenBSD+3.3) utility works similarly to [rlogin(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=rlogin&section=1).
55
56
57
58
59
60 # ssh user@example.com
61
62 Host key not found from the list of known hosts.
63
64 Are you sure you want to continue connecting (yes/no)? yes
65
66 Host 'example.com' added to the list of known hosts.
67
68 user@example.com's password: *******
69
70
71
72
73
74The login will continue just as it would have if a session was created using `rlogin` or `telnet`. SSH utilizes a key fingerprint system for verifying the authenticity of the server when the client connects. The user is prompted to enter `yes` only when connecting for the first time. Future attempts to login are all verified against the saved fingerprint key. The SSH client will alert you if the saved fingerprint differs from the received fingerprint on future login attempts. The fingerprints are saved in `~/.ssh/known_hosts`, or `~/.ssh/known_hosts2` for SSH v2 fingerprints.
75
76
77
78By default, **OpenSSH** servers are configured to accept both SSH v1 and SSH v2 connections. The client, however, can choose between the two. Version 2 is known to be more robust and secure than its predecessor.
79
80
81
82The [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh&section1&manpath=OpenBSD+3.3) command can be forced to use either protocol by passing it the `-1` or `-2` argument for v1 and v2, respectively.
83
84
85
86### 10.10.4 Secure Copy
87
88
89
90The [scp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#scp&section1&manpath=OpenBSD+3.3) command works similarly to [rcp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=rcp&section=1); it copies a file to or from a remote machine, except in a secure fashion.
91
92
93
94
95
96 # scp user@example.com:/COPYRIGHT COPYRIGHT
97
98 user@example.com's password: *******
99
100 COPYRIGHT 100% |*****************************| 4735
101
102 00:00
103
104 #
105
106
107
108
109
110Since the fingerprint was already saved for this host in the previous example, it is verified when using [scp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#scp&section1&manpath=OpenBSD+3.3) here.
111
112
113
114The arguments passed to [scp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#scp&section1&manpath=OpenBSD+3.3) are similar to [cp(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=cp&section=1), with the file or files in the first argument, and the destination in the second. Since the file is fetched over the network, through SSH, one or more of the file arguments takes on the form `user@host:<path_to_remote_file>`. The `user@` part is optional. If omitted, it will default to the same username as you are currently logged in as, unless configured otherwise.
115
116
117
118### 10.10.5 Configuration
119
120
121
122The system-wide configuration files for both the **OpenSSH** daemon and client reside within the `/etc/ssh` directory.
123
124
125
126`ssh_config` configures the client settings, while `sshd_config` configures the daemon.
127
128
129
130Additionally, the `sshd_program` (`/usr/sbin/sshd` by default), and `sshd_flags` `rc.conf` options can provide more levels of configuration.
131
132
133
134Each user can have a personal configuration file in `~/.ssh/config`. The file can configure various client options, and can include host-specific options. With the following configuration file, a user could type `ssh shell` which would be equivalent to `ssh -X user@shell.example.com`.
135
136
137
138
139
140 Host shell
141
142 Hostname shell.example.com
143
144 Username user
145
146 Protocol 2
147
148 ForwardX11 yes
149
150
151
152
153
154### 10.10.6 ssh-keygen
155
156
157
158Instead of using passwords, [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen&section1&manpath=OpenBSD+3.3) can be used to generate RSA keys to authenticate a user:
159
160
161
162
163
164 % ssh-keygen -t rsa1
165
166 Initializing random number generator...
167
168 Generating p: .++ (distance 66)
169
170 Generating q: ..............................++ (distance 498)
171
172 Computing the keys...
173
174 Key generation complete.
175
176 Enter file in which to save the key (/home/user/.ssh/identity):
177
178 Enter passphrase:
179
180 Enter the same passphrase again:
181
182 Your identification has been saved in /home/user/.ssh/identity.
183
184 ...
185
186
187
188
189
190[ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen&section1&manpath=OpenBSD+3.3) will create a public and private key pair for use in authentication. The private key is stored in `~/.ssh/identity`, whereas the public key is stored in `~/.ssh/identity.pub`. The public key must be placed in `~/.ssh/authorized_keys` of the remote machine in order for the setup to work.
191
192
193
194This will allow connection to the remote machine based upon RSA authentication instead of passwords.
195
196
197
198 **Note:** The `-t rsa1` option will create RSA keys for use by SSH protocol version 1. If you want to use RSA keys with the SSH protocol version 2, you have to use the command `ssh-keygen -t rsa`.
199
200
201
202If a passphrase is used in [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen&section1&manpath=OpenBSD+3.3), the user will be prompted for a password each time in order to use the private key.
203
204
205
206A SSH protocol version 2 DSA key can be created for the same purpose by using the `ssh-keygen -t dsa` command. This will create a public/private DSA key for use in SSH protocol version 2 sessions only. The public key is stored in `~/.ssh/id_dsa.pub`, while the private key is in `~/.ssh/id_dsa`.
207
208
209
210DSA public keys are also placed in `~/.ssh/authorized_keys` on the remote machine.
211
212
213
214[ssh-agent(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-agent&section1&manpath=OpenBSD+3.3) and [ssh-add(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ssh-add&section=1&manpath=OpenBSD+3.3) are utilities used in managing multiple passworded private keys.
215
216
217
218 **Warning:** The various options and files can be different according to the **OpenSSH** version you have on your system, to avoid problems you should consult the [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen&section1&manpath=OpenBSD+3.3) manual page.
219
220
221
222### 10.10.7 SSH Tunneling
223
224
225
226 **OpenSSH** has the ability to create a tunnel to encapsulate another protocol in an encrypted session.
227
228
229
230The following command tells [ssh(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh&section1&manpath=OpenBSD+3.3) to create a tunnel for **telnet** :
231
232
233
234
235
236 % ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com
237
238 %
239
240
241
242
243
244The `ssh` command is used with the following options:
245
246
247
248`-2`
249
250 :: Forces `ssh` to use version 2 of the protocol. (Do not use if you are working with older SSH servers)
251
252`-N`
253
254 :: Indicates no command, or tunnel only. If omitted, `ssh` would initiate a normal session.
255
256`-f`
257
258 :: Forces `ssh` to run in the background.
259
260`-L`
261
262 :: Indicates a local tunnel in `***localport:remotehost:remoteport***` fashion.
263
264`user@foo.example.com`
265
266 :: The remote SSH server.
267
268
269
270An SSH tunnel works by creating a listen socket on `localhost` on the specified port. It then forwards any connection received on the local host/port via the SSH connection to the specified remote host and port.
271
272
273
274In the example, port `***5023***` on `localhost` is being forwarded to port `***23***` on `localhost` of the remote machine. Since `***23***` is **telnet** , this would create a secure **telnet** session through an SSH tunnel.
275
276
277
278This can be used to wrap any number of insecure TCP protocols such as SMTP, POP3, FTP, etc.
279
280
281
282 **Example 10-1. Using SSH to Create a Secure Tunnel for SMTP**
283
284
285
286
287
288 % ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com
289
290 user@mailserver.example.com's password: *****
291
292 % telnet localhost 5025
293
294 Trying 127.0.0.1...
295
296 Connected to localhost.
297
298 Escape character is '^]'.
299
300 220 mailserver.example.com ESMTP
301
302
303
304
305
306This can be used in conjunction with an [ssh-keygen(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ssh-keygen&section1&manpath=OpenBSD+3.3) and additional user accounts to create a more seamless/hassle-free SSH tunneling environment. Keys can be used in place of typing a password, and the tunnels can be run as a separate user.
307
308
309
310#### 10.10.7.1 Practical SSH Tunneling Examples
311
312
313
314##### 10.10.7.1.1 Secure Access of a POP3 Server
315
316
317
318At work, there is an SSH server that accepts connections from the outside. On the same office network resides a mail server running a POP3 server. The network, or network path between your home and office may or may not be completely trustable. Because of this, you need to check your e-mail in a secure manner. The solution is to create an SSH connection to your office's SSH server, and tunnel through to the mail server.
319
320
321
322
323
324 % ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com
325
326 user@ssh-server.example.com's password: ******
327
328
329
330
331
332When the tunnel is up and running, you can point your mail client to send POP3 requests to `localhost` port 2110. A connection here will be forwarded securely across the tunnel to `mail.example.com`.
333
334
335
336##### 10.10.7.1.2 Bypassing a Draconian Firewall
337
338
339
340Some network administrators impose extremely draconian firewall rules, filtering not only incoming connections, but outgoing connections. You may be only given access to contact remote machines on ports 22 and 80 for SSH and web surfing.
341
342
343
344You may wish to access another (perhaps non-work related) service, such as an Ogg Vorbis server to stream music. If this Ogg Vorbis server is streaming on some other port than 22 or 80, you will not be able to access it.
345
346
347
348The solution is to create an SSH connection to a machine outside of your network's firewall, and use it to tunnel to the Ogg Vorbis server.
349
350
351
352
353
354 % ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org
355
356 user@unfirewalled-system.example.org's password: *******
357
358
359
360
361
362Your streaming client can now be pointed to `localhost` port 8888, which will be forwarded over to `music.example.com` port 8000, successfully evading the firewall.
363
364
365
366----
367
368
369
370
371