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