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]
  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 several flavours.  Their names in the
  36 configuration file are:
  37  tun:  Linux-2.4; only one device file (usually /dev/net/tun)
  38  tun-old:  Linux-2.2, BSD; device files /dev/tun*
  39  tun-solaris:  Solaris (not yet implemented)
  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 If you're using the 'soft routes' feature (for some classes of mobile
  49 device) you'll have to run as root all the time, to enable secnet to
  50 add and remove routes from your kernel's routing table.  (This
  51 restriction may be relaxed later if someone writes a userv service to
  52 modify the routing table.)
  53
  54 If you are joining an existing VPN, read that VPN's documentation now.
  55 It may supersede the next paragraph.
  56
  57 In most configurations, you will need to allocate two IP addresses for
  58 use by secnet.  One will be for the tunnel interface on your tunnel
  59 endpoint machine (i.e. the address you see in 'ifconfig' when you look
  60 at the tunnel interface).  The other will be for secnet itself.  These
  61 addresses should probably be allocated from the range used by your
  62 internal network: if you do this, you should provide appropriate
  63 proxy-ARP on the internal network interface of the machine running
  64 secnet (eg. add an entry net/ipv4/conf/eth_whatever/proxy_arp = 1 to
  65 /etc/sysctl.conf on Debian systems and run sysctl -p).  Alternatively
  66 the addresses could be from some other range - this works well if the
  67 machine running secnet is the default route out of your network - but
  68 this requires more thought.
  69
  70 http://www.ucam.org/cam-grin/ may be useful.
  71
  72 * Installation
  73
  74 If you installed the Debian package of secnet, skip to "If installing
  75 for the first time", below, and note that example.conf can be found in
  76 /usr/share/doc/secnet/examples.
  77
  78 To install secnet do
  79
  80 $ ./configure
  81 $ make
  82 # make install
  83 # mkdir /etc/secnet
  84
  85 (Note: you may see the following warning while compiling
  86 conffile.tab.c; this is a bug in bison-1.28:
  87 /usr/share/bison/bison.simple: In function `yyparse':
  88 /usr/share/bison/bison.simple:285: warning: `yyval' might be used
  89  uninitialized in this function
  90
  91 You may if you wish apply the following patch to bison.simple:
  92 diff -pu -r1.28.0.1 -r1.28.0.3
  93 --- bison.s1    1999/08/30 19:23:24     1.28.0.1
  94 +++ bison.s1    1999/08/30 21:15:18     1.28.0.3
  95 @@ -523,8 +523,14 @@ yydefault:
  96  /* Do a reduction.  yyn is the number of a rule to reduce with.  */
  97  yyreduce:
  98    yylen = yyr2[yyn];
  99 -  if (yylen > 0)
 100 -    yyval = yyvsp[1-yylen]; /* implement default value of the action */
 101 +
 102 +  /* If yylen is nonzero, implement the default value of the action.
 103 +     Otherwise, the following line sets yyval to the semantic value of
 104 +     the lookahead token.  This behavior is undocumented and bison
 105 +     users should not rely upon it.  Assigning to yyval
 106 +     unconditionally makes the parser a bit smaller, and it avoids a
 107 +     GCC warning that yyval may be used uninitialized.  */
 108 +  yyval = yyvsp[1-yylen];
 109
 110  #if YYDEBUG != 0
 111    if (yydebug)
 112 )
 113
 114 Any other warnings or errors should be reported to
 115 steve@greenend.org.uk.
 116
 117 If installing for the first time, do
 118
 119 # cp example.conf /etc/secnet/secnet.conf
 120 # cd /etc/secnet
 121 # ssh-keygen -f key -N ""
 122
 123 [On BSD use
 124 $ LDFLAGS="-L/usr/local/lib" ./configure
 125 $ gmake CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"
 126 XXX this should eventually be worked out automatically by 'configure'.]
 127
 128 Generate a site file fragment for your site (see your VPN's
 129 documentation, or see below), and submit it for inclusion in your
 130 VPN's 'sites' file.  Download the vpn-sites file to /etc/secnet/sites
 131 - MAKE SURE YOU GET AN AUTHENTIC COPY because the sites file contains
 132 public keys for all the sites in the VPN.  Use the make-secnet-sites
 133 program provided with the secnet distribution to convert the
 134 distributed sites file into one that can be included in a secnet
 135 configuration file:
 136
 137 # make-secnet-sites /etc/secnet/sites /etc/secnet/sites.conf
 138
 139 * Configuration
 140
 141 Should be reasonably obvious - edit /etc/secnet/secnet.conf as
 142 prompted by the comments in example.conf.  XXX Fuller documentation of
 143 the configuration file format should be forthcoming in time.  Its
 144 syntax is described in the README file at the moment.
 145
 146 * Constructing your site file fragment
 147
 148 You need the following information:
 149
 150 1. the name of your VPN.
 151
 152 2. the name of your location(s).
 153
 154 3. a short name for your site, eg. "sinister".  This is used to
 155 identify your site in the vpn-sites file, and should probably be the
 156 same as its hostname.
 157
 158 4. the DNS name of the machine that will be the "front-end" for your
 159 secnet installation.  This will typically be the name of the gateway
 160 machine for your network, eg. sinister.dynamic.greenend.org.uk
 161
 162 secnet does not actually have to run on this machine, as long as the
 163 machine can be configured to forward UDP packets to the machine that
 164 is running secnet.
 165
 166 5. the port number used to contact secnet at your site.  This is the
 167 port number on the front-end machine, and does not necessarily have to
 168 match the port number on the machine running secnet.  If you want to
 169 use a privileged port number we suggest 410.  An appropriate
 170 unprivileged port number is 51396.
 171
 172 6. the list of networks accessible at your site over the VPN.
 173
 174 7. the public part of the RSA key you generated during installation
 175 (in /etc/secnet/key.pub if you followed the installation
 176 instructions).  This file contains three numbers and a comment on one
 177 line.
 178
 179 If you are running secnet on a particularly slow machine, you may like
 180 to specify a larger value for the key setup retry timeout than the
 181 default, to prevent unnecessary retransmissions of key setup packets.
 182 See the notes in the example configuration file for more on this.
 183
 184 The site file fragment should look something like this:
 185
 186 vpn sgo
 187 location greenend
 188 contact steve@greenend.org.uk
 189 site sinister
 190   networks 192.168.73.0/24 192.168.1.0/24 172.19.71.0/24
 191   address sinister.dynamic.greenend.org.uk 51396
 192   pubkey 1024 35 142982503......[lots more].....0611 steve@sinister