1 .\" Man page for secnet.
3 .\" See the secnet.git README, or the Debian copyright file, for full
4 .\" list of copyright holders.
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 3 of the License, or
9 .\" (at your option) any later version.
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.
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.
22 secnet \- VPN router daemon
25 \fBsecnet\fR [\fIOPTIONS\fR]
28 \fBsecnet\fR allows virtual private networks to be constructed
29 spanning multiple separate sites.
33 .B --verbose\fR, \fB-v
34 Enable extra diagnostics.
36 .B --nowarnings\fR, \fB-w
40 Display usage message.
43 Display version string.
45 .B --nodetach\fR, \fB-n
46 Don't go into background.
47 The default behaviour is to become a daemon during startup.
49 .B --silent\fR, \fB--quiet\fR, \fB-f
50 Suppress error messages.
53 Enable debug messages.
55 .B --config\fR, \fB-c \fIPATH
56 Specify configuration file.
57 The default is \fI/etc/secnet/secnet.conf\fR.
59 .B --just-check-config\fR, \fB-j
60 Check configuration and exit.
62 .B --sites-key\fR, \fB-s \fIKEY
63 Configuration file key defining active sites.
64 The default is \fBsites\fR.
66 .SH "CONFIGURATION FILE"
68 The default configuration file is \fI/etc/secnet/secnet.conf\fR.
69 This can be overridden with the \fB--config\fR option.
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.
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
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.
88 Whitespace, including newlines, is ignored except to the extent that
89 it bounds other symbols.
91 Comment begin with "#" and continues to the end of the line.
94 A file may be recursively included into the configuration file using a
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
102 .\" check if this is true. it's probably a bug!
104 The configuration file contains one or more assigments.
105 Each assignment is written:
107 \fIkey\fR [\fB=\fR] \fIlist\fR\fB;\fR
109 i.e. the equals sign is optional.
110 The semicolon is mandatory in all contexts.
112 Keys start with a letter or "_" and continue with any numbers of
113 letters, digits, "_" and "-".
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
122 Strings are contained within "double quotes".
123 There is (currently) no escape syntax and no way to include quotes
128 filename "/var/log/secnet";
131 Numbers are encoded in decimal and do not include a sign.
132 Numbers must lie in the range 0 to 4294967295.
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 "}".
148 pidfile "/var/run/secnet.pid";
152 Paths allow a key already defined in the configuration to be aliased.
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".
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.
167 It is not possible to refer to a \fIlater\fR key using a path.
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;
179 all-sites vpn/test/all-sites;
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
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.
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
193 In all six cases, variants with just the first letter capitalized, and
194 with all letters capitalized, are also provided.
198 random randomfile("/dev/urandom",no);
200 .SS "Closure Evaluation"
201 Closure evaluation uses the following syntax:
203 \fICLOSURE \fB( \fIARGUMENTS \fB)
205 \fICLOSURE\fR may be a path referring to a closure, or may itself be a
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:
212 \fICLOSURE \fB{ \fR... \fB}
216 sites map(site, vpn/test/all-sites);
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.
224 Two keys are mandatory.
225 \fBsystem\fR must be a dictionary in which the following keys can be
229 A \fIlog closure\fR; see the \fBlogfile\fR documentation below.
230 The destination for log messages.
235 The userid to run as after dropping privilege.
240 The path to write a pidfile.
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
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
253 \fBsecnet\fR contains a collection of built-in closures
254 with names (i.e. single-element paths) given below.
256 Most of them return anonymous closures of various types,
257 which are described contextually.
260 \fBadns(\fIDICT\fB)\fR => \fIresolver closure\fR
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.
267 A \fIresolver closure\fR is a means of converting hostnames into
272 \fBdiffie-hellman(\fIMODULUS\fB, \fIGENERATOR\fR[\fB, \fICHECK\fR]\fB)\fR => \fIdh closure\fR
276 The prime modulus \fIp\fR in hex.
280 The generator \fIg\fR in hex.
284 If \fBtrue\fR (the default) then check if \fIp\fR is prime.
286 A \fIdh closure\fR defines a group to be used for key exchange.
289 \fBlogfile(\fIDICT\fB)\fR => \fIlog closure\fR
291 Valid keys in the \fIDICT\fR argument are:
297 A list of strings defining which classes of message to log.
298 The 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.
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,
306 \fBquiet\fR is equivalent to \fBfatal\fR.
308 A \fIlog closure\fR is a means of saving log messages.
309 See also \fBsyslog\fR below.
312 \fBmakelist(\fIDICT\fB)\fR => \fILIST\fR
314 Returns the (flattened) list of values from the dictionary, discarding
318 \fBmap(\fICLOSURE\fB, \fIINPUT\fR...\fB)\fR => \fILIST\fR
320 Applies \fICLOSURE\fR to all its additional input arguments and
321 returns the resulting list.
324 \fBmd5\fR is a \fIhash closure\fR implementing the MD5 algorithm.
327 \fBnull-netlink(\fIDICT\fB)\fR => \fInetlink closure\fR
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
333 Valid keys in the \fIDICT\fR argument are:
337 The name for the netlink device.
338 The default is \fBnull-netlink\fR.
342 The networks on the host side of the netlink device.
346 Networks that may be claimed by remote sites using this netlink device.
350 IP address of this netlink.
351 Incompatible with \fBptp-address\fR.
355 IP address of the other end of a point-to-point link.
356 Incompatible with \fBsecnet-address\fR.
360 The MTU of the netlink device.
363 If \fBptp-address\fR is used then the result is a \fInetlink closure\fR.
364 This can be used directly with the \fBlink\fR key in the \fBsites\fR
367 If \fBsecnet-address\fR is used then the result is a \fIpure
369 This must be evaluated to yield a \fInetlink closure\fR, using a
370 dictionary argument with the following keys:
374 networks reachable via this tunnel, in \fIaddress\fB/\fIbits\fR format.
382 Allow packets received via this tunnel to be routed down other tunnels
383 (without this option only packets from the host will be routed).
386 Remove these routes from the host routing table when the link quality
392 Default MTU over this link.
393 The default is inherited from the \fIpure closure\fR.
397 The priority of this link.
398 Higher values beat lower values.
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.
406 A \fInetlink closure\fR is a virtual IP link, and is supplied to the
407 \fBlink\fR key of a \fIsite\fR closure.
409 The netlink created by \fBnull-netlink\fR has no connection to the
411 See \fBtun\fR and \fBuserv-ipif\fR below for more useful alternatives.
416 \fBrandomfile(\fIFILENAME\fR[\fB, \fIBLOCKING\fR]\fB)\fR => \fIrandomsource closure\fR
420 Path to random device, e.g. \fI/dev/urandom\fR.
424 \fBTrue\fR if this is a blocking device and \fBfalse\fR otherwise (the default).
425 Blocking device support is not implemented so this must always be
426 \fBFalse\fR or absent.
428 A \fIrandomsource closure\fR is a source of random numbers.
431 \fBreadfile(\fIPATH\fB)\fR => \fISTRING\fR
433 Read the contents of the file \fIPATH\fR (a string) and return it as a string.
436 \fBeax-serpent(\fIDICT\fB)\fR => \fItransform closure\fR
438 Valid keys in the \fIDICT\fR argument are:
441 The maximum acceptable difference between the sequence number in a
442 received, decrypted message and the previous one.
444 It may be necessary to increase this is if connectivity is poor.
447 The length of the message authentication tag. The default is 16,
448 for a 128-bit tag length. It must be no longer than the Serpent
449 blocksize, 16. Must be have the same value at both ends.
452 Messages are padded to a multiple of this many bytes. This
453 serves to obscure the exact length of messages. The default is 16,
456 The capability number to use when advertising this
457 transform. Both ends must have the same meaning (or, at least,
458 refer to compatible constructions) for each capability number they have
459 in common. The default for serpent-eax is 9.
461 Capability numbers in the range 8..15 are intended for
462 allocation by the implementation, and may be assigned as the default
463 for new transforms in the future. Capability numbers in the
464 range 0..7 are reserved for definition by the user.
466 A \fItransform closure\fR is a reversible means of transforming
467 messages for transmission over a (presumably) insecure network.
468 It is responsible for both confidentiality and integrity.
471 \fBserpent256-cbc(\fIDICT\fB)\fR => \fItransform closure\fR
474 is deprecated as its security properties are poor; it should be
475 specified only alongside a better transform such as eax-serpent.
477 Valid keys in the \fIDICT\fR argument are:
480 As above. The default for serpent256-cbc is 8.
485 Note that this uses a big-endian variant of the Serpent block cipher
486 (which is not compatible with most other Serpent implementations).
488 \fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR
492 The path to a file containing an RSA private key in SSH format
494 There must be no passphrase.
498 If \fBtrue\fR (the default) then check that the key is valid.
501 \fBrsa-public(\fIKEY\fB, \fIMODULUS\fB)\fR => \fIrsapubkey closure\fR
505 The public key exponent (\fIe\fR), in decimal.
509 The modulus (\fIn\fR), in decimal.
512 \fBsha1\fR is a \fIhash closure\fR implementing the SHA-1 algorithm.
515 \fBsite(\fIDICT\fB)\fR => \fIsite closure\fR
517 Valid keys in the \fIDICT\fR argument are:
521 The site's name for itself.
525 The name of the site's peer.
528 A \fInetlink closure\fR.
531 A \fIcomm closure\fR.
534 A \fIresolver closure\fR.
537 A \fIrandomsource closure\fR.
540 An \fIrsaprivkey closure\fR.
541 The key used to prove our identity to the peer.
545 The DNS name of the peer.
546 Optional, but if it is missing then it will not be possible to
547 initiate new connections to the peer.
551 The port to contact the peer.
554 An \fIrsapubkey closure\fR.
555 The key used to verify the peer's identity.
558 One or more \fItransform closures\fR.
559 Used to protect packets exchanged with the peer. These should
560 all have distinct \fBcapab-num\fR values, and the same \fBcapab-num\fR
561 value should have the same (or a compatible) meaning at both
562 ends. The list should be in order of preference, most preferred
563 first. (The end which sends MSG1,MSG3 ends up choosing; the ordering
564 at the other end is irrelevant.)
568 The group to use in key exchange.
571 The hash function used during setup.
572 .\" TODO clarify what we actually use it for!
576 The maximum lifetime of a session key in milliseconds.
577 The default is one hour.
581 The maximum number of times a key negotiation packet will be
582 transmitted before giving up.
587 The time between retransmissions of key negotiation packets, in milliseconds.
588 The default is one second.
592 The time to wait after a failed key setup before making another
593 attempt, in milliseconds.
598 The time after which a new session key will be negotiated, \fIif\fR
599 there is traffic on the link, in milliseconds.
600 It must not be greater than the \fBkey-lifetime\fR.
601 The default 5 minutes less than the key lifetime, unless the lifetime
602 is less than 10 minutes in which case the default is half the
607 If \fBtrue\fR then attempt to always maintain a live session key.
612 Types of event to log for this site.
616 Unexpected key setup packets (including late retransmissions).
619 Start of attempt to setup a session key.
622 Failure of attempt to setup a session key, through timeout.
625 Activation of a new session key.
628 Deletion of current session key through age.
631 Anything potentially suspicious.
634 Steps in the key setup protocol.
637 Whenever we throw away an outgoing packet.
640 Every key setup packet we see.
643 Failure of name resolution, internal errors.
646 Everything (too much!)
649 A \fIsite closure\fR defines one site to communicate with.
650 \fBsecnet\fR expects the (root) key \fBsite\fR to be a list of site
654 \fBsysbuffer(\fR[\fISIZE\fR[\fB, \fIOPTIONS\fR]]\fB)\fR => \fIbuffer closure\fR
658 The size of the buffer in bytes.
659 This must be between 64 and 131072.
664 Optional and presently unused.
665 .\" lockdown is accepted but ignored.
667 A \fIbuffer closure\fR is a means of buffering packets to send or that
671 \fBsyslog(\fIDICT\fB)\fR => \fIlog closure\fR
673 Valid keys in the \fIDICT\fR argument are:
677 The ident string to pass to \fBopenlog\fR(3); this value will appear
682 The facility to log as.
683 The 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.
687 See also \fBlogfile\fR above.
690 \fBtun(\fIDICT\fB)\fR => \fInetlink closure\fR
692 \fBtun(\fIDICT\fB)\fR => \fIpure closure\fR
694 Valid keys in the \fIDICT\fR argument are those documented for
695 \fBnull-netlink\fR above, plus:
699 The type of TUN interface to use.
700 Possible values are \fBlinux\fR, \fBbsd\fR, \fBstreams\fR and \fBguess\fR.
701 The default is \fBguess\fR.
705 The path to the TUN/TAP device file.
706 The default is \fI/dev/net/tun\fR for the \fBlinux\fR flavour and
707 \fI/dev/tun\fR for the others.
711 The interface to use.
712 The default is to pick one automatically.
713 This cannot be used with the \fBstreams\fR flavour.
717 IP address of the host's tunnel interface.
718 .\" README says this belongs to netlink-null but actually it's
719 \" duplicated between slip & tun
723 The name of the \fBifconfig\fR command.
724 The default is simply "ifconfig".
728 The name of the \fBroute\fR command.
729 The default is simply "route".
733 The syntax expected by the \fBifconfig\fR command.
734 Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
735 \fBsolaris-2.5\fR and \fBguess\fR.
736 The default is \fBguess\fR.
740 The syntax expected by the \fBifconfig\fR command.
741 Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
742 \fBsolaris-2.5\fR and \fBguess\fR.
743 The default is \fBguess\fR.
746 A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
747 The 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
752 The \fBifconfig-type\fR and \fBroute-type\fR values determine how
753 those commands are executed.
754 If they are set to \fBioctl\fR then low-level system calls are used
755 directly instead of invoking the commands.
757 The netlink created by \fBtun\fR uses the \fBtun\fR device to
758 communicate with the host kernel.
761 \fBudp(\fIDICT\fB)\fR => \fIcomm closure\fR
763 Valid keys in the \fIDICT\fR argument are:
767 The IP address to bind on.
768 The default is 0.0.0.0, i.e. "any".
772 The port number to bind to.
773 The default is 0, i.e. the OS will choose one.
774 It is suggested that any given VPN agree a common port number.
777 A \fIbuffer closure\fR.
778 See the \fBsysbuffer\fR closure above.
782 The path to a helper program to bind the socket.
785 The program will be invoked with the address and port number as its
786 arguments, and with the socket to bind as file descriptor 0.
787 It should either bind the socket as requested, or exit with nonzero
790 A \fIcomm closure\fR is a means of sending and receiving messages via
792 It does not provide confidentiality, reliablity or availability.
795 \fBuserv-ipif(\fIDICT\fB)\fR => \fInetlink closure\fR
797 \fBuserv-ipif(\fIDICT\fB)\fR => \fIpure closure\fR
799 Valid keys in the \fIDICT\fR argument are those documented for
800 \fBnull-netlink\fR above, plus:
804 IP address of the host's SLIP interface.
805 .\" README says this belongs to netlink-null but actually it's
806 \" duplicated between SLIP & tun
810 Where to find \fBuserv\fR(1).
811 The default is \fB"userv"\fR.
815 The name of the user that owns the service.
816 The default is \fB"root"\fR.
820 The name of the service to request.
821 The default is \fB"ipif"\fR.
824 A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
826 The netlink created by \fBuserv-ipif\fR invokes the specified \fBuserv\fR service with pipes connected to its standard input and output.
827 It uses SLIP to communicate with the host kernel via these pipes.
831 .I /etc/secnet/secnet.conf