INSTALL

   1 INSTALLATION INSTRUCTIONS for SECNET
   2
   3 USE AT YOUR OWN RISK.  THIS IS ALPHA TEST SOFTWARE.  I DO NOT
   4 GUARANTEE THAT THERE WILL BE PROTOCOL COMPATIBILITY BETWEEN DIFFERENT
   5 VERSIONS.
   6
   7 PROTOCOL COMPATIBILITY WAS BROKEN BETWEEN secnet-0.06, secnet-0.07 AND
   8 secnet-0.08 FOR ENDIANNESS FIXES.
   9
  10 THERE WILL BE ANOTHER CHANGE IN PROTOCOL IN THE secnet-0.1.x SERIES
  11
  12 * Preparation
  13
  14 ** System software support
  15
  16 Ensure that you have libgmp2-dev and adns installed (and bison and
  17 flex, and for that matter gcc...).
  18
  19 [On BSD install /usr/ports/devel/bison and /usr/ports/devel/libgnugetopt]
  20
  21 If you intend to configure secnet to obtain packets from the kernel
  22 through userv-ipif, install and configure userv-ipif.  It is part of
  23 userv-utils, available from ftp.chiark.greenend.org.uk in
  24 /users/ian/userv
  25
  26 If you intend to configure secnet to obtain packets from the kernel
  27 using the universal TUN/TAP driver, make sure it's configured in your
  28 kernel (it's under "network device support" in Linux-2.4) and that
  29 you've created the appropriate device files; see
  30 linux/Documentation/networking/tuntap.txt
  31
  32 If you're using TUN/TAP on a platform other than Linux-2.4, see
  33 http://vtun.sourceforge.net/tun/
  34
  35 Note than TUN comes in two flavours, one (called 'tun' in the secnet
  36 config file) which has only one device file (usually /dev/net/tun) and
  37 the other (called 'tun-old') which has many device files (/dev/tun*).
  38 Linux-2.4 has new-style TUN, Linux-2.2, BSD and Solaris have old-style
  39 TUN.
  40
  41 ** System and network configuration
  42
  43 If you intend to start secnet as root, I suggest you create a userid
  44 for it to run as once it's ready to drop its privileges.  Example (on
  45 Debian):
  46 # adduser --system --no-create-home secnet
  47
  48 If you're using the 'soft routes' feature (for some classes of mobile
  49 device) you'll have to run as root all the time, to enable secnet to
  50 add and remove routes from your kernel's routing table.  (This
  51 restriction may be relaxed later if someone writes a userv service to
  52 modify the routing table.)
  53
  54 If you are joining an existing VPN, read that VPN's documentation now.
  55 It may supersede the next paragraph.
  56
  57 You will need to allocate two IP addresses for use by secnet.  One
  58 will be for the tunnel interface on your tunnel endpoint machine (i.e.
  59 the address you see in 'ifconfig' when you look at the tunnel
  60 interface).  The other will be for secnet itself.  These addresses
  61 should probably be allocated from the range used by your internal
  62 network: if you do this, you should provide appropriate proxy-ARP on
  63 the internal network interface of the machine running secnet (eg. add
  64 an entry net/ipv4/conf/eth_whatever/proxy_arp = 1 to /etc/sysctl.conf
  65 on Debian systems and run sysctl -p).  Alternatively the addresses
  66 could be from some other range - this works well if the machine
  67 running secnet is the default route out of your network - but this
  68 requires more thought.
  69
  70 http://www.ucam.org/cam-grin/ may be useful.
  71
  72 * Installation
  73
  74 If you installed the Debian package of secnet, skip to "If installing
  75 for the first time", below, and note that example.conf can be found in
  76 /usr/share/doc/secnet/examples.
  77
  78 To install secnet do
  79
  80 $ ./configure
  81 $ make
  82 # make install
  83 # mkdir /etc/secnet
  84
  85 (Note: you may see the following warning while compiling
  86 conffile.tab.c; I believe this is a bison bug:
  87 /usr/share/bison/bison.simple: In function `yyparse':
  88 /usr/share/bison/bison.simple:285: warning: `yyval' might be used
  89  uninitialized in this function
  90 )
  91
  92 Any other warnings or errors should be reported to
  93 steve@greenend.org.uk.
  94
  95 If installing for the first time, do
  96
  97 # cp example.conf /etc/secnet/secnet.conf
  98 # cd /etc/secnet
  99 # ssh-keygen -f key -N ""
 100
 101 [On BSD use
 102 $ LDFLAGS="-L/usr/local/lib" ./configure
 103 $ gmake CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"
 104 XXX this should eventually be worked out automatically by 'configure'.]
 105
 106 Generate a site file fragment for your site (see below), and submit it
 107 for inclusion in your VPN's 'sites' file.  Download the vpn-sites file
 108 to /etc/secnet/sites - MAKE SURE YOU GET AN AUTHENTIC COPY because the
 109 sites file contains public keys for all the sites in the VPN.  Use the
 110 make-secnet-sites.py program provided with the secnet distribution to
 111 convert the distributed sites file into one that can be included in a
 112 secnet configuration file:
 113
 114 # make-secnet-sites.py sites sites.conf
 115
 116 * Configuration
 117
 118 Should be reasonably obvious - edit /etc/secnet/secnet.conf as
 119 prompted by the comments.  XXX Fuller documentation of the
 120 configuration file format should be forthcoming in time.  Its syntax
 121 is described in the README file at the moment.
 122
 123 * Constructing your site file fragment
 124
 125 You need the following information:
 126
 127 1. the name of your VPN.
 128
 129 2. the name of your location(s).
 130
 131 3. a short name for your site, eg. "sinister".  This is used to
 132 identify your site in the vpn-sites file, and should probably be the
 133 same as its hostname.
 134
 135 4. the DNS name of the machine that will be the "front-end" for your
 136 secnet installation.  This will typically be the name of the gateway
 137 machine for your network, eg. sinister.dynamic.greenend.org.uk
 138
 139 secnet does not actually have to run on this machine, as long as the
 140 machine can be configured to forward UDP packets to the machine that
 141 is running secnet.
 142
 143 5. the port number used to contact secnet at your site.  This is the
 144 port number on the front-end machine, and does not necessarily have to
 145 match the port number on the machine running secnet.  If you want to
 146 use a privileged port number we suggest 410.  An appropriate
 147 unprivileged port number is 51396.  (These numbers were picked at
 148 random.)
 149
 150 6. the list of networks accessible at your site over the VPN.
 151
 152 7. the public part of the RSA key you generated during installation
 153 (in /etc/secnet/key.pub if you followed the installation
 154 instructions).  This file contains three numbers and a comment on one
 155 line.
 156
 157 If you are running secnet on a particularly slow machine, you may like
 158 to specify a larger value for the key setup retry timeout than the
 159 default, to prevent unnecessary retransmissions of key setup packets.
 160 See the notes in the example configuration file for more on this.
 161
 162 The site file fragment should look something like this:
 163
 164 vpn sgo
 165 location greenend
 166 contact steve@greenend.org.uk
 167 site sinister
 168   networks 192.168.73.0/24 192.168.1.0/24 172.19.71.0/24
 169   address sinister.dynamic.greenend.org.uk 51396
 170   pubkey 1024 35 142982503......[lots more].....0611 steve@sinister