1 secnet - flexible VPN software
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.
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
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.
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.
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
32 * Mailing lists and bug reporting
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
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.
43 Bug reports should be sent to <steve@greenend.org.uk>; they will be
44 forwarded to the -discuss list by me.
50 * secnet configuration file format
52 By default secnet on linux reads /etc/secnet/secnet.conf. The default
53 may be different on other platforms.
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.
61 The configuration file has a very simple syntax; keys are defined as
70 Keys must match the following regular expression:
71 [[:alpha:]_][[:alnum:]\-_]*
73 i.e. the first character must be an alpha or an underscore, and the
74 remaining characters may be alphanumeric, '-' or '_'.
76 Keys can be defined to be a comma-separated list of any of the
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
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).
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.
105 The following paths are valid:
117 Note that f/g/e is NOT 4.
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).
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.
127 closure { definitions } is short for closure({definitions}).
129 The main body of secnet, and all the additional modules, predefine
130 some keys in the root dictionary. The main ones are:
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
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.
141 Keys defined by modules are described below, in the module
144 Other configuration files can be included inline by writing "include
145 filename" at the start of a line.
147 After the configuration file is read, secnet looks for particular keys
148 in configuration space to tell it what to do:
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
155 sites: a list of closures of type 'site', which define other tunnel
156 endpoints that secnet will attempt to communicate with
158 * secnet command line options
160 Usage: secnet [OPTION]...
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
172 * secnet builtin modules
177 adns (closure => resolver closure)
180 config (string): optional, a resolv.conf for ADNS to use
185 randomsrc (closure => randomsrc closure)
187 randomsrc: string[,bool]
188 arg1: filename of random source
189 arg2: if True then source is blocking
194 udp (closure => comm closure)
197 address (string list): IPv6 or IPv4 addresses to listen and send on
198 port (integer): UDP port to listen and send on
199 buffer (buffer closure): buffer for incoming packets
200 authbind (string): optional, path to authbind-helper program
205 polypath (closure => comm closure)
207 polypath: dict argument
208 port (integer): UDP port to listen and send on
209 buffer (buffer closure): buffer for incoming packets
210 authbind (string): optional, path to authbind-helper program
211 max-interfaces (number): optional, max number of different interfaces to
212 use (also, maximum steady-state amount of packet multiplication)
213 interfaces (string list): which interfaces to process; each entry is
214 optionally `!' or `+' followed by a glob pattern (which is applied to a
215 prospective interface using fnmatch with no flags). If no list is
216 specified, or the list ends with a `!' entry, a default list is
217 used/appended: "!tun*","!tap*","!sl*","!userv*","!lo","*". Patterns
218 which do not start with `*' or an alphanumeric need to be preceded
220 monitor-command (string list): Program to use to monitor appearance
221 and disappearance of addresses on local network interfaces. Should
222 produce lines of the form `+|-<ifname> 4|6 <addr>' where <addr> is
223 an address literal. Each - line should relate to a previously
224 printed + line. On startup, should produce a + line for each
225 currently existing address. secnet does filtering so there is no
226 need to strip out tun interfaces, multicast addresses, and so on.
227 The default depends on the operating system.
229 When using this comm, packets are sent out of every active interface
230 on the host (where possible). It is important that interfaces created
231 by secnet itself are not included! secnet's default filter list tries
234 This comm only makes sense for sites which are mobile. That is, the
235 site closures used with this comm should all have the `local-mobile'
236 parameter set to `true'. When the local site site is not marked
237 mobile the address selection machinery might fixate on an unsuitable
240 For an interface to work with polypath, it must either have a suitable
241 default route, or be a point-to-point interface. In the general case
242 this might mean that the host would have to have multiple default
243 routes. However in practice the most useful configuration is two
244 interfaces being (1) wifi (2) mobile internet.
246 I have had success on Linux by using network-manager for wifi and
247 invoking ppp directly for mobile internet. ppp sets up a
248 point-to-point link, and does not add a default route if there already
249 is one. network-manager always sets up a default route. The result
250 is that the wifi always has a default route (so is useable); ppp
251 (being a point-to-point link) does not need one.
253 The use of polypath currently requires that secnet have root
254 privilege, to make the setsockopt(,,SO_BINDTODEVICE,) call.
256 polypath support is only available when secnet is built against an
257 IPv6-capable version of adns (because it wants features in the newer
263 logfile (closure => log closure)
264 syslog (closure => log closure)
266 logfile: dict argument
267 filename (string): where to log to
268 class (string list): what type of messages to log
269 { "debug-config", M_DEBUG_CONFIG },
270 { "debug-phase", M_DEBUG_PHASE },
271 { "debug", M_DEBUG },
272 { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG },
274 { "notice", M_NOTICE },
275 { "warning", M_WARNING },
276 { "error", M_ERROR },
277 { "security", M_SECURITY },
278 { "fatal", M_FATAL },
279 { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
280 { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
283 logfile will close and reopen its file upon receipt of SIGHUP.
285 syslog: dict argument
286 ident (string): include this string in every log message
287 facility (string): facility to log as
288 { "authpriv", LOG_AUTHPRIV },
289 { "cron", LOG_CRON },
290 { "daemon", LOG_DAEMON },
291 { "kern", LOG_KERN },
292 { "local0", LOG_LOCAL0 },
293 { "local1", LOG_LOCAL1 },
294 { "local2", LOG_LOCAL2 },
295 { "local3", LOG_LOCAL3 },
296 { "local4", LOG_LOCAL4 },
297 { "local5", LOG_LOCAL5 },
298 { "local6", LOG_LOCAL6 },
299 { "local7", LOG_LOCAL7 },
301 { "mail", LOG_MAIL },
302 { "news", LOG_NEWS },
303 { "syslog", LOG_SYSLOG },
304 { "user", LOG_USER },
310 sysbuffer (closure => buffer closure)
312 sysbuffer: integer[,dict]
315 lockdown (boolean): if True, mlock() the buffer
320 site (closure => site closure)
323 local-name (string): this site's name for itself
324 name (string): the name of the site's peer
325 link (netlink closure)
326 comm (one or more comm closures): if there is more than one, the
327 first one will be used for any key setups initiated by us using the
328 configured address. Others are only used if our peer talks to
330 resolver (resolver closure)
331 random (randomsrc closure)
332 local-key (rsaprivkey closure)
333 address (string list): optional, DNS name(s) used to find our peer;
334 address literals are supported too if enclosed in `[' `]'.
335 port (integer): mandatory if 'address' is specified: the port used
337 key (rsapubkey closure): our peer's public key
338 transform (transform closure): how to mangle packets sent between sites
341 key-lifetime (integer): max lifetime of a session key, in ms
342 [one hour; mobile: 2 days]
343 setup-retries (integer): max number of times to transmit a key negotiation
344 packet [5; mobile: 30]
345 setup-timeout (integer): time between retransmissions of key negotiation
346 packets, in ms [2000; mobile: 1000]
347 wait-time (integer): after failed key setup, wait this long (in ms) before
348 allowing another attempt [20000; mobile: 10000]
349 renegotiate-time (integer): if we see traffic on the link after this time
350 then renegotiate another session key immediately (in ms)
351 [half key-lifetime, or key-lifetime minus 5 mins (mobile: 12 hours),
352 whichever is longer].
353 keepalive (bool): if True then attempt always to keep a valid session key.
354 Not actually currently implemented. [false]
355 log-events (string list): types of events to log for this site
356 unexpected: unexpected key setup packets (may be late retransmissions)
357 setup-init: start of attempt to setup a session key
358 setup-timeout: failure of attempt to setup a session key, through timeout
359 activate-key: activation of a new session key
360 timeout-key: deletion of current session key through age
361 security: anything potentially suspicious
362 state-change: steps in the key setup protocol
363 packet-drop: whenever we throw away an outgoing packet
364 dump-packets: every key setup packet we see
365 errors: failure of name resolution, internal errors
366 peer-addrs: changes to sets of peer addresses (interesting for mobile peers)
367 all: everything (too much!)
368 mobile (bool): if True then peer is "mobile" ie we assume it may
369 change its apparent IP address and port number without either it
370 or us being aware of the change; so, we remember the last several
371 port/addr pairs we've seen and send packets to all of them
372 (subject to a timeout). We maintain one set of addresses for key
373 setup exchanges, and another for data traffic. Two communicating
374 peers must not each regard the other as mobile, or all the traffic
375 in each direction will be triplicated (strictly, transmitted
376 mobile-peers-max times) and anyway two peers whose public contact
377 address may suddenly change couldn't communicate reliably because
378 their contact addresses might both change at once. [false]
379 mobile-peers-max (integer): Maximum number of peer port/addr pairs we
380 remember and send to. Must be at least 1 and no more than 5. [3]
381 static-peers-max (integer): Maximum number of peer port/addr pairs
382 we can try for a static site. Must be at least 1 and no more
384 mobile-peer-expiry (integer): For "mobile" peers only, the length
385 of time (in seconds) for which we will keep sending to multiple
386 address/ports from which we have not seen incoming traffic. [120]
387 local-mobile (bool): if True then other peers have been told we are
388 "mobile". This should be True iff the peers' site configurations
389 for us have "mobile True" (and if we find a site configuration for
390 ourselves in the config, we insist on this). The effect is to
391 check that there are no links both ends of which are allegedly
392 mobile (which is not supported, so those links are ignored) and
393 to change some of the tuning parameter defaults. [false]
394 mtu-target (integer): Desired value of the inter-site MTU for this
395 peering. This value will be advertised to the peer (which ought
396 to affect incoming packets), and if the peer advertises an MTU its
397 value will be combined with this setting to compute the inter-site
398 MTU. (secnet will still accept packets which exceed the
399 (negotiated or assumed) inter-site MTU.) Setting a lower
400 inter-site MTU can be used to try to restrict the sizes of the
401 packets sent over the underlying public network (e.g. to work
402 around network braindamage). It is not normally useful to set a
403 larger value for mtu-target than the VPN's general MTU (which
404 should be reflected in the local private interface MTU, ie the mtu
405 parameter to netlink). If this parameter is not set, or is set
406 to 0, the default is to use the local private link mtu.
408 Links involving mobile peers have some different tuning parameter
409 default values, which are generally more aggressive about retrying key
410 setup but more relaxed about using old keys. These are noted with
411 "mobile:", above, and apply whether the mobile peer is local or
417 eax-serpent (closure => transform closure)
422 serpent256-cbc (closure => transform closure)
427 null-netlink (closure => closure or netlink closure)
429 null-netlink: dict argument
430 name (string): name for netlink device, used in log messages
431 networks (string list): networks on the host side of the netlink device
432 remote-networks (string list): networks that may be claimed
433 by the remote site using this netlink device
434 local-address (string): IP address of host's tunnel interface
435 secnet-address (string): IP address of this netlink device
436 ptp-address (string): IP address of the other end of a point-to-point link
437 mtu (integer): MTU of host's tunnel interface
439 Only one of secnet-address or ptp-address may be specified. If
440 point-to-point mode is in use then the "routes" option must also be
441 specified, and netlink returns a netlink closure that should be used
442 directly with the "link" option to the site closure. If
443 point-to-point mode is not in use then netlink returns a closure that
444 may be invoked using a dict argument with the following keys to yield
446 routes (string list): networks reachable down the tunnel attached to
447 this instance of netlink
448 options (string list):
449 allow-route: allow packets coming from this tunnel to be routed to
450 other tunnels as well as the host (used for mobile devices like laptops)
451 soft: remove these routes from the host's routing table when
452 the tunnel link quality is zero
453 mtu (integer): MTU of host's tunnel interface
455 Netlink will dump its current routing table to the system/log on
461 userv-ipif (closure => netlink closure)
463 userv-ipif: dict argument
464 userv-path (string): optional, where to find userv ["userv"]
465 service-user (string): optional, username for userv-ipif service ["root"]
466 service-name (string): optional, name of userv-ipif service ["ipif"]
467 buffer (buffer closure): buffer for assembly of host->secnet packets
468 plus generic netlink options, as for 'null-netlink'
473 tun (closure => netlink closure) [only on linux-2.4]
474 tun-old (closure => netlink closure)
477 flavour (string): optional, type of TUN interface to use
478 ("guess","linux","bsd","streams")
479 device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
480 interface (string): optional, name of tunnel network interface
481 ifconfig-path (string): optional, path to ifconfig command
482 route-path (string): optional, path to route command
483 ifconfig-type (string): optional, how to perform ifconfig
484 route-type (string): optional, how to add and remove routes
485 types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5"
486 buffer (buffer closure): buffer for host->secnet packets
487 plus generic netlink options, as for 'null-netlink'
489 I recommend you don't specify the 'interface' option unless you're
490 doing something that requires the interface name to be constant.
495 rsa-private (closure => rsaprivkey closure)
496 rsa-public (closure => rsapubkey closure)
498 rsa-private: string[,bool]
499 arg1: filename of SSH private key file (version 1, no password)
500 arg2: whether to check that the key is usable [default True]
502 rsa-public: string,string
503 arg1: encryption key (decimal)
504 arg2: modulus (decimal)
509 diffie-hellman (closure => dh closure)
511 diffie-hellman: string,string[,bool]
513 arg2: generator (hex)
514 arg3: whether to check that the modulus is prime [default True]
529 makelist (dictionary => list of definitions)
530 readfile (string => string)
531 map (closure,list => list)
534 returns a list consisting of the definitions in the dictionary. The keys
538 reads the named file and returns its contents as a string
541 applies the closure specified as arg1 to each of the elements in the list.
542 Returns a list made up of the outputs of the closure.