X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=secnet.git;a=blobdiff_plain;f=INSTALL;h=08eac9a0ec8dd4b73ec6e5deaf494d48278d7607;hp=8ad676f3766d0174b6aace6e19b30831c9a43090;hb=78d458950e6cec7e8fce890362e54e4e9ba5c635;hpb=9d3a4132788b198345116624761c12ed7bc936b6 diff --git a/INSTALL b/INSTALL index 8ad676f..08eac9a 100644 --- a/INSTALL +++ b/INSTALL @@ -4,11 +4,6 @@ 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 @@ -16,7 +11,7 @@ THERE WILL BE ANOTHER CHANGE IN PROTOCOL IN THE secnet-0.1.x SERIES 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 and /usr/ports/devel/libgnugetopt] +[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 @@ -32,12 +27,6 @@ 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 @@ -45,17 +34,27 @@ for it to run as once it's ready to drop its privileges. Example (on Debian): # adduser --system --no-create-home secnet -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 -could possibly be allocated from the range used by your internal -network: if you do this, you should think about providing appropriate +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. +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. @@ -73,10 +72,32 @@ $ make # mkdir /etc/secnet (Note: you may see the following warning while compiling -conffile.tab.c; I believe this is a bison bug: +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 @@ -86,36 +107,44 @@ If installing for the first time, do # cp example.conf /etc/secnet/secnet.conf # cd /etc/secnet -# ssh-keygen -f key -N "" +# ssh-keygen -f key -t rsa1 -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. +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 * 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. +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: -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 +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 @@ -123,18 +152,18 @@ 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 -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 instructions). This file contains three numbers and a comment on one -line. The first number is the key length in bits, and should be -ignored. The second number (typically small) is the encryption key -'e', and the third number (large) is the modulus 'n'. +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 @@ -143,12 +172,10 @@ See the notes in the example configuration file for more on 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"); - }; - -See 'example-sites-file' for more examples. +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