chiark / gitweb /
site: Pass whynot through to named_for_us
[secnet.git] / secnet.8
1 .\" Man page for secnet.
2 .\"
3 .\" See the secnet.git README, or the Debian copyright file, for full
4 .\" list of copyright holders.
5 .\"
6 .\" secnet is free software; you can redistribute it and/or modify it
7 .\" under the terms of the GNU General Public License as published by
8 .\" the Free Software Foundation; either version 3 of the License, or
9 .\" (at your option) any later version.
10 .\" 
11 .\" secnet is distributed in the hope that it will be useful, but
12 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
13 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 .\" General Public License for more details.
15 .\" 
16 .\" You should have received a copy of the GNU General Public License
17 .\" version 3 along with secnet; if not, see
18 .\" https://www.gnu.org/licenses/gpl.html.
19 .TH secnet 8
20
21 .SH NAME
22 secnet \- VPN router daemon
23
24 .SH SYNOPSIS
25 \fBsecnet\fR [\fIOPTIONS\fR]
26
27 .SH DESCRIPTION
28 \fBsecnet\fR allows virtual private networks to be constructed
29 spanning multiple separate sites.
30
31 .SH OPTIONS
32 .TP
33 .B --verbose\fR, \fB-v
34 Enable extra diagnostics.
35 .TP
36 .B --nowarnings\fR, \fB-w
37 Suppress warnings.
38 .TP
39 .B --help
40 Display usage message.
41 .TP
42 .B --version
43 Display version string.
44 .TP
45 .B --nodetach\fR, \fB-n
46 Don't go into background.
47 The default behaviour is to become a daemon during startup.
48 .TP
49 .B --silent\fR, \fB--quiet\fR, \fB-f
50 Suppress error messages.
51 .TP
52 .B --debug\fR, \fB-d
53 Enable debug messages.
54 .TP
55 .B --config\fR, \fB-c \fIPATH
56 Specify configuration file.
57 The default is \fI/etc/secnet/secnet.conf\fR.
58 .TP
59 .B --just-check-config\fR, \fB-j
60 Check configuration and exit.
61 .TP
62 .B --sites-key\fR, \fB-s \fIKEY
63 Configuration file key defining active sites.
64 The default is \fBsites\fR.
65
66 .SH "CAPABILITY NEGOTIATION"
67 Sites negotiate with each other during key exchange
68 in order to determine which cryptographic algorithms and other features
69 \(en termed
70 .I capabilities
71 \(en
72 they each support.
73 Capabilities are assigned small integer numbers.
74 In many cases,
75 capability numbers can be assigned in the configuration file,
76 as described below;
77 but secnet's default assignments will often be satisfactory.
78 .PP
79 Capability numbers between 0 and 7 inclusive
80 are reserved for local use:
81 secnet will never make use of them without explicit configuration.
82 This may be useful to migrate from one set of parameters
83 for a particular cryptographic algorithm
84 to different, incompatible, parameters for the same algorithm.
85 Other capability numbers are assigned by default
86 by various kinds of closures.
87 See the descriptions below for details.
88 .PP
89 It is essential that a capability number mean the same thing
90 to each of a pair of peers.
91 It's possible to configure a site
92 so that it uses different capability numbers for the same feature
93 when it communicates with different peer sites,
94 but this is likely to be more confusing than useful.
95
96 .SH "CONFIGURATION FILE"
97 .SS Overview
98 The default configuration file is \fI/etc/secnet/secnet.conf\fR.
99 This can be overridden with the \fB--config\fR option.
100 .PP
101 The configuration file defines a dictionary (a mapping from keys to
102 values) of configuration information for secnet.
103 It is recursive in nature, i.e. values may themselves include dictionaries.
104 Any node in the nested structure thus defined can be identified by a
105 \fIpath\fR, which is the sequence of keys necessary to reach it from
106 the root, separated by "/" characters.
107 See \fBPaths\fR below for how this is used.
108 .PP
109 Furthermore, when a key is looked up in a dictionary, if it cannot be
110 found, it is sought in the parent dictionary, and so on back to the
111 root.
112 For instance, each \fIsite\fR must contain the \fBresolver\fR key, but
113 in a typical configuration there is no value in having different
114 resolvers for each site.
115 Therefore \fBresolver\fR is defined at the root and thus automatically
116 incorporated into all sites.
117 .SS Whitespace
118 Whitespace, including newlines, is ignored except to the extent that
119 it bounds other symbols.
120 .PP
121 Comment begin with "#" and continues to the end of the line.
122 Comments are ignored.
123 .SS Inclusion
124 A file may be recursively included into the configuration file using a
125 line of the form:
126 .IP
127 \fBinclude \fIPATH
128 .PP
129 This is handled at a higher level than the main parser and so
130 precludes the possibility of using the string \fBinclude\fR for any
131 other purpose.
132 .\" check if this is true.  it's probably a bug!
133 .SS Assignments
134 The configuration file contains one or more assigments.
135 Each assignment is written:
136 .IP
137 \fIkey\fR [\fB=\fR] \fIlist\fR\fB;\fR
138 .PP
139 i.e. the equals sign is optional.
140 The semicolon is mandatory in all contexts.
141 .PP
142 Keys start with a letter or "_" and continue with any numbers of
143 letters, digits, "_" and "-".
144 .PP
145 Each \fIkey\fR is a list of one or more \fIvalues\fR, separated by commas.
146 Possible values types are \fIboolean\fR, \fIstring\fR, \fInumber\fR,
147 \fIdictionary\fR, \fIpath\fR and \fIclosure evaluation\fR.
148 .\" This man page draws a distinction between a closure (the thing
149 .\" evaluated) and a closure evaluation (the closure plus is
150 .\" arguments).
151 .SS "Strings"
152 Strings are contained within "double quotes".
153 There is (currently) no escape syntax and no way to include quotes
154 inside strings.
155 .PP
156 Example:
157 .nf
158         filename "/var/log/secnet";
159 .fi
160 .SS "Numbers"
161 Numbers are encoded in decimal and do not include a sign.
162 Numbers must lie in the range 0 to 4294967295.
163 .PP
164 Example:
165 .nf
166         mtu 1400;
167 .fi
168 .SS "Dictionaries"
169 .\" In conffile.y dictionaries can be preceded by a search path, but
170 .\" this is not implemented elsewhere, so not documented here.
171 Dictionaries consist of one or more assignments, in the same syntax as
172 given above, enclosed in "{" and "}".
173 .PP
174 Example:
175 .nf
176         system {
177                 userid "secnet";
178                 pidfile "/var/run/secnet.pid";
179         };
180 .fi
181 .SS "Paths"
182 Paths allow a key already defined in the configuration to be aliased.
183 .PP
184 Paths consist of a sequence of keys separated by "/".
185 If the path starts with a "/" then it is an \fIabsolute path\fR and
186 the search starts at the root of the configuration.
187 Otherwise it is a \fIrelative path\fR and starts in the containing
188 dictionary or in any of its parents, down to and including the root.
189 If there is more than one match, the one furthest from the root "wins".
190 .PP
191 The value of a path is the list assigned to the key it refers to.
192 Lists are flattened; for example if a key is defined as a list of two
193 paths, and each of those refers to a list of two integers, the
194 original key is therefore defined to be a list of four integers, not
195 a list consisting of two lists.
196 .PP
197 It is not possible to refer to a \fIlater\fR key using a path.
198 .PP
199 Example:
200 .nf
201         vpn {
202           test {
203             kakajou vpn-data/test/kakajou/kakajou;
204             araminta vpn-data/test/araminta/araminta;
205             deodand vpn-data/test/deodand/deodand;
206             all-sites kakajou,araminta,deodand;
207           };
208         };
209         all-sites vpn/test/all-sites;
210 .fi
211 .PP
212 Here, each of \fBvpn/test/kakajou\fR, \fBvpn/test/araminta\fR and
213 \fBvpn/test/deodand\fR are defined as aliases to values defined
214 elsewhere.
215 \fBvpn/tests/all-sites\fR is defined as the list of all three of those
216 values, and \fBall-sites\fR is then defined to be an alias for that.
217 .SS "Booleans"
218 The (single-element) paths \fBfalse\fR, \fBno\fR and \fBnowise\fR are
219 predefined and refer to a boolean false value.
220 Similarly \fBtrue\fR, \fByes\fR and \fBverily\fR point at a boolean
221 true value.
222 .PP
223 In all six cases, variants with just the first letter capitalized, and
224 with all letters capitalized, are also provided.
225 .PP
226 Example:
227 .nf
228         random randomfile("/dev/urandom",no);
229 .fi
230 .SS "Closure Evaluation"
231 Closure evaluation uses the following syntax:
232 .IP
233 \fICLOSURE \fB( \fIARGUMENTS \fB)
234 .PP
235 \fICLOSURE\fR may be a path referring to a closure, or may itself be a
236 closure evaluation.
237 .PP
238 \fIARGUMENTS\fR is a list of zero or more values, separated by commas.
239 As a shortcut, if the arguments consist of a single dictionary, the
240 parentheses may be ommitted:
241 .IP
242 \fICLOSURE \fB{ \fR... \fB}
243 .PP
244 Example:
245 .nf
246         sites map(site, vpn/test/all-sites);
247 .fi
248 .PP
249 When a closure is evaluated it returns a value (a list, much as above)
250 and may also have side effects (which may be immediate or may be
251 deferred to some later phase of execution).
252 A list of built-in closures is given below.
253 .SS "Mandatory Keys"
254 Two keys are mandatory.
255 \fBsystem\fR must be a dictionary in which the following keys can be
256 looked up:
257 .TP
258 .B log
259 A \fIlog closure\fR; see the \fBlogfile\fR documentation below.
260 The destination for log messages.
261 Mandatory.
262 .TP
263 .B userid
264 A string.
265 The userid to run as after dropping privilege.
266 Optional.
267 .TP
268 .B pidfile
269 A string.
270 The path to write a pidfile.
271 Optional.
272 .PP
273 \fBsites\fR should be a list of \fIsite closures\fR; see the \fBsite\fR documentation below.
274 This defines the collection of tunnel endpoints that \fBsecnet\fR will
275 communicate with.
276 .PP
277 Recall the recursive lookup logic described in \fBOverview\fR above:
278 if (for instance) \fBlog\fR is defined in the top level dictionary but
279 not in \fBsystem\fR, it will nevertheless be found when looked up in
280 the latter.
281
282 .SH CLOSURES
283 \fBsecnet\fR contains a collection of built-in closures
284 with names (i.e. single-element paths) given below.
285 .PP
286 Most of them return anonymous closures of various types,
287 which are described contextually.
288
289 .SS adns
290 \fBadns(\fIDICT\fB)\fR => \fIresolver closure\fR
291 .TP
292 .I DICT
293 This either be empty or contain the single key \fBconfig\fR, with a
294 string value giving configuration to supply to ADNS.
295 This might be read from a file using \fBreadfile\fR.
296 .PP
297 A \fIresolver closure\fR is a means of converting hostnames into
298 network addresses.
299
300 .SS diffie-hellman
301 .PP
302 \fBdiffie-hellman(\fIMODULUS\fB, \fIGENERATOR\fR[\fB, \fICHECK\fR]\fB)\fR => \fIdh closure\fR
303 .TP
304 .I MODULUS
305 String.
306 The prime modulus \fIp\fR in hex.
307 .TP
308 .I GENERATOR
309 String.
310 The generator \fIg\fR in hex.
311 .TP
312 .I CHECK
313 Boolean.
314 If \fBtrue\fR (the default) then check if \fIp\fR is prime.
315 .PP
316 A \fIdh closure\fR defines a group to be used for key exchange.
317
318 .SS logfile
319 \fBlogfile(\fIDICT\fB)\fR => \fIlog closure\fR
320 .PP
321 Valid keys in the \fIDICT\fR argument are:
322 .TP
323 .B filename
324 The path to log to.
325 .TP
326 .B class
327 A list of strings defining which classes of message to log.
328 The possible message classes are \fBdebug-config\fR,
329 \fBdebug-phase\fR, \fBdebug\fR, \fBinfo\fR, \fBnotice\fR,
330 \fBwarning\fR, \fBerror\fR, \fBsecurity\fR and \fBfatal\fR.
331 .IP
332 \fBall-debug\fR is the union of all the \fBdebug\fR... classes.
333 \fBdefault\fR is equivalent to \fBwarning, error, security, fatal\fR.
334 \fBverbose\fR is equivalent to \fBinfo, notice, warning, error,
335 security, fatal\fR.
336 \fBquiet\fR is equivalent to \fBfatal\fR.
337 .PP
338 A \fIlog closure\fR is a means of saving log messages.
339 See also \fBsyslog\fR below.
340
341 .SS makelist
342 \fBmakelist(\fIDICT\fB)\fR => \fILIST\fR
343 .PP
344 Returns the (flattened) list of values from the dictionary, discarding
345 the keys.
346
347 .SS map
348 \fBmap(\fICLOSURE\fB, \fIINPUT\fR...\fB)\fR => \fILIST\fR
349 .PP
350 Applies \fICLOSURE\fR to all its additional input arguments and
351 returns the resulting list.
352
353 .SS md5
354 \fBmd5\fR is a \fIhash closure\fR implementing the MD5 algorithm.
355
356 .SS null-netlink
357 \fBnull-netlink(\fIDICT\fB)\fR => \fInetlink closure\fR
358 .br
359 \fBnull-netlink(\fIDICT\fB)\fR => \fIpure closure\fR
360 .\" TODO pure closure is what it's called internally but this is a
361 .\" very opaque name to use in docs
362 .PP
363 Valid keys in the \fIDICT\fR argument are:
364 .TP
365 .B name
366 String.
367 The name for the netlink device.
368 The default is \fBnull-netlink\fR.
369 .TP
370 .B networks
371 List of strings.
372 The networks on the host side of the netlink device.
373 .TP
374 .B remote-networks
375 List of strings.
376 Networks that may be claimed by remote sites using this netlink device.
377 .TP
378 .B secnet-address
379 String.
380 IP address of this netlink.
381 Incompatible with \fBptp-address\fR.
382 .TP
383 .B ptp-address
384 String.
385 IP address of the other end of a point-to-point link.
386 Incompatible with \fBsecnet-address\fR.
387 .TP
388 .B mtu
389 Number.
390 The MTU of the netlink device.
391 The default is 1000.
392 .PP
393 If \fBptp-address\fR is used then the result is a \fInetlink closure\fR.
394 This can be used directly with the \fBlink\fR key in the \fBsites\fR
395 closure (see below).
396 .PP
397 If \fBsecnet-address\fR is used then the result is a \fIpure
398 closure\fR.
399 This must be evaluated to yield a \fInetlink closure\fR, using a
400 dictionary argument with the following keys:
401 .TP
402 .B routes
403 String list.
404 networks reachable via this tunnel, in \fIaddress\fB/\fIbits\fR format.
405 .TP
406 .B options
407 String list.
408 A list of options:
409 .RS
410 .TP
411 .B allow-route
412 Allow packets received via this tunnel to be routed down other tunnels
413 (without this option only packets from the host will be routed).
414 .TP
415 .B soft
416 Remove these routes from the host routing table when the link quality
417 is 0.
418 .RE
419 .TP
420 .B mtu
421 Number.
422 Default MTU over this link.
423 The default is inherited from the \fIpure closure\fR.
424 .TP
425 .B priority
426 Number.
427 The priority of this link.
428 Higher values beat lower values.
429 The default is 0.
430
431 .\" TODO ptp-address turns up in sites.conf, but why?  I think this
432 .\" is a bug in make-secnet-sites; it is not used by
433  \" netlink_inst_create.
434
435 .PP
436 A \fInetlink closure\fR is a virtual IP link, and is supplied to the
437 \fBlink\fR key of a \fIsite\fR closure.
438 .PP
439 The netlink created by \fBnull-netlink\fR has no connection to the
440 host.
441 See \fBtun\fR and \fBuserv-ipif\fR below for more useful alternatives.
442
443
444
445 .SS randomfile
446 \fBrandomfile(\fIFILENAME\fR[\fB, \fIBLOCKING\fR]\fB)\fR => \fIrandomsource closure\fR
447 .TP
448 .I FILENAME
449 String.
450 Path to random device, e.g. \fI/dev/urandom\fR.
451 .TP
452 .I BLOCKING
453 Boolean.
454 \fBTrue\fR if this is a blocking device and \fBfalse\fR otherwise (the default).
455 Blocking device support is not implemented so this must always be
456 \fBFalse\fR or absent.
457 .PP
458 A \fIrandomsource closure\fR is a source of random numbers.
459
460 .SS readfile
461 \fBreadfile(\fIPATH\fB)\fR => \fISTRING\fR
462 .PP
463 Read the contents of the file \fIPATH\fR (a string) and return it as a string.
464
465 .SS eax-serpent
466 \fBeax-serpent(\fIDICT\fB)\fR => \fItransform closure\fR
467 .PP
468 Valid keys in the \fIDICT\fR argument are:
469 .TP
470 .B max-sequence-skew
471 The maximum acceptable difference between the sequence number in a
472 received, decrypted message and the previous one.
473 The default is 10.
474 It may be necessary to increase this is if connectivity is poor.
475 .TP
476 .B tag-length-bytes
477 The length of the message authentication tag.  The default is 16,
478 for a 128-bit tag length.  It must be no longer than the Serpent
479 blocksize, 16.  Must be have the same value at both ends.
480 .TP
481 .B padding-rounding
482 Messages are padded to a multiple of this many bytes.  This
483 serves to obscure the exact length of messages.  The default is 16,
484 .TP
485 .B capab-num
486 The capability number to use when advertising this
487 transform.  The default for serpent-eax is 9.
488 .PP
489 A \fItransform closure\fR is a reversible means of transforming
490 messages for transmission over a (presumably) insecure network.
491 It is responsible for both confidentiality and integrity.
492
493 .SS serpent256-cbc
494 \fBserpent256-cbc(\fIDICT\fB)\fR => \fItransform closure\fR
495 .PP
496 This transform
497 is deprecated as its security properties are poor; it should be
498 specified only alongside a better transform such as eax-serpent.
499 .PP
500 Valid keys in the \fIDICT\fR argument are:
501 .TP
502 .B capab-num
503 As above.  The default for serpent256-cbc is 8.
504 .TP
505 .B max-sequence-skew
506 As above.
507 .PP
508 Note that this uses a big-endian variant of the Serpent block cipher
509 (which is not compatible with most other Serpent implementations).
510 .SS rsa-private
511 \fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR
512 .TP
513 .I PATH
514 String.
515 The path to a file containing an RSA private key in SSH format
516 (version 1).
517 There must be no passphrase.
518 .TP
519 .I CHECK
520 Boolean.
521 If \fBtrue\fR (the default) then check that the key is valid.
522
523 .SS rsa-public
524 \fBrsa-public(\fIKEY\fB, \fIMODULUS\fB)\fR => \fIrsapubkey closure\fR
525 .TP
526 .I KEY
527 String.
528 The public key exponent (\fIe\fR), in decimal.
529 .TP
530 .I MODULUS
531 String.
532 The modulus (\fIn\fR), in decimal.
533
534 .SS sha1
535 \fBsha1\fR is a \fIhash closure\fR implementing the SHA-1 algorithm.
536
537 .SS site
538 \fBsite(\fIDICT\fB)\fR => \fIsite closure\fR
539 .PP
540 Valid keys in the \fIDICT\fR argument are:
541 .TP
542 .B local-name
543 String.
544 The site's name for itself.
545 .TP
546 .B name
547 String.
548 The name of the site's peer.
549 .TP
550 .B link
551 A \fInetlink closure\fR.
552 .TP
553 .B comm
554 A \fIcomm closure\fR.
555 .TP
556 .B resolver
557 A \fIresolver closure\fR.
558 .TP
559 .B random
560 A \fIrandomsource closure\fR.
561 .TP
562 .B local-key
563 An \fIrsaprivkey closure\fR.
564 The key used to prove our identity to the peer.
565 .TP
566 .B address
567 String.
568 The DNS name of the peer.
569 Optional, but if it is missing then it will not be possible to
570 initiate new connections to the peer.
571 .TP
572 .B port
573 Number.
574 The port to contact the peer.
575 .TP
576 .B key
577 An \fIrsapubkey closure\fR.
578 The key used to verify the peer's identity.
579 .TP
580 .B transform
581 One or more \fItransform closures\fR.
582 Used to protect packets exchanged with the peer.  These should
583 all have distinct \fBcapab-num\fR values, and the same \fBcapab-num\fR
584 value should have the same (or a compatible) meaning at both
585 ends.  The list should be in order of preference, most preferred
586 first.  (The end which sends MSG1,MSG3 ends up choosing; the ordering
587 at the other end is irrelevant.)
588 .TP
589 .B dh
590 A \fIdh closure\fR.
591 The group to use in key exchange.
592 .TP
593 .B hash
594 The hash function used during setup.
595 .\" TODO clarify what we actually use it for!
596 .TP
597 .B key-lifetime
598 Number.
599 The maximum lifetime of a session key in milliseconds.
600 The default is one hour.
601 .TP
602 .B setup-retries
603 Number.
604 The maximum number of times a key negotiation packet will be
605 transmitted before giving up.
606 The default is 5.
607 .TP
608 .B setup-timeout
609 Number.
610 The time between retransmissions of key negotiation packets, in milliseconds.
611 The default is one second.
612 .TP
613 .B wait-time
614 Number.
615 The time to wait after a failed key setup before making another
616 attempt, in milliseconds.
617 The default is 20s.
618 .TP
619 .B renegotiate-time
620 Number.
621 The time after which a new session key will be negotiated, \fIif\fR
622 there is traffic on the link, in milliseconds.
623 It must not be greater than the \fBkey-lifetime\fR.
624 The default 5 minutes less than the key lifetime, unless the lifetime
625 is less than 10 minutes in which case the default is half the
626 lifetime.
627 .TP
628 .B keepalive
629 Boolean.
630 If \fBtrue\fR then attempt to always maintain a live session key.
631 Not implemented.
632 .TP
633 .B log-events
634 String list.
635 Types of event to log for this site.
636 .RS
637 .TP
638 .B unexpected
639 Unexpected key setup packets (including late retransmissions).
640 .TP
641 .B setup-init
642 Start of attempt to setup a session key.
643 .TP
644 .B setup-timeout
645 Failure of attempt to setup a session key, through timeout.
646 .TP
647 .B activate-key
648 Activation of a new session key.
649 .TP
650 .B timeout-key
651 Deletion of current session key through age.
652 .TP
653 .B security
654 Anything potentially suspicious.
655 .TP
656 .B state-change
657 Steps in the key setup protocol.
658 .TP
659 .B packet-drop
660 Whenever we throw away an outgoing packet.
661 .TP
662 .B dump-packets
663 Every key setup packet we see.
664 .TP
665 .B errors
666 Failure of name resolution, internal errors.
667 .TP
668 .B all
669 Everything (too much!)
670 .RE
671 .PP
672 A \fIsite closure\fR defines one site to communicate with.
673 \fBsecnet\fR expects the (root) key \fBsite\fR to be a list of site
674 closures.
675
676 .SS sysbuffer
677 \fBsysbuffer(\fR[\fISIZE\fR[\fB, \fIOPTIONS\fR]]\fB)\fR => \fIbuffer closure\fR
678 .TP
679 .I SIZE
680 Number.
681 The size of the buffer in bytes.
682 This must be between 64 and 131072.
683 The default is 4096.
684 .TP
685 .I OPTIONS
686 Dictionary.
687 Optional and presently unused.
688 .\" lockdown is accepted but ignored.
689 .PP
690 A \fIbuffer closure\fR is a means of buffering packets to send or that
691 have been received.
692
693 .SS syslog
694 \fBsyslog(\fIDICT\fB)\fR => \fIlog closure\fR
695 .PP
696 Valid keys in the \fIDICT\fR argument are:
697 .TP
698 .B ident
699 String.
700 The ident string to pass to \fBopenlog\fR(3); this value will appear
701 in each message.
702 .TP
703 .B facility
704 String.
705 The facility to log as.
706 The possible values are \fBauthpriv\fR, \fBcron\fR, \fBdaemon\fR,
707 \fBkern\fR, \fBlocal0\fR-\fB7\fR, \fBlpr\fR, \fBmail\fR, \fBnews\fR,
708 \fBsyslog\fR, \fBuser\fR and \fBuucp\fR.
709 .PP
710 See also \fBlogfile\fR above.
711
712 .SS tun
713 \fBtun(\fIDICT\fB)\fR => \fInetlink closure\fR
714 .br
715 \fBtun(\fIDICT\fB)\fR => \fIpure closure\fR
716 .PP
717 Valid keys in the \fIDICT\fR argument are those documented for
718 \fBnull-netlink\fR above, plus:
719 .TP
720 .B flavour
721 String.
722 The type of TUN interface to use.
723 Possible values are \fBlinux\fR, \fBbsd\fR, \fBstreams\fR and \fBguess\fR.
724 The default is \fBguess\fR.
725 .TP
726 .B device
727 String.
728 The path to the TUN/TAP device file.
729 The default is \fI/dev/net/tun\fR for the \fBlinux\fR flavour and
730 \fI/dev/tun\fR for the others.
731 .TP
732 .B interface
733 String.
734 The interface to use.
735 The default is to pick one automatically.
736 This cannot be used with the \fBstreams\fR flavour.
737 .TP
738 .B local-address
739 String.
740 IP address of the host's tunnel interface.
741 .\" README says this belongs to netlink-null but actually it's
742  \" duplicated between slip & tun
743 .TP
744 .B ifconfig-path
745 String.
746 The name of the \fBifconfig\fR command.
747 The default is simply "ifconfig".
748 .TP
749 .B route-path
750 String.
751 The name of the \fBroute\fR command.
752 The default is simply "route".
753 .TP
754 .B ifconfig-type
755 String.
756 The syntax expected by the \fBifconfig\fR command.
757 Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
758 \fBsolaris-2.5\fR and \fBguess\fR.
759 The default is \fBguess\fR.
760 .TP
761 .B route-type
762 String.
763 The syntax expected by the \fBifconfig\fR command.
764 Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
765 \fBsolaris-2.5\fR and \fBguess\fR.
766 The default is \fBguess\fR.
767 .TP
768 .B buffer
769 A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
770 The buffer size must be at least 60 greater than the MTU.
771 .\" TODO rumour has is that buffers are sometimes shareable between
772 .\" netlink devices - document that if the conditions are reasonable
773 .\" ones.
774 .PP
775 The \fBifconfig-type\fR and \fBroute-type\fR values determine how
776 those commands are executed.
777 If they are set to \fBioctl\fR then low-level system calls are used
778 directly instead of invoking the commands.
779 .PP
780 The netlink created by \fBtun\fR uses the \fBtun\fR device to
781 communicate with the host kernel.
782
783 .SS udp
784 \fBudp(\fIDICT\fB)\fR => \fIcomm closure\fR
785 .PP
786 Valid keys in the \fIDICT\fR argument are:
787 .TP
788 .B address
789 String.
790 The IP address to bind on.
791 The default is 0.0.0.0, i.e. "any".
792 .TP
793 .B port
794 Number.
795 The port number to bind to.
796 The default is 0, i.e. the OS will choose one.
797 It is suggested that any given VPN agree a common port number.
798 .TP
799 .B buffer
800 A \fIbuffer closure\fR.
801 See the \fBsysbuffer\fR closure above.
802 .TP
803 .B authbind
804 String.
805 The path to a helper program to bind the socket.
806 Optional.
807 .IP
808 The program will be invoked with the address and port number as its
809 arguments, and with the socket to bind as file descriptor 0.
810 It should either bind the socket as requested, or exit with nonzero
811 status.
812 .PP
813 A \fIcomm closure\fR is a means of sending and receiving messages via
814 a network.
815 It does not provide confidentiality, reliablity or availability.
816
817 .SS userv-ipif
818 \fBuserv-ipif(\fIDICT\fB)\fR => \fInetlink closure\fR
819 .br
820 \fBuserv-ipif(\fIDICT\fB)\fR => \fIpure closure\fR
821 .PP
822 Valid keys in the \fIDICT\fR argument are those documented for
823 \fBnull-netlink\fR above, plus:
824 .TP
825 .B local-address
826 String.
827 IP address of the host's SLIP interface.
828 .\" README says this belongs to netlink-null but actually it's
829  \" duplicated between SLIP & tun
830 .TP
831 .B userv-path
832 String.
833 Where to find \fBuserv\fR(1).
834 The default is \fB"userv"\fR.
835 .TP
836 .B service-user
837 String.
838 The name of the user that owns the service.
839 The default is \fB"root"\fR.
840 .TP
841 .B service-name
842 String.
843 The name of the service to request.
844 The default is \fB"ipif"\fR.
845 .TP
846 .B buffer
847 A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
848 .PP
849 The netlink created by \fBuserv-ipif\fR invokes the specified \fBuserv\fR service with pipes connected to its standard input and output.
850 It uses SLIP to communicate with the host kernel via these pipes.
851
852 .SH FILES
853 .TP
854 .I /etc/secnet/secnet.conf
855 Configuration file.
856
857 .SH "SEE ALSO"
858 \fBuserv\fR(1)