chiark / gitweb /
netlink: Plumb "sender" through to ICMP generation
[secnet.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 88b1cdb..c0236bc 100644 (file)
--- a/INSTALL
+++ b/INSTALL
 INSTALLATION INSTRUCTIONS for SECNET
 
 INSTALLATION INSTRUCTIONS for SECNET
 
-Ensure that you have libgmp2-dev and adns installed (and bison and
+USE AT YOUR OWN RISK.  THIS IS ALPHA TEST SOFTWARE.  I DO NOT
+GUARANTEE THAT THERE WILL BE PROTOCOL COMPATIBILITY BETWEEN DIFFERENT
+VERSIONS.
+
+* Preparation
+
+** System software support
+
+Ensure that you have libgmp3-dev and adns installed (and bison and
 flex, and for that matter gcc...).
 
 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
 If you intend to configure secnet to obtain packets from the kernel
-through userv-ipif, install and configure userv-ipif. It is part of
+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
 
 userv-utils, available from ftp.chiark.greenend.org.uk in
 /users/ian/userv
 
-Then, to install secnet do
+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/
+
+** 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.
+
+In most configurations, 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
 
 $ ./configure
 $ make
-# cp secnet /usr/local/sbin/secnet
+# make install
 # mkdir /etc/secnet
 # mkdir /etc/secnet
+
+(Note: you may see the following warning while compiling
+conffile.tab.c; this is a bug in bison-1.28:
+/usr/share/bison/bison.simple: In function `yyparse':
+/usr/share/bison/bison.simple:285: warning: `yyval' might be used
+ uninitialized in this function
+
+You may if you wish apply the following patch to bison.simple:
+diff -pu -r1.28.0.1 -r1.28.0.3
+--- bison.s1    1999/08/30 19:23:24     1.28.0.1
++++ bison.s1    1999/08/30 21:15:18     1.28.0.3
+@@ -523,8 +523,14 @@ yydefault:
+ /* Do a reduction.  yyn is the number of a rule to reduce with.  */
+ yyreduce:
+   yylen = yyr2[yyn];
+-  if (yylen > 0)
+-    yyval = yyvsp[1-yylen]; /* implement default value of the action */
++
++  /* If yylen is nonzero, implement the default value of the action.
++     Otherwise, the following line sets yyval to the semantic value of
++     the lookahead token.  This behavior is undocumented and bison
++     users should not rely upon it.  Assigning to yyval
++     unconditionally makes the parser a bit smaller, and it avoids a
++     GCC warning that yyval may be used uninitialized.  */
++  yyval = yyvsp[1-yylen];
+ #if YYDEBUG != 0
+   if (yydebug)
+)
+
+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
 # cp example.conf /etc/secnet/secnet.conf
 # cd /etc/secnet
-# ssh-keygen -f key -N ""
+# ssh-keygen -f key -t rsa1 -N ""
 
 
-(When upgrading, just install the new /usr/local/sbin/secnet; keep
-your current configuration file.)
+[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'.]
 
 
-If you intend to start secnet as root, I suggest you create an userid
-for it to run as once it's ready to drop its privileges. Example:
-# adduser --system --no-create-home secnet
+Generate a site file fragment for your site (see your VPN's
+documentation, or 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 /etc/secnet/sites /etc/secnet/sites.conf
 
 
-Generate a site file fragment for your site, and submit it for
-inclusion in the vpn-sites file. Download the vpn-sites file.
+* Configuration
 
 
-* Constructing a site file fragment
+Should be reasonably obvious - edit /etc/secnet/secnet.conf as
+prompted by the comments in example.conf.  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:
 
 
 You need the following information:
 
-1.  a short name for your site, eg. "greenend". This is used to
-identify your site in the vpn-sites file.
+1. the name of your VPN.
+
+2. the name of your location(s).
 
 
-2.  the name your site will use in the key setup protocol,
-eg. "greenend" (these two will usually be similar or the same).
+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.
 
 
-3.  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
+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.
 
 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.
 
-4.  the port number used to contact secnet at your site. This is the
+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
 port number on the front-end machine, and does not necessarily have to
-match the port number on the machine running secnet.
+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.
 
 
-5.  the list of networks accessible at your site over the VPN.
+6. the list of networks accessible at your site over the VPN.
 
 
-6.  the public part of the RSA key you generated during installation
+7. the public part of the RSA key you generated during installation
 (in /etc/secnet/key.pub if you followed the installation
 (in /etc/secnet/key.pub if you followed the installation
-instructions). This file contains three numbers and a comment on one
-line. The first number is the key length in bits, and can be
-ignored. The second number (typically small) is the encryption key
-'e', and the third number (large) is the modulus 'n'.
+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
 
 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.
+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:
 
 
 The site file fragment should look something like this:
 
-shortname {
-               name "sitename";
-               address "your.public.address.org.uk";
-               port 5678;
-               networks "172.18.45.0/24";
-               key rsa-public("35","153279875126380522437827076871354104097683702803616313419670959273217685015951590424876274370401136371563604396779864283483623325238228723798087715987495590765759771552692972297669972616769731553560605291312242789575053620182470998166393580503400960149506261455420521811814445675652857085993458063584337404329");
-       };
+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