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