Commit | Line | Data |
---|---|---|
558fa3fb SE |
1 | secnet - flexible VPN software |
2 | ||
8dea8d37 SE |
3 | * Copying |
4 | ||
3b83c932 | 5 | secnet is Copyright (C) 1995--2003 Stephen Early <steve@greenend.org.uk> |
8dea8d37 SE |
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 | ||
558fa3fb SE |
124 | Elements that are lists are inserted into lists in definitions, not |
125 | referenced by them (i.e. you can't have lists of lists). | |
126 | ||
127 | Some closures may be followed by an argument list in ( ), and may | |
128 | return any number of whatever type they like (including other | |
129 | closures). Some types of closure (typically those returned from | |
130 | invokations of other closures) cannot be invoked. | |
131 | ||
132 | closure { definitions } is short for closure({definitions}). | |
133 | ||
134 | The main body of secnet, and all the additional modules, predefine | |
135 | some keys in the root dictionary. The main ones are: | |
136 | ||
fe5e9cc4 SE |
137 | yes, true, True, TRUE, on: the boolean value True |
138 | no, false, False, FALSE, off: the boolean value False | |
558fa3fb SE |
139 | makelist: turns a dictionary (arg1) into a list of definitions |
140 | (ignoring the keys) | |
141 | readfile: reads a file (arg1) and returns it as a string | |
3b83c932 SE |
142 | map: applies the closure specified as arg1 to each of the |
143 | remaining elements in the list in turn. Returns a list | |
144 | made up of the outputs of the closure. | |
558fa3fb SE |
145 | |
146 | Keys defined by modules are described below, in the module | |
147 | documentation. | |
148 | ||
149 | Other configuration files can be included inline by writing "include | |
150 | filename" at the start of a line. | |
151 | ||
152 | After the configuration file is read, secnet looks for particular keys | |
153 | in configuration space to tell it what to do: | |
154 | ||
155 | system: a dictionary which can contain the following keys: | |
156 | log (log closure): a destination for system messages | |
157 | userid (string): the userid for secnet to run as once it drops privileges | |
158 | pidfile (string): where to store its PID | |
159 | ||
160 | sites: a list of closures of type 'site', which define other tunnel | |
161 | endpoints that secnet will attempt to communicate with | |
162 | ||
163 | * secnet command line options | |
164 | ||
469fd1d9 SE |
165 | Usage: secnet [OPTION]... |
166 | ||
167 | -f, --silent, --quiet suppress error messages | |
168 | -w, --nowarnings suppress warnings | |
169 | -v, --verbose output extra diagnostics | |
170 | -c, --config=filename specify a configuration file | |
171 | -j, --just-check-config stop after reading configfile | |
172 | -n, --nodetach do not run in background | |
173 | -d, --debug=item,... set debug options | |
174 | --help display this help and exit | |
175 | --version output version information and exit | |
558fa3fb SE |
176 | |
177 | * secnet builtin modules | |
178 | ||
179 | ** resolver | |
180 | ||
181 | Defines: | |
182 | adns (closure => resolver closure) | |
183 | ||
3454dce4 SE |
184 | adns: dict argument |
185 | config (string): optional, a resolv.conf for ADNS to use | |
186 | ||
558fa3fb SE |
187 | ** random |
188 | ||
189 | Defines: | |
190 | randomsrc (closure => randomsrc closure) | |
191 | ||
3454dce4 SE |
192 | randomsrc: string[,bool] |
193 | arg1: filename of random source | |
194 | arg2: if True then source is blocking | |
195 | ||
558fa3fb SE |
196 | ** udp |
197 | ||
198 | Defines: | |
199 | udp (closure => comm closure) | |
200 | ||
3454dce4 | 201 | udp: dict argument |
3b83c932 | 202 | address (string): IP address to listen and send on |
3454dce4 SE |
203 | port (integer): UDP port to listen and send on |
204 | buffer (buffer closure): buffer for incoming packets | |
b2a56f7c | 205 | authbind (string): optional, path to authbind-helper program |
3454dce4 | 206 | |
042a8da9 | 207 | ** log |
558fa3fb SE |
208 | |
209 | Defines: | |
210 | logfile (closure => log closure) | |
b2a56f7c | 211 | syslog (closure => log closure) |
558fa3fb | 212 | |
b2a56f7c SE |
213 | logfile: dict argument |
214 | filename (string): where to log to | |
215 | class (string list): what type of messages to log | |
216 | { "debug-config", M_DEBUG_CONFIG }, | |
217 | { "debug-phase", M_DEBUG_PHASE }, | |
218 | { "debug", M_DEBUG }, | |
219 | { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG }, | |
220 | { "info", M_INFO }, | |
221 | { "notice", M_NOTICE }, | |
222 | { "warning", M_WARNING }, | |
223 | { "error", M_ERROR }, | |
224 | { "security", M_SECURITY }, | |
225 | { "fatal", M_FATAL }, | |
226 | { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL }, | |
227 | { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL }, | |
228 | { "quiet", M_FATAL } | |
229 | ||
042a8da9 SE |
230 | logfile will close and reopen its file upon receipt of SIGHUP. |
231 | ||
b2a56f7c SE |
232 | syslog: dict argument |
233 | ident (string): include this string in every log message | |
234 | facility (string): facility to log as | |
235 | { "authpriv", LOG_AUTHPRIV }, | |
236 | { "cron", LOG_CRON }, | |
237 | { "daemon", LOG_DAEMON }, | |
238 | { "kern", LOG_KERN }, | |
239 | { "local0", LOG_LOCAL0 }, | |
240 | { "local1", LOG_LOCAL1 }, | |
241 | { "local2", LOG_LOCAL2 }, | |
242 | { "local3", LOG_LOCAL3 }, | |
243 | { "local4", LOG_LOCAL4 }, | |
244 | { "local5", LOG_LOCAL5 }, | |
245 | { "local6", LOG_LOCAL6 }, | |
246 | { "local7", LOG_LOCAL7 }, | |
247 | { "lpr", LOG_LPR }, | |
248 | { "mail", LOG_MAIL }, | |
249 | { "news", LOG_NEWS }, | |
250 | { "syslog", LOG_SYSLOG }, | |
251 | { "user", LOG_USER }, | |
252 | { "uucp", LOG_UUCP } | |
253 | ||
042a8da9 SE |
254 | ** util |
255 | ||
256 | Defines: | |
257 | sysbuffer (closure => buffer closure) | |
258 | ||
b2a56f7c SE |
259 | sysbuffer: integer[,dict] |
260 | arg1: buffer length | |
261 | arg2: options: | |
262 | lockdown (boolean): if True, mlock() the buffer | |
263 | ||
558fa3fb SE |
264 | ** site |
265 | ||
266 | Defines: | |
267 | site (closure => site closure) | |
268 | ||
3454dce4 SE |
269 | site: dict argument |
270 | local-name (string): this site's name for itself | |
271 | name (string): the name of the site's peer | |
469fd1d9 | 272 | link (netlink closure) |
3454dce4 SE |
273 | comm (comm closure) |
274 | resolver (resolver closure) | |
275 | random (randomsrc closure) | |
276 | local-key (rsaprivkey closure) | |
277 | address (string): optional, DNS name used to find our peer | |
278 | port (integer): mandatory if 'address' is specified: the port used | |
279 | to contact our peer | |
3454dce4 SE |
280 | key (rsapubkey closure): our peer's public key |
281 | transform (transform closure): how to mangle packets sent between sites | |
282 | dh (dh closure) | |
283 | hash (hash closure) | |
284 | key-lifetime (integer): max lifetime of a session key, in ms [one hour] | |
285 | setup-retries (integer): max number of times to transmit a key negotiation | |
286 | packet [5] | |
287 | setup-timeout (integer): time between retransmissions of key negotiation | |
288 | packets, in ms [1000] | |
289 | wait-time (integer): after failed key setup, wait this long (in ms) before | |
290 | allowing another attempt [20000] | |
291 | renegotiate-time (integer): if we see traffic on the link after this time | |
292 | then renegotiate another session key immediately [depends on key-lifetime] | |
293 | keepalive (bool): if True then attempt always to keep a valid session key | |
294 | log-events (string list): types of events to log for this site | |
295 | unexpected: unexpected key setup packets (may be late retransmissions) | |
296 | setup-init: start of attempt to setup a session key | |
297 | setup-timeout: failure of attempt to setup a session key, through timeout | |
298 | activate-key: activation of a new session key | |
299 | timeout-key: deletion of current session key through age | |
300 | security: anything potentially suspicious | |
301 | state-change: steps in the key setup protocol | |
302 | packet-drop: whenever we throw away an outgoing packet | |
303 | dump-packets: every key setup packet we see | |
304 | errors: failure of name resolution, internal errors | |
305 | all: everything (too much!) | |
3454dce4 | 306 | |
558fa3fb SE |
307 | ** transform |
308 | ||
309 | Defines: | |
310 | serpent256-cbc (closure => transform closure) | |
311 | ||
312 | ** netlink | |
313 | ||
314 | Defines: | |
469fd1d9 | 315 | null-netlink (closure => closure or netlink closure) |
3454dce4 SE |
316 | |
317 | null-netlink: dict argument | |
318 | name (string): name for netlink device, used in log messages | |
319 | networks (string list): networks on the host side of the netlink device | |
320 | exclude-remote-networks (string list): networks that may never be claimed | |
321 | by any remote site using this netlink device | |
322 | local-address (string): IP address of host's tunnel interface | |
323 | secnet-address (string): IP address of this netlink device | |
c6f79b17 | 324 | ptp-address (string): IP address of the other end of a point-to-point link |
3454dce4 SE |
325 | mtu (integer): MTU of host's tunnel interface |
326 | ||
469fd1d9 SE |
327 | Only one of secnet-address or ptp-address may be specified. If |
328 | point-to-point mode is in use then the "routes" option must also be | |
329 | specified, and netlink returns a netlink closure that should be used | |
330 | directly with the "link" option to the site closure. If | |
331 | point-to-point mode is not in use then netlink returns a closure that | |
332 | may be invoked using a dict argument with the following keys to yield | |
333 | a netlink closure: | |
334 | routes (string list): networks reachable down the tunnel attached to | |
335 | this instance of netlink | |
336 | options (string list): | |
337 | allow-route: allow packets coming from this tunnel to be routed to | |
338 | other tunnels as well as the host (used for mobile devices like laptops) | |
339 | soft-route: remove these routes from the host's routing table when | |
340 | the tunnel link quality is zero | |
ff05a229 | 341 | mtu (integer): default MTU over this link; may be updated by tunnel code |
c6f79b17 | 342 | |
042a8da9 SE |
343 | Netlink will dump its current routing table to the system/log on |
344 | receipt of SIGUSR1. | |
345 | ||
3454dce4 SE |
346 | ** slip |
347 | ||
348 | Defines: | |
558fa3fb | 349 | userv-ipif (closure => netlink closure) |
3454dce4 SE |
350 | |
351 | userv-ipif: dict argument | |
352 | userv-path (string): optional, where to find userv ["userv"] | |
353 | service-user (string): optional, username for userv-ipif service ["root"] | |
354 | service-name (string): optional, name of userv-ipif service ["ipif"] | |
355 | buffer (buffer closure): buffer for assembly of host->secnet packets | |
356 | plus generic netlink options, as for 'null-netlink' | |
357 | ||
358 | ** tun | |
359 | ||
360 | Defines: | |
558fa3fb SE |
361 | tun (closure => netlink closure) [only on linux-2.4] |
362 | tun-old (closure => netlink closure) | |
3454dce4 SE |
363 | |
364 | tun: dict argument | |
ff05a229 SE |
365 | flavour (string): optional, type of TUN interface to use |
366 | ("guess","linux","bsd","streams") | |
3454dce4 SE |
367 | device (string): optional, path of TUN/TAP device file ["/dev/net/tun"] |
368 | interface (string): optional, name of tunnel network interface | |
369 | ifconfig-path (string): optional, path to ifconfig command | |
370 | route-path (string): optional, path to route command | |
ff05a229 SE |
371 | ifconfig-type (string): optional, how to perform ifconfig |
372 | route-type (string): optional, how to add and remove routes | |
373 | types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5" | |
3454dce4 SE |
374 | buffer (buffer closure): buffer for host->secnet packets |
375 | plus generic netlink options, as for 'null-netlink' | |
376 | ||
ff05a229 SE |
377 | I recommend you don't specify the 'interface' option unless you're |
378 | doing something that requires the interface name to be constant. | |
c6f79b17 | 379 | |
558fa3fb SE |
380 | ** rsa |
381 | ||
382 | Defines: | |
383 | rsa-private (closure => rsaprivkey closure) | |
384 | rsa-public (closure => rsapubkey closure) | |
385 | ||
3454dce4 SE |
386 | rsa-private: string[,bool] |
387 | arg1: filename of SSH private key file (version 1, no password) | |
388 | arg2: whether to check that the key is usable [default True] | |
389 | ||
390 | rsa-public: string,string | |
391 | arg1: encryption key (decimal) | |
392 | arg2: modulus (decimal) | |
393 | ||
558fa3fb SE |
394 | ** dh |
395 | ||
396 | Defines: | |
397 | diffie-hellman (closure => dh closure) | |
398 | ||
3454dce4 SE |
399 | diffie-hellman: string,string[,bool] |
400 | arg1: modulus (hex) | |
401 | arg2: generator (hex) | |
402 | arg3: whether to check that the modulus is prime [default True] | |
403 | ||
558fa3fb SE |
404 | ** md5 |
405 | ||
406 | Defines: | |
407 | md5 (hash closure) | |
3454dce4 SE |
408 | |
409 | ** sha1 | |
410 | ||
411 | Defines: | |
412 | sha1 (hash closure) | |
c6f79b17 SE |
413 | |
414 | ** conffile | |
415 | ||
416 | Defines: | |
417 | makelist (dictionary => list of definitions) | |
418 | readfile (string => string) | |
419 | map (closure,list => list) | |
420 | ||
421 | makelist: dictionary | |
422 | returns a list consisting of the definitions in the dictionary. The keys | |
423 | are discarded. | |
424 | ||
425 | readfile: string | |
426 | reads the named file and returns its contents as a string | |
427 | ||
428 | map: | |
429 | applies the closure specified as arg1 to each of the elements in the list. | |
430 | Returns a list made up of the outputs of the closure. |