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