4 secnet \- VPN router daemon
7 \fBsecnet\fR [\fIOPTIONS\fR]
10 \fBsecnet\fR allows virtual private networks to be constructed
11 spanning multiple separate sites.
15 .B --verbose\fR, \fB-v
16 Enable extra diagnostics.
18 .B --nowarnings\fR, \fB-w
22 Display usage message.
25 Display version string.
27 .B --nodetach\fR, \fB-n
28 Don't go into background.
29 The default behaviour is to become a daemon during startup.
31 .B --silent\fR, \fB--quiet\fR, \fB-f
32 Suppress error messages.
35 Enable debug messages.
37 .B --config\fR, \fB-c \fIPATH
38 Specify configuration file.
39 The default is \fI/etc/secnet/secnet.conf\fR.
41 .B --just-check-config\fR, \fB-j
42 Check configuration and exit.
44 .B --sites-key\fR, \fB-s \fIKEY
45 Configuration file key defining active sites.
46 The default is \fBsites\fR.
48 .SH "CONFIGURATION FILE"
50 The default configuration file is \fI/etc/secnet/secnet.conf\fR.
51 This can be overridden with the \fB--config\fR option.
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.
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
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.
70 Whitespace, including newlines, is ignored except to the extent that
71 it bounds other symbols.
73 Comment begin with "#" and continues to the end of the line.
76 A file may be recursively included into the configuration file using a
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
84 .\" check if this is true. it's probably a bug!
86 The configuration file contains one or more assigments.
87 Each assignment is written:
89 \fIkey\fR [\fB=\fR] \fIlist\fR\fB;\fR
91 i.e. the equals sign is optional.
92 The semicolon is mandatory in all contexts.
94 Keys start with a letter or "_" and continue with any numbers of
95 letters, digits, "_" and "-".
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
104 Strings are contained within "double quotes".
105 There is (currently) no escape syntax and no way to include quotes
110 filename "/var/log/secnet";
113 Numbers are encoded in decimal and do not include a sign.
114 Numbers must lie in the range 0 to 4294967295.
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 "}".
130 pidfile "/var/run/secnet.pid";
134 Paths allow a key already defined in the configuration to be aliased.
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".
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.
149 It is not possible to refer to a \fIlater\fR key using a path.
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;
161 all-sites vpn/test/all-sites;
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
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.
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
175 In all six cases, variants with just the first letter capitalized, and
176 with all letters capitalized, are also provided.
180 random randomfile("/dev/urandom",no);
182 .SS "Closure Evaluation"
183 Closure evaluation uses the following syntax:
185 \fICLOSURE \fB( \fIARGUMENTS \fB)
187 \fICLOSURE\fR may be a path referring to a closure, or may itself be a
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:
194 \fICLOSURE \fB{ \fR... \fB}
198 sites map(site, vpn/test/all-sites);
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.
206 Two keys are mandatory.
207 \fBsystem\fR must be a dictionary in which the following keys can be
211 A \fIlog closure\fR; see the \fBlogfile\fR documentation below.
212 The destination for log messages.
217 The userid to run as after dropping privilege.
222 The path to write a pidfile.
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
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
235 \fBsecnet\fR contains a collection of built-in closures
236 with names (i.e. single-element paths) given below.
238 Most of them return anonymous closures of various types,
239 which are described contextually.
242 \fBadns(\fIDICT\fB)\fR => \fIresolver closure\fR
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.
249 A \fIresolver closure\fR is a means of converting hostnames into
254 \fBdiffie-hellman(\fIMODULUS\fB, \fIGENERATOR\fR[\fB, \fICHECK\fR]\fB)\fR => \fIdh closure\fR
258 The prime modulus \fIp\fR in hex.
262 The generator \fIg\fR in hex.
266 If \fBtrue\fR (the default) then check if \fIp\fR is prime.
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.
272 \fBlogfile(\fIDICT\fB)\fR => \fIlog closure\fR
274 Valid keys in the \fIDICT\fR argument are:
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.
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,
289 \fBquiet\fR is equivalent to \fBfatal\fR.
291 A \fIlog closure\fR is a means of saving log messages.
292 See also \fBsyslog\fR below.
295 \fBmakelist(\fIDICT\fB)\fR => \fILIST\fR
297 Returns the (flattened) list of values from the dictionary, discarding
301 \fBmap(\fICLOSURE\fB, \fIINPUT\fR...\fB)\fR => \fILIST\fR
303 Applies \fICLOSURE\fR to all its additional input arguments and
304 returns the resulting list.
307 \fBmd5\fR is a \fIhash closure\fR implementing the MD5 algorithm.
310 \fBnull-netlink(\fIDICT\fB)\fR => \fInetlink closure\fR
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
316 Valid keys in the \fIDICT\fR argument are:
320 The name for the netlink device.
321 The default is \fBnull-netlink\fR.
325 The networks on the host side of the netlink device.
329 Networks that may be claimed by remote sites using this netlink device.
333 IP address of this netlink.
334 Incompatible with \fBptp-address\fR.
338 IP address of the other end of a point-to-point link.
339 Incompatible with \fBsecnet-address\fR.
343 The MTU of the netlink device.
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
350 If \fBsecnet-address\fR is used then the result is a \fIpure
352 This must be evaluated to yield a \fInetlink closure\fR, using a
353 dictionary argument with the following keys:
357 networks reachable via this tunnel, in \fIaddress\fB/\fIbits\fR format.
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).
369 Remove these routes from the host routing table when the link quality
375 Default MTU over this link.
376 The default is inherited from the \fIpure closure\fR.
380 The priority of this link.
381 Higher values beat lower values.
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.
389 A \fInetlink closure\fR is a virtual IP link, and is supplied to the
390 \fBlink\fR key of a \fIsite\fR closure.
392 The netlink created by \fBnull-netlink\fR has no connection to the
394 See \fBtun\fR and \fBuserv-ipif\fR below for more useful alternatives.
399 \fBrandomfile(\fIFILENAME\fR[\fB, \fIBLOCKING\fR]\fB)\fR => \fIrandomsource closure\fR
403 Path to random device, e.g. \fI/dev/urandom\fR.
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.
411 A \fIrandomsource closure\fR is a source of random numbers.
414 \fBreadfile(\fIPATH\fB)\fR => \fISTRING\fR
416 Read the contents of the file \fIPATH\fR (a string) and return it as a string.
419 \eax-fBserpent(\fIDICT\fB)\fR => \fItransform closure\fR
421 Valid keys in the \fIDICT\fR argument are:
424 The maximum acceptable difference between the sequence number in a
425 received, decrypted message and the previous one.
427 It may be necessary to increase this is if connectivity is poor.
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.
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,
438 A \fItransform closure\fR is a reversible means of transforming
439 messages for transmission over a (presumably) insecure network.
440 It is responsible for both confidentiality and integrity.
443 \fBserpent256-cbc(\fIDICT\fB)\fR => \fItransform closure\fR
445 Valid keys in the \fIDICT\fR argument are:
450 Note that this uses a big-endian variant of the Serpent block cipher
451 (which is not compatible with most other Serpent implementations).
453 \fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR
457 The path to a file containing an RSA private key in SSH format
459 There must be no passphrase.
463 If \fBtrue\fR (the default) then check that the key is valid.
466 \fBrsa-public(\fIKEY\fB, \fIMODULUS\fB)\fR => \fIrsapubkey closure\fR
470 The public key exponent (\fIe\fR), in decimal.
474 The modulus (\fIn\fR), in decimal.
477 \fBsha1\fR is a \fIhash closure\fR implementing the SHA-1 algorithm.
480 \fBsite(\fIDICT\fB)\fR => \fIsite closure\fR
482 Valid keys in the \fIDICT\fR argument are:
486 The site's name for itself.
490 The name of the site's peer.
493 A \fInetlink closure\fR.
496 A \fIcomm closure\fR.
499 A \fIresolver closure\fR.
502 A \fIrandomsource closure\fR.
505 An \fIrsaprivkey closure\fR.
506 The key used to prove our identity to the peer.
510 The DNS name of the peer.
511 Optional, but if it is missing then it will not be possible to
512 initiate new connections to the peer.
516 The port to contact the peer.
519 An \fIrsapubkey closure\fR.
520 The key used to verify the peer's identity.
523 A \fItransform closure\fR.
524 Used to protect packets exchanged with the peer.
528 The group to use in key exchange.
531 The hash function used during setup.
532 .\" TODO clarify what we actually use it for!
536 The maximum lifetime of a session key in milliseconds.
537 The default is one hour.
541 The maximum number of times a key negotiation packet will be
542 transmitted before giving up.
547 The time between retransmissions of key negotiation packets, in milliseconds.
548 The default is one second.
552 The time to wait after a failed key setup before making another
553 attempt, in milliseconds.
558 The time after which a new session key will be negotiated, \fIif\fR
559 there is traffic on the link, in milliseconds.
560 It must not be greater than the \fBkey-lifetime\fR.
561 The default 5 minutes less than the key lifetime, unless the lifetime
562 is less than 10 minutes in which case the default is half the
567 If \fBtrue\fR then attempt to always maintain a live session key.
572 Types of event to log for this site.
576 Unexpected key setup packets (including late retransmissions).
579 Start of attempt to setup a session key.
582 Failure of attempt to setup a session key, through timeout.
585 Activation of a new session key.
588 Deletion of current session key through age.
591 Anything potentially suspicious.
594 Steps in the key setup protocol.
597 Whenever we throw away an outgoing packet.
600 Every key setup packet we see.
603 Failure of name resolution, internal errors.
606 Everything (too much!)
609 A \fIsite closure\fR defines one site to communicate with.
610 \fBsecnet\fR expects the (root) key \fBsite\fR to be a list of site
614 \fBsysbuffer(\fR[\fISIZE\fR[\fB, \fIOPTIONS\fR]]\fB)\fR => \fIbuffer closure\fR
618 The size of the buffer in bytes.
619 This must be between 64 and 131072.
624 Optional and presently unused.
625 .\" lockdown is accepted but ignored.
627 A \fIbuffer closure\fR is a means of buffering packets to send or that
631 \fBsyslog(\fIDICT\fB)\fR => \fIlog closure\fR
633 Valid keys in the \fIDICT\fR argument are:
637 The ident string to pass to \fBopenlog\fR(3); this value will appear
642 The facility to log as.
643 The possible values are \fBauthpriv\fR, \fBcron\fR, \fBdaemon\fR,
644 \fBkern\fR, \fBlocal0\fR-\fB7\fR, \fBlpr\fR, \fBmail\fR, \fBnews\fR,
645 \fBsyslog\fR, \fBuser\fR and \fBuucp\fR.
647 See also \fBlogfile\fR above.
650 \fBtun(\fIDICT\fB)\fR => \fInetlink closure\fR
652 \fBtun(\fIDICT\fB)\fR => \fIpure closure\fR
654 Valid keys in the \fIDICT\fR argument are those documented for
655 \fBnull-netlink\fR above, plus:
659 The type of TUN interface to use.
660 Possible values are \fBlinux\fR, \fBbsd\fR, \fBstreams\fR and \fBguess\fR.
661 The default is \fBguess\fR.
665 The path to the TUN/TAP device file.
666 The default is \fI/dev/net/tun\fR for the \fBlinux\fR flavour and
667 \fI/dev/tun\fR for the others.
671 The interface to use.
672 The default is to pick one automatically.
673 This cannot be used with the \fBstreams\fR flavour.
677 IP address of the host's tunnel interface.
678 .\" README says this belongs to netlink-null but actually it's
679 \" duplicated between slip & tun
683 The name of the \fBifconfig\fR command.
684 The default is simply "ifconfig".
688 The name of the \fBroute\fR command.
689 The default is simply "route".
693 The syntax expected by the \fBifconfig\fR command.
694 Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
695 \fBsolaris-2.5\fR and \fBguess\fR.
696 The default is \fBguess\fR.
700 The syntax expected by the \fBifconfig\fR command.
701 Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
702 \fBsolaris-2.5\fR and \fBguess\fR.
703 The default is \fBguess\fR.
706 A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
707 The buffer size must be at least 60 greater than the MTU.
708 .\" TODO rumour has is that buffers are sometimes shareable between
709 .\" netlink devices - document that if the conditions are reasonable
712 The \fBifconfig-type\fR and \fBroute-type\fR values determine how
713 those commands are executed.
714 If they are set to \fBioctl\fR then low-level system calls are used
715 directly instead of invoking the commands.
717 The netlink created by \fBtun\fR uses the \fBtun\fR device to
718 communicate with the host kernel.
721 \fBudp(\fIDICT\fB)\fR => \fIcomm closure\fR
723 Valid keys in the \fIDICT\fR argument are:
727 The IP address to bind on.
728 The default is 0.0.0.0, i.e. "any".
732 The port number to bind to.
733 The default is 0, i.e. the OS will choose one.
734 It is suggested that any given VPN agree a common port number.
737 A \fIbuffer closure\fR.
738 See the \fBsysbuffer\fR closure above.
742 The path to a helper program to bind the socket.
745 The program will be invoked with the address and port number as its
746 arguments, and with the socket to bind as file descriptor 0.
747 It should either bind the socket as requested, or exit with nonzero
750 A \fIcomm closure\fR is a means of sending and receiving messages via
752 It does not provide confidentiality, reliablity or availability.
755 \fBuserv-ipif(\fIDICT\fB)\fR => \fInetlink closure\fR
757 \fBuserv-ipif(\fIDICT\fB)\fR => \fIpure closure\fR
759 Valid keys in the \fIDICT\fR argument are those documented for
760 \fBnull-netlink\fR above, plus:
764 IP address of the host's SLIP interface.
765 .\" README says this belongs to netlink-null but actually it's
766 \" duplicated between SLIP & tun
770 Where to find \fBuserv\fR(1).
771 The default is \fB"userv"\fR.
775 The name of the user that owns the service.
776 The default is \fB"root"\fR.
780 The name of the service to request.
781 The default is \fB"ipif"\fR.
784 A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
786 The netlink created by \fBuserv-ipif\fR invokes the specified \fBuserv\fR service with pipes connected to its standard input and output.
787 It uses SLIP to communicate with the host kernel via these pipes.
791 .I /etc/secnet/secnet.conf