chiark / gitweb /
Static buffers: ipaddr_getbuf: Rename some variables
[secnet.git] / 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 [On BSD use
118 $ LDFLAGS="-L/usr/local/lib" ./configure
119 $ gmake CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"
120 XXX this should eventually be worked out automatically by 'configure'.]
121
122 Generate a site file fragment for your site (see your VPN's
123 documentation, or see below), and submit it for inclusion in your
124 VPN's 'sites' file.  Download the vpn-sites file to /etc/secnet/sites
125 - MAKE SURE YOU GET AN AUTHENTIC COPY because the sites file contains
126 public keys for all the sites in the VPN.  Use the make-secnet-sites
127 program provided with the secnet distribution to convert the
128 distributed sites file into one that can be included in a secnet
129 configuration file:
130
131 # make-secnet-sites /etc/secnet/sites /etc/secnet/sites.conf
132
133 * Configuration
134
135 Should be reasonably obvious - edit /etc/secnet/secnet.conf as
136 prompted by the comments in example.conf.  XXX Fuller documentation of
137 the configuration file format should be forthcoming in time.  Its
138 syntax is described in the README file at the moment.
139
140 * Constructing your site file fragment
141
142 You need the following information:
143
144 1. the name of your VPN.
145
146 2. the name of your location(s).
147
148 3. a short name for your site, eg. "sinister".  This is used to
149 identify your site in the vpn-sites file, and should probably be the
150 same as its hostname.
151
152 4. the DNS name of the machine that will be the "front-end" for your
153 secnet installation.  This will typically be the name of the gateway
154 machine for your network, eg. sinister.dynamic.greenend.org.uk
155
156 secnet does not actually have to run on this machine, as long as the
157 machine can be configured to forward UDP packets to the machine that
158 is running secnet.
159
160 5. the port number used to contact secnet at your site.  This is the
161 port number on the front-end machine, and does not necessarily have to
162 match the port number on the machine running secnet.  If you want to
163 use a privileged port number we suggest 410.  An appropriate
164 unprivileged port number is 51396.
165
166 6. the list of networks accessible at your site over the VPN.
167
168 7. the public part of the RSA key you generated during installation
169 (in /etc/secnet/key.pub if you followed the installation
170 instructions).  This file contains three numbers and a comment on one
171 line.
172
173 If you are running secnet on a particularly slow machine, you may like
174 to specify a larger value for the key setup retry timeout than the
175 default, to prevent unnecessary retransmissions of key setup packets.
176 See the notes in the example configuration file for more on this.
177
178 The site file fragment should look something like this:
179
180 vpn sgo
181 location greenend
182 contact steve@greenend.org.uk
183 site sinister
184   networks 192.168.73.0/24 192.168.1.0/24 172.19.71.0/24
185   address sinister.dynamic.greenend.org.uk 51396
186   pubkey 1024 35 142982503......[lots more].....0611 steve@sinister