1 secnet - flexible VPN software
5 secnet allows large virtual private networks to be constructed
6 spanning multiple separate sites. It is designed for the case where a
7 private network connecting many hosts is 'hidden' behind a single
8 globally-routable IP address, but can also be applied in other
9 circumstances. It communicates entirely using UDP, and works well
10 with gateways that implement network address translation.
12 If you are installing secnet to join an existing VPN, you should read
13 the 'INSTALL' file and your particular VPN's documentation now. You
14 may need to refer back to this file for information on the netlink and
15 comm sections of the configuration file.
17 If you are thinking about setting up a new VPN of any size (from one
18 providing complete links between multiple sites to a simple
19 laptop-to-host link), read the section in this file on 'Creating a
26 * secnet configuration file format
28 By default secnet on linux reads /etc/secnet/secnet.conf. The default
29 may be different on other platforms.
31 This file defines a dictionary (a mapping from keys to values) full of
32 configuration information for secnet. Two keys must be defined in
33 this file for secnet to start. One is "system", a dictionary
34 containing systemwide control parameters. The other is "sites", a
35 list of all the sites that you intend to communicate with.
37 The configuration file has a very simple syntax; keys are defined as
46 Keys must match the following regular expression:
47 [[:alpha:]_][[:alnum:]\-_]*
49 i.e. the first character must be an alpha or an underscore, and the
50 remaining characters may be alphanumeric, '-' or '_'.
52 Keys can be defined to be a comma-separated list of any of the
58 a dictionary of definitions, enclosed in { }
59 a "closure", followed by arguments
60 a path to a key that already exists, to reference that definition
62 Note that dictionaries can be nested: a key in one dictionary can
63 refer to another dictionary. When secnet looks for a key in a
64 particular directory and can't find it, it looks in the dictionary's
65 lexical 'parents' in turn until it finds it (or fails to find it at
66 all and stops with an error).
68 Definitions can refer to previous definitions by naming them with a
69 path. Paths are key1/key2/key3... (starting from wherever we find
70 key1, i.e. in the current dictionary or any of its parents), or
71 alternatively /key1/key2/key3... (to start from the root).
72 Definitions cannot refer to future definitions.
81 The following paths are valid:
93 Note that f/g/e is NOT 4.
95 In a future version of secnet it will also be permissible to list
96 other dictionaries before a dictionary definition,
97 eg. <defaults,otherdefaults>{definitions}. These will be searched in
98 order for keys, before the lexical parent. (This is not yet
101 Elements that are lists are inserted into lists in definitions, not
102 referenced by them (i.e. you can't have lists of lists).
104 Some closures may be followed by an argument list in ( ), and may
105 return any number of whatever type they like (including other
106 closures). Some types of closure (typically those returned from
107 invokations of other closures) cannot be invoked.
109 closure { definitions } is short for closure({definitions}).
111 The main body of secnet, and all the additional modules, predefine
112 some keys in the root dictionary. The main ones are:
114 yes, true, True, TRUE: the boolean value True
115 no, false, False, FALSE: the boolean value False
116 makelist: turns a dictionary (arg1) into a list of definitions
118 readfile: reads a file (arg1) and returns it as a string
120 Keys defined by modules are described below, in the module
123 Other configuration files can be included inline by writing "include
124 filename" at the start of a line.
126 After the configuration file is read, secnet looks for particular keys
127 in configuration space to tell it what to do:
129 system: a dictionary which can contain the following keys:
130 log (log closure): a destination for system messages
131 userid (string): the userid for secnet to run as once it drops privileges
132 pidfile (string): where to store its PID
134 sites: a list of closures of type 'site', which define other tunnel
135 endpoints that secnet will attempt to communicate with
137 * secnet command line options
141 * secnet builtin modules
146 adns (closure => resolver closure)
149 config (string): optional, a resolv.conf for ADNS to use
154 randomsrc (closure => randomsrc closure)
156 randomsrc: string[,bool]
157 arg1: filename of random source
158 arg2: if True then source is blocking
163 udp (closure => comm closure)
166 port (integer): UDP port to listen and send on
167 buffer (buffer closure): buffer for incoming packets
172 logfile (closure => log closure)
173 sysbuffer (closure => buffer closure)
178 site (closure => site closure)
181 local-name (string): this site's name for itself
182 name (string): the name of the site's peer
183 netlink (netlink closure)
185 resolver (resolver closure)
186 random (randomsrc closure)
187 local-key (rsaprivkey closure)
188 address (string): optional, DNS name used to find our peer
189 port (integer): mandatory if 'address' is specified: the port used
191 networks (string list): networks that our peer may claim traffic for
192 key (rsapubkey closure): our peer's public key
193 transform (transform closure): how to mangle packets sent between sites
196 key-lifetime (integer): max lifetime of a session key, in ms [one hour]
197 setup-retries (integer): max number of times to transmit a key negotiation
199 setup-timeout (integer): time between retransmissions of key negotiation
200 packets, in ms [1000]
201 wait-time (integer): after failed key setup, wait this long (in ms) before
202 allowing another attempt [20000]
203 renegotiate-time (integer): if we see traffic on the link after this time
204 then renegotiate another session key immediately [depends on key-lifetime]
205 keepalive (bool): if True then attempt always to keep a valid session key
206 log-events (string list): types of events to log for this site
207 unexpected: unexpected key setup packets (may be late retransmissions)
208 setup-init: start of attempt to setup a session key
209 setup-timeout: failure of attempt to setup a session key, through timeout
210 activate-key: activation of a new session key
211 timeout-key: deletion of current session key through age
212 security: anything potentially suspicious
213 state-change: steps in the key setup protocol
214 packet-drop: whenever we throw away an outgoing packet
215 dump-packets: every key setup packet we see
216 errors: failure of name resolution, internal errors
217 all: everything (too much!)
218 netlink-options (string list): options to pass to netlink device when
219 registering remote networks
220 soft: create 'soft' routes that go away when there's no key established
222 allow-route: allow packets from our peer to be sent down other tunnels,
223 as well as to the host
228 serpent256-cbc (closure => transform closure)
233 null-netlink (closure => netlink closure)
235 null-netlink: dict argument
236 name (string): name for netlink device, used in log messages
237 networks (string list): networks on the host side of the netlink device
238 exclude-remote-networks (string list): networks that may never be claimed
239 by any remote site using this netlink device
240 local-address (string): IP address of host's tunnel interface
241 secnet-address (string): IP address of this netlink device
242 mtu (integer): MTU of host's tunnel interface
247 userv-ipif (closure => netlink closure)
249 userv-ipif: dict argument
250 userv-path (string): optional, where to find userv ["userv"]
251 service-user (string): optional, username for userv-ipif service ["root"]
252 service-name (string): optional, name of userv-ipif service ["ipif"]
253 buffer (buffer closure): buffer for assembly of host->secnet packets
254 plus generic netlink options, as for 'null-netlink'
259 tun (closure => netlink closure) [only on linux-2.4]
260 tun-old (closure => netlink closure)
263 device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
264 interface (string): optional, name of tunnel network interface
265 ifconfig-path (string): optional, path to ifconfig command
266 route-path (string): optional, path to route command
267 buffer (buffer closure): buffer for host->secnet packets
268 plus generic netlink options, as for 'null-netlink'
270 tun-old: dict argument
271 device (string): optional, path of TUN/TAP device file ["/dev/tun*"]
272 interface (string): optional, name of tunnel network interface
273 interface-search (bool): optional, whether to search for a free tunnel
274 interface (True if 'device' not specified, otherwise False)
275 ifconfig-path (string): optional, path to ifconfig command
276 route-path (string): optional, path to route command
277 plus generic netlink options, as for 'null-netlink'
282 rsa-private (closure => rsaprivkey closure)
283 rsa-public (closure => rsapubkey closure)
285 rsa-private: string[,bool]
286 arg1: filename of SSH private key file (version 1, no password)
287 arg2: whether to check that the key is usable [default True]
289 rsa-public: string,string
290 arg1: encryption key (decimal)
291 arg2: modulus (decimal)
296 diffie-hellman (closure => dh closure)
298 diffie-hellman: string,string[,bool]
300 arg2: generator (hex)
301 arg3: whether to check that the modulus is prime [default True]