Commit | Line | Data |
---|---|---|
558fa3fb SE |
1 | secnet - flexible VPN software |
2 | ||
8dea8d37 SE |
3 | * Copying |
4 | ||
c215a4bc IJ |
5 | secnet is |
6 | Copyright 1995-2003 Stephen Early <steve@greenend.org.uk> | |
7 | Copyright 2002-2014 Ian Jackson <ijackson@chiark.greenend.org.uk> | |
8 | Copyright 1991 Massachusetts Institute of Technology | |
9 | Copyright 1998 Ross Anderson, Eli Biham, Lars Knudsen | |
10 | Copyright 1993 Colin Plumb | |
11 | Copyright 1998 James H. Brown, Steve Reid | |
12 | Copyright 2000 Vincent Rijmen, Antoon Bosselaers, Paulo Barreto | |
13 | Copyright 2001 Saul Kravitz | |
14 | Copyright 2004 Fabrice Bellard | |
15 | Copyright 2002 Guido Draheim | |
16 | Copyright 2005-2010 Free Software Foundation, Inc. | |
17 | Copyright 1995-2001 Jonathan Amery | |
18 | Copyright 1995-2003 Peter Benie | |
19 | Copyright 2011 Richard Kettlewell | |
20 | Copyright 2012 Matthew Vernon | |
781634ba | 21 | Copyright 2013-2017 Mark Wooding |
c215a4bc IJ |
22 | Copyright 1995-2013 Simon Tatham |
23 | ||
24 | secnet is distributed under the terms of the GNU General Public | |
25 | License, version 3 or later. Some individual files have more | |
26 | permissive licences; where this is the case, it is documented in the | |
27 | header comment for the files in question. | |
28 | ||
29 | secnet is distributed in the hope that it will be useful, but WITHOUT | |
30 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
31 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
32 | for more details. | |
33 | ||
34 | The file COPYING contains a copy of the GNU GPL v3. | |
8dea8d37 | 35 | |
8dea8d37 | 36 | |
558fa3fb SE |
37 | * Introduction |
38 | ||
39 | secnet allows large virtual private networks to be constructed | |
40 | spanning multiple separate sites. It is designed for the case where a | |
41 | private network connecting many hosts is 'hidden' behind a single | |
42 | globally-routable IP address, but can also be applied in other | |
43 | circumstances. It communicates entirely using UDP, and works well | |
44 | with gateways that implement network address translation. | |
45 | ||
46 | If you are installing secnet to join an existing VPN, you should read | |
47 | the 'INSTALL' file and your particular VPN's documentation now. You | |
48 | may need to refer back to this file for information on the netlink and | |
49 | comm sections of the configuration file. | |
50 | ||
51 | If you are thinking about setting up a new VPN of any size (from one | |
52 | providing complete links between multiple sites to a simple | |
53 | laptop-to-host link), read the section in this file on 'Creating a | |
54 | VPN'. | |
55 | ||
469fd1d9 SE |
56 | * Mailing lists and bug reporting |
57 | ||
58 | There are two mailing lists associated with secnet: an 'announce' list | |
59 | and a 'discuss' list. Their addresses are: | |
60 | http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-announce | |
61 | http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-discuss | |
62 | ||
63 | The -announce list receives one message per secnet release. The | |
64 | -discuss list is for general discussion, including help with | |
65 | configuration, bug reports, feature requests, etc. | |
66 | ||
67 | Bug reports should be sent to <steve@greenend.org.uk>; they will be | |
68 | forwarded to the -discuss list by me. | |
69 | ||
558fa3fb SE |
70 | * Creating a VPN |
71 | ||
72 | XXX TODO | |
73 | ||
74 | * secnet configuration file format | |
75 | ||
76 | By default secnet on linux reads /etc/secnet/secnet.conf. The default | |
77 | may be different on other platforms. | |
78 | ||
79 | This file defines a dictionary (a mapping from keys to values) full of | |
80 | configuration information for secnet. Two keys must be defined in | |
81 | this file for secnet to start. One is "system", a dictionary | |
82 | containing systemwide control parameters. The other is "sites", a | |
83 | list of all the sites that you intend to communicate with. | |
84 | ||
85 | The configuration file has a very simple syntax; keys are defined as | |
86 | follows: | |
87 | ||
88 | key definition; | |
89 | or | |
90 | key = definition; | |
91 | ||
92 | (the "=" is optional) | |
93 | ||
94 | Keys must match the following regular expression: | |
95 | [[:alpha:]_][[:alnum:]\-_]* | |
96 | ||
97 | i.e. the first character must be an alpha or an underscore, and the | |
98 | remaining characters may be alphanumeric, '-' or '_'. | |
99 | ||
100 | Keys can be defined to be a comma-separated list of any of the | |
101 | following types: | |
102 | ||
103 | a boolean | |
104 | a string, in quotes | |
105 | a number, in decimal | |
106 | a dictionary of definitions, enclosed in { } | |
107 | a "closure", followed by arguments | |
108 | a path to a key that already exists, to reference that definition | |
109 | ||
110 | Note that dictionaries can be nested: a key in one dictionary can | |
111 | refer to another dictionary. When secnet looks for a key in a | |
112 | particular directory and can't find it, it looks in the dictionary's | |
113 | lexical 'parents' in turn until it finds it (or fails to find it at | |
114 | all and stops with an error). | |
115 | ||
116 | Definitions can refer to previous definitions by naming them with a | |
117 | path. Paths are key1/key2/key3... (starting from wherever we find | |
118 | key1, i.e. in the current dictionary or any of its parents), or | |
119 | alternatively /key1/key2/key3... (to start from the root). | |
120 | Definitions cannot refer to future definitions. | |
121 | ||
122 | Example: | |
123 | ||
124 | a=1; | |
125 | b=2; | |
126 | c={ d=3; e=a; }; | |
127 | f={ a=4; g=c; }; | |
128 | ||
129 | The following paths are valid: | |
130 | a is 1 | |
131 | b is 2 | |
132 | c is a dictionary: | |
133 | c/d is 3 | |
134 | c/e is 1 | |
135 | f is a dictionary: | |
136 | f/a is 4 | |
137 | f/g is a dictionary: | |
138 | f/g/d is 3 | |
139 | f/g/e is 1 | |
140 | ||
141 | Note that f/g/e is NOT 4. | |
142 | ||
558fa3fb SE |
143 | Elements that are lists are inserted into lists in definitions, not |
144 | referenced by them (i.e. you can't have lists of lists). | |
145 | ||
146 | Some closures may be followed by an argument list in ( ), and may | |
147 | return any number of whatever type they like (including other | |
148 | closures). Some types of closure (typically those returned from | |
149 | invokations of other closures) cannot be invoked. | |
150 | ||
151 | closure { definitions } is short for closure({definitions}). | |
152 | ||
153 | The main body of secnet, and all the additional modules, predefine | |
154 | some keys in the root dictionary. The main ones are: | |
155 | ||
fe5e9cc4 SE |
156 | yes, true, True, TRUE, on: the boolean value True |
157 | no, false, False, FALSE, off: the boolean value False | |
558fa3fb SE |
158 | makelist: turns a dictionary (arg1) into a list of definitions |
159 | (ignoring the keys) | |
160 | readfile: reads a file (arg1) and returns it as a string | |
3b83c932 SE |
161 | map: applies the closure specified as arg1 to each of the |
162 | remaining elements in the list in turn. Returns a list | |
163 | made up of the outputs of the closure. | |
558fa3fb SE |
164 | |
165 | Keys defined by modules are described below, in the module | |
166 | documentation. | |
167 | ||
168 | Other configuration files can be included inline by writing "include | |
169 | filename" at the start of a line. | |
170 | ||
171 | After the configuration file is read, secnet looks for particular keys | |
172 | in configuration space to tell it what to do: | |
173 | ||
174 | system: a dictionary which can contain the following keys: | |
175 | log (log closure): a destination for system messages | |
176 | userid (string): the userid for secnet to run as once it drops privileges | |
177 | pidfile (string): where to store its PID | |
178 | ||
179 | sites: a list of closures of type 'site', which define other tunnel | |
180 | endpoints that secnet will attempt to communicate with | |
181 | ||
182 | * secnet command line options | |
183 | ||
469fd1d9 SE |
184 | Usage: secnet [OPTION]... |
185 | ||
186 | -f, --silent, --quiet suppress error messages | |
187 | -w, --nowarnings suppress warnings | |
188 | -v, --verbose output extra diagnostics | |
189 | -c, --config=filename specify a configuration file | |
190 | -j, --just-check-config stop after reading configfile | |
191 | -n, --nodetach do not run in background | |
192 | -d, --debug=item,... set debug options | |
193 | --help display this help and exit | |
194 | --version output version information and exit | |
558fa3fb SE |
195 | |
196 | * secnet builtin modules | |
197 | ||
198 | ** resolver | |
199 | ||
200 | Defines: | |
201 | adns (closure => resolver closure) | |
202 | ||
3454dce4 SE |
203 | adns: dict argument |
204 | config (string): optional, a resolv.conf for ADNS to use | |
205 | ||
558fa3fb SE |
206 | ** random |
207 | ||
208 | Defines: | |
209 | randomsrc (closure => randomsrc closure) | |
210 | ||
3454dce4 SE |
211 | randomsrc: string[,bool] |
212 | arg1: filename of random source | |
213 | arg2: if True then source is blocking | |
214 | ||
558fa3fb SE |
215 | ** udp |
216 | ||
217 | Defines: | |
218 | udp (closure => comm closure) | |
219 | ||
3454dce4 | 220 | udp: dict argument |
9c44ef13 IJ |
221 | address (string list): IPv6 or IPv4 addresses to listen and send on; |
222 | default is all local addresses | |
223 | port (integer): UDP port to listen and send on; optional if you | |
224 | don't need to have a stable address for your peers to talk to | |
225 | (in which case your site ought probably to have `local-mobile true'). | |
3454dce4 | 226 | buffer (buffer closure): buffer for incoming packets |
b2a56f7c | 227 | authbind (string): optional, path to authbind-helper program |
3454dce4 | 228 | |
ce5c098f IJ |
229 | ** polypath |
230 | ||
231 | Defines: | |
232 | polypath (closure => comm closure) | |
233 | ||
234 | polypath: dict argument | |
235 | port (integer): UDP port to listen and send on | |
236 | buffer (buffer closure): buffer for incoming packets | |
237 | authbind (string): optional, path to authbind-helper program | |
238 | max-interfaces (number): optional, max number of different interfaces to | |
03cbfbd2 IJ |
239 | use (also, maximum steady-state amount of packet multiplication); |
240 | interfaces marked with `@' do not count. | |
ce5c098f | 241 | interfaces (string list): which interfaces to process; each entry is |
03cbfbd2 IJ |
242 | optionally `!' or `+' or `@' followed by a glob pattern (which is |
243 | applied to a prospective interface using fnmatch with no flags). | |
244 | `+' or nothing means to process normally. `!' means to ignore; | |
245 | `@' means to use only in conjunction with dedicated-interface-addr. | |
246 | If no list is specified, or the list ends with a `!' entry, a | |
247 | default list is used/appended: | |
248 | "!tun*","!tap*","!sl*","!userv*","!lo","@hippo*","*". | |
249 | Patterns which do not start with `*' or an alphanumeric need to be | |
250 | preceded by `!' or `+' or `@'. | |
ce5c098f IJ |
251 | monitor-command (string list): Program to use to monitor appearance |
252 | and disappearance of addresses on local network interfaces. Should | |
253 | produce lines of the form `+|-<ifname> 4|6 <addr>' where <addr> is | |
254 | an address literal. Each - line should relate to a previously | |
255 | printed + line. On startup, should produce a + line for each | |
256 | currently existing address. secnet does filtering so there is no | |
257 | need to strip out tun interfaces, multicast addresses, and so on. | |
258 | The command is run as the user secnet is started as (not the one | |
259 | which secnet may drop privilege to due to the configured `userid'). | |
260 | The default depends on the operating system. | |
261 | permit-loopback (boolean): Normally, loopback IPv6 and IPv4 | |
262 | addresses on local interfaces are disregarded, because such | |
263 | interfaces are not interesting for communicating with distant | |
264 | hosts. Setting this option will ignore that check, which can be | |
265 | useful for testing. Setting this option also removes "!lo*" from | |
266 | the default interface pattern list. | |
267 | ||
268 | When using this comm, packets are sent out of every active interface | |
269 | on the host (where possible). It is important that interfaces created | |
270 | by secnet itself are not included! secnet's default filter list tries | |
271 | to do this. | |
272 | ||
273 | This comm only makes sense for sites which are mobile. That is, the | |
274 | site closures used with this comm should all have the `local-mobile' | |
275 | parameter set to `true'. When the local site site is not marked | |
276 | mobile the address selection machinery might fixate on an unsuitable | |
277 | address. | |
278 | ||
03cbfbd2 IJ |
279 | polypath takes site-specific informtion as passed to the `comm-info' |
280 | site closure parameter. The entries understood in the dictionary | |
281 | are: | |
282 | dedicated-interface-addr (string): IPv4 or IPv6 address | |
283 | literal. Interfaces specified with `@' in `interfaces' will be | |
284 | used for the corresponding site iff the interface local address | |
285 | is this address. | |
286 | ||
ce5c098f IJ |
287 | For an interface to work with polypath, it must either have a suitable |
288 | default route, or be a point-to-point interface. In the general case | |
289 | this might mean that the host would have to have multiple default | |
290 | routes. However in practice the most useful configuration is two | |
291 | interfaces being (1) wifi (2) mobile internet. | |
292 | ||
293 | I have had success on Linux by using network-manager for wifi and | |
294 | invoking ppp directly for mobile internet. ppp sets up a | |
295 | point-to-point link, and does not add a default route if there already | |
296 | is one. network-manager always sets up a default route. The result | |
297 | is that the wifi always has a default route (so is useable); ppp | |
298 | (being a point-to-point link) does not need one. | |
299 | ||
93cdea57 IJ |
300 | The use of polypath requires that secnet be started with root |
301 | privilege, to make the setsockopt(,,SO_BINDTODEVICE,) calls. If the | |
302 | configuration specifies that secnet should drop privilege (see | |
303 | `userid' above), secnet will keep a special process around for this | |
304 | purpose; that process will handle local network interface changes but | |
305 | does not deal with any packets, key exchange, etc. | |
ce5c098f IJ |
306 | |
307 | polypath support is only available when secnet is built against an | |
308 | IPv6-capable version of adns (because it wants features in the newer | |
309 | adns). | |
310 | ||
042a8da9 | 311 | ** log |
558fa3fb SE |
312 | |
313 | Defines: | |
314 | logfile (closure => log closure) | |
b2a56f7c | 315 | syslog (closure => log closure) |
558fa3fb | 316 | |
b2a56f7c SE |
317 | logfile: dict argument |
318 | filename (string): where to log to | |
319 | class (string list): what type of messages to log | |
320 | { "debug-config", M_DEBUG_CONFIG }, | |
321 | { "debug-phase", M_DEBUG_PHASE }, | |
322 | { "debug", M_DEBUG }, | |
323 | { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG }, | |
324 | { "info", M_INFO }, | |
325 | { "notice", M_NOTICE }, | |
326 | { "warning", M_WARNING }, | |
327 | { "error", M_ERROR }, | |
328 | { "security", M_SECURITY }, | |
329 | { "fatal", M_FATAL }, | |
330 | { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL }, | |
331 | { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL }, | |
332 | { "quiet", M_FATAL } | |
333 | ||
042a8da9 SE |
334 | logfile will close and reopen its file upon receipt of SIGHUP. |
335 | ||
b2a56f7c SE |
336 | syslog: dict argument |
337 | ident (string): include this string in every log message | |
338 | facility (string): facility to log as | |
339 | { "authpriv", LOG_AUTHPRIV }, | |
340 | { "cron", LOG_CRON }, | |
341 | { "daemon", LOG_DAEMON }, | |
342 | { "kern", LOG_KERN }, | |
343 | { "local0", LOG_LOCAL0 }, | |
344 | { "local1", LOG_LOCAL1 }, | |
345 | { "local2", LOG_LOCAL2 }, | |
346 | { "local3", LOG_LOCAL3 }, | |
347 | { "local4", LOG_LOCAL4 }, | |
348 | { "local5", LOG_LOCAL5 }, | |
349 | { "local6", LOG_LOCAL6 }, | |
350 | { "local7", LOG_LOCAL7 }, | |
351 | { "lpr", LOG_LPR }, | |
352 | { "mail", LOG_MAIL }, | |
353 | { "news", LOG_NEWS }, | |
354 | { "syslog", LOG_SYSLOG }, | |
355 | { "user", LOG_USER }, | |
356 | { "uucp", LOG_UUCP } | |
357 | ||
042a8da9 SE |
358 | ** util |
359 | ||
360 | Defines: | |
361 | sysbuffer (closure => buffer closure) | |
362 | ||
b2a56f7c SE |
363 | sysbuffer: integer[,dict] |
364 | arg1: buffer length | |
365 | arg2: options: | |
366 | lockdown (boolean): if True, mlock() the buffer | |
367 | ||
558fa3fb SE |
368 | ** site |
369 | ||
370 | Defines: | |
371 | site (closure => site closure) | |
372 | ||
3454dce4 SE |
373 | site: dict argument |
374 | local-name (string): this site's name for itself | |
375 | name (string): the name of the site's peer | |
469fd1d9 | 376 | link (netlink closure) |
59533c16 IJ |
377 | comm (one or more comm closures): if there is more than one, the |
378 | first one will be used for any key setups initiated by us using the | |
379 | configured address. Others are only used if our peer talks to | |
380 | them. | |
3454dce4 SE |
381 | resolver (resolver closure) |
382 | random (randomsrc closure) | |
383 | local-key (rsaprivkey closure) | |
83dbdd3f IJ |
384 | address (string list): optional, DNS name(s) used to find our peer; |
385 | address literals are supported too if enclosed in `[' `]'. | |
3454dce4 SE |
386 | port (integer): mandatory if 'address' is specified: the port used |
387 | to contact our peer | |
3454dce4 SE |
388 | key (rsapubkey closure): our peer's public key |
389 | transform (transform closure): how to mangle packets sent between sites | |
390 | dh (dh closure) | |
391 | hash (hash closure) | |
e57264d6 IJ |
392 | key-lifetime (integer): max lifetime of a session key, in ms |
393 | [one hour; mobile: 2 days] | |
3454dce4 | 394 | setup-retries (integer): max number of times to transmit a key negotiation |
e57264d6 | 395 | packet [5; mobile: 30] |
3454dce4 | 396 | setup-timeout (integer): time between retransmissions of key negotiation |
e57264d6 | 397 | packets, in ms [2000; mobile: 1000] |
19074a85 IJ |
398 | wait-time (integer): after failed key setup, wait roughly this long |
399 | (in ms) before allowing another attempt [20000; mobile: 10000] | |
400 | Actual wait time is randomly chosen between ~0.5x and ~1.5x this. | |
3454dce4 | 401 | renegotiate-time (integer): if we see traffic on the link after this time |
e7f8ec2a | 402 | then renegotiate another session key immediately (in ms) |
e57264d6 IJ |
403 | [half key-lifetime, or key-lifetime minus 5 mins (mobile: 12 hours), |
404 | whichever is longer]. | |
b98e450d | 405 | keepalive (bool): if True then attempt always to keep a valid session key. |
e6d6991c | 406 | [false] |
3454dce4 SE |
407 | log-events (string list): types of events to log for this site |
408 | unexpected: unexpected key setup packets (may be late retransmissions) | |
409 | setup-init: start of attempt to setup a session key | |
410 | setup-timeout: failure of attempt to setup a session key, through timeout | |
411 | activate-key: activation of a new session key | |
412 | timeout-key: deletion of current session key through age | |
413 | security: anything potentially suspicious | |
414 | state-change: steps in the key setup protocol | |
415 | packet-drop: whenever we throw away an outgoing packet | |
416 | dump-packets: every key setup packet we see | |
417 | errors: failure of name resolution, internal errors | |
446353cd | 418 | peer-addrs: changes to sets of peer addresses (interesting for mobile peers) |
3454dce4 | 419 | all: everything (too much!) |
446353cd IJ |
420 | mobile (bool): if True then peer is "mobile" ie we assume it may |
421 | change its apparent IP address and port number without either it | |
422 | or us being aware of the change; so, we remember the last several | |
423 | port/addr pairs we've seen and send packets to all of them | |
424 | (subject to a timeout). We maintain one set of addresses for key | |
425 | setup exchanges, and another for data traffic. Two communicating | |
426 | peers must not each regard the other as mobile, or all the traffic | |
427 | in each direction will be triplicated (strictly, transmitted | |
428 | mobile-peers-max times) and anyway two peers whose public contact | |
429 | address may suddenly change couldn't communicate reliably because | |
430 | their contact addresses might both change at once. [false] | |
431 | mobile-peers-max (integer): Maximum number of peer port/addr pairs we | |
d18903cf | 432 | remember and send to. Must be at least 1 and no more than 5. |
83dbdd3f | 433 | [4 if any address is configured, otherwise 3] |
0f27325c IJ |
434 | static-peers-max (integer): Maximum number of peer port/addr pairs |
435 | we can try for a static site. Must be at least 1 and no more | |
d18903cf | 436 | than 5. [4 or 3, as above] |
446353cd IJ |
437 | mobile-peer-expiry (integer): For "mobile" peers only, the length |
438 | of time (in seconds) for which we will keep sending to multiple | |
439 | address/ports from which we have not seen incoming traffic. [120] | |
dba19f84 IJ |
440 | local-mobile (bool): if True then other peers have been told we are |
441 | "mobile". This should be True iff the peers' site configurations | |
442 | for us have "mobile True" (and if we find a site configuration for | |
443 | ourselves in the config, we insist on this). The effect is to | |
444 | check that there are no links both ends of which are allegedly | |
e57264d6 IJ |
445 | mobile (which is not supported, so those links are ignored) and |
446 | to change some of the tuning parameter defaults. [false] | |
3ed1846a IJ |
447 | mtu-target (integer): Desired value of the inter-site MTU for this |
448 | peering. This value will be advertised to the peer (which ought | |
449 | to affect incoming packets), and if the peer advertises an MTU its | |
450 | value will be combined with this setting to compute the inter-site | |
451 | MTU. (secnet will still accept packets which exceed the | |
452 | (negotiated or assumed) inter-site MTU.) Setting a lower | |
453 | inter-site MTU can be used to try to restrict the sizes of the | |
454 | packets sent over the underlying public network (e.g. to work | |
455 | around network braindamage). It is not normally useful to set a | |
456 | larger value for mtu-target than the VPN's general MTU (which | |
457 | should be reflected in the local private interface MTU, ie the mtu | |
458 | parameter to netlink). If this parameter is not set, or is set | |
459 | to 0, the default is to use the local private link mtu. | |
5dfe538b IJ |
460 | comm-info (dict): Information for the comm, used when this site |
461 | wants to transmit. If the comm does not support this, it is | |
03cbfbd2 | 462 | ignored. |
e57264d6 IJ |
463 | |
464 | Links involving mobile peers have some different tuning parameter | |
465 | default values, which are generally more aggressive about retrying key | |
466 | setup but more relaxed about using old keys. These are noted with | |
467 | "mobile:", above, and apply whether the mobile peer is local or | |
468 | remote. | |
3454dce4 | 469 | |
b02b720a IJ |
470 | ** transform-eax |
471 | ||
472 | Defines: | |
473 | eax-serpent (closure => transform closure) | |
474 | ||
92a7d254 | 475 | ** transform-cbcmac |
558fa3fb SE |
476 | |
477 | Defines: | |
478 | serpent256-cbc (closure => transform closure) | |
479 | ||
480 | ** netlink | |
481 | ||
482 | Defines: | |
469fd1d9 | 483 | null-netlink (closure => closure or netlink closure) |
3454dce4 SE |
484 | |
485 | null-netlink: dict argument | |
486 | name (string): name for netlink device, used in log messages | |
487 | networks (string list): networks on the host side of the netlink device | |
0e212483 RK |
488 | remote-networks (string list): networks that may be claimed |
489 | by the remote site using this netlink device | |
3454dce4 SE |
490 | local-address (string): IP address of host's tunnel interface |
491 | secnet-address (string): IP address of this netlink device | |
c6f79b17 | 492 | ptp-address (string): IP address of the other end of a point-to-point link |
3454dce4 SE |
493 | mtu (integer): MTU of host's tunnel interface |
494 | ||
469fd1d9 SE |
495 | Only one of secnet-address or ptp-address may be specified. If |
496 | point-to-point mode is in use then the "routes" option must also be | |
497 | specified, and netlink returns a netlink closure that should be used | |
498 | directly with the "link" option to the site closure. If | |
499 | point-to-point mode is not in use then netlink returns a closure that | |
500 | may be invoked using a dict argument with the following keys to yield | |
501 | a netlink closure: | |
502 | routes (string list): networks reachable down the tunnel attached to | |
503 | this instance of netlink | |
504 | options (string list): | |
505 | allow-route: allow packets coming from this tunnel to be routed to | |
506 | other tunnels as well as the host (used for mobile devices like laptops) | |
0e212483 | 507 | soft: remove these routes from the host's routing table when |
469fd1d9 | 508 | the tunnel link quality is zero |
3ed1846a | 509 | mtu (integer): MTU of host's tunnel interface |
c6f79b17 | 510 | |
042a8da9 SE |
511 | Netlink will dump its current routing table to the system/log on |
512 | receipt of SIGUSR1. | |
513 | ||
3454dce4 SE |
514 | ** slip |
515 | ||
516 | Defines: | |
558fa3fb | 517 | userv-ipif (closure => netlink closure) |
3454dce4 SE |
518 | |
519 | userv-ipif: dict argument | |
520 | userv-path (string): optional, where to find userv ["userv"] | |
521 | service-user (string): optional, username for userv-ipif service ["root"] | |
522 | service-name (string): optional, name of userv-ipif service ["ipif"] | |
523 | buffer (buffer closure): buffer for assembly of host->secnet packets | |
524 | plus generic netlink options, as for 'null-netlink' | |
525 | ||
526 | ** tun | |
527 | ||
528 | Defines: | |
558fa3fb SE |
529 | tun (closure => netlink closure) [only on linux-2.4] |
530 | tun-old (closure => netlink closure) | |
3454dce4 SE |
531 | |
532 | tun: dict argument | |
ff05a229 SE |
533 | flavour (string): optional, type of TUN interface to use |
534 | ("guess","linux","bsd","streams") | |
3454dce4 SE |
535 | device (string): optional, path of TUN/TAP device file ["/dev/net/tun"] |
536 | interface (string): optional, name of tunnel network interface | |
537 | ifconfig-path (string): optional, path to ifconfig command | |
538 | route-path (string): optional, path to route command | |
ff05a229 SE |
539 | ifconfig-type (string): optional, how to perform ifconfig |
540 | route-type (string): optional, how to add and remove routes | |
541 | types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5" | |
3454dce4 SE |
542 | buffer (buffer closure): buffer for host->secnet packets |
543 | plus generic netlink options, as for 'null-netlink' | |
544 | ||
ff05a229 SE |
545 | I recommend you don't specify the 'interface' option unless you're |
546 | doing something that requires the interface name to be constant. | |
c6f79b17 | 547 | |
558fa3fb SE |
548 | ** rsa |
549 | ||
550 | Defines: | |
551 | rsa-private (closure => rsaprivkey closure) | |
552 | rsa-public (closure => rsapubkey closure) | |
553 | ||
3454dce4 SE |
554 | rsa-private: string[,bool] |
555 | arg1: filename of SSH private key file (version 1, no password) | |
556 | arg2: whether to check that the key is usable [default True] | |
557 | ||
558 | rsa-public: string,string | |
559 | arg1: encryption key (decimal) | |
560 | arg2: modulus (decimal) | |
561 | ||
558fa3fb SE |
562 | ** dh |
563 | ||
564 | Defines: | |
565 | diffie-hellman (closure => dh closure) | |
566 | ||
3454dce4 SE |
567 | diffie-hellman: string,string[,bool] |
568 | arg1: modulus (hex) | |
569 | arg2: generator (hex) | |
570 | arg3: whether to check that the modulus is prime [default True] | |
571 | ||
558fa3fb SE |
572 | ** md5 |
573 | ||
574 | Defines: | |
575 | md5 (hash closure) | |
3454dce4 SE |
576 | |
577 | ** sha1 | |
578 | ||
579 | Defines: | |
580 | sha1 (hash closure) | |
c6f79b17 SE |
581 | |
582 | ** conffile | |
583 | ||
584 | Defines: | |
585 | makelist (dictionary => list of definitions) | |
586 | readfile (string => string) | |
587 | map (closure,list => list) | |
588 | ||
589 | makelist: dictionary | |
590 | returns a list consisting of the definitions in the dictionary. The keys | |
591 | are discarded. | |
592 | ||
593 | readfile: string | |
594 | reads the named file and returns its contents as a string | |
595 | ||
596 | map: | |
597 | applies the closure specified as arg1 to each of the elements in the list. | |
598 | Returns a list made up of the outputs of the closure. |