ipif/INSTALL

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