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 (Note: you may see the following warning while compiling
  69 conffile.tab.c; I believe this is a bison bug:
  70 /usr/share/bison/bison.simple: In function `yyparse':
  71 /usr/share/bison/bison.simple:285: warning: `yyval' might be used
  72  uninitialized in this function
  73 )
  74
  75 Any other warnings or errors should be reported to
  76 steve@greenend.org.uk.
  77
  78 If installing for the first time, do
  79
  80 # mkdir /etc/secnet
  81 # cp example.conf /etc/secnet/secnet.conf
  82 # cd /etc/secnet
  83 # ssh-keygen -f key -N ""
  84
  85 [On BSD use
  86 $ LDFLAGS="-L/usr/local/lib" ./configure
  87 $ gmake CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"
  88 XXX this should eventually be worked out automatically by 'configure'.]
  89
  90 Generate a site file fragment for your site (see below), and submit it
  91 for inclusion in your VPN's 'sites' file.  Download the vpn-sites file
  92 to /etc/secnet/sites - MAKE SURE YOU GET AN AUTHENTIC COPY because the
  93 sites file contains public keys for all the sites in the VPN.
  94
  95 * Configuration
  96
  97 Should be reasonably obvious - edit /etc/secnet/secnet.conf as
  98 prompted by the comments.  XXX Fuller documentation of the
  99 configuration file format should be forthcoming in time.  Its syntax
 100 is described in the README file at the moment.
 101
 102 * Constructing your site file fragment
 103
 104 You need the following information:
 105
 106 1. a short name for your site, eg.  "greenend".  This is used to
 107 identify your site in the vpn-sites file.
 108
 109 2. the name your site will use in the key setup protocol,
 110 eg. "greenend" (these two will usually be similar or the same).
 111
 112 3. the DNS name of the machine that will be the "front-end" for your
 113 secnet installation.  This will typically be the name of the gateway
 114 machine for your network, eg.  sinister.dynamic.greenend.org.uk
 115
 116 secnet does not actually have to run on this machine, as long as the
 117 machine can be configured to forward UDP packets to the machine that
 118 is running secnet.
 119
 120 4. the port number used to contact secnet at your site.  This is the
 121 port number on the front-end machine, and does not necessarily have to
 122 match the port number on the machine running secnet.
 123
 124 5. the list of networks accessible at your site over the VPN.
 125
 126 6. the public part of the RSA key you generated during installation
 127 (in /etc/secnet/key.pub if you followed the installation
 128 instructions).  This file contains three numbers and a comment on one
 129 line.  The first number is the key length in bits, and should be
 130 ignored.  The second number (typically small) is the encryption key
 131 'e', and the third number (large) is the modulus 'n'.
 132
 133 If you are running secnet on a particularly slow machine, you may like
 134 to specify a larger value for the key setup retry timeout than the
 135 default, to prevent unnecessary retransmissions of key setup packets.
 136 See the notes in the example configuration file for more on this.
 137
 138 The site file fragment should look something like this:
 139
 140 shortname {
 141                 name "sitename";
 142                 address "your.public.address.org.uk";
 143                 port 5678;
 144                 networks "172.18.45.0/24";
 145                 key rsa-public("35","153279875126380522437827076871354104097683702803616313419670959273217685015951590424876274370401136371563604396779864283483623325238228723798087715987495590765759771552692972297669972616769731553560605291312242789575053620182470998166393580503400960149506261455420521811814445675652857085993458063584337404329");
 146         };
 147
 148 See 'example-sites-file' for more examples.