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