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