1 secnet - flexible VPN software
3 See LICENCE for legal information and CREDITS for a list of
9 secnet allows large virtual private networks to be constructed
10 spanning multiple separate sites. It is designed for the case where a
11 private network connecting many hosts is 'hidden' behind a single
12 globally-routable IP address, but can also be applied in other
13 circumstances. It communicates entirely using UDP, and works well
14 with gateways that implement network address translation.
16 If you are installing secnet to join an existing VPN, you should read
17 the 'INSTALL' file and your particular VPN's documentation now. You
18 may need to refer back to this file for information on the netlink and
19 comm sections of the configuration file.
21 If you are thinking about setting up a new VPN of any size (from one
22 providing complete links between multiple sites to a simple
23 laptop-to-host link), read the section in this file on 'Creating a
26 * Mailing lists and bug reporting
28 There are two mailing lists associated with secnet: an 'announce' list
29 and a 'discuss' list. Their addresses are:
30 http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-announce
31 http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-discuss
33 The -announce list receives one message per secnet release. The
34 -discuss list is for general discussion, including help with
35 configuration, bug reports, feature requests, etc.
37 Bug reports should be sent to <steve@greenend.org.uk>; they will be
38 forwarded to the -discuss list by me.
44 * secnet configuration file format
46 By default secnet on linux reads /etc/secnet/secnet.conf. The default
47 may be different on other platforms.
49 This file defines a dictionary (a mapping from keys to values) full of
50 configuration information for secnet. Two keys must be defined in
51 this file for secnet to start. One is "system", a dictionary
52 containing systemwide control parameters. The other is "sites", a
53 list of all the sites that you intend to communicate with.
55 The configuration file has a very simple syntax; keys are defined as
64 Keys must match the following regular expression:
65 [[:alpha:]_][[:alnum:]\-_]*
67 i.e. the first character must be an alpha or an underscore, and the
68 remaining characters may be alphanumeric, '-' or '_'.
70 Keys can be defined to be a comma-separated list of any of the
76 a dictionary of definitions, enclosed in { }
77 a "closure", followed by arguments
78 a path to a key that already exists, to reference that definition
80 Note that dictionaries can be nested: a key in one dictionary can
81 refer to another dictionary. When secnet looks for a key in a
82 particular directory and can't find it, it looks in the dictionary's
83 lexical 'parents' in turn until it finds it (or fails to find it at
84 all and stops with an error).
86 Definitions can refer to previous definitions by naming them with a
87 path. Paths are key1/key2/key3... (starting from wherever we find
88 key1, i.e. in the current dictionary or any of its parents), or
89 alternatively /key1/key2/key3... (to start from the root).
90 Definitions cannot refer to future definitions.
99 The following paths are valid:
111 Note that f/g/e is NOT 4.
113 Elements that are lists are inserted into lists in definitions, not
114 referenced by them (i.e. you can't have lists of lists).
116 Some closures may be followed by an argument list in ( ), and may
117 return any number of whatever type they like (including other
118 closures). Some types of closure (typically those returned from
119 invokations of other closures) cannot be invoked.
121 closure { definitions } is short for closure({definitions}).
123 The main body of secnet, and all the additional modules, predefine
124 some keys in the root dictionary. The main ones are:
126 yes, true, True, TRUE, on: the boolean value True
127 no, false, False, FALSE, off: the boolean value False
128 makelist: turns a dictionary (arg1) into a list of definitions
130 readfile: reads a file (arg1) and returns it as a string
131 map: applies the closure specified as arg1 to each of the
132 remaining elements in the list in turn. Returns a list
133 made up of the outputs of the closure.
135 Keys defined by modules are described below, in the module
138 Other configuration files can be included inline by writing "include
139 filename" at the start of a line.
141 After the configuration file is read, secnet looks for particular keys
142 in configuration space to tell it what to do:
144 system: a dictionary which can contain the following keys:
145 log (log closure): a destination for system messages
146 userid (string): the userid for secnet to run as once it drops privileges
147 pidfile (string): where to store its PID
149 sites: a list of closures of type 'site', which define other tunnel
150 endpoints that secnet will attempt to communicate with
152 * secnet command line options
154 Usage: secnet [OPTION]...
156 -f, --silent, --quiet suppress error messages
157 -w, --nowarnings suppress warnings
158 -v, --verbose output extra diagnostics
159 -c, --config=filename specify a configuration file
160 -j, --just-check-config stop after reading configfile
161 -n, --nodetach do not run in background
162 -d, --debug=item,... set debug options
163 --help display this help and exit
164 --version output version information and exit
168 secnet defines a variant of the base91 encoding `basE91', from
169 http://base91.sourceforge.net/
171 base91s is the same as baseE91 except that:
172 - in the encoded charset, `"' is replaced with `-'
173 - spaces, newlines etc. and other characters outside the charset
174 are not permitted (although in some places they may be ignored,
175 this is not guaranteed).
177 * secnet builtin modules
182 adns (closure => resolver closure)
185 config (string): optional, a resolv.conf for ADNS to use
190 randomsrc (closure => randomsrc closure)
192 randomsrc: string[,bool]
193 arg1: filename of random source
194 arg2: if True then source is blocking
199 udp (closure => comm closure)
202 address (string list): IPv6 or IPv4 addresses to listen and send on;
203 default is all local addresses
204 port (integer): UDP port to listen and send on; optional if you
205 don't need to have a stable address for your peers to talk to
206 (in which case your site ought probably to have `local-mobile true').
207 buffer (buffer closure): buffer for incoming packets
208 authbind (string): optional, path to authbind-helper program
213 polypath (closure => comm closure)
215 polypath: dict argument
216 port (integer): UDP port to listen and send on
217 buffer (buffer closure): buffer for incoming packets
218 authbind (string): optional, path to authbind-helper program
219 max-interfaces (number): optional, max number of different interfaces to
220 use (also, maximum steady-state amount of packet multiplication);
221 interfaces marked with `@' do not count.
222 interfaces (string list): which interfaces to process; each entry is
223 optionally `!' or `+' or `@' followed by a glob pattern (which is
224 applied to a prospective interface using fnmatch with no flags).
225 `+' or nothing means to process normally. `!' means to ignore;
226 `@' means to use only in conjunction with dedicated-interface-addr.
227 If no list is specified, or the list ends with a `!' entry, a
228 default list is used/appended:
229 "!tun*","!tap*","!sl*","!userv*","!lo","@hippo*","*".
230 Patterns which do not start with `*' or an alphanumeric need to be
231 preceded by `!' or `+' or `@'.
232 monitor-command (string list): Program to use to monitor appearance
233 and disappearance of addresses on local network interfaces. Should
234 produce lines of the form `+|-<ifname> 4|6 <addr>' where <addr> is
235 an address literal. Each - line should relate to a previously
236 printed + line. On startup, should produce a + line for each
237 currently existing address. secnet does filtering so there is no
238 need to strip out tun interfaces, multicast addresses, and so on.
239 The command is run as the user secnet is started as (not the one
240 which secnet may drop privilege to due to the configured `userid').
241 The default depends on the operating system.
242 permit-loopback (boolean): Normally, loopback IPv6 and IPv4
243 addresses on local interfaces are disregarded, because such
244 interfaces are not interesting for communicating with distant
245 hosts. Setting this option will ignore that check, which can be
246 useful for testing. Setting this option also removes "!lo*" from
247 the default interface pattern list.
249 When using this comm, packets are sent out of every active interface
250 on the host (where possible). It is important that interfaces created
251 by secnet itself are not included! secnet's default filter list tries
254 This comm only makes sense for sites which are mobile. That is, the
255 site closures used with this comm should all have the `local-mobile'
256 parameter set to `true'. When the local site site is not marked
257 mobile the address selection machinery might fixate on an unsuitable
260 polypath takes site-specific informtion as passed to the `comm-info'
261 site closure parameter. The entries understood in the dictionary
263 dedicated-interface-addr (string): IPv4 or IPv6 address
264 literal. Interfaces specified with `@' in `interfaces' will be
265 used for the corresponding site iff the interface local address
268 For an interface to work with polypath, it must either have a suitable
269 default route, or be a point-to-point interface. In the general case
270 this might mean that the host would have to have multiple default
271 routes. However in practice the most useful configuration is two
272 interfaces being (1) wifi (2) mobile internet.
274 I have had success on Linux by using network-manager for wifi and
275 invoking ppp directly for mobile internet. ppp sets up a
276 point-to-point link, and does not add a default route if there already
277 is one. network-manager always sets up a default route. The result
278 is that the wifi always has a default route (so is useable); ppp
279 (being a point-to-point link) does not need one.
281 The use of polypath requires that secnet be started with root
282 privilege, to make the setsockopt(,,SO_BINDTODEVICE,) calls. If the
283 configuration specifies that secnet should drop privilege (see
284 `userid' above), secnet will keep a special process around for this
285 purpose; that process will handle local network interface changes but
286 does not deal with any packets, key exchange, etc.
288 polypath support is only available when secnet is built against an
289 IPv6-capable version of adns (because it wants features in the newer
295 logfile (closure => log closure)
296 syslog (closure => log closure)
298 logfile: dict argument
299 filename (string): where to log to; default is stderr
300 prefix (string): added to messages [""]
301 class (string list): what type of messages to log
302 { "debug-config", M_DEBUG_CONFIG },
303 { "debug-phase", M_DEBUG_PHASE },
304 { "debug", M_DEBUG },
305 { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG },
307 { "notice", M_NOTICE },
308 { "warning", M_WARNING },
309 { "error", M_ERROR },
310 { "security", M_SECURITY },
311 { "fatal", M_FATAL },
312 { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
313 { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
316 logfile will close and reopen its file upon receipt of SIGHUP.
318 syslog: dict argument
319 ident (string): include this string in every log message
320 facility (string): facility to log as
321 { "authpriv", LOG_AUTHPRIV },
322 { "cron", LOG_CRON },
323 { "daemon", LOG_DAEMON },
324 { "kern", LOG_KERN },
325 { "local0", LOG_LOCAL0 },
326 { "local1", LOG_LOCAL1 },
327 { "local2", LOG_LOCAL2 },
328 { "local3", LOG_LOCAL3 },
329 { "local4", LOG_LOCAL4 },
330 { "local5", LOG_LOCAL5 },
331 { "local6", LOG_LOCAL6 },
332 { "local7", LOG_LOCAL7 },
334 { "mail", LOG_MAIL },
335 { "news", LOG_NEWS },
336 { "syslog", LOG_SYSLOG },
337 { "user", LOG_USER },
343 sysbuffer (closure => buffer closure)
345 sysbuffer: integer[,dict]
348 lockdown (boolean): if True, mlock() the buffer
353 site (closure => site closure)
356 local-name (string): this site's name for itself
357 name (string): the name of the site's peer
358 link (netlink closure)
359 comm (one or more comm closures): if there is more than one, the
360 first one will be used for any key setups initiated by us using the
361 configured address. Others are only used if our peer talks to
363 resolver (resolver closure)
364 random (randomsrc closure)
365 key-cache (privcache closure)
366 local-key (sigprivkey closure): Deprecated; use key-cache instead.
367 address (string list): optional, DNS name(s) used to find our peer;
368 address literals are supported too if enclosed in `[' `]'.
369 port (integer): mandatory if 'address' is specified: the port used
371 peer-keys (string): path (prefix) for peer public key set file(s);
372 see README.make-secnet-sites re `pub' etc. and NOTES.peer-keys.
373 key (sigpubkey closure): our peer's public key (obsolete)
374 transform (transform closure): how to mangle packets sent between sites
376 key-lifetime (integer): max lifetime of a session key, in ms
377 [one hour; mobile: 2 days]
378 setup-retries (integer): max number of times to transmit a key negotiation
379 packet [5; mobile: 30]
380 setup-timeout (integer): time between retransmissions of key negotiation
381 packets, in ms [2000; mobile: 1000]
382 wait-time (integer): after failed key setup, wait roughly this long
383 (in ms) before allowing another attempt [20000; mobile: 10000]
384 Actual wait time is randomly chosen between ~0.5x and ~1.5x this.
385 renegotiate-time (integer): if we see traffic on the link after this time
386 then renegotiate another session key immediately (in ms)
387 [half key-lifetime, or key-lifetime minus 5 mins (mobile: 12 hours),
388 whichever is longer].
389 keepalive (bool): if True then attempt always to keep a valid session key.
391 log-events (string list): types of events to log for this site
392 unexpected: unexpected key setup packets (may be late retransmissions)
393 setup-init: start of attempt to setup a session key
394 setup-timeout: failure of attempt to setup a session key, through timeout
395 activate-key: activation of a new session key
396 timeout-key: deletion of current session key through age
397 security: anything potentially suspicious
398 state-change: steps in the key setup protocol
399 packet-drop: whenever we throw away an outgoing packet
400 dump-packets: every key setup packet we see
401 errors: failure of name resolution, internal errors
402 peer-addrs: changes to sets of peer addresses (interesting for mobile peers)
403 all: everything (too much!)
404 mobile (bool): if True then peer is "mobile" ie we assume it may
405 change its apparent IP address and port number without either it
406 or us being aware of the change; so, we remember the last several
407 port/addr pairs we've seen and send packets to all of them
408 (subject to a timeout). We maintain one set of addresses for key
409 setup exchanges, and another for data traffic. Two communicating
410 peers must not each regard the other as mobile, or all the traffic
411 in each direction will be triplicated (strictly, transmitted
412 mobile-peers-max times) and anyway two peers whose public contact
413 address may suddenly change couldn't communicate reliably because
414 their contact addresses might both change at once. [false]
415 mobile-peers-max (integer): Maximum number of peer port/addr pairs we
416 remember and send to. Must be at least 1 and no more than 5.
417 [4 if any address is configured, otherwise 3]
418 static-peers-max (integer): Maximum number of peer port/addr pairs
419 we can try for a static site. Must be at least 1 and no more
420 than 5. [4 or 3, as above]
421 mobile-peer-expiry (integer): For "mobile" peers only, the length
422 of time (in seconds) for which we will keep sending to multiple
423 address/ports from which we have not seen incoming traffic. [120]
424 local-mobile (bool): if True then other peers have been told we are
425 "mobile". This should be True iff the peers' site configurations
426 for us have "mobile True" (and if we find a site configuration for
427 ourselves in the config, we insist on this). The effect is to
428 check that there are no links both ends of which are allegedly
429 mobile (which is not supported, so those links are ignored) and
430 to change some of the tuning parameter defaults. [false]
431 mtu-target (integer): Desired value of the inter-site MTU for this
432 peering. This value will be advertised to the peer (which ought
433 to affect incoming packets), and if the peer advertises an MTU its
434 value will be combined with this setting to compute the inter-site
435 MTU. (secnet will still accept packets which exceed the
436 (negotiated or assumed) inter-site MTU.) Setting a lower
437 inter-site MTU can be used to try to restrict the sizes of the
438 packets sent over the underlying public network (e.g. to work
439 around network braindamage). It is not normally useful to set a
440 larger value for mtu-target than the VPN's general MTU (which
441 should be reflected in the local private interface MTU, ie the mtu
442 parameter to netlink). If this parameter is not set, or is set
443 to 0, the default is to use the local private link mtu.
444 comm-info (dict): Information for the comm, used when this site
445 wants to transmit. If the comm does not support this, it is
448 Links involving mobile peers have some different tuning parameter
449 default values, which are generally more aggressive about retrying key
450 setup but more relaxed about using old keys. These are noted with
451 "mobile:", above, and apply whether the mobile peer is local or
457 eax-serpent (closure => transform closure)
462 serpent256-cbc (closure => transform closure)
467 null-netlink (closure => closure or netlink closure)
469 null-netlink: dict argument
470 name (string): name for netlink device, used in log messages
471 networks (string list): networks on the host side of the netlink device
472 remote-networks (string list): networks that may be claimed
473 by the remote site using this netlink device
474 local-address (string): IP address of host's tunnel interface
475 secnet-address (string): IP address of this netlink device
476 ptp-address (string): IP address of the other end of a point-to-point link
477 mtu (integer): MTU of host's tunnel interface
479 Only one of secnet-address or ptp-address may be specified. If
480 point-to-point mode is in use then the "routes" option must also be
481 specified, and netlink returns a netlink closure that should be used
482 directly with the "link" option to the site closure. If
483 point-to-point mode is not in use then netlink returns a closure that
484 may be invoked using a dict argument with the following keys to yield
486 routes (string list): networks reachable down the tunnel attached to
487 this instance of netlink
488 options (string list):
489 allow-route: allow packets coming from this tunnel to be routed to
490 other tunnels as well as the host (used for mobile devices like laptops)
491 soft: remove these routes from the host's routing table when
492 the tunnel link quality is zero
493 mtu (integer): MTU of host's tunnel interface
495 Netlink will dump its current routing table to the system/log on
501 userv-ipif (closure => netlink closure)
503 userv-ipif: dict argument
504 userv-path (string): optional, where to find userv ["userv"]
505 service-user (string): optional, username for userv-ipif service ["root"]
506 service-name (string): optional, name of userv-ipif service ["ipif"]
507 buffer (buffer closure): buffer for assembly of host->secnet packets
508 plus generic netlink options, as for 'null-netlink'
513 tun (closure => netlink closure) [only on linux-2.4]
514 tun-old (closure => netlink closure)
517 flavour (string): optional, type of TUN interface to use
518 ("guess","linux","bsd","streams")
519 device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
520 interface (string): optional, name of tunnel network interface
521 ifconfig-path (string): optional, path to ifconfig command
522 route-path (string): optional, path to route command
523 ifconfig-type (string): optional, how to perform ifconfig
524 route-type (string): optional, how to add and remove routes
525 types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5"
526 buffer (buffer closure): buffer for host->secnet packets
527 plus generic netlink options, as for 'null-netlink'
529 I recommend you don't specify the 'interface' option unless you're
530 doing something that requires the interface name to be constant.
534 Cache of dynamically loaded private keys.
537 priv-cache (closure => privcache closure)
539 priv-cache: dict argument
540 privkeys (string): path prefix for private keys. Each key is
541 looked for at this path prefix followed by the 10-character
543 privcache-size (integer): optional, maximum number of private
544 keys to retain at once. [5]
545 privkey-max (integer): optional, maximum size of private key
546 file in bytes. [4095]
551 make-public (closure => sigpubkey closure)
555 arg2: base91s encoded public key data, according to algorithm
560 sigscheme algorithm 00 "rsa1"
561 rsa-private (closure => sigprivkey closure)
562 rsa-public (closure => sigpubkey closure)
564 rsa1 sigscheme algorithm:
565 private key: SSH private key file, version 1, no password
566 public key: SSH public key file, version 1
567 (length, restrictions, email, etc., ignored)
569 rsa-private: string[,bool]
570 arg1: filename of SSH private key file (version 1, no password)
571 arg2: whether to check that the key is usable [default True]
573 rsa-public: string,string
574 arg1: encryption key (decimal)
575 arg2: modulus (decimal)
577 The sigscheme is hardcoded to use sha1. Both rsa-private and
578 rsa-public look for the following config key in their context:
579 hash (hash closure): hash function [sha1]
585 diffie-hellman (closure => dh closure)
587 diffie-hellman: string,string[,bool]
589 arg2: generator (hex)
590 arg3: whether to check that the modulus is prime [default True]
605 makelist (dictionary => list of definitions)
606 readfile (string => string)
607 map (closure,list => list)
610 returns a list consisting of the definitions in the dictionary. The keys
614 reads the named file and returns its contents as a string
617 applies the closure specified as arg1 to each of the elements in the list.
618 Returns a list made up of the outputs of the closure.
623 This file is part of secnet.
624 See LICENCE and CREDITS for full list of copyright holders.
625 SPDX-License-Identifier: GPL-3.0-or-later
626 There is NO WARRANTY.