chiark / gitweb /
comm, site: pass a new "struct comm_addr" rather than sockaddr_in
[secnet.git] / README
1 secnet - flexible VPN software
2
3 * Copying
4
5 secnet is Copyright (C) 1995--2003 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
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
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
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 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
137   yes, true, True, TRUE, on:   the boolean value True
138   no, false, False, FALSE, off: the boolean value False
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
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.
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
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
176
177 * secnet builtin modules
178
179 ** resolver
180
181 Defines:
182   adns (closure => resolver closure)
183
184 adns: dict argument
185   config (string): optional, a resolv.conf for ADNS to use
186
187 ** random
188
189 Defines:
190   randomsrc (closure => randomsrc closure)
191
192 randomsrc: string[,bool]
193   arg1: filename of random source
194   arg2: if True then source is blocking
195
196 ** udp
197
198 Defines:
199   udp (closure => comm closure)
200
201 udp: dict argument
202   address (string): IP address to listen and send on
203   port (integer): UDP port to listen and send on
204   buffer (buffer closure): buffer for incoming packets
205   authbind (string): optional, path to authbind-helper program
206
207 ** log
208
209 Defines:
210   logfile (closure => log closure)
211   syslog (closure => log closure)
212
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
230 logfile will close and reopen its file upon receipt of SIGHUP.
231
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
254 ** util
255
256 Defines:
257   sysbuffer (closure => buffer closure)
258
259 sysbuffer: integer[,dict]
260   arg1: buffer length
261   arg2: options:
262     lockdown (boolean): if True, mlock() the buffer
263
264 ** site
265
266 Defines:
267   site (closure => site closure)
268
269 site: dict argument
270   local-name (string): this site's name for itself
271   name (string): the name of the site's peer
272   link (netlink closure)
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
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     Not actually currently implemented. [false]
295   log-events (string list): types of events to log for this site
296     unexpected: unexpected key setup packets (may be late retransmissions)
297     setup-init: start of attempt to setup a session key
298     setup-timeout: failure of attempt to setup a session key, through timeout
299     activate-key: activation of a new session key
300     timeout-key: deletion of current session key through age
301     security: anything potentially suspicious
302     state-change: steps in the key setup protocol
303     packet-drop: whenever we throw away an outgoing packet
304     dump-packets: every key setup packet we see
305     errors: failure of name resolution, internal errors
306     all: everything (too much!)
307
308 ** transform
309
310 Defines:
311   serpent256-cbc (closure => transform closure)
312
313 ** netlink
314
315 Defines:
316   null-netlink (closure => closure or netlink closure)
317
318 null-netlink: dict argument
319   name (string): name for netlink device, used in log messages
320   networks (string list): networks on the host side of the netlink device
321   remote-networks (string list): networks that may be claimed
322     by the remote site using this netlink device
323   local-address (string): IP address of host's tunnel interface
324   secnet-address (string): IP address of this netlink device
325   ptp-address (string): IP address of the other end of a point-to-point link
326   mtu (integer): MTU of host's tunnel interface
327
328 Only one of secnet-address or ptp-address may be specified.  If
329 point-to-point mode is in use then the "routes" option must also be
330 specified, and netlink returns a netlink closure that should be used
331 directly with the "link" option to the site closure.  If
332 point-to-point mode is not in use then netlink returns a closure that
333 may be invoked using a dict argument with the following keys to yield
334 a netlink closure:
335   routes (string list): networks reachable down the tunnel attached to
336     this instance of netlink
337   options (string list):
338     allow-route: allow packets coming from this tunnel to be routed to
339       other tunnels as well as the host (used for mobile devices like laptops)
340     soft: remove these routes from the host's routing table when
341       the tunnel link quality is zero
342   mtu (integer): default MTU over this link; may be updated by tunnel code
343
344 Netlink will dump its current routing table to the system/log on
345 receipt of SIGUSR1.
346
347 ** slip
348
349 Defines:
350   userv-ipif (closure => netlink closure)
351
352 userv-ipif: dict argument
353   userv-path (string): optional, where to find userv ["userv"]
354   service-user (string): optional, username for userv-ipif service ["root"]
355   service-name (string): optional, name of userv-ipif service ["ipif"]
356   buffer (buffer closure): buffer for assembly of host->secnet packets
357  plus generic netlink options, as for 'null-netlink'
358
359 ** tun
360
361 Defines:
362   tun (closure => netlink closure) [only on linux-2.4]
363   tun-old (closure => netlink closure)
364
365 tun: dict argument
366   flavour (string): optional, type of TUN interface to use
367     ("guess","linux","bsd","streams")
368   device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
369   interface (string): optional, name of tunnel network interface
370   ifconfig-path (string): optional, path to ifconfig command
371   route-path (string): optional, path to route command
372   ifconfig-type (string): optional, how to perform ifconfig
373   route-type (string): optional, how to add and remove routes
374    types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5"
375   buffer (buffer closure): buffer for host->secnet packets
376  plus generic netlink options, as for 'null-netlink'
377
378 I recommend you don't specify the 'interface' option unless you're
379 doing something that requires the interface name to be constant.
380
381 ** rsa
382
383 Defines:
384   rsa-private (closure => rsaprivkey closure)
385   rsa-public (closure => rsapubkey closure)
386
387 rsa-private: string[,bool]
388   arg1: filename of SSH private key file (version 1, no password)
389   arg2: whether to check that the key is usable [default True]
390
391 rsa-public: string,string
392   arg1: encryption key (decimal)
393   arg2: modulus (decimal)
394
395 ** dh
396
397 Defines:
398   diffie-hellman (closure => dh closure)
399
400 diffie-hellman: string,string[,bool]
401   arg1: modulus (hex)
402   arg2: generator (hex)
403   arg3: whether to check that the modulus is prime [default True]
404
405 ** md5
406
407 Defines:
408   md5 (hash closure)
409
410 ** sha1
411
412 Defines:
413   sha1 (hash closure)
414
415 ** conffile
416
417 Defines:
418   makelist (dictionary => list of definitions)
419   readfile (string => string)
420   map (closure,list => list)
421
422 makelist: dictionary
423   returns a list consisting of the definitions in the dictionary. The keys
424   are discarded.
425
426 readfile: string
427   reads the named file and returns its contents as a string
428
429 map:
430   applies the closure specified as arg1 to each of the elements in the list.
431   Returns a list made up of the outputs of the closure.