-This file, INSTALL, is a tutorial on how to
- * install userv ipif and udptunnel, and
- * configure them to create a VPN tunnel between two hosts or networks.
+This file, INSTALL, is a -*- text -*- file tutorial on how to
+ * install userv ipif and udptunnel,
+ * configure them to create a VPN tunnel between two hosts or
+ networks, or
+ * use udptunnel-reconf to create a multi-site VPN.
+
See README for details of other available documentation.
2. Make sure your Linux kernel has SLIP and CSLIP compiled in.
You will need to be using Linux 2.2 (with Unix98-style ptys).
-3. Obtain a fresh copy of userv-utils, if you haven't already.
+3. udptunnel works best if your ssh can do ssh-protocol-level
+ keepalives. Currently these are only supported by using a special
+ patch, which can be found (for OpenSSH 1.2.x) at
+ ftp.chiark.greenend.org.uk:/users/ian/openssh+protocolkeepalives.
+
+4. Obtain a fresh copy of userv-utils, if you haven't already.
cd to ipif, and run `make' and (as root) `make install'.
After you have done this the software will still not do anything, and
host or network number - - - Encrypted Data Flow ||
-2. SETUP INSTRUCTIONS
+2. INFORMATION COLLECTION AND PRELIMINARY SETUP
- All of these steps can be done using the appropriate normal user
- accounts, unless otherwise indicated.
+ You will need to collect and/or decide upon various information, and
+ make sure that your two endpoint systems can talk to each other over
+ the public network.
2.1. Find out, or choose, private network numbers
In some situations you may find yourself using a `public network'
which is not actually the public Internet - for example, you may want
to run one tunnel `through' another, or your `public network' is
- actually a private radio LAN. In this case you'll have to choose the
- addresses to use from RFC1918-space, as above.
+ actually a `private', but not sufficiently secure, radio LAN. In
+ this case you'll have to choose the addresses to use from
+ RFC1918-space, as above.
2.3. Decide which user account(s) on alice and bob you will use
(Obviously, if you need to create accounts, edit groups, or change
the sshd configuratioon, you may need to be root.)
-2.3. Configure the private network numbers in /etc/userv/ipif-networks
+2.4. Decide whether to use `udptunnel-reconf'
+
+ There are two ways to set up a tunnel with udptunnel. Either you can
+ simply give udptunnel the right command, by putting it in an
+ appropriate script and arranging it to be called, or you can have a
+ program `udptunnel-reconf' read some configuration files and do it
+ for you.
+
+ udptunnel-reconf is not as well documented, but its behaviour is
+ somewhat more `cooked'. It is especially useful if you need to
+ maintain many tunnels as part of an organised, multi-site, VPN.
+
+ Using udptunnel directly is somewhat more flexible, and may be easier
+ if you only want one tunnel.
+
+
+3. SETUP INSTRUCTIONS - USING UDPTUNNEL-RECONF
+
+ Edit or create the following files, as root:
+ /etc/userv/vpn/sites
+ /etc/userv/vpn/tunnels
+ /etc/userv/vpn/global
+
+ Run udptunnel-reconf, as root. This will create:
+ /var/lib/userv/vpn/passive-sites
+ /var/lib/userv/vpn/active-sites
+ /var/lib/userv/vpn/command.<site>
+
+ It will also spit out to stdout two things: firstly, a list of
+ suggested commands to put in your inittab, and secondly a suggested
+ line to put in your /etc/userv/ipif-networks.
+
+ Test that your setup is working, by running (one of) the
+ /var/lib/userv/vpn/command.<site> file(s) by hand - see section 5.
+ If it works, you can put the relevant things in your inittab and say
+ `init q'.
+
+ 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.)
interface with that address, but the address may not be assigned to a
remote host or route.
-2.4. Construct the udptunnel invocation (on alice)
+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
You have to fill in the right values for things in angle brackets.
(See also section 6. for a moderately complex example, below.)
-
2.4.1. Syntax of <alice-private-nets> and <bob-private-nets>
+
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
just to connect alice to bob and things at bob's end, then specify
`-' for <alice-private-nets>.
-2.4.2. IP masquerading (NAT) at alice's end
+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
way alice doesn't need to know what port number the NAT proxy will
use.
-2.4.3. Using fixed UDP port numbers (eg to make firewally happy)
+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
with
<bob-physical-hostname>,<bob-physical-port> \
-2.4.4. Clock skew and excessive delay
+4.4.4. Clock skew and excessive delay
The default configuration given above, which includes this
-e nonce -e timestamp/10/30 \
with
-e sequence \
-2.4.5. Other things to tweak (it's usually safe to ignore this part)
+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.
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
+
-3. Test your udptunnel invocation script
+5. TESTING YOUR UDPTUNNEL INVOCATION SCRIPT
-3.1. Invocation
+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. Go to 3.2.
+ 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:
because their checksums don't match. In this case they should go
away in a minute or two.
-3.2. Testing, once the tunnel claims to be working
+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
that, they can be a complete pain to debug.
-4. 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. DNS, firewall, mail, etc.
+6. DNS, firewall, mail, etc.
- Now you have IP level connectivity between your two networks. You
- must now arrange for:
+ When you have IP level connectivity between your two networks, you
+ must also arrange for:
* An appropriate firewall on each tunnel endpoint (to stop attacks
from one network to another) and also at all the borders of each
How to do these things is beyond the scope of this document.
-6. Example
+7. Example
This example is the tunnel between chiark and Relativity. I'll quote
it and explain the details, below. See also the comment at the top of
t0:235:respawn:/usr/local/sbin/really -u ian /usr/local/sbin/udptunnel-invoke 2>&1 | logger -p local2.info -t tunnel-chiark
-7. Copyright notice
+8. Copyright notice
Copyright (C) 1999-2000 Ian Jackson
~ian / userv-utils.git / blobdiff