@@ -1,3 +1,12 @@

[userv-utils] / ipif / INSTALL

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 $