Commit | Line | Data |
---|---|---|
558fa3fb SE |
1 | secnet - flexible VPN software |
2 | ||
8dea8d37 SE |
3 | * Copying |
4 | ||
5 | secnet is Copyright (C) 1995--2001 Stephen Early <steve@greenend.org.uk> | |
6 | It is distributed under the terms of the GNU General Public License, | |
7 | version 2 or later. See the file COPYING for more information. | |
8 | ||
9 | The portable snprintf implementation in snprintf.c is Copyright (C) | |
10 | 1999 Mark Martinec <mark.martinec@ijs.si> and is distributed under the | |
11 | terms of the Frontier Artistic License. You can find the standard | |
12 | version of snprintf.c at http://www.ijs.si/software/snprintf/ | |
13 | ||
14 | The IP address handling library in ipaddr.py is Copyright (C) | |
15 | 1996--2000 Cendio Systems AB, and is distributed under the terms of | |
16 | the GPL. | |
17 | ||
558fa3fb SE |
18 | * Introduction |
19 | ||
20 | secnet allows large virtual private networks to be constructed | |
21 | spanning multiple separate sites. It is designed for the case where a | |
22 | private network connecting many hosts is 'hidden' behind a single | |
23 | globally-routable IP address, but can also be applied in other | |
24 | circumstances. It communicates entirely using UDP, and works well | |
25 | with gateways that implement network address translation. | |
26 | ||
27 | If you are installing secnet to join an existing VPN, you should read | |
28 | the 'INSTALL' file and your particular VPN's documentation now. You | |
29 | may need to refer back to this file for information on the netlink and | |
30 | comm sections of the configuration file. | |
31 | ||
32 | If you are thinking about setting up a new VPN of any size (from one | |
33 | providing complete links between multiple sites to a simple | |
34 | laptop-to-host link), read the section in this file on 'Creating a | |
35 | VPN'. | |
36 | ||
469fd1d9 SE |
37 | * Mailing lists and bug reporting |
38 | ||
39 | There are two mailing lists associated with secnet: an 'announce' list | |
40 | and a 'discuss' list. Their addresses are: | |
41 | http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-announce | |
42 | http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-discuss | |
43 | ||
44 | The -announce list receives one message per secnet release. The | |
45 | -discuss list is for general discussion, including help with | |
46 | configuration, bug reports, feature requests, etc. | |
47 | ||
48 | Bug reports should be sent to <steve@greenend.org.uk>; they will be | |
49 | forwarded to the -discuss list by me. | |
50 | ||
558fa3fb SE |
51 | * Creating a VPN |
52 | ||
53 | XXX TODO | |
54 | ||
55 | * secnet configuration file format | |
56 | ||
57 | By default secnet on linux reads /etc/secnet/secnet.conf. The default | |
58 | may be different on other platforms. | |
59 | ||
60 | This file defines a dictionary (a mapping from keys to values) full of | |
61 | configuration information for secnet. Two keys must be defined in | |
62 | this file for secnet to start. One is "system", a dictionary | |
63 | containing systemwide control parameters. The other is "sites", a | |
64 | list of all the sites that you intend to communicate with. | |
65 | ||
66 | The configuration file has a very simple syntax; keys are defined as | |
67 | follows: | |
68 | ||
69 | key definition; | |
70 | or | |
71 | key = definition; | |
72 | ||
73 | (the "=" is optional) | |
74 | ||
75 | Keys must match the following regular expression: | |
76 | [[:alpha:]_][[:alnum:]\-_]* | |
77 | ||
78 | i.e. the first character must be an alpha or an underscore, and the | |
79 | remaining characters may be alphanumeric, '-' or '_'. | |
80 | ||
81 | Keys can be defined to be a comma-separated list of any of the | |
82 | following types: | |
83 | ||
84 | a boolean | |
85 | a string, in quotes | |
86 | a number, in decimal | |
87 | a dictionary of definitions, enclosed in { } | |
88 | a "closure", followed by arguments | |
89 | a path to a key that already exists, to reference that definition | |
90 | ||
91 | Note that dictionaries can be nested: a key in one dictionary can | |
92 | refer to another dictionary. When secnet looks for a key in a | |
93 | particular directory and can't find it, it looks in the dictionary's | |
94 | lexical 'parents' in turn until it finds it (or fails to find it at | |
95 | all and stops with an error). | |
96 | ||
97 | Definitions can refer to previous definitions by naming them with a | |
98 | path. Paths are key1/key2/key3... (starting from wherever we find | |
99 | key1, i.e. in the current dictionary or any of its parents), or | |
100 | alternatively /key1/key2/key3... (to start from the root). | |
101 | Definitions cannot refer to future definitions. | |
102 | ||
103 | Example: | |
104 | ||
105 | a=1; | |
106 | b=2; | |
107 | c={ d=3; e=a; }; | |
108 | f={ a=4; g=c; }; | |
109 | ||
110 | The following paths are valid: | |
111 | a is 1 | |
112 | b is 2 | |
113 | c is a dictionary: | |
114 | c/d is 3 | |
115 | c/e is 1 | |
116 | f is a dictionary: | |
117 | f/a is 4 | |
118 | f/g is a dictionary: | |
119 | f/g/d is 3 | |
120 | f/g/e is 1 | |
121 | ||
122 | Note that f/g/e is NOT 4. | |
123 | ||
124 | In a future version of secnet it will also be permissible to list | |
125 | other dictionaries before a dictionary definition, | |
126 | eg. <defaults,otherdefaults>{definitions}. These will be searched in | |
127 | order for keys, before the lexical parent. (This is not yet | |
128 | implemented) | |
129 | ||
130 | Elements that are lists are inserted into lists in definitions, not | |
131 | referenced by them (i.e. you can't have lists of lists). | |
132 | ||
133 | Some closures may be followed by an argument list in ( ), and may | |
134 | return any number of whatever type they like (including other | |
135 | closures). Some types of closure (typically those returned from | |
136 | invokations of other closures) cannot be invoked. | |
137 | ||
138 | closure { definitions } is short for closure({definitions}). | |
139 | ||
140 | The main body of secnet, and all the additional modules, predefine | |
141 | some keys in the root dictionary. The main ones are: | |
142 | ||
143 | yes, true, True, TRUE: the boolean value True | |
144 | no, false, False, FALSE: the boolean value False | |
145 | makelist: turns a dictionary (arg1) into a list of definitions | |
146 | (ignoring the keys) | |
147 | readfile: reads a file (arg1) and returns it as a string | |
148 | ||
149 | Keys defined by modules are described below, in the module | |
150 | documentation. | |
151 | ||
152 | Other configuration files can be included inline by writing "include | |
153 | filename" at the start of a line. | |
154 | ||
155 | After the configuration file is read, secnet looks for particular keys | |
156 | in configuration space to tell it what to do: | |
157 | ||
158 | system: a dictionary which can contain the following keys: | |
159 | log (log closure): a destination for system messages | |
160 | userid (string): the userid for secnet to run as once it drops privileges | |
161 | pidfile (string): where to store its PID | |
162 | ||
163 | sites: a list of closures of type 'site', which define other tunnel | |
164 | endpoints that secnet will attempt to communicate with | |
165 | ||
166 | * secnet command line options | |
167 | ||
469fd1d9 SE |
168 | Usage: secnet [OPTION]... |
169 | ||
170 | -f, --silent, --quiet suppress error messages | |
171 | -w, --nowarnings suppress warnings | |
172 | -v, --verbose output extra diagnostics | |
173 | -c, --config=filename specify a configuration file | |
174 | -j, --just-check-config stop after reading configfile | |
175 | -n, --nodetach do not run in background | |
176 | -d, --debug=item,... set debug options | |
177 | --help display this help and exit | |
178 | --version output version information and exit | |
558fa3fb SE |
179 | |
180 | * secnet builtin modules | |
181 | ||
182 | ** resolver | |
183 | ||
184 | Defines: | |
185 | adns (closure => resolver closure) | |
186 | ||
3454dce4 SE |
187 | adns: dict argument |
188 | config (string): optional, a resolv.conf for ADNS to use | |
189 | ||
558fa3fb SE |
190 | ** random |
191 | ||
192 | Defines: | |
193 | randomsrc (closure => randomsrc closure) | |
194 | ||
3454dce4 SE |
195 | randomsrc: string[,bool] |
196 | arg1: filename of random source | |
197 | arg2: if True then source is blocking | |
198 | ||
558fa3fb SE |
199 | ** udp |
200 | ||
201 | Defines: | |
202 | udp (closure => comm closure) | |
203 | ||
3454dce4 SE |
204 | udp: dict argument |
205 | port (integer): UDP port to listen and send on | |
206 | buffer (buffer closure): buffer for incoming packets | |
b2a56f7c | 207 | authbind (string): optional, path to authbind-helper program |
3454dce4 | 208 | |
042a8da9 | 209 | ** log |
558fa3fb SE |
210 | |
211 | Defines: | |
212 | logfile (closure => log closure) | |
b2a56f7c | 213 | syslog (closure => log closure) |
558fa3fb | 214 | |
b2a56f7c SE |
215 | logfile: dict argument |
216 | filename (string): where to log to | |
217 | class (string list): what type of messages to log | |
218 | { "debug-config", M_DEBUG_CONFIG }, | |
219 | { "debug-phase", M_DEBUG_PHASE }, | |
220 | { "debug", M_DEBUG }, | |
221 | { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG }, | |
222 | { "info", M_INFO }, | |
223 | { "notice", M_NOTICE }, | |
224 | { "warning", M_WARNING }, | |
225 | { "error", M_ERROR }, | |
226 | { "security", M_SECURITY }, | |
227 | { "fatal", M_FATAL }, | |
228 | { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL }, | |
229 | { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL }, | |
230 | { "quiet", M_FATAL } | |
231 | ||
042a8da9 SE |
232 | logfile will close and reopen its file upon receipt of SIGHUP. |
233 | ||
b2a56f7c SE |
234 | syslog: dict argument |
235 | ident (string): include this string in every log message | |
236 | facility (string): facility to log as | |
237 | { "authpriv", LOG_AUTHPRIV }, | |
238 | { "cron", LOG_CRON }, | |
239 | { "daemon", LOG_DAEMON }, | |
240 | { "kern", LOG_KERN }, | |
241 | { "local0", LOG_LOCAL0 }, | |
242 | { "local1", LOG_LOCAL1 }, | |
243 | { "local2", LOG_LOCAL2 }, | |
244 | { "local3", LOG_LOCAL3 }, | |
245 | { "local4", LOG_LOCAL4 }, | |
246 | { "local5", LOG_LOCAL5 }, | |
247 | { "local6", LOG_LOCAL6 }, | |
248 | { "local7", LOG_LOCAL7 }, | |
249 | { "lpr", LOG_LPR }, | |
250 | { "mail", LOG_MAIL }, | |
251 | { "news", LOG_NEWS }, | |
252 | { "syslog", LOG_SYSLOG }, | |
253 | { "user", LOG_USER }, | |
254 | { "uucp", LOG_UUCP } | |
255 | ||
042a8da9 SE |
256 | ** util |
257 | ||
258 | Defines: | |
259 | sysbuffer (closure => buffer closure) | |
260 | ||
b2a56f7c SE |
261 | sysbuffer: integer[,dict] |
262 | arg1: buffer length | |
263 | arg2: options: | |
264 | lockdown (boolean): if True, mlock() the buffer | |
265 | ||
558fa3fb SE |
266 | ** site |
267 | ||
268 | Defines: | |
269 | site (closure => site closure) | |
270 | ||
3454dce4 SE |
271 | site: dict argument |
272 | local-name (string): this site's name for itself | |
273 | name (string): the name of the site's peer | |
469fd1d9 | 274 | link (netlink closure) |
3454dce4 SE |
275 | comm (comm closure) |
276 | resolver (resolver closure) | |
277 | random (randomsrc closure) | |
278 | local-key (rsaprivkey closure) | |
279 | address (string): optional, DNS name used to find our peer | |
280 | port (integer): mandatory if 'address' is specified: the port used | |
281 | to contact our peer | |
3454dce4 SE |
282 | key (rsapubkey closure): our peer's public key |
283 | transform (transform closure): how to mangle packets sent between sites | |
284 | dh (dh closure) | |
285 | hash (hash closure) | |
286 | key-lifetime (integer): max lifetime of a session key, in ms [one hour] | |
287 | setup-retries (integer): max number of times to transmit a key negotiation | |
288 | packet [5] | |
289 | setup-timeout (integer): time between retransmissions of key negotiation | |
290 | packets, in ms [1000] | |
291 | wait-time (integer): after failed key setup, wait this long (in ms) before | |
292 | allowing another attempt [20000] | |
293 | renegotiate-time (integer): if we see traffic on the link after this time | |
294 | then renegotiate another session key immediately [depends on key-lifetime] | |
295 | keepalive (bool): if True then attempt always to keep a valid session key | |
296 | log-events (string list): types of events to log for this site | |
297 | unexpected: unexpected key setup packets (may be late retransmissions) | |
298 | setup-init: start of attempt to setup a session key | |
299 | setup-timeout: failure of attempt to setup a session key, through timeout | |
300 | activate-key: activation of a new session key | |
301 | timeout-key: deletion of current session key through age | |
302 | security: anything potentially suspicious | |
303 | state-change: steps in the key setup protocol | |
304 | packet-drop: whenever we throw away an outgoing packet | |
305 | dump-packets: every key setup packet we see | |
306 | errors: failure of name resolution, internal errors | |
307 | all: everything (too much!) | |
3454dce4 | 308 | |
558fa3fb SE |
309 | ** transform |
310 | ||
311 | Defines: | |
312 | serpent256-cbc (closure => transform closure) | |
313 | ||
314 | ** netlink | |
315 | ||
316 | Defines: | |
469fd1d9 | 317 | null-netlink (closure => closure or netlink closure) |
3454dce4 SE |
318 | |
319 | null-netlink: dict argument | |
320 | name (string): name for netlink device, used in log messages | |
321 | networks (string list): networks on the host side of the netlink device | |
322 | exclude-remote-networks (string list): networks that may never be claimed | |
323 | by any remote site using this netlink device | |
324 | local-address (string): IP address of host's tunnel interface | |
325 | secnet-address (string): IP address of this netlink device | |
c6f79b17 | 326 | ptp-address (string): IP address of the other end of a point-to-point link |
3454dce4 SE |
327 | mtu (integer): MTU of host's tunnel interface |
328 | ||
469fd1d9 SE |
329 | Only one of secnet-address or ptp-address may be specified. If |
330 | point-to-point mode is in use then the "routes" option must also be | |
331 | specified, and netlink returns a netlink closure that should be used | |
332 | directly with the "link" option to the site closure. If | |
333 | point-to-point mode is not in use then netlink returns a closure that | |
334 | may be invoked using a dict argument with the following keys to yield | |
335 | a netlink closure: | |
336 | routes (string list): networks reachable down the tunnel attached to | |
337 | this instance of netlink | |
338 | options (string list): | |
339 | allow-route: allow packets coming from this tunnel to be routed to | |
340 | other tunnels as well as the host (used for mobile devices like laptops) | |
341 | soft-route: remove these routes from the host's routing table when | |
342 | the tunnel link quality is zero | |
ff05a229 | 343 | mtu (integer): default MTU over this link; may be updated by tunnel code |
c6f79b17 | 344 | |
042a8da9 SE |
345 | Netlink will dump its current routing table to the system/log on |
346 | receipt of SIGUSR1. | |
347 | ||
3454dce4 SE |
348 | ** slip |
349 | ||
350 | Defines: | |
558fa3fb | 351 | userv-ipif (closure => netlink closure) |
3454dce4 SE |
352 | |
353 | userv-ipif: dict argument | |
354 | userv-path (string): optional, where to find userv ["userv"] | |
355 | service-user (string): optional, username for userv-ipif service ["root"] | |
356 | service-name (string): optional, name of userv-ipif service ["ipif"] | |
357 | buffer (buffer closure): buffer for assembly of host->secnet packets | |
358 | plus generic netlink options, as for 'null-netlink' | |
359 | ||
360 | ** tun | |
361 | ||
362 | Defines: | |
558fa3fb SE |
363 | tun (closure => netlink closure) [only on linux-2.4] |
364 | tun-old (closure => netlink closure) | |
3454dce4 SE |
365 | |
366 | tun: dict argument | |
ff05a229 SE |
367 | flavour (string): optional, type of TUN interface to use |
368 | ("guess","linux","bsd","streams") | |
3454dce4 SE |
369 | device (string): optional, path of TUN/TAP device file ["/dev/net/tun"] |
370 | interface (string): optional, name of tunnel network interface | |
371 | ifconfig-path (string): optional, path to ifconfig command | |
372 | route-path (string): optional, path to route command | |
ff05a229 SE |
373 | ifconfig-type (string): optional, how to perform ifconfig |
374 | route-type (string): optional, how to add and remove routes | |
375 | types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5" | |
3454dce4 SE |
376 | buffer (buffer closure): buffer for host->secnet packets |
377 | plus generic netlink options, as for 'null-netlink' | |
378 | ||
ff05a229 SE |
379 | I recommend you don't specify the 'interface' option unless you're |
380 | doing something that requires the interface name to be constant. | |
c6f79b17 | 381 | |
558fa3fb SE |
382 | ** rsa |
383 | ||
384 | Defines: | |
385 | rsa-private (closure => rsaprivkey closure) | |
386 | rsa-public (closure => rsapubkey closure) | |
387 | ||
3454dce4 SE |
388 | rsa-private: string[,bool] |
389 | arg1: filename of SSH private key file (version 1, no password) | |
390 | arg2: whether to check that the key is usable [default True] | |
391 | ||
392 | rsa-public: string,string | |
393 | arg1: encryption key (decimal) | |
394 | arg2: modulus (decimal) | |
395 | ||
558fa3fb SE |
396 | ** dh |
397 | ||
398 | Defines: | |
399 | diffie-hellman (closure => dh closure) | |
400 | ||
3454dce4 SE |
401 | diffie-hellman: string,string[,bool] |
402 | arg1: modulus (hex) | |
403 | arg2: generator (hex) | |
404 | arg3: whether to check that the modulus is prime [default True] | |
405 | ||
558fa3fb SE |
406 | ** md5 |
407 | ||
408 | Defines: | |
409 | md5 (hash closure) | |
3454dce4 SE |
410 | |
411 | ** sha1 | |
412 | ||
413 | Defines: | |
414 | sha1 (hash closure) | |
c6f79b17 SE |
415 | |
416 | ** conffile | |
417 | ||
418 | Defines: | |
419 | makelist (dictionary => list of definitions) | |
420 | readfile (string => string) | |
421 | map (closure,list => list) | |
422 | ||
423 | makelist: dictionary | |
424 | returns a list consisting of the definitions in the dictionary. The keys | |
425 | are discarded. | |
426 | ||
427 | readfile: string | |
428 | reads the named file and returns its contents as a string | |
429 | ||
430 | map: | |
431 | applies the closure specified as arg1 to each of the elements in the list. | |
432 | Returns a list made up of the outputs of the closure. |