chiark / gitweb /
string_item_to_iaddr: Actually set port if !CONFIG_IPV6
[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 IP address handling library in ipaddr.py is Copyright (C)
10 1996--2000 Cendio Systems AB, and is distributed under the terms of
11 the GPL.
12
13 * Introduction
14
15 secnet allows large virtual private networks to be constructed
16 spanning multiple separate sites.  It is designed for the case where a
17 private network connecting many hosts is 'hidden' behind a single
18 globally-routable IP address, but can also be applied in other
19 circumstances.  It communicates entirely using UDP, and works well
20 with gateways that implement network address translation.
21
22 If you are installing secnet to join an existing VPN, you should read
23 the 'INSTALL' file and your particular VPN's documentation now.  You
24 may need to refer back to this file for information on the netlink and
25 comm sections of the configuration file.
26
27 If you are thinking about setting up a new VPN of any size (from one
28 providing complete links between multiple sites to a simple
29 laptop-to-host link), read the section in this file on 'Creating a
30 VPN'.
31
32 * Mailing lists and bug reporting
33
34 There are two mailing lists associated with secnet: an 'announce' list
35 and a 'discuss' list.  Their addresses are:
36 http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-announce
37 http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-discuss
38
39 The -announce list receives one message per secnet release.  The
40 -discuss list is for general discussion, including help with
41 configuration, bug reports, feature requests, etc.
42
43 Bug reports should be sent to <steve@greenend.org.uk>; they will be
44 forwarded to the -discuss list by me.
45
46 * Creating a VPN
47
48 XXX TODO
49
50 * secnet configuration file format
51
52 By default secnet on linux reads /etc/secnet/secnet.conf.  The default
53 may be different on other platforms.
54
55 This file defines a dictionary (a mapping from keys to values) full of
56 configuration information for secnet.  Two keys must be defined in
57 this file for secnet to start.  One is "system", a dictionary
58 containing systemwide control parameters.  The other is "sites", a
59 list of all the sites that you intend to communicate with.
60
61 The configuration file has a very simple syntax; keys are defined as
62 follows:
63
64 key definition;
65 or
66 key = definition;
67
68 (the "=" is optional)
69
70 Keys must match the following regular expression:
71 [[:alpha:]_][[:alnum:]\-_]*
72
73 i.e. the first character must be an alpha or an underscore, and the
74 remaining characters may be alphanumeric, '-' or '_'.
75
76 Keys can be defined to be a comma-separated list of any of the
77 following types:
78
79   a boolean
80   a string, in quotes
81   a number, in decimal
82   a dictionary of definitions, enclosed in { }
83   a "closure", followed by arguments
84   a path to a key that already exists, to reference that definition
85
86 Note that dictionaries can be nested: a key in one dictionary can
87 refer to another dictionary. When secnet looks for a key in a
88 particular directory and can't find it, it looks in the dictionary's
89 lexical 'parents' in turn until it finds it (or fails to find it at
90 all and stops with an error).
91
92 Definitions can refer to previous definitions by naming them with a
93 path.  Paths are key1/key2/key3... (starting from wherever we find
94 key1, i.e. in the current dictionary or any of its parents), or
95 alternatively /key1/key2/key3... (to start from the root).
96 Definitions cannot refer to future definitions.
97
98 Example:
99
100 a=1;
101 b=2;
102 c={ d=3; e=a; };
103 f={ a=4; g=c; };
104
105 The following paths are valid:
106 a is 1
107 b is 2
108 c is a dictionary:
109  c/d is 3
110  c/e is 1
111 f is a dictionary:
112  f/a is 4
113  f/g is a dictionary:
114   f/g/d is 3
115   f/g/e is 1
116
117 Note that f/g/e is NOT 4.
118
119 Elements that are lists are inserted into lists in definitions, not
120 referenced by them (i.e. you can't have lists of lists).
121
122 Some closures may be followed by an argument list in ( ), and may
123 return any number of whatever type they like (including other
124 closures).  Some types of closure (typically those returned from
125 invokations of other closures) cannot be invoked.
126
127 closure { definitions } is short for closure({definitions}).
128
129 The main body of secnet, and all the additional modules, predefine
130 some keys in the root dictionary.  The main ones are:
131
132   yes, true, True, TRUE, on:   the boolean value True
133   no, false, False, FALSE, off: the boolean value False
134   makelist:   turns a dictionary (arg1) into a list of definitions
135               (ignoring the keys)
136   readfile:   reads a file (arg1) and returns it as a string
137   map:        applies the closure specified as arg1 to each of the
138               remaining elements in the list in turn.  Returns a list
139               made up of the outputs of the closure.
140
141 Keys defined by modules are described below, in the module
142 documentation.
143
144 Other configuration files can be included inline by writing "include
145 filename" at the start of a line.
146
147 After the configuration file is read, secnet looks for particular keys
148 in configuration space to tell it what to do:
149
150  system: a dictionary which can contain the following keys:
151    log (log closure): a destination for system messages
152    userid (string): the userid for secnet to run as once it drops privileges
153    pidfile (string): where to store its PID
154    
155  sites: a list of closures of type 'site', which define other tunnel
156         endpoints that secnet will attempt to communicate with
157
158 * secnet command line options
159
160 Usage: secnet [OPTION]...
161
162   -f, --silent, --quiet   suppress error messages
163   -w, --nowarnings        suppress warnings
164   -v, --verbose           output extra diagnostics
165   -c, --config=filename   specify a configuration file
166   -j, --just-check-config stop after reading configfile
167   -n, --nodetach          do not run in background
168   -d, --debug=item,...    set debug options
169       --help              display this help and exit
170       --version           output version information and exit
171
172 * secnet builtin modules
173
174 ** resolver
175
176 Defines:
177   adns (closure => resolver closure)
178
179 adns: dict argument
180   config (string): optional, a resolv.conf for ADNS to use
181
182 ** random
183
184 Defines:
185   randomsrc (closure => randomsrc closure)
186
187 randomsrc: string[,bool]
188   arg1: filename of random source
189   arg2: if True then source is blocking
190
191 ** udp
192
193 Defines:
194   udp (closure => comm closure)
195
196 udp: dict argument
197   address (string list): IPv6 or IPv4 addresses to listen and send on;
198    default is all local addresses
199   port (integer): UDP port to listen and send on; optional if you
200    don't need to have a stable address for your peers to talk to
201    (in which case your site ought probably to have `local-mobile true').
202   buffer (buffer closure): buffer for incoming packets
203   authbind (string): optional, path to authbind-helper program
204
205 ** polypath
206
207 Defines:
208   polypath (closure => comm closure)
209
210 polypath: dict argument
211   port (integer): UDP port to listen and send on
212   buffer (buffer closure): buffer for incoming packets
213   authbind (string): optional, path to authbind-helper program
214   max-interfaces (number): optional, max number of different interfaces to
215    use (also, maximum steady-state amount of packet multiplication)
216   interfaces (string list): which interfaces to process; each entry is
217    optionally `!' or `+' followed by a glob pattern (which is applied to a
218    prospective interface using fnmatch with no flags).  If no list is
219    specified, or the list ends with a `!' entry, a default list is
220    used/appended: "!tun*","!tap*","!sl*","!userv*","!lo","*".  Patterns
221    which do not start with `*' or an alphanumeric need to be preceded
222    by `!' or `+'.
223   monitor-command (string list): Program to use to monitor appearance
224    and disappearance of addresses on local network interfaces.  Should
225    produce lines of the form `+|-<ifname> 4|6 <addr>' where <addr> is
226    an address literal.  Each - line should relate to a previously
227    printed + line.  On startup, should produce a + line for each
228    currently existing address.  secnet does filtering so there is no
229    need to strip out tun interfaces, multicast addresses, and so on.
230    The command is run as the user secnet is started as (not the one
231    which secnet may drop privilege to due to the configured `userid').
232    The default depends on the operating system.
233   permit-loopback (boolean): Normally, loopback IPv6 and IPv4
234    addresses on local interfaces are disregarded, because such
235    interfaces are not interesting for communicating with distant
236    hosts.  Setting this option will ignore that check, which can be
237    useful for testing.  Setting this option also removes "!lo*" from
238    the default interface pattern list.
239
240 When using this comm, packets are sent out of every active interface
241 on the host (where possible).  It is important that interfaces created
242 by secnet itself are not included!  secnet's default filter list tries
243 to do this.
244
245 This comm only makes sense for sites which are mobile.  That is, the
246 site closures used with this comm should all have the `local-mobile'
247 parameter set to `true'.  When the local site site is not marked
248 mobile the address selection machinery might fixate on an unsuitable
249 address.
250
251 For an interface to work with polypath, it must either have a suitable
252 default route, or be a point-to-point interface.  In the general case
253 this might mean that the host would have to have multiple default
254 routes.  However in practice the most useful configuration is two
255 interfaces being (1) wifi (2) mobile internet.
256
257 I have had success on Linux by using network-manager for wifi and
258 invoking ppp directly for mobile internet.  ppp sets up a
259 point-to-point link, and does not add a default route if there already
260 is one.  network-manager always sets up a default route.  The result
261 is that the wifi always has a default route (so is useable); ppp
262 (being a point-to-point link) does not need one.
263
264 The use of polypath requires that secnet be started with root
265 privilege, to make the setsockopt(,,SO_BINDTODEVICE,) calls.  If the
266 configuration specifies that secnet should drop privilege (see
267 `userid' above), secnet will keep a special process around for this
268 purpose; that process will handle local network interface changes but
269 does not deal with any packets, key exchange, etc.
270
271 polypath support is only available when secnet is built against an
272 IPv6-capable version of adns (because it wants features in the newer
273 adns).
274
275 ** log
276
277 Defines:
278   logfile (closure => log closure)
279   syslog (closure => log closure)
280
281 logfile: dict argument
282   filename (string): where to log to
283   class (string list): what type of messages to log
284     { "debug-config", M_DEBUG_CONFIG },
285     { "debug-phase", M_DEBUG_PHASE },
286     { "debug", M_DEBUG },
287     { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG },
288     { "info", M_INFO },
289     { "notice", M_NOTICE },
290     { "warning", M_WARNING },
291     { "error", M_ERROR },
292     { "security", M_SECURITY },
293     { "fatal", M_FATAL },
294     { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
295     { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
296     { "quiet", M_FATAL }
297
298 logfile will close and reopen its file upon receipt of SIGHUP.
299
300 syslog: dict argument
301   ident (string): include this string in every log message
302   facility (string): facility to log as
303     { "authpriv", LOG_AUTHPRIV },
304     { "cron", LOG_CRON },
305     { "daemon", LOG_DAEMON },
306     { "kern", LOG_KERN },
307     { "local0", LOG_LOCAL0 },
308     { "local1", LOG_LOCAL1 },
309     { "local2", LOG_LOCAL2 },
310     { "local3", LOG_LOCAL3 },
311     { "local4", LOG_LOCAL4 },
312     { "local5", LOG_LOCAL5 },
313     { "local6", LOG_LOCAL6 },
314     { "local7", LOG_LOCAL7 },
315     { "lpr", LOG_LPR },
316     { "mail", LOG_MAIL },
317     { "news", LOG_NEWS },
318     { "syslog", LOG_SYSLOG },
319     { "user", LOG_USER },
320     { "uucp", LOG_UUCP }
321
322 ** util
323
324 Defines:
325   sysbuffer (closure => buffer closure)
326
327 sysbuffer: integer[,dict]
328   arg1: buffer length
329   arg2: options:
330     lockdown (boolean): if True, mlock() the buffer
331
332 ** site
333
334 Defines:
335   site (closure => site closure)
336
337 site: dict argument
338   local-name (string): this site's name for itself
339   name (string): the name of the site's peer
340   link (netlink closure)
341   comm (one or more comm closures): if there is more than one, the
342    first one will be used for any key setups initiated by us using the
343    configured address.  Others are only used if our peer talks to
344    them.
345   resolver (resolver closure)
346   random (randomsrc closure)
347   local-key (rsaprivkey closure)
348   address (string list): optional, DNS name(s) used to find our peer;
349     address literals are supported too if enclosed in `[' `]'.
350   port (integer): mandatory if 'address' is specified: the port used
351     to contact our peer
352   key (rsapubkey closure): our peer's public key
353   transform (transform closure): how to mangle packets sent between sites
354   dh (dh closure)
355   hash (hash closure)
356   key-lifetime (integer): max lifetime of a session key, in ms
357     [one hour; mobile: 2 days]
358   setup-retries (integer): max number of times to transmit a key negotiation
359     packet [5; mobile: 30]
360   setup-timeout (integer): time between retransmissions of key negotiation
361     packets, in ms [2000; mobile: 1000]
362   wait-time (integer): after failed key setup, wait this long (in ms) before
363     allowing another attempt [20000; mobile: 10000]
364   renegotiate-time (integer): if we see traffic on the link after this time
365     then renegotiate another session key immediately (in ms)
366     [half key-lifetime, or key-lifetime minus 5 mins (mobile: 12 hours),
367      whichever is longer].
368   keepalive (bool): if True then attempt always to keep a valid session key.
369     Not actually currently implemented. [false]
370   log-events (string list): types of events to log for this site
371     unexpected: unexpected key setup packets (may be late retransmissions)
372     setup-init: start of attempt to setup a session key
373     setup-timeout: failure of attempt to setup a session key, through timeout
374     activate-key: activation of a new session key
375     timeout-key: deletion of current session key through age
376     security: anything potentially suspicious
377     state-change: steps in the key setup protocol
378     packet-drop: whenever we throw away an outgoing packet
379     dump-packets: every key setup packet we see
380     errors: failure of name resolution, internal errors
381     peer-addrs: changes to sets of peer addresses (interesting for mobile peers)
382     all: everything (too much!)
383   mobile (bool): if True then peer is "mobile" ie we assume it may
384     change its apparent IP address and port number without either it
385     or us being aware of the change; so, we remember the last several
386     port/addr pairs we've seen and send packets to all of them
387     (subject to a timeout).  We maintain one set of addresses for key
388     setup exchanges, and another for data traffic. Two communicating
389     peers must not each regard the other as mobile, or all the traffic
390     in each direction will be triplicated (strictly, transmitted
391     mobile-peers-max times) and anyway two peers whose public contact
392     address may suddenly change couldn't communicate reliably because
393     their contact addresses might both change at once. [false]
394   mobile-peers-max (integer): Maximum number of peer port/addr pairs we
395     remember and send to.  Must be at least 1 and no more than 5.
396     [4 if any address is configured, otherwise 3]
397   static-peers-max (integer): Maximum number of peer port/addr pairs
398     we can try for a static site.  Must be at least 1 and no more
399     than 5.  [4 or 3, as above]
400   mobile-peer-expiry (integer): For "mobile" peers only, the length
401     of time (in seconds) for which we will keep sending to multiple
402     address/ports from which we have not seen incoming traffic. [120]
403   local-mobile (bool): if True then other peers have been told we are
404     "mobile".  This should be True iff the peers' site configurations
405     for us have "mobile True" (and if we find a site configuration for
406     ourselves in the config, we insist on this).  The effect is to
407     check that there are no links both ends of which are allegedly
408     mobile (which is not supported, so those links are ignored) and
409     to change some of the tuning parameter defaults. [false]
410   mtu-target (integer): Desired value of the inter-site MTU for this
411     peering.  This value will be advertised to the peer (which ought
412     to affect incoming packets), and if the peer advertises an MTU its
413     value will be combined with this setting to compute the inter-site
414     MTU.  (secnet will still accept packets which exceed the
415     (negotiated or assumed) inter-site MTU.)  Setting a lower
416     inter-site MTU can be used to try to restrict the sizes of the
417     packets sent over the underlying public network (e.g. to work
418     around network braindamage).  It is not normally useful to set a
419     larger value for mtu-target than the VPN's general MTU (which
420     should be reflected in the local private interface MTU, ie the mtu
421     parameter to netlink).  If this parameter is not set, or is set
422     to 0, the default is to use the local private link mtu.
423
424 Links involving mobile peers have some different tuning parameter
425 default values, which are generally more aggressive about retrying key
426 setup but more relaxed about using old keys.  These are noted with
427 "mobile:", above, and apply whether the mobile peer is local or
428 remote.
429
430 ** transform-eax
431
432 Defines:
433    eax-serpent (closure => transform closure)
434
435 ** transform-cbcmac
436
437 Defines:
438   serpent256-cbc (closure => transform closure)
439
440 ** netlink
441
442 Defines:
443   null-netlink (closure => closure or netlink closure)
444
445 null-netlink: dict argument
446   name (string): name for netlink device, used in log messages
447   networks (string list): networks on the host side of the netlink device
448   remote-networks (string list): networks that may be claimed
449     by the remote site using this netlink device
450   local-address (string): IP address of host's tunnel interface
451   secnet-address (string): IP address of this netlink device
452   ptp-address (string): IP address of the other end of a point-to-point link
453   mtu (integer): MTU of host's tunnel interface
454
455 Only one of secnet-address or ptp-address may be specified.  If
456 point-to-point mode is in use then the "routes" option must also be
457 specified, and netlink returns a netlink closure that should be used
458 directly with the "link" option to the site closure.  If
459 point-to-point mode is not in use then netlink returns a closure that
460 may be invoked using a dict argument with the following keys to yield
461 a netlink closure:
462   routes (string list): networks reachable down the tunnel attached to
463     this instance of netlink
464   options (string list):
465     allow-route: allow packets coming from this tunnel to be routed to
466       other tunnels as well as the host (used for mobile devices like laptops)
467     soft: remove these routes from the host's routing table when
468       the tunnel link quality is zero
469   mtu (integer): MTU of host's tunnel interface
470
471 Netlink will dump its current routing table to the system/log on
472 receipt of SIGUSR1.
473
474 ** slip
475
476 Defines:
477   userv-ipif (closure => netlink closure)
478
479 userv-ipif: dict argument
480   userv-path (string): optional, where to find userv ["userv"]
481   service-user (string): optional, username for userv-ipif service ["root"]
482   service-name (string): optional, name of userv-ipif service ["ipif"]
483   buffer (buffer closure): buffer for assembly of host->secnet packets
484  plus generic netlink options, as for 'null-netlink'
485
486 ** tun
487
488 Defines:
489   tun (closure => netlink closure) [only on linux-2.4]
490   tun-old (closure => netlink closure)
491
492 tun: dict argument
493   flavour (string): optional, type of TUN interface to use
494     ("guess","linux","bsd","streams")
495   device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
496   interface (string): optional, name of tunnel network interface
497   ifconfig-path (string): optional, path to ifconfig command
498   route-path (string): optional, path to route command
499   ifconfig-type (string): optional, how to perform ifconfig
500   route-type (string): optional, how to add and remove routes
501    types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5"
502   buffer (buffer closure): buffer for host->secnet packets
503  plus generic netlink options, as for 'null-netlink'
504
505 I recommend you don't specify the 'interface' option unless you're
506 doing something that requires the interface name to be constant.
507
508 ** rsa
509
510 Defines:
511   rsa-private (closure => rsaprivkey closure)
512   rsa-public (closure => rsapubkey closure)
513
514 rsa-private: string[,bool]
515   arg1: filename of SSH private key file (version 1, no password)
516   arg2: whether to check that the key is usable [default True]
517
518 rsa-public: string,string
519   arg1: encryption key (decimal)
520   arg2: modulus (decimal)
521
522 ** dh
523
524 Defines:
525   diffie-hellman (closure => dh closure)
526
527 diffie-hellman: string,string[,bool]
528   arg1: modulus (hex)
529   arg2: generator (hex)
530   arg3: whether to check that the modulus is prime [default True]
531
532 ** md5
533
534 Defines:
535   md5 (hash closure)
536
537 ** sha1
538
539 Defines:
540   sha1 (hash closure)
541
542 ** conffile
543
544 Defines:
545   makelist (dictionary => list of definitions)
546   readfile (string => string)
547   map (closure,list => list)
548
549 makelist: dictionary
550   returns a list consisting of the definitions in the dictionary. The keys
551   are discarded.
552
553 readfile: string
554   reads the named file and returns its contents as a string
555
556 map:
557   applies the closure specified as arg1 to each of the elements in the list.
558   Returns a list made up of the outputs of the closure.