2e082dfe |
1 | This file, INSTALL, is a -*- text -*- file tutorial on how to |
2 | * install userv ipif and udptunnel, |
3 | * configure them to create a VPN tunnel between two hosts or |
4 | networks, or |
5 | * use udptunnel-reconf to create a multi-site VPN. |
6 | |
5edd1887 |
7 | |
5124214b |
8 | See README for details of other available documentation. |
5edd1887 |
9 | |
5edd1887 |
10 | |
5124214b |
11 | BUILD AND INSTALLATION INSTRUCTIONS |
12 | ----------------------------------- |
5edd1887 |
13 | |
5124214b |
14 | 1. Install userv, 1.0.1 or later. This is in Debian GNU/Linux. |
0f91e874 |
15 | |
5124214b |
16 | 2. Make sure your Linux kernel has SLIP and CSLIP compiled in. |
17 | You will need to be using Linux 2.2 (with Unix98-style ptys). |
0f91e874 |
18 | |
2e082dfe |
19 | 3. udptunnel works best if your ssh can do ssh-protocol-level |
20 | keepalives. Currently these are only supported by using a special |
223e990a |
21 | patch, which can be found (for various OpenSSH versions) at |
2e082dfe |
22 | ftp.chiark.greenend.org.uk:/users/ian/openssh+protocolkeepalives. |
223e990a |
23 | Pre-compiled Debian packages are available there too. |
2e082dfe |
24 | |
25 | 4. Obtain a fresh copy of userv-utils, if you haven't already. |
5124214b |
26 | cd to ipif, and run `make' and (as root) `make install'. |
27 | |
28 | After you have done this the software will still not do anything, and |
29 | by default userv ipif will not allow anyone (except root) to create |
30 | network interfaces. |
0f91e874 |
31 | |
5124214b |
32 | The software will probably only work on Linux - in particular, userv |
33 | ipif's service program (service.c) uses Linux-specific ways of |
34 | setting up SLIP interfaces. It might be possible in principle to |
35 | create alternatives for other platforms. |
0f91e874 |
36 | |
5124214b |
37 | `slattach' problem: |
0f91e874 |
38 | |
5124214b |
39 | There is a problem with some versions of `slattach' on Linux. If you |
40 | see a message from it about being unable to open /dev/2 or some such, |
41 | then you need to upgrade or patch your `slattach'. In Debian |
42 | GNU/Linux it's in the `netbase' package, and the fix is in Debian 2.1 |
43 | in 3.16-3 and later; however the bug has regressed, and is known to |
44 | be in Debian 2.2's 3.18-4 and earlier. The relevant Debian bug |
45 | reports are #45515 (now closed) and #45944. A patch to correct |
46 | 3.18-4 is provided here as `slattach.diff', and a fixed binary is |
223e990a |
47 | available from me. |
0f91e874 |
48 | |
0f91e874 |
49 | |
0f91e874 |
50 | |
5124214b |
51 | UDPTUNNEL SETUP TUTORIAL |
52 | ------------------------ |
0f91e874 |
53 | |
0f91e874 |
54 | |
5124214b |
55 | 1. BACKGROUND INFORMATION |
0f91e874 |
56 | |
5124214b |
57 | Firstly, note that userv ipif and udptunnel are extremely flexible, |
58 | as they aim to be `Lego brick' networking components. Many much more |
59 | interesting configurations can be constructed than there is room to |
60 | document here. If you want to do something strange, consult the |
61 | README to locate the appropriate reference documentation. |
0f91e874 |
62 | |
5124214b |
63 | 1.1. About udptunnel |
0f91e874 |
64 | |
5124214b |
65 | udptunnel is point-to-point; you need a separate `invocation' for |
66 | each pair of machines (or networks) you wish to connect. |
0f91e874 |
67 | |
5124214b |
68 | It is `one-shot': it will set up a tunnel and keep it going as long |
69 | as it can, and then exit; if you want a permanent tunnel you must |
70 | arrange to reinvoke udptunnel. |
0f91e874 |
71 | |
5124214b |
72 | It is asymmetric, in that one of the endpoints starts the tunnel, and |
73 | the other sits and waits to be contacted. We'll call the active |
74 | endpoint `alice' and the passive endpoint `bob'. Usually alice |
75 | invokes udptunnel on bob via OpenSSH (`ssh'). |
0f91e874 |
76 | |
5124214b |
77 | udptunnel does not need root privilege to run. However, you do need |
78 | to configure userv ipif to know that the user who will be running |
79 | udptunnel is permitted to use the IP addresses and network ranges |
80 | which will be used. So, though most of the configuration can be done |
81 | as the normal users who will run udptunnel on each end, a small |
82 | amount (editing /etc/userv/ipif-networks) needs to be done as root on |
83 | each end - and the information configured as root needs to match up |
0f91e874 |
84 | |
5124214b |
85 | This tutorial will explain how to do these things. |
0f91e874 |
86 | |
5124214b |
87 | 1.2. About point-to-point tunnelling in general |
0f91e874 |
88 | |
5124214b |
89 | A tunnel is an _additional_ (in the case of udptunnel, encrypted) |
90 | network link between a pair of machines. Packets are encapsulated at |
91 | one end, sent over the real network between them, and decoded again |
92 | at the other end. As with any network connection, it is possible to |
93 | arrange for networks behind the endpoint machines to be able to |
94 | communicate via the tunnel. |
0f91e874 |
95 | |
5124214b |
96 | Each endpoint machine will have at least two network interfaces: |
97 | Firstly, the real `physical' interface through which the encapsulated |
98 | packets will be really sent and received. Secondly, the `virtual' |
99 | interface created by the tunnelling software, which represents its |
100 | end of the (encrypted) tunnel link. The physical and virtual |
101 | interfaces MUST have different addresses. |
0f91e874 |
102 | |
5124214b |
103 | Each endpoint machine may also have additional network interfaces; |
104 | for example, it may be the router for a network which sits behind it, |
105 | which an interface on that network, or it may be the endpoint for |
106 | more than one tunnel. It is OK for several tunnels terminating at |
107 | the same machine to use the same virtual address (provided that the |
108 | tunnels are not `layered' on top of each other but are `in |
109 | parallel'), and it is also OK to use as the virtual tunnel address a |
110 | router's address on a private network which will be sent via the |
111 | tunnel. |
0f91e874 |
112 | |
5124214b |
113 | 1.3. Diagram |
0f91e874 |
114 | |
5124214b |
115 | ____ ______________ ______________ ____ |
116 | __( )__ |ALICE | | BOB| __( )__ |
117 | ,' ` ' `. | _ | Tunnel | _ | ,' ` ' `. |
118 | | alice | | |\\ ,- - - - - - - - - -. //| | | bob | |
119 | `._private _.' | | || | | || | | `._private _.' |
120 | | networks |==+--------'|| | Public | ||`--------+==| networks | |
121 | | | | alice | Network | bob | | | |
122 | `.~ ~.' | virtual +=============+ virtual | `.~ ~.' |
123 | (__,'`.__) |______________|alice bob|______________| (__,'`.__) |
124 | physical physical |
125 | _ |
126 | Key: HOSTNAME +===+ Actual Network |\\ Tunnel |
127 | Descriptive Text ----- Data Flow | ||Endpoint |
128 | host or network number - - - Encrypted Data Flow || |
129 | |
130 | |
2e082dfe |
131 | 2. INFORMATION COLLECTION AND PRELIMINARY SETUP |
5124214b |
132 | |
2e082dfe |
133 | You will need to collect and/or decide upon various information, and |
134 | make sure that your two endpoint systems can talk to each other over |
135 | the public network. |
5124214b |
136 | |
137 | 2.1. Find out, or choose, private network numbers |
138 | |
139 | You need to make sure you know what all of the addresses in the above |
140 | diagram are going to be. |
141 | |
142 | Usually you must choose the private and virtual addresses yourself: |
143 | hosts on the private networks usually won't communicate with the |
144 | global Internet other than through proxies or masquerading firewalls. |
145 | |
146 | You MUST choose from the reserved ranges in RFC1918, which are: |
147 | 172.16.0.0/12 192.168.0.0/16 10.0.0.0/8 |
148 | If you do not do so you'll end up reusing someone else's addresses, |
149 | which can cause lots of hard-to-diagnose and embarrasing problems. |
150 | |
151 | You should CHOOSE RANDOMLY ! This makes sure that when you decide to |
152 | connect your VPN to someone else's VPN, your network allocation |
153 | numbers are unlikely to clash. If you both choose 192.168.0.0/24 |
154 | you'll have to renumber (and will look like fools). |
155 | |
156 | To help with choosing random network numbers from RFC1918 space, the |
157 | author maintains a web page at <http://www.ucam.org/cam-grin/>, which |
158 | can pick network numbers for you. |
159 | |
160 | Additionally, there is a database there - people in Cambridge (in |
161 | England) are encouraged to register their network address usage |
162 | there. Please do not register in the database unless you're likely |
163 | to want to connect your VPN to others already listed. |
164 | |
165 | 2.2. Find out, or choose, public network numbers |
166 | |
167 | These are usually specified by your ISP, either statically or |
168 | dynamically assigned. If the active end (`alice physical') is |
169 | dynamically assigned you can use the `Wait' option (see below) to |
170 | avoid specifying it, but otherwise you will need to have some kind of |
171 | script to find it each time you invoke udptunnel, or use a hostname |
172 | which automatically tracks the source host using dynamic DNS. |
173 | |
174 | In some situations you may find yourself using a `public network' |
175 | which is not actually the public Internet - for example, you may want |
176 | to run one tunnel `through' another, or your `public network' is |
2e082dfe |
177 | actually a `private', but not sufficiently secure, radio LAN. In |
178 | this case you'll have to choose the addresses to use from |
179 | RFC1918-space, as above. |
5124214b |
180 | |
181 | 2.3. Decide which user account(s) on alice and bob you will use |
182 | |
183 | These user accounts will see the plaintext for all network packets |
184 | going over the tunnel and if compromised will be able steal or forge |
185 | tunnel traffic. So, they should be reasonably secure. |
186 | |
187 | Let us assume that the account on alice is called Tbob, and the |
188 | account on bob is called Talice. (NB that your system may not |
189 | correctly handle usernames containing uppercase.) |
190 | |
191 | Each account should be in a group of its own, which will be used for |
192 | the userv ipif access control. |
193 | |
194 | Arrange that Tbob@alice can ssh to Talice@bob without needing a |
195 | passphrase or other user interaction. |
196 | |
197 | (Obviously, if you need to create accounts, edit groups, or change |
198 | the sshd configuratioon, you may need to be root.) |
199 | |
2e082dfe |
200 | 2.4. Decide whether to use `udptunnel-reconf' |
201 | |
202 | There are two ways to set up a tunnel with udptunnel. Either you can |
203 | simply give udptunnel the right command, by putting it in an |
204 | appropriate script and arranging it to be called, or you can have a |
205 | program `udptunnel-reconf' read some configuration files and do it |
206 | for you. |
207 | |
208 | udptunnel-reconf is not as well documented, but its behaviour is |
209 | somewhat more `cooked'. It is especially useful if you need to |
210 | maintain many tunnels as part of an organised, multi-site, VPN. |
211 | |
212 | Using udptunnel directly is somewhat more flexible, and may be easier |
213 | if you only want one tunnel. |
214 | |
215 | |
216 | 3. SETUP INSTRUCTIONS - USING UDPTUNNEL-RECONF |
217 | |
218 | Edit or create the following files, as root: |
219 | /etc/userv/vpn/sites |
220 | /etc/userv/vpn/tunnels |
221 | /etc/userv/vpn/global |
222 | |
223 | Run udptunnel-reconf, as root. This will create: |
224 | /var/lib/userv/vpn/passive-sites |
225 | /var/lib/userv/vpn/active-sites |
226 | /var/lib/userv/vpn/command.<site> |
227 | |
228 | It will also spit out to stdout two things: firstly, a list of |
229 | suggested commands to put in your inittab, and secondly a suggested |
230 | line to put in your /etc/userv/ipif-networks. |
231 | |
232 | Test that your setup is working, by running (one of) the |
233 | /var/lib/userv/vpn/command.<site> file(s) by hand - see section 5. |
234 | If it works, you can put the relevant things in your inittab and say |
235 | `init q'. |
236 | |
237 | To find out what all the configuration settings do, look at |
238 | /usr/local/share/userv/udptunnel-vpn-defaults, which contains the |
239 | default settings and shows where all the hooks are. Consult section |
240 | 4 of this file to understand what the options to udptunnel do. |
241 | |
242 | |
243 | 4. SETUP INSTRUCTIONS - INVOKING UDPTUNNEL DIRECTLY |
244 | |
245 | All of these steps can be done using the appropriate normal user |
246 | accounts, unless otherwise indicated. |
247 | |
248 | 4.1. Configure the private network numbers in /etc/userv/ipif-networks |
5124214b |
249 | |
250 | (This step needs to be done as root.) |
251 | |
252 | On alice, in /etc/userv/ipif-networks, put |
253 | <Tbob-gid>,=<alice-virt-addr>/32, <Tbob-group>, <comment> |
254 | <Tbob-gid>,<bob-virt-addr>/32, <Tbob-group>, <comment> |
255 | and for each of bob's private networks |
256 | <Tbob-gid>,<network>/<prefix-len>, <Tbob-group>, <comment> |
257 | You can leave out the <bob-virt-addr>/32 line if bob's virtual |
258 | address is in one of bob's private networks. |
259 | |
260 | On bob, do the corresponding. In /etc/userv/ipif-networks, put |
261 | <Talice-gid>,=<bob-virt-addr>/32, <Talice-group>, <comment> |
262 | <Talice-gid>,<alice-virt-addr>/32, <Talice-group>, <comment> |
263 | and for each of alice's private networks |
264 | <Talice-gid>,<network>/<prefix-len>, <Talice-group>, <comment> |
265 | Again, you can leave out <alice-virt-addr> if one of the virtual |
266 | networks covers it. |
267 | |
268 | All the specifications in /etc/userv/ipif-networks must be numerical |
269 | addresses - hostnames are not allowed. Also, the /32 indicating a |
270 | specific host cannot be omitted. |
271 | |
272 | Note the use of `=' for each host's own virtual address, which |
273 | indicates to userv ipif that it's OK for that gid to create a local |
274 | interface with that address, but the address may not be assigned to a |
275 | remote host or route. |
276 | |
2e082dfe |
277 | 4.2. Construct the udptunnel invocation (on alice) |
5124214b |
278 | |
279 | udptunnel has a long and complicated command line, rather than a |
280 | configuration file. The best way to deal with this is to create a |
281 | shell script which runs udptunnel with the right options. This |
282 | script will live on alice in ~Tbob, and be run by Tbob. Let us call |
283 | it `udptunnel-invoke-bob'. |
284 | |
285 | For the most basic setup, it should look something like this: |
286 | |
287 | #!/bin/sh |
288 | set -e |
289 | set -x |
290 | |
291 | udptunnel \ |
292 | -e nonce -e timestamp/10/30 \ |
293 | -e pkcs5/8 -e blowfish-cbcmac/128 -e blowfish-cbc/128 \ |
294 | <alice-physical-hostname>,Any \ |
295 | <bob-physical-hostname>,Command \ |
296 | <alice-virtual>,<bob-virtual>,1000,cslip \ |
297 | 30,130,1800 \ |
298 | <bob-private-nets> <alice-private-nets> \ |
299 | ssh -o 'BatchMode yes' \ |
300 | -v <Talice>@<bob-physical-hostname> \ |
301 | udptunnel |
302 | |
303 | You have to fill in the right values for things in angle brackets. |
304 | (See also section 6. for a moderately complex example, below.) |
305 | |
2e082dfe |
306 | 4.4.1. Syntax of <alice-private-nets> and <bob-private-nets> |
5124214b |
307 | |
308 | These arguments to udptunnel are the network address ranges at each |
309 | end which are to be connected via the tunnel. Let us consider just |
310 | <alice-private-nets>; <bob-private-nets> is just the same, but for |
311 | bob's end. |
312 | |
313 | <alice-private-nets> is a comma-separated list of networks specified |
314 | as <network>/<prefix-len>. The network address must be numerical, |
315 | and the prefix length must always be specified. |
316 | |
317 | If there are no private networks `behind' alice, ie the tunnel is |
318 | just to connect alice to bob and things at bob's end, then specify |
319 | `-' for <alice-private-nets>. |
320 | |
2e082dfe |
321 | 4.4.2. IP masquerading (NAT) at alice's end |
5124214b |
322 | |
323 | If alice is behind a masquerading (NAT) firewall, you can still get |
324 | it to work. You need to add an option `-m' before the other |
325 | arguments. This will make udptunnel on alice tell udptunnel on bob |
326 | to wait for alice's first encapsulated packet before deciding what |
327 | alice's physcial address and port number are, as seen by bob. That |
328 | way alice doesn't need to know what port number the NAT proxy will |
329 | use. |
330 | |
2e082dfe |
331 | 4.4.3. Using fixed UDP port numbers (eg to make firewally happy) |
5124214b |
332 | |
333 | If alice is behind a firewall which will not allow incoming UDP to |
334 | arbitrary ports, even when sent in reply to packets of alice's, you |
335 | have to arrange for alice to use a fixed port number. Change |
336 | <alice-physical-hostname>,Any \ |
337 | to |
338 | <alice-physical-hostname>,<alice-physical-port> \ |
339 | |
340 | udptunnel will need to be able to bind to the relevant port, so you |
341 | must either (i) choose a port number over 1024, which risks other |
342 | processes on alice accidentally using that port, (ii) run udptunnel |
343 | as root on alice, or (iii) use authbind (authbind is a utility, |
344 | included in Debian, which can allow non-root programs to bind to low |
345 | ports in a controlled way). |
346 | |
347 | If bob is behind such a firewall too, you can replace |
348 | <bob-physical-hostname>,Command \ |
349 | with |
350 | <bob-physical-hostname>,<bob-physical-port> \ |
351 | |
2e082dfe |
352 | 4.4.4. Clock skew and excessive delay |
5124214b |
353 | |
354 | The default configuration given above, which includes this |
355 | -e nonce -e timestamp/10/30 \ |
356 | will not work if there is more than 10s of clock skew between alice |
357 | and bob's system clocks, or if the lag in either direction is more |
358 | than 30s. It is best if your systems run with synchronised clocks |
359 | (you can run NTP over the tunnel if necessary) and don't have such |
360 | bad lag, of course. |
361 | |
362 | However, you can increase these parameters if you really want. To |
363 | increase the tolerance to clock skew to some amount, make sure that |
364 | both numbers are at least the amount of clock skew you're willing to |
365 | tolerate. To increase the tolerance to delay it's only necessary to |
366 | increase the second number. |
367 | |
368 | Warning: if you increase these numbers too much there is a risk that |
369 | packets delayed or repeated by an attacker will be treated as genuine |
370 | and cause communication or security problems. I would not recommend |
371 | using a value more than 120 (2 minutes). |
372 | |
373 | If you really can't get reasonable clock synch at all, you can use |
374 | sequence number replay detection instead of clock-based replay |
375 | detection. Replace |
376 | -e nonce -e timestamp/10/30 \ |
377 | with |
378 | -e sequence \ |
379 | |
2e082dfe |
380 | 4.4.5. Other things to tweak (it's usually safe to ignore this part) |
5124214b |
381 | |
382 | Do not mess with the `-e' parameters and arguments except as |
383 | explained above, unless you are a cryptographer. |
384 | |
385 | 30,130,1800 are timeouts which control the `dead tunnel detection'. |
386 | The first is the keepalive interval: when one end hasn't sent |
387 | anything for that many seconds, it will send an empty keepalive |
388 | packet. The second is the dead tunnel timeout: when one end hasn't |
389 | received anything for that many seconds, it assumes the tunnel is |
390 | dead and dies (the other end will then usually die shortly if it |
391 | hasn't already). The third is the status reporting interval - at |
392 | intervals of that many seconds each end will report (to udptunnel's |
393 | stdout) that the tunnel is still open and give some statistics; these |
394 | diagnostics also prevent the controlling ssh connection's entry in |
395 | masquerading and firewall tables from timing out. |
396 | |
397 | 1000 (in ...,...,1000,cslip) is the MTU - the maximum size of packet |
398 | which will be sent through the tunnel. It is best if this number is |
399 | a certain amount smaller than the path MTU over the physical network, |
400 | so that encapsulated packets do not get fragmented. (Each packet |
401 | will be increased in size by 24 bytes + the size of a UDP and IP |
402 | header + the effects of SLIP duplication of certain bytes.) |
403 | |
2e082dfe |
404 | 4.5. Testing your script |
405 | |
406 | After you've written your script, you should run it to see if it |
407 | works. See section 5 for details. |
408 | |
409 | 4.6. Configure the tunnel to run automatically |
410 | |
411 | Now that the tunnel works if you invoke it by hand, it is time to |
412 | arrange to run it automatically. |
413 | |
414 | If you want the tunnel to run over a dialup link only when the dialup |
415 | link is up, then I'm afraid you'll have to arrange to start and kill |
416 | it yourself, probably. I haven't set up such a configuration. More |
417 | information about this for this document, if you manage to do it, |
418 | would be good. |
419 | |
420 | So, I shall assume that you want the tunnel to be up all of the time |
421 | (or at least, as much as possible). The best way to do this is to |
422 | run it from `init', by setting it up in inittab. |
423 | |
424 | For example, you could put something like this in your inittab: |
425 | t0:23:respawn:su Tbob -c ./udptunnel-invoke-bob 2>&1 | logger -p local2.info -t tunnel-bob |
426 | (Note that if you have more than one tunnel the `id' field, at the |
427 | start of the inittab line, must be different for each one.) |
428 | |
429 | This would use `su' to become bob and run the actual tunnelling |
430 | software, and arrange for the diagnostic output to be sent to syslog |
431 | with facility `local2' and priority `info', tagged with `tunnel-bob'. |
432 | With an appropriate line in /etc/syslog.conf, such as |
433 | local2.* /var/log/local2-all.log |
434 | (remember that you have to use tabs in syslog.conf) this will |
435 | produce, in /var/log/local2-all.log, all the diagnostics, including |
436 | reassuring messages like this: |
437 | Sep 18 00:27:48 alice tunnel-bob: udptunnel-forwarder: alice: tunnel still open: received 5262 packets, 5262 bytes |
438 | Sep 18 00:28:44 alice tunnel-bob: udptunnel-forwarder: bob: tunnel still open: received 5280 packets, 5280 bytes |
439 | |
5124214b |
440 | |
2e082dfe |
441 | 5. TESTING YOUR UDPTUNNEL INVOCATION SCRIPT |
5124214b |
442 | |
2e082dfe |
443 | 5.1. Invocation |
5124214b |
444 | |
445 | Log into alice as Tbob, and run ./udptunnel-invoke-bob. |
446 | A great deal of diagnostic output will ensue. |
447 | |
448 | If all is well you will see two messages looking something like this |
449 | udptunnel-forwarder: bob: tunnel open with peer 127.0.0.3:76543 |
450 | udptunnel-forwarder: alice: tunnel open |
2e082dfe |
451 | and the session will just sit there. This means it thinks it's |
452 | working; go on to section 5.2. |
5124214b |
453 | |
454 | If it didn't say that, here are some debugging tips: |
455 | |
456 | * If it just sits there for a minute or two and then udptunnel times |
457 | out, the physical packets aren't getting back and forth. Use |
458 | tcpdump, check your firewall and routing (as below), and consult the |
459 | sections above about NAT and firewalls. |
460 | |
461 | * If it bombed out, look for an error message in the diagnostics. |
462 | There will be lots of `subprocess somethingorother exited with |
463 | nonzero exit status 47', `no details received from remote' and the |
464 | like, but these are probably not the ones you want to look at, |
465 | because they're usually just consequences of some other failure. |
466 | |
467 | Permission denied. |
468 | udptunnel - alice: fatal error: remote command failed (code ...) |
469 | Tbob had trouble ssh'ing to Talice@bob. Check that the ssh |
470 | configuration is set up, and test it separately. |
471 | |
472 | userv-ipif service: access denied for ...., .... |
473 | udptunnel - alice: subprocess local command failed with code 2048 |
474 | The arguments to udptunnel don't correspond to |
475 | /etc/userv/ipif-networks on alice. Either the arguments to |
476 | udptunnel or the ipif-networks file is wrong. (Or, if the message |
477 | about `local command failed' mentions bob, look on bob.) |
478 | |
479 | udptunnel - alice: subprocess forwarder failed with code 14 |
480 | The tunnel timed out - no packets were successfully received for |
481 | 130 seconds. See 2.4.5 above for details of the timeout |
482 | parameters. (NB, applies to `code 14' only.) |
483 | |
484 | usage errors from udptunnel or ssh, or sh: ...: unknown command |
485 | Perhaps you dropped a \ from the udptunnel-invoke-bob script ? |
486 | |
487 | udptunnel not found, udptunnel-forwarder not found |
488 | Check that the PATH includes /usr/local/bin. Noninteractive `ssh' |
489 | invocations (ie, ones with a command specified) often have a |
490 | different PATH. |
491 | |
492 | slattach cannot open /dev/2 (or similar messages) |
493 | Your slattach is buggy. See under `slattach problem' in the build |
494 | and installation instructions, above. |
495 | |
496 | slattach cannot change line discipline (or some other weird message) |
497 | Check whether your kernel is compiled with SLIP and/or CSLIP |
498 | support. |
499 | |
500 | * Other messages: |
501 | |
502 | udptunnel-forwarder: alice: bad packet: blowfish-cbcmac: verify failed |
503 | This can be caused by actual packet corruption on the physical |
504 | network (or even by an actual hostile attack), but when using |
505 | fixed port numbers these messages are common after the tunnel has |
506 | died and been restarted: they correspond to packets from the |
507 | previous invocation (which is usung different keys) being rejected |
508 | because their checksums don't match. In this case they should go |
509 | away in a minute or two. |
510 | |
2e082dfe |
511 | 5.2. Testing, once the tunnel claims to be working |
5124214b |
512 | |
513 | In another session on alice, you should be able to ping bob's virtual |
514 | interface. If this works, test pinging between hosts on the private |
515 | networks behind alice and bob. If all is well, go onto step 4. |
516 | |
517 | If not, here are some troubleshooting hints: |
518 | |
519 | * Use numerical addresses when testing. This eliminates DNS problems |
520 | from your test strategy. |
521 | |
522 | * Use `ifconfig' and `route -n' on alice and bob to check that the |
523 | interfaces and routes all look right. The tunnel will show up as a |
524 | `sl<n>' for some <n>. |
525 | |
526 | * Use `tcpdump -n -i <interface>' to watch the traffic go across some |
527 | interface, to try to figure out where the traffic is going. Look |
528 | both for the private traffic before it goes into the tunnel, and the |
529 | physical traffic, to try to find out where it disappears. The |
530 | diagnostics will tell you which physical ports it's using, something |
531 | like this: |
532 | udptunnel - alice: debug: using remote Wait,Wait local 131.111.232.108,1422 |
533 | udptunnel - bob: debug: using remote 131.111.232.108,1422 local 195.224.38.6,2413 |
534 | |
535 | * alice and bob can see each other but the private networks can't ? |
536 | Make sure alice and bob both have IP forwarding enabled. |
0f91e874 |
537 | |
5124214b |
538 | * Check your firewalls, if you have them. It's most helpful if your |
539 | firewall configuration arranges to log rejected packets - without |
540 | that, they can be a complete pain to debug. |
0f91e874 |
541 | |
0f91e874 |
542 | |
2e082dfe |
543 | 6. DNS, firewall, mail, etc. |
0f91e874 |
544 | |
2e082dfe |
545 | When you have IP level connectivity between your two networks, you |
546 | must also arrange for: |
0f91e874 |
547 | |
5124214b |
548 | * An appropriate firewall on each tunnel endpoint (to stop attacks |
549 | from one network to another) and also at all the borders of each |
550 | network (to stop traffic that is going to, or looks like it came |
551 | from, the private networks). |
0f91e874 |
552 | |
5124214b |
553 | * DNS configuration so that hosts on both sides of the tunnel can see |
554 | each other's names, addresses and other information. |
0f91e874 |
555 | |
5124214b |
556 | * Mail, news and other application protocols may need to be |
557 | configured to use the private tunnel connectivity, rather than |
558 | treating the other private network's names as being `elsewhere' and |
559 | using unencrypted connectivity via the global Internet. |
0f91e874 |
560 | |
5124214b |
561 | How to do these things is beyond the scope of this document. |
0f91e874 |
562 | |
0f91e874 |
563 | |
2e082dfe |
564 | 7. Example |
5124214b |
565 | |
566 | This example is the tunnel between chiark and Relativity. I'll quote |
567 | it and explain the details, below. See also the comment at the top of |
568 | udptunnel. |
569 | |
570 | authbind udptunnel \ |
571 | -m \ |
572 | -e nonce -e timestamp/10/30 -e pkcs5/8 \ |
573 | -e blowfish-cbcmac/128 -e blowfish-cbc/128 \ |
574 | davenant-external,410 \ |
575 | chiark-public,Command \ |
576 | 172.31.80.6,172.31.80.9,1000,cslip \ |
577 | 30,120,1800 \ |
578 | - 172.18.45.0/24 \ |
579 | ssh -o 'ForwardAgent no' -o 'ForwardX11 no' \ |
580 | -o 'BatchMode yes' \ |
581 | -i ~ian/.ssh/identity -l ian \ |
582 | -v chiark.greenend.org.uk \ |
583 | udptunnel |
584 | |
585 | Because at Relativity the tunnel endpoint has to not be our firewall, |
586 | because the firewall is a 386SX/16 and so not powerful enough, |
587 | Relativity practically has to be the active partner in any tunnels it |
588 | is involved in. This also necessitates the use of the `-m' option and |
589 | various other things. |
590 | |
591 | Exposition of the example udptunnel invocation: |
592 | |
593 | > authbind udptunnel \ |
594 | |
595 | `authbind' is used because at Relativity the tunnel endpoint address |
596 | has to be on a fixed port because our tunnel endpoint is not on the |
597 | firewall system (if it's not on a fixed port we can't write a good |
598 | firewall rule to let it through). |
599 | |
600 | The port we are using is port 410, a low port to prevent other |
601 | processes `stealing' it, so root privilege or authbind is needed. |
602 | |
603 | > -m \ |
604 | |
605 | -m tells this invocation of udptunnel that its endpoint address and |
606 | port (for encapsulated packets) are going to be NATted before the far |
607 | end sees them. The effect is that instead of supplying this |
608 | information to the far end, the far end is told to `wait and see'. |
609 | |
610 | This should not usually be used in other circumstances. (For full |
611 | details see the comment at the top of udptunnel.) |
612 | |
613 | > -e nonce -e timestamp/10/30 -e pkcs5/8 \ |
614 | > -e blowfish-cbcmac/128 -e blowfish-cbc/128 \ |
615 | |
616 | This is the crypto configuration. |
617 | |
618 | > davenant-external,410 \ |
619 | |
620 | This is the local physical address and port. davenant is the tunnel |
621 | endpoint, and davenant-external is its public address (we run two |
622 | networks on the wire at Relativity, an internal one and a public |
623 | one). |
624 | |
625 | > chiark-public,Command \ |
626 | |
627 | This is the physical remote address and port. `Command' means find |
628 | out the remote physical address or port by having udptunnel at the |
629 | far end print its address and port when they have been allocated. |
630 | |
631 | Another possibility here is to use a fixed remote port number. |
632 | |
633 | The DNS at GR is configured so that just `chiark' means chiark via |
634 | the tunnel, so we have to use chiark-public which means its public |
635 | IP address. |
636 | |
637 | > 172.31.80.6,172.31.80.9,1000,cslip \ |
638 | |
639 | 172.31.80.6 is davenant's virtual address. |
640 | 172.31.80.9 is chiark's virtual address for the Relativity tunnel. |
641 | |
642 | > 30,130,1800 \ |
643 | |
644 | These are the timing parameters. |
645 | |
646 | > - 172.18.45.0/24 \ |
647 | |
648 | No remote virtual networks are reachable via chiark. 172.18.45.0/24 |
649 | is the Relativity house ethernet, which is to be reachable via the |
650 | tunnel from chiark. |
651 | |
652 | > ssh -o 'ForwardAgent no' -o 'ForwardX11 no' \ |
653 | > -o 'BatchMode yes' \ |
654 | > -i ~ian/.ssh/identity -l ian \ |
655 | > -v chiark.greenend.org.uk \ |
656 | > udptunnel |
657 | |
658 | This is the ssh invocation to run udptunnel at the far end. |
659 | |
660 | At Relativity we put the udptunnel invocation in a file and run it |
661 | out of inittab, like this: |
662 | |
663 | t0:235:respawn:/usr/local/sbin/really -u ian /usr/local/sbin/udptunnel-invoke 2>&1 | logger -p local2.info -t tunnel-chiark |
664 | |
665 | |
2e082dfe |
666 | 8. Copyright notice |
5124214b |
667 | |
c07be359 |
668 | Copyright (C) 1999-2000,2003 Ian Jackson |
669 | This file is part of ipif, part of userv-utils |
5124214b |
670 | |
671 | This is free software; you can redistribute it and/or modify it |
672 | under the terms of the GNU General Public License as published by |
673 | the Free Software Foundation; either version 2 of the License, or |
674 | (at your option) any later version. |
675 | |
676 | This program is distributed in the hope that it will be useful, but |
677 | WITHOUT ANY WARRANTY; without even the implied warranty of |
678 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
679 | General Public License for more details. |
680 | |
681 | You should have received a copy of the GNU General Public License |
682 | along with userv-utils; if not, write to the Free Software |
683 | Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
0f91e874 |
684 | |
685 | |
686 | $Id$ |