INSTALL

   1 INSTALLATION INSTRUCTIONS for SECNET
   2
   3 USE AT YOUR OWN RISK. THIS IS ALPHA QUALITY SOFTWARE. I DO NOT
   4 GUARANTEE THAT THERE WILL BE PROTOCOL COMPATIBILITY BETWEEN DIFFERENT
   5 VERSIONS.
   6
   7 * Preparation
   8
   9 ** System software support
  10
  11 Ensure that you have libgmp2-dev and adns installed (and bison and
  12 flex, and for that matter gcc...).
  13
  14 If you intend to configure secnet to obtain packets from the kernel
  15 through userv-ipif, install and configure userv-ipif. It is part of
  16 userv-utils, available from ftp.chiark.greenend.org.uk in
  17 /users/ian/userv
  18
  19 If you intend to configure secnet to obtain packets from the kernel
  20 using the universal TUN/TAP driver, make sure it's configured in your
  21 kernel (it's under "network device support" in Linux) and that you've
  22 created the appropriate device files; see
  23 linux/Documentation/networking/tuntap.txt
  24
  25 If you're using TUN/TAP on a platform other than Linux-2.4, see
  26 http://vtun.sourceforge.net/tun/
  27
  28 Note than TUN comes in two flavours, one (called 'tun' in the secnet
  29 config file) which has only one device file (usually /dev/net/tun) and
  30 the other (called 'tun-old') which has many device files
  31 (/dev/tun*). Linux-2.4 has new-style TUN, Linux-2.2, BSD and Solaris
  32 have old-style TUN. Currently only new-style TUN has been tested with
  33 secnet.
  34
  35 ** System and network configuration
  36
  37 If you intend to start secnet as root, I suggest you create an userid
  38 for it to run as once it's ready to drop its privileges. Example (on
  39 Debian):
  40 # adduser --system --no-create-home secnet
  41
  42 You will need to allocate two IP addresses for use by secnet. One will
  43 be for the tunnel interface on your tunnel endpoint machine (i.e. the
  44 address you see in 'ifconfig' when you look at the tunnel
  45 interface). The other will be for secnet itself. These addresses could
  46 possibly be allocated from the range used by your internal network: if
  47 you do this, you should think about providing appropriate proxy-ARP on
  48 the machine running secnet for the two addresses. Alternatively the
  49 addresses could be from some other range - this works well if the
  50 machine running secnet is the default route out of your network.
  51
  52 http://www.ucam.org/cam-grin/ may be useful.
  53
  54 Advanced users: secnet's IP address does not _have_ to be in the range
  55 of networks claimed by your end of the tunnel; it could be in the
  56 range of networks claimed by the other end. Doing this is confusing,
  57 but works (in the case where you can't get the administrator of the
  58 other end to allocate an IP address for his copy of secnet [hint hint
  59 Ian]).
  60
  61 * Installation
  62
  63 To install secnet do
  64
  65 $ ./configure
  66 $ make
  67 # cp secnet /usr/local/sbin/secnet
  68 # mkdir /etc/secnet
  69 # cp example.conf /etc/secnet/secnet.conf
  70 # cd /etc/secnet
  71 # ssh-keygen -f key -N ""
  72
  73 (When upgrading, just install the new /usr/local/sbin/secnet; keep
  74 your current configuration file.)
  75
  76 Generate a site file fragment for your site (see below), and submit it
  77 for inclusion in the vpn-sites file. Download the vpn-sites file to
  78 /etc/secnet/sites - MAKE SURE YOU GET AN AUTHENTIC COPY because the
  79 sites file contains public keys for all the sites in the VPN.
  80
  81 * Configuration
  82
  83 Should be reasonably obvious - edit /etc/secnet/secnet.conf as
  84 prompted by the comments. XXX Fuller documentation of the
  85 configuration file format should be forthcoming in time. Its syntax is
  86 described in the README file at the moment.
  87
  88 * Constructing your site file fragment
  89
  90 You need the following information:
  91
  92 1.  a short name for your site, eg. "greenend". This is used to
  93 identify your site in the vpn-sites file.
  94
  95 2.  the name your site will use in the key setup protocol,
  96 eg. "greenend" (these two will usually be similar or the same).
  97
  98 3.  the DNS name of the machine that will be the "front-end" for your
  99 secnet installation. This will typically be the name of the gateway
 100 machine for your network, eg. sinister.dynamic.greenend.org.uk
 101
 102 secnet does not actually have to run on this machine, as long as the
 103 machine can be configured to forward UDP packets to the machine that
 104 is running secnet.
 105
 106 4.  the port number used to contact secnet at your site. This is the
 107 port number on the front-end machine, and does not necessarily have to
 108 match the port number on the machine running secnet.
 109
 110 5.  the list of networks accessible at your site over the VPN.
 111
 112 6.  the public part of the RSA key you generated during installation
 113 (in /etc/secnet/key.pub if you followed the installation
 114 instructions). This file contains three numbers and a comment on one
 115 line. The first number is the key length in bits, and can be
 116 ignored. The second number (typically small) is the encryption key
 117 'e', and the third number (large) is the modulus 'n'.
 118
 119 If you are running secnet on a particularly slow machine, you may like
 120 to specify a larger value for the key setup retry timeout than the
 121 default, to prevent unnecessary retransmissions of key setup
 122 packets. See the notes in the example configuration file for more on
 123 this.
 124
 125 The site file fragment should look something like this:
 126
 127 shortname {
 128                 name "sitename";
 129                 address "your.public.address.org.uk";
 130                 port 5678;
 131                 networks "172.18.45.0/24";
 132                 key rsa-public("35","153279875126380522437827076871354104097683702803616313419670959273217685015951590424876274370401136371563604396779864283483623325238228723798087715987495590765759771552692972297669972616769731553560605291312242789575053620182470998166393580503400960149506261455420521811814445675652857085993458063584337404329");
 133         };
 134
 135 See 'example-sites-file' for more examples.