+ To find out what all the configuration settings do, look at
+ /usr/local/share/userv/udptunnel-vpn-defaults, which contains the
+ default settings and shows where all the hooks are. Consult section
+ 4 of this file to understand what the options to udptunnel do.
+
+
+4. SETUP INSTRUCTIONS - INVOKING UDPTUNNEL DIRECTLY
+
+ All of these steps can be done using the appropriate normal user
+ accounts, unless otherwise indicated.
+
+4.1. Configure the private network numbers in /etc/userv/ipif-networks
+
+ (This step needs to be done as root.)
+
+ On alice, in /etc/userv/ipif-networks, put
+ <Tbob-gid>,=<alice-virt-addr>/32, <Tbob-group>, <comment>
+ <Tbob-gid>,<bob-virt-addr>/32, <Tbob-group>, <comment>
+ and for each of bob's private networks
+ <Tbob-gid>,<network>/<prefix-len>, <Tbob-group>, <comment>
+ You can leave out the <bob-virt-addr>/32 line if bob's virtual
+ address is in one of bob's private networks.
+
+ On bob, do the corresponding. In /etc/userv/ipif-networks, put
+ <Talice-gid>,=<bob-virt-addr>/32, <Talice-group>, <comment>
+ <Talice-gid>,<alice-virt-addr>/32, <Talice-group>, <comment>
+ and for each of alice's private networks
+ <Talice-gid>,<network>/<prefix-len>, <Talice-group>, <comment>
+ Again, you can leave out <alice-virt-addr> if one of the virtual
+ networks covers it.
+
+ All the specifications in /etc/userv/ipif-networks must be numerical
+ addresses - hostnames are not allowed. Also, the /32 indicating a
+ specific host cannot be omitted.
+
+ Note the use of `=' for each host's own virtual address, which
+ indicates to userv ipif that it's OK for that gid to create a local
+ interface with that address, but the address may not be assigned to a
+ remote host or route.
+
+4.2. Construct the udptunnel invocation (on alice)
+
+ udptunnel has a long and complicated command line, rather than a
+ configuration file. The best way to deal with this is to create a
+ shell script which runs udptunnel with the right options. This
+ script will live on alice in ~Tbob, and be run by Tbob. Let us call
+ it `udptunnel-invoke-bob'.
+
+ For the most basic setup, it should look something like this:
+
+ #!/bin/sh
+ set -e
+ set -x
+
+ udptunnel \
+ -e nonce -e timestamp/10/30 \
+ -e pkcs5/8 -e blowfish-cbcmac/128 -e blowfish-cbc/128 \
+ <alice-physical-hostname>,Any \
+ <bob-physical-hostname>,Command \
+ <alice-virtual>,<bob-virtual>,1000,cslip \
+ 30,130,1800 \
+ <bob-private-nets> <alice-private-nets> \
+ ssh -o 'BatchMode yes' \
+ -v <Talice>@<bob-physical-hostname> \
+ udptunnel
+
+ You have to fill in the right values for things in angle brackets.
+ (See also section 6. for a moderately complex example, below.)
+
+4.4.1. Syntax of <alice-private-nets> and <bob-private-nets>
+
+ These arguments to udptunnel are the network address ranges at each
+ end which are to be connected via the tunnel. Let us consider just
+ <alice-private-nets>; <bob-private-nets> is just the same, but for
+ bob's end.
+
+ <alice-private-nets> is a comma-separated list of networks specified
+ as <network>/<prefix-len>. The network address must be numerical,
+ and the prefix length must always be specified.
+
+ If there are no private networks `behind' alice, ie the tunnel is
+ just to connect alice to bob and things at bob's end, then specify
+ `-' for <alice-private-nets>.
+
+4.4.2. IP masquerading (NAT) at alice's end
+
+ If alice is behind a masquerading (NAT) firewall, you can still get
+ it to work. You need to add an option `-m' before the other
+ arguments. This will make udptunnel on alice tell udptunnel on bob
+ to wait for alice's first encapsulated packet before deciding what
+ alice's physcial address and port number are, as seen by bob. That
+ way alice doesn't need to know what port number the NAT proxy will
+ use.
+
+4.4.3. Using fixed UDP port numbers (eg to make firewally happy)
+
+ If alice is behind a firewall which will not allow incoming UDP to
+ arbitrary ports, even when sent in reply to packets of alice's, you
+ have to arrange for alice to use a fixed port number. Change
+ <alice-physical-hostname>,Any \
+ to
+ <alice-physical-hostname>,<alice-physical-port> \
+
+ udptunnel will need to be able to bind to the relevant port, so you
+ must either (i) choose a port number over 1024, which risks other
+ processes on alice accidentally using that port, (ii) run udptunnel
+ as root on alice, or (iii) use authbind (authbind is a utility,
+ included in Debian, which can allow non-root programs to bind to low
+ ports in a controlled way).
+
+ If bob is behind such a firewall too, you can replace
+ <bob-physical-hostname>,Command \
+ with
+ <bob-physical-hostname>,<bob-physical-port> \
+
+4.4.4. Clock skew and excessive delay
+
+ The default configuration given above, which includes this
+ -e nonce -e timestamp/10/30 \
+ will not work if there is more than 10s of clock skew between alice
+ and bob's system clocks, or if the lag in either direction is more
+ than 30s. It is best if your systems run with synchronised clocks
+ (you can run NTP over the tunnel if necessary) and don't have such
+ bad lag, of course.
+
+ However, you can increase these parameters if you really want. To
+ increase the tolerance to clock skew to some amount, make sure that
+ both numbers are at least the amount of clock skew you're willing to
+ tolerate. To increase the tolerance to delay it's only necessary to
+ increase the second number.
+
+ Warning: if you increase these numbers too much there is a risk that
+ packets delayed or repeated by an attacker will be treated as genuine
+ and cause communication or security problems. I would not recommend
+ using a value more than 120 (2 minutes).
+
+ If you really can't get reasonable clock synch at all, you can use
+ sequence number replay detection instead of clock-based replay
+ detection. Replace
+ -e nonce -e timestamp/10/30 \
+ with
+ -e sequence \
+
+4.4.5. Other things to tweak (it's usually safe to ignore this part)
+
+ Do not mess with the `-e' parameters and arguments except as
+ explained above, unless you are a cryptographer.
+
+ 30,130,1800 are timeouts which control the `dead tunnel detection'.
+ The first is the keepalive interval: when one end hasn't sent
+ anything for that many seconds, it will send an empty keepalive
+ packet. The second is the dead tunnel timeout: when one end hasn't
+ received anything for that many seconds, it assumes the tunnel is
+ dead and dies (the other end will then usually die shortly if it
+ hasn't already). The third is the status reporting interval - at
+ intervals of that many seconds each end will report (to udptunnel's
+ stdout) that the tunnel is still open and give some statistics; these
+ diagnostics also prevent the controlling ssh connection's entry in
+ masquerading and firewall tables from timing out.
+
+ 1000 (in ...,...,1000,cslip) is the MTU - the maximum size of packet
+ which will be sent through the tunnel. It is best if this number is
+ a certain amount smaller than the path MTU over the physical network,
+ so that encapsulated packets do not get fragmented. (Each packet
+ will be increased in size by 24 bytes + the size of a UDP and IP
+ header + the effects of SLIP duplication of certain bytes.)
+
+4.5. Testing your script
+
+ After you've written your script, you should run it to see if it
+ works. See section 5 for details.
+
+4.6. Configure the tunnel to run automatically
+
+ Now that the tunnel works if you invoke it by hand, it is time to
+ arrange to run it automatically.
+
+ If you want the tunnel to run over a dialup link only when the dialup
+ link is up, then I'm afraid you'll have to arrange to start and kill
+ it yourself, probably. I haven't set up such a configuration. More
+ information about this for this document, if you manage to do it,
+ would be good.
+
+ So, I shall assume that you want the tunnel to be up all of the time
+ (or at least, as much as possible). The best way to do this is to
+ run it from `init', by setting it up in inittab.
+
+ For example, you could put something like this in your inittab:
+ t0:23:respawn:su Tbob -c ./udptunnel-invoke-bob 2>&1 | logger -p local2.info -t tunnel-bob
+ (Note that if you have more than one tunnel the `id' field, at the
+ start of the inittab line, must be different for each one.)
+
+ This would use `su' to become bob and run the actual tunnelling
+ software, and arrange for the diagnostic output to be sent to syslog
+ with facility `local2' and priority `info', tagged with `tunnel-bob'.
+ With an appropriate line in /etc/syslog.conf, such as
+ local2.* /var/log/local2-all.log
+ (remember that you have to use tabs in syslog.conf) this will
+ produce, in /var/log/local2-all.log, all the diagnostics, including
+ reassuring messages like this:
+ Sep 18 00:27:48 alice tunnel-bob: udptunnel-forwarder: alice: tunnel still open: received 5262 packets, 5262 bytes
+ Sep 18 00:28:44 alice tunnel-bob: udptunnel-forwarder: bob: tunnel still open: received 5280 packets, 5280 bytes
+
+
+5. TESTING YOUR UDPTUNNEL INVOCATION SCRIPT
+
+5.1. Invocation
+
+ Log into alice as Tbob, and run ./udptunnel-invoke-bob.
+ A great deal of diagnostic output will ensue.
+
+ If all is well you will see two messages looking something like this
+ udptunnel-forwarder: bob: tunnel open with peer 127.0.0.3:76543
+ udptunnel-forwarder: alice: tunnel open
+ and the session will just sit there. This means it thinks it's
+ working; go on to section 5.2.
+
+ If it didn't say that, here are some debugging tips:
+
+ * If it just sits there for a minute or two and then udptunnel times
+ out, the physical packets aren't getting back and forth. Use
+ tcpdump, check your firewall and routing (as below), and consult the
+ sections above about NAT and firewalls.
+
+ * If it bombed out, look for an error message in the diagnostics.
+ There will be lots of `subprocess somethingorother exited with
+ nonzero exit status 47', `no details received from remote' and the
+ like, but these are probably not the ones you want to look at,
+ because they're usually just consequences of some other failure.
+
+ Permission denied.
+ udptunnel - alice: fatal error: remote command failed (code ...)
+ Tbob had trouble ssh'ing to Talice@bob. Check that the ssh
+ configuration is set up, and test it separately.
+
+ userv-ipif service: access denied for ...., ....
+ udptunnel - alice: subprocess local command failed with code 2048
+ The arguments to udptunnel don't correspond to
+ /etc/userv/ipif-networks on alice. Either the arguments to
+ udptunnel or the ipif-networks file is wrong. (Or, if the message
+ about `local command failed' mentions bob, look on bob.)
+
+ udptunnel - alice: subprocess forwarder failed with code 14
+ The tunnel timed out - no packets were successfully received for
+ 130 seconds. See 2.4.5 above for details of the timeout
+ parameters. (NB, applies to `code 14' only.)
+
+ usage errors from udptunnel or ssh, or sh: ...: unknown command
+ Perhaps you dropped a \ from the udptunnel-invoke-bob script ?
+
+ udptunnel not found, udptunnel-forwarder not found
+ Check that the PATH includes /usr/local/bin. Noninteractive `ssh'
+ invocations (ie, ones with a command specified) often have a
+ different PATH.
+
+ slattach cannot open /dev/2 (or similar messages)
+ Your slattach is buggy. See under `slattach problem' in the build
+ and installation instructions, above.
+
+ slattach cannot change line discipline (or some other weird message)
+ Check whether your kernel is compiled with SLIP and/or CSLIP
+ support.
+
+ * Other messages:
+
+ udptunnel-forwarder: alice: bad packet: blowfish-cbcmac: verify failed
+ This can be caused by actual packet corruption on the physical
+ network (or even by an actual hostile attack), but when using
+ fixed port numbers these messages are common after the tunnel has
+ died and been restarted: they correspond to packets from the
+ previous invocation (which is usung different keys) being rejected
+ because their checksums don't match. In this case they should go
+ away in a minute or two.
+
+5.2. Testing, once the tunnel claims to be working
+
+ In another session on alice, you should be able to ping bob's virtual
+ interface. If this works, test pinging between hosts on the private
+ networks behind alice and bob. If all is well, go onto step 4.
+
+ If not, here are some troubleshooting hints: