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