Commit | Line | Data |
---|---|---|
2fe58dfd SE |
1 | INSTALLATION INSTRUCTIONS for SECNET |
2 | ||
974d0468 | 3 | USE AT YOUR OWN RISK. THIS IS ALPHA TEST SOFTWARE. I DO NOT |
df1b18fc SE |
4 | GUARANTEE THAT THERE WILL BE PROTOCOL COMPATIBILITY BETWEEN DIFFERENT |
5 | VERSIONS. | |
6 | ||
7 | * Preparation | |
8 | ||
9 | ** System software support | |
10 | ||
962c66f5 | 11 | Ensure that you have libgmp3-dev and adns installed (and bison and |
2fe58dfd SE |
12 | flex, and for that matter gcc...). |
13 | ||
8dea8d37 | 14 | [On BSD install /usr/ports/devel/bison] |
59635212 | 15 | |
2fe58dfd | 16 | If you intend to configure secnet to obtain packets from the kernel |
974d0468 | 17 | through userv-ipif, install and configure userv-ipif. It is part of |
2fe58dfd SE |
18 | userv-utils, available from ftp.chiark.greenend.org.uk in |
19 | /users/ian/userv | |
20 | ||
4efd681a SE |
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 | |
974d0468 SE |
23 | kernel (it's under "network device support" in Linux-2.4) and that |
24 | you've created the appropriate device files; see | |
4efd681a SE |
25 | linux/Documentation/networking/tuntap.txt |
26 | ||
df1b18fc | 27 | If you're using TUN/TAP on a platform other than Linux-2.4, see |
4efd681a SE |
28 | http://vtun.sourceforge.net/tun/ |
29 | ||
71d65e4c IJ |
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 | ||
df1b18fc SE |
35 | ** System and network configuration |
36 | ||
974d0468 SE |
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 | |
df1b18fc SE |
39 | Debian): |
40 | # adduser --system --no-create-home secnet | |
41 | ||
b2a56f7c SE |
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 | ||
794f2398 SE |
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. | |
df1b18fc SE |
63 | |
64 | http://www.ucam.org/cam-grin/ may be useful. | |
65 | ||
df1b18fc SE |
66 | * Installation |
67 | ||
9d3a4132 SE |
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 | ||
df1b18fc | 72 | To install secnet do |
2fe58dfd SE |
73 | |
74 | $ ./configure | |
75 | $ make | |
974d0468 | 76 | # make install |
9d3a4132 | 77 | # mkdir /etc/secnet |
8689b3a9 | 78 | |
558fa3fb | 79 | (Note: you may see the following warning while compiling |
794f2398 | 80 | conffile.tab.c; this is a bug in bison-1.28: |
558fa3fb SE |
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 | |
794f2398 SE |
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) | |
558fa3fb SE |
106 | ) |
107 | ||
108 | Any other warnings or errors should be reported to | |
109 | steve@greenend.org.uk. | |
110 | ||
8689b3a9 SE |
111 | If installing for the first time, do |
112 | ||
2fe58dfd SE |
113 | # cp example.conf /etc/secnet/secnet.conf |
114 | # cd /etc/secnet | |
3b83c932 | 115 | # ssh-keygen -f key -t rsa1 -N "" |
2fe58dfd | 116 | |
8689b3a9 SE |
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'.] | |
2fe58dfd | 121 | |
794f2398 SE |
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: | |
b2a56f7c | 130 | |
794f2398 | 131 | # make-secnet-sites /etc/secnet/sites /etc/secnet/sites.conf |
2fe58dfd | 132 | |
df1b18fc | 133 | * Configuration |
2fe58dfd | 134 | |
df1b18fc | 135 | Should be reasonably obvious - edit /etc/secnet/secnet.conf as |
794f2398 SE |
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. | |
df1b18fc SE |
139 | |
140 | * Constructing your site file fragment | |
2fe58dfd SE |
141 | |
142 | You need the following information: | |
143 | ||
b2a56f7c | 144 | 1. the name of your VPN. |
2fe58dfd | 145 | |
b2a56f7c | 146 | 2. the name of your location(s). |
2fe58dfd | 147 | |
b2a56f7c SE |
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 | |
974d0468 | 153 | secnet installation. This will typically be the name of the gateway |
9d3a4132 | 154 | machine for your network, eg. sinister.dynamic.greenend.org.uk |
2fe58dfd SE |
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 | ||
b2a56f7c | 160 | 5. the port number used to contact secnet at your site. This is the |
2fe58dfd | 161 | port number on the front-end machine, and does not necessarily have to |
b2a56f7c SE |
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 | |
ff05a229 | 164 | unprivileged port number is 51396. |
2fe58dfd | 165 | |
b2a56f7c | 166 | 6. the list of networks accessible at your site over the VPN. |
2fe58dfd | 167 | |
b2a56f7c | 168 | 7. the public part of the RSA key you generated during installation |
2fe58dfd | 169 | (in /etc/secnet/key.pub if you followed the installation |
974d0468 | 170 | instructions). This file contains three numbers and a comment on one |
b2a56f7c | 171 | line. |
2fe58dfd SE |
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 | |
974d0468 SE |
175 | default, to prevent unnecessary retransmissions of key setup packets. |
176 | See the notes in the example configuration file for more on this. | |
2fe58dfd SE |
177 | |
178 | The site file fragment should look something like this: | |
179 | ||
b2a56f7c SE |
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 |