ipif/INSTALL

   1 This directory contains:
   2
   3 * A userv service (`ipif') for allowing users to create network
   4 interfaces and handle the traffic for them.  For instructions, see the
   5 comment at the top of service.c.
   6
   7 * A VPN tunnelling system based on that userv service, which does
   8 encryption and can be used to join two networks.  It uses its own
   9 nonstandard protocols, not IPSEC.  Key setup is done via an ssh
  10 connection.  For installation instructions, read this file.
  11
  12 These tools have only been tested on GNU/Linux, and the ipif service
  13 in particular uses the Linux-specific `slattach' utility.
  14
  15 NB that this is a very bare set of installation instructions for the
  16 VPN system !  It describes a fairly `default' configuration; you can
  17 do more esoteric things if you wish.
  18
  19
  20 In any case, on each tunnel endpoint system (not the eventual
  21 end-system, but the point where the packets are `detunnelled'):
  22
  23 * Install userv, 1.0.1 or later.  This should be in Debian.  Get this
  24 * package, userv-utils from the location above, unpack it, cd to the
  25   `ipif' subdirectory, and say `make' then as root `make install'.
  26
  27
  28 The tunnel is always set up by one of its endpoints, using ssh (we
  29 recommend you use OpenSSH).  So the active endpoint must have ssh
  30 installed; the passive endpoint must have sshd accessible to the
  31 active endpoint, and be willing to allow the active endpoint to run
  32 the appropriate command.
  33
  34 So: create an account for the active endpoint on the passive.  You
  35 probably want to use RSAAuthentication, so configure the relevant key
  36 into the passive account's authorized_keys file.
  37
  38 Each account must have the ability to run the `userv ipif' service
  39 with appropriate parameters.  This is achieved by editing
  40 /etc/userv/ipif-networks, each line of which is in the format:
  41
  42 <gid>,[=]<network-prefix>/<prefix-length>,  <groupname>,  <comment>
  43
  44 Both the local and remote endpoint addresses, and the remote network
  45 address(es), need to be recorded in this file.  The `=' restricts the
  46 address to be used, by that group, as the local tunnel endpoint
  47 address; without `=' the address ranges specified may refer to remote
  48 endpoints and networks.  Every address involved with the tunnel must
  49 be covered by an appropriate line in ipif-networks.
  50
  51 For example, a configuration to talk to Relativity, the author's home
  52 site, would include:
  53 <gid>,172.31.80.6/32,       <group>,    Relativity tunnel endpoint
  54 <gid>,172.18.45.0/24,       <group>,    Relativity house ethernet
  55 as well as the local tunnel endpoint address, for example:
  56 <gid>,=192.168.160.124/32,  <group>,    Local tunnel endpoint
  57
  58 There is no NAT (address translation) in the tunnelling software, so
  59 all the addresses must be RFC1918-allocated and distinct (except that
  60 a single tunnel endpoint address can be used for all the tunnels
  61 terminating on a particular endpoint system).
  62
  63 You are strongly advised to choose your private network ranges
  64 randomly, as recommended in BCP5 (currently RFC1918).  Users in
  65 Cambridge may like to use the Cambridge G-RIN at
  66 http://www.ucam.org/cam-grin/ to choose and register their networks.
  67
  68
  69 When these things are all thought to be set up, you can test the
  70 tunnel by running `udptunnel' in the active account.  It is invoked
  71 something like this:
  72
  73 authbind udptunnel                                              \
  74         -m                                                      \
  75         -e nonce -e timestamp/10/30 -e pkcs5/8                  \
  76         -e blowfish-cbcmac/128 -e blowfish-cbc/128              \
  77         davenant-external,410                                   \
  78         chiark-public,Command                                   \
  79         172.31.80.6,172.31.80.9,1000,cslip                      \
  80         30,120,1800                                             \
  81         - 172.18.45.0/24                                        \
  82         ssh     -o 'ForwardAgent no' -o 'ForwardX11 no'         \
  83                 -o 'BatchMode yes'                              \
  84                 -i ~ian/.ssh/identity -l ian                    \
  85                 -v chiark.greenend.org.uk                       \
  86                 udptunnel
  87
  88 This example is the tunnel between chiark and Relativity.  I'll quote
  89 it and explain the details, below.  See also the comment at the top of
  90 udptunnel.
  91
  92
  93 Because at Relativity the tunnel endpoint has to not be our firewall,
  94 because the firewall is a 386SX/16 and so not powerful enough,
  95 Relativity practically has to be the active partner in any tunnels it
  96 is involved in.  This also necessitates the use of the `-m' option and
  97 various other things.
  98
  99
 100 Exposition of an example udptunnel invocation:
 101
 102 > authbind udptunnel                                              \
 103
 104 `authbind' is used because at Relativity the tunnel endpoint address
 105 has to be on a fixed port because our tunnel endpoint is not on the
 106 firewall system (if it's not on a fixed port we can't write a firewall
 107 rule to let it through).
 108
 109 The port is port 410, so root privilege or authbind is needed.
 110 authbind is in Debian GNU/Linux.
 111
 112 >         -m                                                      \
 113
 114 -m tells this invocation of udptunnel that its endpoint address and
 115 port (for encapsulated packets) are going to be NATted before the far
 116 end sees them.  The effect is that instead of supplying this
 117 information to the far end, the far end is told to `wait and see'.
 118
 119 This should not usually be used in other circumstances.  (For full
 120 details see the comment at the top of udptunnel.)
 121
 122 >         -e nonce -e timestamp/10/30 -e pkcs5/8                  \
 123 >         -e blowfish-cbcmac/128 -e blowfish-cbc/128              \
 124
 125 This is the crypto configuration.  I wouldn't mess with it too much if
 126 I were you.  If you have serious (>10s) clock skew then the -e
 127 timestamp option may not work properly; I'd recommend having your
 128 systems NTP-synchronised.  Here 10 is the maximum number of seconds
 129 into the future the timestamp on an incoming packet might be, and 30
 130 the maximum age of an incoming packet.  You can tweak these numbers if
 131 you really want.  If you really can't get any kind of good clock
 132 synch, then it's probably OK to replace
 133      -e nonce -e timestamp/10/30
 134 with
 135      -e sequence
 136 (NB that we don't use -e sequence so it has not been well tested.)
 137
 138 >         davenant-external,410                                   \
 139
 140 This is the local address and port for sending/receiving encapsulated
 141 packets.  davenant is the tunnel endpoint, and davenant-external is
 142 its globally-reachable address (we run two networks on the wire at
 143 Relativity, an internal one and a globally-reachable one).
 144
 145 >         chiark-public,Command                                   \
 146
 147 This is the remote address and port for encapsulated packets.
 148 `Command' means find out the remote address or port to send
 149 encapsulated packets to by having udptunnel at the far end print its
 150 address and port when they have been allocated.
 151
 152 Another possibility here is to use a fixed remote port number.
 153
 154 The DNS at GR has just `chiark' meaning chiark via the tunnel, so we
 155 have to use chiark-public which means its public IP address.
 156
 157 >         172.31.80.6,172.31.80.9,1000,cslip                      \
 158
 159 172.31.80.6 is davenant's tunnel endpoint address.
 160 172.31.80.9 is the address of chiark's Relativity tunnel endpoint.
 161
 162 >         30,120,1800                                             \
 163
 164 These are timing parameters.  30 is the `keep alive' timeout; if
 165 nothing is sent for this many seconds, an empty packet is sent.  120
 166 is the `broken' timeout; if nothing valid is received for this many
 167 seconds, the tunnel is declared dead and dies (hopefully to be
 168 restarted); 1800 is the time in seconds between messages of the form
 169   udptunnel-forwarder: chiark: tunnel still open: received 746
 170   packets, 103257 bytes
 171 These serve as a useful diagnostic, and also prevent the controlling
 172 ssh connection from timing out from NAT tables.
 173
 174 >         - 172.18.45.0/24                                        \
 175
 176 `-' here is the remote networks which are reachable.  None are
 177 reachable via chiark.  172.18.45.0/24 is the Relativity house
 178 ethernet.
 179
 180 >         ssh     -o 'ForwardAgent no' -o 'ForwardX11 no'         \
 181 >                 -o 'BatchMode yes'                              \
 182 >                 -i ~ian/.ssh/identity -l ian                    \
 183 >                 -v chiark.greenend.org.uk                       \
 184 >                 udptunnel
 185
 186 This is the ssh invocation to run udptunnel at the far end.
 187
 188 When you have this invocation working in a shell window you need to
 189 make it run automatically.  Since the tunnel will die whenever your
 190 IP address changes, or when other troublesome events happen, you must
 191 arrange for it to be restarted.  At Relativity we put the udptunnel
 192 invocation in a file and run it out of inittab, like this:
 193
 194 t0:235:respawn:/usr/local/sbin/really -u ian /usr/local/sbin/udptunnel-invoke 2>&1 | logger -p local2.info -t tunnel-chiark
 195
 196
 197 Troubleshooting:
 198
 199 Look at the error messages, they will hopefully be informative.
 200
 201 If you see a message from `slattach' about being unable to open /dev/2
 202 or some such, then you need to upgrade your `slattach'.  In Debian
 203 GNU/Linux it's in the `netbase' package, and the fix is in 3.16-3 and
 204 later; however the bug has regressed, and is known to be in 3.18-4 and
 205 earlier.  The relevant Debian bug reports are #45515 (now closed) and
 206 #45944.  A patch to correct 3.18-4 is in this directory as
 207 `slattach.diff'.
 208
 209
 210 $Id$