+NB that this is a very bare set of installation instructions ! It
+describes a `default' configuration; you can do more esoteric things
+if you wish.
+
+
+In any case, on each tunnel endpoint system (not the eventual
+end-system, but the point where the packets are `detunnelled'):
+
+* Install userv, 0.95.0 or later. This should be in Debian.
+* Get userv-utils 0.1.9 from the location above, unpack it, cd to the
+ `ipif' subdirectory, and say `make' then `really make install'.
+
+
+The tunnel is always set up by one of its endpoints, using ssh. So
+the active endpoint must have ssh installed; the passive endpoint must
+have sshd accessible to the active endpoint, and be willing to allow
+the active endpoint to run the appropriate command.
+
+So: create an account for the active endpoint on the passive. You
+probably want to use RSAAuthentication, so configure the relevant key
+into the passive account's authorized_keys file.
+
+Each account must have the ability to run the `userv ipif' service
+with appropriate parameters. This is achieved by editing
+/etc/userv/ipif-networks, each line of which is in the format:
+
+<gid>,[=]<network-prefix>/<prefix-length>, <groupname>, <comment>
+
+Both the local and remote endpoint addresses, and the remote network
+address(es), need to be recorded in this file. The `=' restricts the
+address to be used, by that group, as the local tunnel endpoint
+address; without `=' the address ranges specified may refer to remote
+endpoints and networks. Every address involved with the tunnel must
+be covered by an appropriate line in ipif-networks.
+
+For example, a configuration to talk to Relativity, the author's home
+site, would include:
+<gid>,172.31.80.6/32, <group>, Relativity tunnel endpoint
+<gid>,172.18.45.0/24, <group>, Relativity house ethernet
+as well as the local tunnel endpoint address, for example:
+<gid>,=192.168.160.124/32, <group>, Local tunnel endpoint
+
+There is no NAT (address translation) in the tunnelling software, so
+all the addresses must be RFC1918-allocated and distinct (except that
+a single tunnel endpoint address can be used for all the tunnels
+terminating on a particular endpoint system).
+
+You are strongly advised to choose your private network ranges
+randomly, as recommended in BCP5 (currently RFC1918). Users in
+Cambridge may like to use the Cambridge G-RIN at
+http://www.ucam.org/cam-grin/ to choose and register their networks.
+
+
+When these things are all thought to be set up, you can test the
+tunnel by running `udptunnel' in the active account. It is invoked
+something like this:
+
+authbind udptunnel \
+ -m \
+ -e nonce -e timestamp/10/30 -e pkcs5/8 \
+ -e blowfish-cbcmac/128 -e blowfish-cbc/128 \
+ davenant-external,410 \
+ chiark-public,Command \
+ 172.31.80.6,172.31.80.9,1000,cslip \
+ 30,120,1800 \
+ - 172.18.45.0/24 \
+ ssh -o 'ForwardAgent no' -o 'ForwardX11 no' \
+ -o 'BatchMode yes' \
+ -i ~ian/.ssh/identity -l ian \
+ -v chiark.greenend.org.uk \
+ udptunnel
+
+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
+udptunnel.
+
+
+Because at Relativity the tunnel endpoint has to not be our firewall,
+because the firewall is a 386SX/16 and so not powerful enough,
+Relativity practically has to be the active partner in any tunnels it
+is involved in. This also necessitates the use of the `-m' option and
+various other things.
+
+
+Exposition of an example udptunnel invocation:
+
+> authbind udptunnel \
+
+`authbind' is used because at Relativity the tunnel endpoint address
+has to be on a fixed port because our tunnel endpoint is not on the
+firewall system (if it's not on a fixed port we can't write a firewall
+rule to let it through).
+
+The port is port 410, so root privilege or authbind is needed.
+authbind is in Debian GNU/Linux.
+
+> -m \
+
+-m tells this invocation of udptunnel that its endpoint address and
+port (for encapsulated packets) are going to be NATted before the far
+end sees them. The effect is that instead of supplying this
+information to the far end, the far end is told to `wait and see'.
+
+This should not usually be used in other circumstances. (For full
+details see the comment at the top of udptunnel.)
+
+> -e nonce -e timestamp/10/30 -e pkcs5/8 \
+> -e blowfish-cbcmac/128 -e blowfish-cbc/128 \
+
+This is the crypto configuration. I wouldn't mess with it too much if
+I were you. If you have serious (>10s) clock skew then the -e
+timestamp option may not work properly; I'd recommend having your
+systems NTP-synchronised. Here 10 is the maximum number of seconds
+into the future the timestamp on an incoming packet might be, and 30
+the maximum age of an incoming packet. You can tweak these numbers if
+you really want. If you really can't get any kind of good clock
+synch, then it's probably OK to replace
+ -e nonce -e timestamp/10/30
+with
+ -e sequence
+(NB that we don't use -e sequence so it has not been well tested.)
+
+> davenant-external,410 \
+
+This is the local address and port for sending/receiving encapsulated
+packets. davenant is the tunnel endpoint, and davenant-external is
+its globally-reachable address (we run two networks on the wire at
+Relativity, an internal one and a globally-reachable one).
+
+> chiark-public,Command \
+
+This is the remote address and port for encapsulated packets.
+`Command' means find out the remote address or port to send
+encapsulated packets to by having udptunnel at the far end print its
+address and port when they have been allocated.
+
+Another possibility here is to use a fixed remote port number.
+
+The DNS at GR has just `chiark' meaning chiark via the tunnel, so we
+have to use chiark-public which means its public IP address.
+
+> 172.31.80.6,172.31.80.9,1000,cslip \
+
+172.31.80.6 is davenant's tunnel endpoint address.
+172.31.80.9 is the address of chiark's Relativity tunnel endpoint.
+
+> 30,120,1800 \
+
+These are timing parameters. 30 is the `keep alive' timeout; if
+nothing is sent for this many seconds, an empty packet is sent. 120
+is the `broken' timeout; if nothing valid is received for this many
+seconds, the tunnel is declared dead and dies (hopefully to be
+restarted); 1800 is the time in seconds between messages of the form
+ udptunnel-forwarder: chiark: tunnel still open: received 746
+ packets, 103257 bytes
+These serve as a useful diagnostic, and also prevent the controlling
+ssh connection from timing out from NAT tables.
+
+> - 172.18.45.0/24 \
+
+`-' here is the remote networks which are reachable. None are
+reachable via chiark. 172.18.45.0/24 is the Relativity house
+ethernet.
+
+> ssh -o 'ForwardAgent no' -o 'ForwardX11 no' \
+> -o 'BatchMode yes' \
+> -i ~ian/.ssh/identity -l ian \
+> -v chiark.greenend.org.uk \
+> udptunnel
+
+This is the ssh invocation to run udptunnel at the far end.
+
+When you have this invocation working in a shell window you need to
+make it run automatically. Since the tunnel will die whenever your
+IP address changes, or when other troublesome events happen, you must
+arrange for it to be restarted. At Relativity we put the udptunnel
+invocation in a file and run it out of inittab, like this:
+
+t0:235:respawn:/usr/local/sbin/really -u ian /usr/local/sbin/udptunnel-invoke 2>&1 | logger -p local2.info -t tunnel-chiark
+
+
+Troubleshooting:
+
+Look at the error messages, they will hopefully be informative.
+
+If you see a message from `slattach' about being unable to open /dev/2
+or some such, then you need to upgrade your `slattach'. In Debian
+GNU/Linux it's in the `netbase' package, and the fix is in 3.16-3 and
+later. The relevant Debian bug reports are #45515 and #45944, and Ian
+Jackson can supply the patch to slattach or a working binary.
+
+
+$Id: INSTALL,v 1.1 2000/06/21 22:48:29 ian Exp $
~mdw / userv-utils / commitdiff