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