1 secnet - flexible VPN software
5 secnet is Copyright (C) 1995--2001 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 In a future version of secnet it will also be permissible to list
125 other dictionaries before a dictionary definition,
126 eg. <defaults,otherdefaults>{definitions}. These will be searched in
127 order for keys, before the lexical parent. (This is not yet
130 Elements that are lists are inserted into lists in definitions, not
131 referenced by them (i.e. you can't have lists of lists).
133 Some closures may be followed by an argument list in ( ), and may
134 return any number of whatever type they like (including other
135 closures). Some types of closure (typically those returned from
136 invokations of other closures) cannot be invoked.
138 closure { definitions } is short for closure({definitions}).
140 The main body of secnet, and all the additional modules, predefine
141 some keys in the root dictionary. The main ones are:
143 yes, true, True, TRUE: the boolean value True
144 no, false, False, FALSE: the boolean value False
145 makelist: turns a dictionary (arg1) into a list of definitions
147 readfile: reads a file (arg1) and returns it as a string
149 Keys defined by modules are described below, in the module
152 Other configuration files can be included inline by writing "include
153 filename" at the start of a line.
155 After the configuration file is read, secnet looks for particular keys
156 in configuration space to tell it what to do:
158 system: a dictionary which can contain the following keys:
159 log (log closure): a destination for system messages
160 userid (string): the userid for secnet to run as once it drops privileges
161 pidfile (string): where to store its PID
163 sites: a list of closures of type 'site', which define other tunnel
164 endpoints that secnet will attempt to communicate with
166 * secnet command line options
168 Usage: secnet [OPTION]...
170 -f, --silent, --quiet suppress error messages
171 -w, --nowarnings suppress warnings
172 -v, --verbose output extra diagnostics
173 -c, --config=filename specify a configuration file
174 -j, --just-check-config stop after reading configfile
175 -n, --nodetach do not run in background
176 -d, --debug=item,... set debug options
177 --help display this help and exit
178 --version output version information and exit
180 * secnet builtin modules
185 adns (closure => resolver closure)
188 config (string): optional, a resolv.conf for ADNS to use
193 randomsrc (closure => randomsrc closure)
195 randomsrc: string[,bool]
196 arg1: filename of random source
197 arg2: if True then source is blocking
202 udp (closure => comm closure)
205 port (integer): UDP port to listen and send on
206 buffer (buffer closure): buffer for incoming packets
207 authbind (string): optional, path to authbind-helper program
212 logfile (closure => log closure)
213 syslog (closure => log closure)
215 logfile: dict argument
216 filename (string): where to log to
217 class (string list): what type of messages to log
218 { "debug-config", M_DEBUG_CONFIG },
219 { "debug-phase", M_DEBUG_PHASE },
220 { "debug", M_DEBUG },
221 { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG },
223 { "notice", M_NOTICE },
224 { "warning", M_WARNING },
225 { "error", M_ERROR },
226 { "security", M_SECURITY },
227 { "fatal", M_FATAL },
228 { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
229 { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
232 logfile will close and reopen its file upon receipt of SIGHUP.
234 syslog: dict argument
235 ident (string): include this string in every log message
236 facility (string): facility to log as
237 { "authpriv", LOG_AUTHPRIV },
238 { "cron", LOG_CRON },
239 { "daemon", LOG_DAEMON },
240 { "kern", LOG_KERN },
241 { "local0", LOG_LOCAL0 },
242 { "local1", LOG_LOCAL1 },
243 { "local2", LOG_LOCAL2 },
244 { "local3", LOG_LOCAL3 },
245 { "local4", LOG_LOCAL4 },
246 { "local5", LOG_LOCAL5 },
247 { "local6", LOG_LOCAL6 },
248 { "local7", LOG_LOCAL7 },
250 { "mail", LOG_MAIL },
251 { "news", LOG_NEWS },
252 { "syslog", LOG_SYSLOG },
253 { "user", LOG_USER },
259 sysbuffer (closure => buffer closure)
261 sysbuffer: integer[,dict]
264 lockdown (boolean): if True, mlock() the buffer
269 site (closure => site closure)
272 local-name (string): this site's name for itself
273 name (string): the name of the site's peer
274 link (netlink closure)
276 resolver (resolver closure)
277 random (randomsrc closure)
278 local-key (rsaprivkey closure)
279 address (string): optional, DNS name used to find our peer
280 port (integer): mandatory if 'address' is specified: the port used
282 key (rsapubkey closure): our peer's public key
283 transform (transform closure): how to mangle packets sent between sites
286 key-lifetime (integer): max lifetime of a session key, in ms [one hour]
287 setup-retries (integer): max number of times to transmit a key negotiation
289 setup-timeout (integer): time between retransmissions of key negotiation
290 packets, in ms [1000]
291 wait-time (integer): after failed key setup, wait this long (in ms) before
292 allowing another attempt [20000]
293 renegotiate-time (integer): if we see traffic on the link after this time
294 then renegotiate another session key immediately [depends on key-lifetime]
295 keepalive (bool): if True then attempt always to keep a valid session key
296 log-events (string list): types of events to log for this site
297 unexpected: unexpected key setup packets (may be late retransmissions)
298 setup-init: start of attempt to setup a session key
299 setup-timeout: failure of attempt to setup a session key, through timeout
300 activate-key: activation of a new session key
301 timeout-key: deletion of current session key through age
302 security: anything potentially suspicious
303 state-change: steps in the key setup protocol
304 packet-drop: whenever we throw away an outgoing packet
305 dump-packets: every key setup packet we see
306 errors: failure of name resolution, internal errors
307 all: everything (too much!)
312 serpent256-cbc (closure => transform closure)
317 null-netlink (closure => closure or netlink closure)
319 null-netlink: dict argument
320 name (string): name for netlink device, used in log messages
321 networks (string list): networks on the host side of the netlink device
322 exclude-remote-networks (string list): networks that may never be claimed
323 by any remote site using this netlink device
324 local-address (string): IP address of host's tunnel interface
325 secnet-address (string): IP address of this netlink device
326 ptp-address (string): IP address of the other end of a point-to-point link
327 mtu (integer): MTU of host's tunnel interface
329 Only one of secnet-address or ptp-address may be specified. If
330 point-to-point mode is in use then the "routes" option must also be
331 specified, and netlink returns a netlink closure that should be used
332 directly with the "link" option to the site closure. If
333 point-to-point mode is not in use then netlink returns a closure that
334 may be invoked using a dict argument with the following keys to yield
336 routes (string list): networks reachable down the tunnel attached to
337 this instance of netlink
338 options (string list):
339 allow-route: allow packets coming from this tunnel to be routed to
340 other tunnels as well as the host (used for mobile devices like laptops)
341 soft-route: remove these routes from the host's routing table when
342 the tunnel link quality is zero
343 mtu (integer): default MTU over this link; may be updated by tunnel code
345 Netlink will dump its current routing table to the system/log on
351 userv-ipif (closure => netlink closure)
353 userv-ipif: dict argument
354 userv-path (string): optional, where to find userv ["userv"]
355 service-user (string): optional, username for userv-ipif service ["root"]
356 service-name (string): optional, name of userv-ipif service ["ipif"]
357 buffer (buffer closure): buffer for assembly of host->secnet packets
358 plus generic netlink options, as for 'null-netlink'
363 tun (closure => netlink closure) [only on linux-2.4]
364 tun-old (closure => netlink closure)
367 flavour (string): optional, type of TUN interface to use
368 ("guess","linux","bsd","streams")
369 device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
370 interface (string): optional, name of tunnel network interface
371 ifconfig-path (string): optional, path to ifconfig command
372 route-path (string): optional, path to route command
373 ifconfig-type (string): optional, how to perform ifconfig
374 route-type (string): optional, how to add and remove routes
375 types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5"
376 buffer (buffer closure): buffer for host->secnet packets
377 plus generic netlink options, as for 'null-netlink'
379 I recommend you don't specify the 'interface' option unless you're
380 doing something that requires the interface name to be constant.
385 rsa-private (closure => rsaprivkey closure)
386 rsa-public (closure => rsapubkey closure)
388 rsa-private: string[,bool]
389 arg1: filename of SSH private key file (version 1, no password)
390 arg2: whether to check that the key is usable [default True]
392 rsa-public: string,string
393 arg1: encryption key (decimal)
394 arg2: modulus (decimal)
399 diffie-hellman (closure => dh closure)
401 diffie-hellman: string,string[,bool]
403 arg2: generator (hex)
404 arg3: whether to check that the modulus is prime [default True]
419 makelist (dictionary => list of definitions)
420 readfile (string => string)
421 map (closure,list => list)
424 returns a list consisting of the definitions in the dictionary. The keys
428 reads the named file and returns its contents as a string
431 applies the closure specified as arg1 to each of the elements in the list.
432 Returns a list made up of the outputs of the closure.