Makefile.in: Drop dist target
[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
9c6a8729 8.\" the Free Software Foundation; either version 3 of the License, or
c215a4bc
IJ
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.
3ca86f6d
RK
287
288.SS logfile
289\fBlogfile(\fIDICT\fB)\fR => \fIlog closure\fR
290.PP
291Valid keys in the \fIDICT\fR argument are:
292.TP
293.B filename
294The path to log to.
295.TP
296.B class
297A list of strings defining which classes of message to log.
298The possible message classes are \fBdebug-config\fR,
299\fBdebug-phase\fR, \fBdebug\fR, \fBinfo\fR, \fBnotice\fR,
300\fBwarning\fR, \fBerror\fR, \fBsecurity\fR and \fBfatal\fR.
301.IP
302\fBall-debug\fR is the union of all the \fBdebug\fR... classes.
303\fBdefault\fR is equivalent to \fBwarning, error, security, fatal\fR.
304\fBverbose\fR is equivalent to \fBinfo, notice, warning, error,
305security, fatal\fR.
306\fBquiet\fR is equivalent to \fBfatal\fR.
307.PP
308A \fIlog closure\fR is a means of saving log messages.
309See also \fBsyslog\fR below.
310
311.SS makelist
312\fBmakelist(\fIDICT\fB)\fR => \fILIST\fR
313.PP
314Returns the (flattened) list of values from the dictionary, discarding
315the keys.
316
317.SS map
318\fBmap(\fICLOSURE\fB, \fIINPUT\fR...\fB)\fR => \fILIST\fR
319.PP
320Applies \fICLOSURE\fR to all its additional input arguments and
321returns the resulting list.
322
323.SS md5
324\fBmd5\fR is a \fIhash closure\fR implementing the MD5 algorithm.
325
326.SS null-netlink
327\fBnull-netlink(\fIDICT\fB)\fR => \fInetlink closure\fR
328.br
329\fBnull-netlink(\fIDICT\fB)\fR => \fIpure closure\fR
330.\" TODO pure closure is what it's called internally but this is a
331.\" very opaque name to use in docs
332.PP
333Valid keys in the \fIDICT\fR argument are:
334.TP
335.B name
336String.
337The name for the netlink device.
338The default is \fBnull-netlink\fR.
339.TP
340.B networks
341List of strings.
342The networks on the host side of the netlink device.
343.TP
344.B remote-networks
345List of strings.
346Networks that may be claimed by remote sites using this netlink device.
347.TP
348.B secnet-address
349String.
350IP address of this netlink.
351Incompatible with \fBptp-address\fR.
352.TP
353.B ptp-address
354String.
355IP address of the other end of a point-to-point link.
356Incompatible with \fBsecnet-address\fR.
357.TP
358.B mtu
359Number.
360The MTU of the netlink device.
361The default is 1000.
362.PP
363If \fBptp-address\fR is used then the result is a \fInetlink closure\fR.
364This can be used directly with the \fBlink\fR key in the \fBsites\fR
365closure (see below).
366.PP
367If \fBsecnet-address\fR is used then the result is a \fIpure
368closure\fR.
369This must be evaluated to yield a \fInetlink closure\fR, using a
370dictionary argument with the following keys:
371.TP
372.B routes
373String list.
374networks reachable via this tunnel, in \fIaddress\fB/\fIbits\fR format.
375.TP
376.B options
377String list.
378A list of options:
379.RS
380.TP
381.B allow-route
382Allow packets received via this tunnel to be routed down other tunnels
383(without this option only packets from the host will be routed).
384.TP
385.B soft
386Remove these routes from the host routing table when the link quality
387is 0.
388.RE
389.TP
390.B mtu
391Number.
392Default MTU over this link.
393The default is inherited from the \fIpure closure\fR.
394.TP
395.B priority
396Number.
397The priority of this link.
398Higher values beat lower values.
399The default is 0.
400
401.\" TODO ptp-address turns up in sites.conf, but why? I think this
402.\" is a bug in make-secnet-sites; it is not used by
403 \" netlink_inst_create.
404
405.PP
406A \fInetlink closure\fR is a virtual IP link, and is supplied to the
407\fBlink\fR key of a \fIsite\fR closure.
408.PP
409The netlink created by \fBnull-netlink\fR has no connection to the
410host.
411See \fBtun\fR and \fBuserv-ipif\fR below for more useful alternatives.
412
413
414
415.SS randomfile
416\fBrandomfile(\fIFILENAME\fR[\fB, \fIBLOCKING\fR]\fB)\fR => \fIrandomsource closure\fR
417.TP
418.I FILENAME
419String.
420Path to random device, e.g. \fI/dev/urandom\fR.
421.TP
422.I BLOCKING
423Boolean.
424\fBTrue\fR if this is a blocking device and \fBfalse\fR otherwise (the default).
425Blocking device support is not implemented so this must always be
426\fBFalse\fR or absent.
427.PP
428A \fIrandomsource closure\fR is a source of random numbers.
429
430.SS readfile
431\fBreadfile(\fIPATH\fB)\fR => \fISTRING\fR
432.PP
433Read the contents of the file \fIPATH\fR (a string) and return it as a string.
434
b02b720a 435.SS eax-serpent
161f20c2 436\fBeax-serpent(\fIDICT\fB)\fR => \fItransform closure\fR
3ca86f6d
RK
437.PP
438Valid keys in the \fIDICT\fR argument are:
439.TP
440.B max-sequence-skew
441The maximum acceptable difference between the sequence number in a
442received, decrypted message and the previous one.
443The default is 10.
444It may be necessary to increase this is if connectivity is poor.
b02b720a
IJ
445.TP
446.B tag-length-bytes
447The length of the message authentication tag. The default is 16,
448for a 128-bit tag length. It must be no longer than the Serpent
449blocksize, 16. Must be have the same value at both ends.
450.TP
451.B padding-rounding
452Messages are padded to a multiple of this many bytes. This
453serves to obscure the exact length of messages. The default is 16,
5b5f297f
IJ
454.TP
455.B capab-num
456The transform capability number to use when advertising this
457transform. Both ends must have the same meaning (or, at least, a
458compatible transform) for each transform capability number they have
459in common. The default for serpent-eax is 9.
460.IP
461Transform capability numbers in the range 8..15 are intended for
462allocation by the implementation, and may be assigned as the default
463for new transforms in the future. Transform capability numbers in the
464range 0..7 are reserved for definition by the user.
3ca86f6d
RK
465.PP
466A \fItransform closure\fR is a reversible means of transforming
467messages for transmission over a (presumably) insecure network.
468It is responsible for both confidentiality and integrity.
b02b720a
IJ
469
470.SS serpent256-cbc
471\fBserpent256-cbc(\fIDICT\fB)\fR => \fItransform closure\fR
472.PP
5b5f297f
IJ
473This transform
474is deprecated as its security properties are poor; it should be
475specified only alongside a better transform such as eax-serpent.
476.PP
b02b720a
IJ
477Valid keys in the \fIDICT\fR argument are:
478.TP
5b5f297f
IJ
479.B capab-num
480As above. The default for serpent256-cbc is 8.
481.TP
b02b720a
IJ
482.B max-sequence-skew
483As above.
af43f0b7
IJ
484.PP
485Note that this uses a big-endian variant of the Serpent block cipher
486(which is not compatible with most other Serpent implementations).
3ca86f6d
RK
487.SS rsa-private
488\fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR
489.TP
490.I PATH
491String.
492The path to a file containing an RSA private key in SSH format
493(version 1).
494There must be no passphrase.
495.TP
496.I CHECK
497Boolean.
498If \fBtrue\fR (the default) then check that the key is valid.
499
500.SS rsa-public
501\fBrsa-public(\fIKEY\fB, \fIMODULUS\fB)\fR => \fIrsapubkey closure\fR
502.TP
503.I KEY
504String.
505The public key exponent (\fIe\fR), in decimal.
506.TP
507.I MODULUS
508String.
509The modulus (\fIn\fR), in decimal.
510
511.SS sha1
512\fBsha1\fR is a \fIhash closure\fR implementing the SHA-1 algorithm.
513
514.SS site
515\fBsite(\fIDICT\fB)\fR => \fIsite closure\fR
516.PP
517Valid keys in the \fIDICT\fR argument are:
518.TP
519.B local-name
520String.
521The site's name for itself.
522.TP
523.B name
524String.
525The name of the site's peer.
526.TP
527.B link
528A \fInetlink closure\fR.
529.TP
530.B comm
531A \fIcomm closure\fR.
532.TP
533.B resolver
534A \fIresolver closure\fR.
535.TP
536.B random
537A \fIrandomsource closure\fR.
538.TP
539.B local-key
540An \fIrsaprivkey closure\fR.
541The key used to prove our identity to the peer.
542.TP
543.B address
544String.
545The DNS name of the peer.
546Optional, but if it is missing then it will not be possible to
547initiate new connections to the peer.
548.TP
549.B port
550Number.
551The port to contact the peer.
552.TP
553.B key
554An \fIrsapubkey closure\fR.
555The key used to verify the peer's identity.
556.TP
557.B transform
5b5f297f
IJ
558One or more \fItransform closures\fR.
559Used to protect packets exchanged with the peer. These should
560all have distinct \fBcapab-num\fR values, and the same \fBcapab-num\fR
561value should refer to the same (or a compatible) transform at both
562ends. The list should be in order of preference, most preferred
563first. (The end which sends MSG1,MSG3 ends up choosing; the ordering
564at the other end is irrelevant.)
3ca86f6d
RK
565.TP
566.B dh
567A \fIdh closure\fR.
568The group to use in key exchange.
569.TP
570.B hash
571The hash function used during setup.
572.\" TODO clarify what we actually use it for!
573.TP
574.B key-lifetime
575Number.
576The maximum lifetime of a session key in milliseconds.
577The default is one hour.
578.TP
579.B setup-retries
580Number.
581The maximum number of times a key negotiation packet will be
582transmitted before giving up.
583The default is 5.
584.TP
585.B setup-timeout
586Number.
587The time between retransmissions of key negotiation packets, in milliseconds.
588The default is one second.
589.TP
590.B wait-time
591Number.
592The time to wait after a failed key setup before making another
593attempt, in milliseconds.
594The default is 20s.
595.TP
596.B renegotiate-time
597Number.
598The time after which a new session key will be negotiated, \fIif\fR
599there is traffic on the link, in milliseconds.
600It must not be greater than the \fBkey-lifetime\fR.
601The default 5 minutes less than the key lifetime, unless the lifetime
602is less than 10 minutes in which case the default is half the
603lifetime.
604.TP
605.B keepalive
606Boolean.
607If \fBtrue\fR then attempt to always maintain a live session key.
608Not implemented.
609.TP
610.B log-events
611String list.
612Types of event to log for this site.
613.RS
614.TP
615.B unexpected
616Unexpected key setup packets (including late retransmissions).
617.TP
618.B setup-init
619Start of attempt to setup a session key.
620.TP
621.B setup-timeout
622Failure of attempt to setup a session key, through timeout.
623.TP
624.B activate-key
625Activation of a new session key.
626.TP
627.B timeout-key
628Deletion of current session key through age.
629.TP
630.B security
631Anything potentially suspicious.
632.TP
633.B state-change
634Steps in the key setup protocol.
635.TP
636.B packet-drop
637Whenever we throw away an outgoing packet.
638.TP
639.B dump-packets
640Every key setup packet we see.
641.TP
642.B errors
643Failure of name resolution, internal errors.
644.TP
645.B all
646Everything (too much!)
647.RE
648.PP
649A \fIsite closure\fR defines one site to communicate with.
650\fBsecnet\fR expects the (root) key \fBsite\fR to be a list of site
651closures.
652
653.SS sysbuffer
654\fBsysbuffer(\fR[\fISIZE\fR[\fB, \fIOPTIONS\fR]]\fB)\fR => \fIbuffer closure\fR
655.TP
656.I SIZE
657Number.
658The size of the buffer in bytes.
659This must be between 64 and 131072.
660The default is 4096.
661.TP
662.I OPTIONS
663Dictionary.
664Optional and presently unused.
665.\" lockdown is accepted but ignored.
666.PP
667A \fIbuffer closure\fR is a means of buffering packets to send or that
668have been received.
669
670.SS syslog
671\fBsyslog(\fIDICT\fB)\fR => \fIlog closure\fR
672.PP
673Valid keys in the \fIDICT\fR argument are:
674.TP
675.B ident
676String.
677The ident string to pass to \fBopenlog\fR(3); this value will appear
678in each message.
679.TP
680.B facility
681String.
682The facility to log as.
683The possible values are \fBauthpriv\fR, \fBcron\fR, \fBdaemon\fR,
684\fBkern\fR, \fBlocal0\fR-\fB7\fR, \fBlpr\fR, \fBmail\fR, \fBnews\fR,
685\fBsyslog\fR, \fBuser\fR and \fBuucp\fR.
686.PP
687See also \fBlogfile\fR above.
688
689.SS tun
690\fBtun(\fIDICT\fB)\fR => \fInetlink closure\fR
691.br
692\fBtun(\fIDICT\fB)\fR => \fIpure closure\fR
693.PP
694Valid keys in the \fIDICT\fR argument are those documented for
695\fBnull-netlink\fR above, plus:
696.TP
697.B flavour
698String.
699The type of TUN interface to use.
700Possible values are \fBlinux\fR, \fBbsd\fR, \fBstreams\fR and \fBguess\fR.
701The default is \fBguess\fR.
702.TP
703.B device
704String.
705The path to the TUN/TAP device file.
706The default is \fI/dev/net/tun\fR for the \fBlinux\fR flavour and
707\fI/dev/tun\fR for the others.
708.TP
709.B interface
710String.
711The interface to use.
712The default is to pick one automatically.
713This cannot be used with the \fBstreams\fR flavour.
714.TP
715.B local-address
716String.
717IP address of the host's tunnel interface.
718.\" README says this belongs to netlink-null but actually it's
719 \" duplicated between slip & tun
720.TP
721.B ifconfig-path
722String.
723The name of the \fBifconfig\fR command.
724The default is simply "ifconfig".
725.TP
726.B route-path
727String.
728The name of the \fBroute\fR command.
729The default is simply "route".
730.TP
731.B ifconfig-type
732String.
733The syntax expected by the \fBifconfig\fR command.
734Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
735\fBsolaris-2.5\fR and \fBguess\fR.
736The default is \fBguess\fR.
737.TP
738.B route-type
739String.
740The syntax expected by the \fBifconfig\fR command.
741Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
742\fBsolaris-2.5\fR and \fBguess\fR.
743The default is \fBguess\fR.
744.TP
745.B buffer
746A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
747The buffer size must be at least 60 greater than the MTU.
748.\" TODO rumour has is that buffers are sometimes shareable between
749.\" netlink devices - document that if the conditions are reasonable
750.\" ones.
751.PP
752The \fBifconfig-type\fR and \fBroute-type\fR values determine how
753those commands are executed.
754If they are set to \fBioctl\fR then low-level system calls are used
755directly instead of invoking the commands.
756.PP
757The netlink created by \fBtun\fR uses the \fBtun\fR device to
758communicate with the host kernel.
759
760.SS udp
761\fBudp(\fIDICT\fB)\fR => \fIcomm closure\fR
762.PP
763Valid keys in the \fIDICT\fR argument are:
764.TP
765.B address
766String.
767The IP address to bind on.
768The default is 0.0.0.0, i.e. "any".
769.TP
770.B port
771Number.
772The port number to bind to.
773The default is 0, i.e. the OS will choose one.
774It is suggested that any given VPN agree a common port number.
775.TP
776.B buffer
777A \fIbuffer closure\fR.
778See the \fBsysbuffer\fR closure above.
779.TP
780.B authbind
781String.
782The path to a helper program to bind the socket.
783Optional.
784.IP
785The program will be invoked with the address and port number as its
786arguments, and with the socket to bind as file descriptor 0.
787It should either bind the socket as requested, or exit with nonzero
788status.
789.PP
790A \fIcomm closure\fR is a means of sending and receiving messages via
791a network.
792It does not provide confidentiality, reliablity or availability.
793
794.SS userv-ipif
795\fBuserv-ipif(\fIDICT\fB)\fR => \fInetlink closure\fR
796.br
797\fBuserv-ipif(\fIDICT\fB)\fR => \fIpure closure\fR
798.PP
799Valid keys in the \fIDICT\fR argument are those documented for
800\fBnull-netlink\fR above, plus:
801.TP
802.B local-address
803String.
804IP address of the host's SLIP interface.
805.\" README says this belongs to netlink-null but actually it's
806 \" duplicated between SLIP & tun
807.TP
808.B userv-path
809String.
810Where to find \fBuserv\fR(1).
811The default is \fB"userv"\fR.
812.TP
813.B service-user
814String.
815The name of the user that owns the service.
816The default is \fB"root"\fR.
817.TP
818.B service-name
819String.
820The name of the service to request.
821The default is \fB"ipif"\fR.
822.TP
823.B buffer
824A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
825.PP
826The netlink created by \fBuserv-ipif\fR invokes the specified \fBuserv\fR service with pipes connected to its standard input and output.
827It uses SLIP to communicate with the host kernel via these pipes.
828
829.SH FILES
830.TP
831.I /etc/secnet/secnet.conf
832Configuration file.
833
834.SH "SEE ALSO"
835\fBuserv\fR(1)