Import release 0.1.10

[secnet] / INSTALL

INSTALLATION INSTRUCTIONS for SECNET

USE AT YOUR OWN RISK.  THIS IS ALPHA TEST SOFTWARE.  I DO NOT
GUARANTEE THAT THERE WILL BE PROTOCOL COMPATIBILITY BETWEEN DIFFERENT
VERSIONS.

PROTOCOL COMPATIBILITY WAS BROKEN BETWEEN secnet-0.06, secnet-0.07 AND
secnet-0.08 FOR ENDIANNESS FIXES.

THERE WILL BE ANOTHER CHANGE IN PROTOCOL IN THE secnet-0.1.x SERIES

* Preparation

** System software support

Ensure that you have libgmp2-dev and adns installed (and bison and
flex, and for that matter gcc...).

[On BSD install /usr/ports/devel/bison]

If you intend to configure secnet to obtain packets from the kernel
through userv-ipif, install and configure userv-ipif.  It is part of
userv-utils, available from ftp.chiark.greenend.org.uk in
/users/ian/userv

If you intend to configure secnet to obtain packets from the kernel
using the universal TUN/TAP driver, make sure it's configured in your
kernel (it's under "network device support" in Linux-2.4) and that
you've created the appropriate device files; see
linux/Documentation/networking/tuntap.txt

If you're using TUN/TAP on a platform other than Linux-2.4, see
http://vtun.sourceforge.net/tun/

Note than TUN comes in two flavours, one (called 'tun' in the secnet
config file) which has only one device file (usually /dev/net/tun) and
the other (called 'tun-old') which has many device files (/dev/tun*).
Linux-2.4 has new-style TUN, Linux-2.2, BSD and Solaris have old-style
TUN.

** System and network configuration

If you intend to start secnet as root, I suggest you create a userid
for it to run as once it's ready to drop its privileges.  Example (on
Debian):
# adduser --system --no-create-home secnet

If you're using the 'soft routes' feature (for some classes of mobile
device) you'll have to run as root all the time, to enable secnet to
add and remove routes from your kernel's routing table.  (This
restriction may be relaxed later if someone writes a userv service to
modify the routing table.)

If you are joining an existing VPN, read that VPN's documentation now.
It may supersede the next paragraph.

You will need to allocate two IP addresses for use by secnet.  One
will be for the tunnel interface on your tunnel endpoint machine (i.e.
the address you see in 'ifconfig' when you look at the tunnel
interface).  The other will be for secnet itself.  These addresses
should probably be allocated from the range used by your internal
network: if you do this, you should provide appropriate proxy-ARP on
the internal network interface of the machine running secnet (eg. add
an entry net/ipv4/conf/eth_whatever/proxy_arp = 1 to /etc/sysctl.conf
on Debian systems and run sysctl -p).  Alternatively the addresses
could be from some other range - this works well if the machine
running secnet is the default route out of your network - but this
requires more thought.

http://www.ucam.org/cam-grin/ may be useful.

* Installation

If you installed the Debian package of secnet, skip to "If installing
for the first time", below, and note that example.conf can be found in
/usr/share/doc/secnet/examples.

To install secnet do

$ ./configure
$ make
# make install
# mkdir /etc/secnet

(Note: you may see the following warning while compiling
conffile.tab.c; I believe this is a bison bug:
/usr/share/bison/bison.simple: In function `yyparse':
/usr/share/bison/bison.simple:285: warning: `yyval' might be used
 uninitialized in this function
)

Any other warnings or errors should be reported to
steve@greenend.org.uk.

If installing for the first time, do

# cp example.conf /etc/secnet/secnet.conf
# cd /etc/secnet
# ssh-keygen -f key -N ""

[On BSD use
$ LDFLAGS="-L/usr/local/lib" ./configure
$ gmake CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"
XXX this should eventually be worked out automatically by 'configure'.]

Generate a site file fragment for your site (see below), and submit it
for inclusion in your VPN's 'sites' file.  Download the vpn-sites file
to /etc/secnet/sites - MAKE SURE YOU GET AN AUTHENTIC COPY because the
sites file contains public keys for all the sites in the VPN.  Use the
make-secnet-sites program provided with the secnet distribution to
convert the distributed sites file into one that can be included in a
secnet configuration file:

# make-secnet-sites sites sites.conf

* Configuration

Should be reasonably obvious - edit /etc/secnet/secnet.conf as
prompted by the comments.  XXX Fuller documentation of the
configuration file format should be forthcoming in time.  Its syntax
is described in the README file at the moment.

* Constructing your site file fragment

You need the following information:

1. the name of your VPN.

2. the name of your location(s).

3. a short name for your site, eg. "sinister".  This is used to
identify your site in the vpn-sites file, and should probably be the
same as its hostname.

4. the DNS name of the machine that will be the "front-end" for your
secnet installation.  This will typically be the name of the gateway
machine for your network, eg. sinister.dynamic.greenend.org.uk

secnet does not actually have to run on this machine, as long as the
machine can be configured to forward UDP packets to the machine that
is running secnet.

5. the port number used to contact secnet at your site.  This is the
port number on the front-end machine, and does not necessarily have to
match the port number on the machine running secnet.  If you want to
use a privileged port number we suggest 410.  An appropriate
unprivileged port number is 51396.  (These numbers were picked at
random.)

6. the list of networks accessible at your site over the VPN.

7. the public part of the RSA key you generated during installation
(in /etc/secnet/key.pub if you followed the installation
instructions).  This file contains three numbers and a comment on one
line.

If you are running secnet on a particularly slow machine, you may like
to specify a larger value for the key setup retry timeout than the
default, to prevent unnecessary retransmissions of key setup packets.
See the notes in the example configuration file for more on this.

The site file fragment should look something like this:

vpn sgo
location greenend
contact steve@greenend.org.uk
site sinister
  networks 192.168.73.0/24 192.168.1.0/24 172.19.71.0/24
  address sinister.dynamic.greenend.org.uk 51396
  pubkey 1024 35 142982503......[lots more].....0611 steve@sinister