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