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 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/
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
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.
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.
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
37 * Mailing lists and bug reporting
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
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.
48 Bug reports should be sent to <steve@greenend.org.uk>; they will be
49 forwarded to the -discuss list by me.
55 * secnet configuration file format
57 By default secnet on linux reads /etc/secnet/secnet.conf. The default
58 may be different on other platforms.
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.
66 The configuration file has a very simple syntax; keys are defined as
75 Keys must match the following regular expression:
76 [[:alpha:]_][[:alnum:]\-_]*
78 i.e. the first character must be an alpha or an underscore, and the
79 remaining characters may be alphanumeric, '-' or '_'.
81 Keys can be defined to be a comma-separated list of any of the
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
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).
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.
110 The following paths are valid:
122 Note that f/g/e is NOT 4.
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).
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.
132 closure { definitions } is short for closure({definitions}).
134 The main body of secnet, and all the additional modules, predefine
135 some keys in the root dictionary. The main ones are:
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
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.
146 Keys defined by modules are described below, in the module
149 Other configuration files can be included inline by writing "include
150 filename" at the start of a line.
152 After the configuration file is read, secnet looks for particular keys
153 in configuration space to tell it what to do:
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
160 sites: a list of closures of type 'site', which define other tunnel
161 endpoints that secnet will attempt to communicate with
163 * secnet command line options
165 Usage: secnet [OPTION]...
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
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): IP address to listen and send on
203 port (integer): UDP port to listen and send on
204 resolver (resolver closure)
205 buffer (buffer closure): buffer for incoming packets
206 authbind (string): optional, path to authbind-helper program
208 udp looks up the following keys in its calling closure (usually, this
209 is a site closure) when a peer needs to be found:
211 address (string): optional, DNS name used to find our peer
212 port (integer): mandatory if 'address' is specified: the port used
219 logfile (closure => log closure)
220 syslog (closure => log closure)
222 logfile: dict argument
223 filename (string): where to log to
224 class (string list): what type of messages to log
225 { "debug-config", M_DEBUG_CONFIG },
226 { "debug-phase", M_DEBUG_PHASE },
227 { "debug", M_DEBUG },
228 { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG },
230 { "notice", M_NOTICE },
231 { "warning", M_WARNING },
232 { "error", M_ERROR },
233 { "security", M_SECURITY },
234 { "fatal", M_FATAL },
235 { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
236 { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
239 logfile will close and reopen its file upon receipt of SIGHUP.
241 syslog: dict argument
242 ident (string): include this string in every log message
243 facility (string): facility to log as
244 { "authpriv", LOG_AUTHPRIV },
245 { "cron", LOG_CRON },
246 { "daemon", LOG_DAEMON },
247 { "kern", LOG_KERN },
248 { "local0", LOG_LOCAL0 },
249 { "local1", LOG_LOCAL1 },
250 { "local2", LOG_LOCAL2 },
251 { "local3", LOG_LOCAL3 },
252 { "local4", LOG_LOCAL4 },
253 { "local5", LOG_LOCAL5 },
254 { "local6", LOG_LOCAL6 },
255 { "local7", LOG_LOCAL7 },
257 { "mail", LOG_MAIL },
258 { "news", LOG_NEWS },
259 { "syslog", LOG_SYSLOG },
260 { "user", LOG_USER },
266 sysbuffer (closure => buffer closure)
268 sysbuffer: integer[,dict]
271 lockdown (boolean): if True, mlock() the buffer
276 site (closure => site closure)
279 local-name (string): this site's name for itself
280 name (string): the name of the site's peer
281 link (netlink closure)
282 comm (one or more comm closures): if there is more than one, the
283 first one will be used for any key setups initiated by us using the
284 configured address. Others are only used if our peer talks to
286 random (randomsrc closure)
287 local-key (rsaprivkey closure)
288 key (rsapubkey closure): our peer's public key
289 transform (transform closure): how to mangle packets sent between sites
292 key-lifetime (integer): max lifetime of a session key, in ms
293 [one hour; mobile: 2 days]
294 setup-retries (integer): max number of times to transmit a key negotiation
295 packet [5; mobile: 30]
296 setup-timeout (integer): time between retransmissions of key negotiation
297 packets, in ms [2000; mobile: 1000]
298 wait-time (integer): after failed key setup, wait this long (in ms) before
299 allowing another attempt [20000; mobile: 10000]
300 renegotiate-time (integer): if we see traffic on the link after this time
301 then renegotiate another session key immediately (in ms)
302 [half key-lifetime, or key-lifetime minus 5 mins (mobile: 12 hours),
303 whichever is longer].
304 keepalive (bool): if True then attempt always to keep a valid session key.
305 Not actually currently implemented. [false]
306 log-events (string list): types of events to log for this site
307 unexpected: unexpected key setup packets (may be late retransmissions)
308 setup-init: start of attempt to setup a session key
309 setup-timeout: failure of attempt to setup a session key, through timeout
310 activate-key: activation of a new session key
311 timeout-key: deletion of current session key through age
312 security: anything potentially suspicious
313 state-change: steps in the key setup protocol
314 packet-drop: whenever we throw away an outgoing packet
315 dump-packets: every key setup packet we see
316 errors: failure of name resolution, internal errors
317 peer-addrs: changes to sets of peer addresses (interesting for mobile peers)
318 all: everything (too much!)
319 mobile (bool): if True then peer is "mobile" ie we assume it may
320 change its apparent IP address and port number without either it
321 or us being aware of the change; so, we remember the last several
322 port/addr pairs we've seen and send packets to all of them
323 (subject to a timeout). We maintain one set of addresses for key
324 setup exchanges, and another for data traffic. Two communicating
325 peers must not each regard the other as mobile, or all the traffic
326 in each direction will be triplicated (strictly, transmitted
327 mobile-peers-max times) and anyway two peers whose public contact
328 address may suddenly change couldn't communicate reliably because
329 their contact addresses might both change at once. [false]
330 mobile-peers-max (integer): Maximum number of peer port/addr pairs we
331 remember and send to. Must be at least 1 and no more than 5. [3]
332 mobile-peer-expiry (integer): For "mobile" peers only, the length
333 of time (in seconds) for which we will keep sending to multiple
334 address/ports from which we have not seen incoming traffic. [120]
335 local-mobile (bool): if True then other peers have been told we are
336 "mobile". This should be True iff the peers' site configurations
337 for us have "mobile True" (and if we find a site configuration for
338 ourselves in the config, we insist on this). The effect is to
339 check that there are no links both ends of which are allegedly
340 mobile (which is not supported, so those links are ignored) and
341 to change some of the tuning parameter defaults. [false]
342 Plus further keys depending on the first comm.
344 Links involving mobile peers have some different tuning parameter
345 default values, which are generally more aggressive about retrying key
346 setup but more relaxed about using old keys. These are noted with
347 "mobile:", above, and apply whether the mobile peer is local or
353 serpent256-cbc (closure => transform closure)
358 null-netlink (closure => closure or netlink closure)
360 null-netlink: dict argument
361 name (string): name for netlink device, used in log messages
362 networks (string list): networks on the host side of the netlink device
363 remote-networks (string list): networks that may be claimed
364 by the remote site using this netlink device
365 local-address (string): IP address of host's tunnel interface
366 secnet-address (string): IP address of this netlink device
367 ptp-address (string): IP address of the other end of a point-to-point link
368 mtu (integer): MTU of host's tunnel interface
370 Only one of secnet-address or ptp-address may be specified. If
371 point-to-point mode is in use then the "routes" option must also be
372 specified, and netlink returns a netlink closure that should be used
373 directly with the "link" option to the site closure. If
374 point-to-point mode is not in use then netlink returns a closure that
375 may be invoked using a dict argument with the following keys to yield
377 routes (string list): networks reachable down the tunnel attached to
378 this instance of netlink
379 options (string list):
380 allow-route: allow packets coming from this tunnel to be routed to
381 other tunnels as well as the host (used for mobile devices like laptops)
382 soft: remove these routes from the host's routing table when
383 the tunnel link quality is zero
384 mtu (integer): default MTU over this link; may be updated by tunnel code
386 Netlink will dump its current routing table to the system/log on
392 userv-ipif (closure => netlink closure)
394 userv-ipif: dict argument
395 userv-path (string): optional, where to find userv ["userv"]
396 service-user (string): optional, username for userv-ipif service ["root"]
397 service-name (string): optional, name of userv-ipif service ["ipif"]
398 buffer (buffer closure): buffer for assembly of host->secnet packets
399 plus generic netlink options, as for 'null-netlink'
404 tun (closure => netlink closure) [only on linux-2.4]
405 tun-old (closure => netlink closure)
408 flavour (string): optional, type of TUN interface to use
409 ("guess","linux","bsd","streams")
410 device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
411 interface (string): optional, name of tunnel network interface
412 ifconfig-path (string): optional, path to ifconfig command
413 route-path (string): optional, path to route command
414 ifconfig-type (string): optional, how to perform ifconfig
415 route-type (string): optional, how to add and remove routes
416 types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5"
417 buffer (buffer closure): buffer for host->secnet packets
418 plus generic netlink options, as for 'null-netlink'
420 I recommend you don't specify the 'interface' option unless you're
421 doing something that requires the interface name to be constant.
426 rsa-private (closure => rsaprivkey closure)
427 rsa-public (closure => rsapubkey closure)
429 rsa-private: string[,bool]
430 arg1: filename of SSH private key file (version 1, no password)
431 arg2: whether to check that the key is usable [default True]
433 rsa-public: string,string
434 arg1: encryption key (decimal)
435 arg2: modulus (decimal)
440 diffie-hellman (closure => dh closure)
442 diffie-hellman: string,string[,bool]
444 arg2: generator (hex)
445 arg3: whether to check that the modulus is prime [default True]
460 makelist (dictionary => list of definitions)
461 readfile (string => string)
462 map (closure,list => list)
465 returns a list consisting of the definitions in the dictionary. The keys
469 reads the named file and returns its contents as a string
472 applies the closure specified as arg1 to each of the elements in the list.
473 Returns a list made up of the outputs of the closure.