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