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 "CAPABILITY NEGOTIATION"
67 Sites negotiate with each other during key exchange
68 in order to determine which cryptographic algorithms and other features
73 Capabilities are assigned small integer numbers.
75 capability numbers can be assigned in the configuration file,
77 but secnet's default assignments will often be satisfactory.
79 Capability numbers between 0 and 7 inclusive
80 are reserved for local use:
81 secnet will never make use of them without explicit configuration.
82 This may be useful to migrate from one set of parameters
83 for a particular cryptographic algorithm
84 to different, incompatible, parameters for the same algorithm.
85 Other capability numbers are assigned by default
86 by various kinds of closures.
87 See the descriptions below for details.
89 It is essential that a capability number mean the same thing
90 to each of a pair of peers.
91 It's possible to configure a site
92 so that it uses different capability numbers for the same feature
93 when it communicates with different peer sites,
94 but this is likely to be more confusing than useful.
96 .SH "CONFIGURATION FILE"
98 The default configuration file is \fI/etc/secnet/secnet.conf\fR.
99 This can be overridden with the \fB--config\fR option.
101 The configuration file defines a dictionary (a mapping from keys to
102 values) of configuration information for secnet.
103 It is recursive in nature, i.e. values may themselves include dictionaries.
104 Any node in the nested structure thus defined can be identified by a
105 \fIpath\fR, which is the sequence of keys necessary to reach it from
106 the root, separated by "/" characters.
107 See \fBPaths\fR below for how this is used.
109 Furthermore, when a key is looked up in a dictionary, if it cannot be
110 found, it is sought in the parent dictionary, and so on back to the
112 For instance, each \fIsite\fR must contain the \fBresolver\fR key, but
113 in a typical configuration there is no value in having different
114 resolvers for each site.
115 Therefore \fBresolver\fR is defined at the root and thus automatically
116 incorporated into all sites.
118 Whitespace, including newlines, is ignored except to the extent that
119 it bounds other symbols.
121 Comment begin with "#" and continues to the end of the line.
122 Comments are ignored.
124 A file may be recursively included into the configuration file using a
129 This is handled at a higher level than the main parser and so
130 precludes the possibility of using the string \fBinclude\fR for any
132 .\" check if this is true. it's probably a bug!
134 The configuration file contains one or more assigments.
135 Each assignment is written:
137 \fIkey\fR [\fB=\fR] \fIlist\fR\fB;\fR
139 i.e. the equals sign is optional.
140 The semicolon is mandatory in all contexts.
142 Keys start with a letter or "_" and continue with any numbers of
143 letters, digits, "_" and "-".
145 Each \fIkey\fR is a list of one or more \fIvalues\fR, separated by commas.
146 Possible values types are \fIboolean\fR, \fIstring\fR, \fInumber\fR,
147 \fIdictionary\fR, \fIpath\fR and \fIclosure evaluation\fR.
148 .\" This man page draws a distinction between a closure (the thing
149 .\" evaluated) and a closure evaluation (the closure plus is
152 Strings are contained within "double quotes".
153 There is (currently) no escape syntax and no way to include quotes
158 filename "/var/log/secnet";
161 Numbers are encoded in decimal and do not include a sign.
162 Numbers must lie in the range 0 to 4294967295.
169 .\" In conffile.y dictionaries can be preceded by a search path, but
170 .\" this is not implemented elsewhere, so not documented here.
171 Dictionaries consist of one or more assignments, in the same syntax as
172 given above, enclosed in "{" and "}".
178 pidfile "/var/run/secnet.pid";
182 Paths allow a key already defined in the configuration to be aliased.
184 Paths consist of a sequence of keys separated by "/".
185 If the path starts with a "/" then it is an \fIabsolute path\fR and
186 the search starts at the root of the configuration.
187 Otherwise it is a \fIrelative path\fR and starts in the containing
188 dictionary or in any of its parents, down to and including the root.
189 If there is more than one match, the one furthest from the root "wins".
191 The value of a path is the list assigned to the key it refers to.
192 Lists are flattened; for example if a key is defined as a list of two
193 paths, and each of those refers to a list of two integers, the
194 original key is therefore defined to be a list of four integers, not
195 a list consisting of two lists.
197 It is not possible to refer to a \fIlater\fR key using a path.
203 kakajou vpn-data/test/kakajou/kakajou;
204 araminta vpn-data/test/araminta/araminta;
205 deodand vpn-data/test/deodand/deodand;
206 all-sites kakajou,araminta,deodand;
209 all-sites vpn/test/all-sites;
212 Here, each of \fBvpn/test/kakajou\fR, \fBvpn/test/araminta\fR and
213 \fBvpn/test/deodand\fR are defined as aliases to values defined
215 \fBvpn/tests/all-sites\fR is defined as the list of all three of those
216 values, and \fBall-sites\fR is then defined to be an alias for that.
218 The (single-element) paths \fBfalse\fR, \fBno\fR and \fBnowise\fR are
219 predefined and refer to a boolean false value.
220 Similarly \fBtrue\fR, \fByes\fR and \fBverily\fR point at a boolean
223 In all six cases, variants with just the first letter capitalized, and
224 with all letters capitalized, are also provided.
228 random randomfile("/dev/urandom",no);
230 .SS "Closure Evaluation"
231 Closure evaluation uses the following syntax:
233 \fICLOSURE \fB( \fIARGUMENTS \fB)
235 \fICLOSURE\fR may be a path referring to a closure, or may itself be a
238 \fIARGUMENTS\fR is a list of zero or more values, separated by commas.
239 As a shortcut, if the arguments consist of a single dictionary, the
240 parentheses may be ommitted:
242 \fICLOSURE \fB{ \fR... \fB}
246 sites map(site, vpn/test/all-sites);
249 When a closure is evaluated it returns a value (a list, much as above)
250 and may also have side effects (which may be immediate or may be
251 deferred to some later phase of execution).
252 A list of built-in closures is given below.
254 Two keys are mandatory.
255 \fBsystem\fR must be a dictionary in which the following keys can be
259 A \fIlog closure\fR; see the \fBlogfile\fR documentation below.
260 The destination for log messages.
265 The userid to run as after dropping privilege.
270 The path to write a pidfile.
273 \fBsites\fR should be a list of \fIsite closures\fR; see the \fBsite\fR documentation below.
274 This defines the collection of tunnel endpoints that \fBsecnet\fR will
277 Recall the recursive lookup logic described in \fBOverview\fR above:
278 if (for instance) \fBlog\fR is defined in the top level dictionary but
279 not in \fBsystem\fR, it will nevertheless be found when looked up in
283 \fBsecnet\fR contains a collection of built-in closures
284 with names (i.e. single-element paths) given below.
286 Most of them return anonymous closures of various types,
287 which are described contextually.
290 \fBadns(\fIDICT\fB)\fR => \fIresolver closure\fR
293 This either be empty or contain the single key \fBconfig\fR, with a
294 string value giving configuration to supply to ADNS.
295 This might be read from a file using \fBreadfile\fR.
297 A \fIresolver closure\fR is a means of converting hostnames into
302 \fBdiffie-hellman(\fIMODULUS\fB, \fIGENERATOR\fR[\fB, \fICHECK\fR]\fB)\fR => \fIdh closure\fR
304 \fBdiffie-hellman(\fIDICT\fB)\fR => \fIdh closure\fR
305 Defines a Diffie\(enHellman group which uses
306 traditional Diffie\(enHellman modulo a large prime number.
307 Arguments may be provided
308 either as positional arguments
310 Dictionary keys are described below;
311 those keys which correspond with positional arguments
312 are mentioned in the individual descriptions.
316 The prime modulus \fIp\fR in hex.
323 The generator \fIg\fR in hex.
330 If \fBtrue\fR (the default) then check if \fIp\fR is prime.
336 The capability number to use when advertising
337 this Diffie\(enHellman group.
338 The default capability number is 10.
341 A \fIdh closure\fR defines a group to be used for key exchange.
347 A premade \fIdh closure\fR
348 which uses Daniel Bernstein's X25519 key-exchange function.
349 This uses an elliptic curve called Curve25519,
350 defined over a 255-bit field.
351 The function is fast and very well-studied.
353 A \fIdh closure\fR defines a group to be used for key exchange.
356 Diffie\(enHellman group always uses capability number 24.
362 A premade \fIdh closure\fR
363 which uses Mike Hamburg's X448 key-exchange function.
364 This uses an elliptic curve called Ed448-Goldilocks,
365 defined over a 448-bit field.
366 The function is unusually quick and fairly well studied.
368 A \fIdh closure\fR defines a group to be used for key exchange.
371 Diffie\(enHellman group always uses capability number 25.
374 \fBlogfile(\fIDICT\fB)\fR => \fIlog closure\fR
376 Valid keys in the \fIDICT\fR argument are:
382 A list of strings defining which classes of message to log.
383 The possible message classes are \fBdebug-config\fR,
384 \fBdebug-phase\fR, \fBdebug\fR, \fBinfo\fR, \fBnotice\fR,
385 \fBwarning\fR, \fBerror\fR, \fBsecurity\fR and \fBfatal\fR.
387 \fBall-debug\fR is the union of all the \fBdebug\fR... classes.
388 \fBdefault\fR is equivalent to \fBwarning, error, security, fatal\fR.
389 \fBverbose\fR is equivalent to \fBinfo, notice, warning, error,
391 \fBquiet\fR is equivalent to \fBfatal\fR.
393 A \fIlog closure\fR is a means of saving log messages.
394 See also \fBsyslog\fR below.
397 \fBmakelist(\fIDICT\fB)\fR => \fILIST\fR
399 Returns the (flattened) list of values from the dictionary, discarding
403 \fBmap(\fICLOSURE\fB, \fIINPUT\fR...\fB)\fR => \fILIST\fR
405 Applies \fICLOSURE\fR to all its additional input arguments and
406 returns the resulting list.
409 \fBmd5\fR is a \fIhash closure\fR implementing the MD5 algorithm.
412 \fBnull-netlink(\fIDICT\fB)\fR => \fInetlink closure\fR
414 \fBnull-netlink(\fIDICT\fB)\fR => \fIpure closure\fR
415 .\" TODO pure closure is what it's called internally but this is a
416 .\" very opaque name to use in docs
418 Valid keys in the \fIDICT\fR argument are:
422 The name for the netlink device.
423 The default is \fBnull-netlink\fR.
427 The networks on the host side of the netlink device.
431 Networks that may be claimed by remote sites using this netlink device.
435 IP address of this netlink.
436 Incompatible with \fBptp-address\fR.
440 IP address of the other end of a point-to-point link.
441 Incompatible with \fBsecnet-address\fR.
445 The MTU of the netlink device.
448 If \fBptp-address\fR is used then the result is a \fInetlink closure\fR.
449 This can be used directly with the \fBlink\fR key in the \fBsites\fR
452 If \fBsecnet-address\fR is used then the result is a \fIpure
454 This must be evaluated to yield a \fInetlink closure\fR, using a
455 dictionary argument with the following keys:
459 networks reachable via this tunnel, in \fIaddress\fB/\fIbits\fR format.
467 Allow packets received via this tunnel to be routed down other tunnels
468 (without this option only packets from the host will be routed).
471 Remove these routes from the host routing table when the link quality
477 Default MTU over this link.
478 The default is inherited from the \fIpure closure\fR.
482 The priority of this link.
483 Higher values beat lower values.
486 .\" TODO ptp-address turns up in sites.conf, but why? I think this
487 .\" is a bug in make-secnet-sites; it is not used by
488 \" netlink_inst_create.
491 A \fInetlink closure\fR is a virtual IP link, and is supplied to the
492 \fBlink\fR key of a \fIsite\fR closure.
494 The netlink created by \fBnull-netlink\fR has no connection to the
496 See \fBtun\fR and \fBuserv-ipif\fR below for more useful alternatives.
501 \fBrandomfile(\fIFILENAME\fR[\fB, \fIBLOCKING\fR]\fB)\fR => \fIrandomsource closure\fR
505 Path to random device, e.g. \fI/dev/urandom\fR.
509 \fBTrue\fR if this is a blocking device and \fBfalse\fR otherwise (the default).
510 Blocking device support is not implemented so this must always be
511 \fBFalse\fR or absent.
513 A \fIrandomsource closure\fR is a source of random numbers.
516 \fBreadfile(\fIPATH\fB)\fR => \fISTRING\fR
518 Read the contents of the file \fIPATH\fR (a string) and return it as a string.
521 \fBeax-serpent(\fIDICT\fB)\fR => \fItransform closure\fR
523 Valid keys in the \fIDICT\fR argument are:
526 The maximum acceptable difference between the sequence number in a
527 received, decrypted message and the previous one.
529 It may be necessary to increase this is if connectivity is poor.
532 The length of the message authentication tag. The default is 16,
533 for a 128-bit tag length. It must be no longer than the Serpent
534 blocksize, 16. Must be have the same value at both ends.
537 Messages are padded to a multiple of this many bytes. This
538 serves to obscure the exact length of messages. The default is 16,
541 The capability number to use when advertising this
542 transform. The default for serpent-eax is 9.
544 A \fItransform closure\fR is a reversible means of transforming
545 messages for transmission over a (presumably) insecure network.
546 It is responsible for both confidentiality and integrity.
549 \fBserpent256-cbc(\fIDICT\fB)\fR => \fItransform closure\fR
552 is deprecated as its security properties are poor; it should be
553 specified only alongside a better transform such as eax-serpent.
555 Valid keys in the \fIDICT\fR argument are:
558 As above. The default for serpent256-cbc is 8.
563 Note that this uses a big-endian variant of the Serpent block cipher
564 (which is not compatible with most other Serpent implementations).
566 \fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR
570 The path to a file containing an RSA private key in SSH format
572 There must be no passphrase.
576 If \fBtrue\fR (the default) then check that the key is valid.
579 \fBrsa-public(\fIKEY\fB, \fIMODULUS\fB)\fR => \fIrsapubkey closure\fR
583 The public key exponent (\fIe\fR), in decimal.
587 The modulus (\fIn\fR), in decimal.
590 \fBsha1\fR is a \fIhash closure\fR implementing the SHA-1 algorithm.
593 \fBsha512\fR is a \fIhash closure\fR implementing the SHA-512 algorithm.
596 \fBsite(\fIDICT\fB)\fR => \fIsite closure\fR
598 Valid keys in the \fIDICT\fR argument are:
602 The site's name for itself.
606 The name of the site's peer.
609 A \fInetlink closure\fR.
612 A \fIcomm closure\fR.
615 A \fIresolver closure\fR.
618 A \fIrandomsource closure\fR.
621 An \fIrsaprivkey closure\fR.
622 The key used to prove our identity to the peer.
626 The DNS name of the peer.
627 Optional, but if it is missing then it will not be possible to
628 initiate new connections to the peer.
632 The port to contact the peer.
635 An \fIrsapubkey closure\fR.
636 The key used to verify the peer's identity.
639 One or more \fItransform closures\fR.
640 Used to protect packets exchanged with the peer. These should
641 all have distinct \fBcapab-num\fR values, and the same \fBcapab-num\fR
642 value should have the same (or a compatible) meaning at both
643 ends. The list should be in order of preference, most preferred
644 first. (The end which sends MSG1,MSG3 ends up choosing; the ordering
645 at the other end is irrelevant.)
648 A list of one or more \fIdh closure\fRs.
649 The groups to use in key exchange.
650 These should all have distinct
655 value should have the same (or a compatible) meaning at both ends.
656 The list should be in order of preference,
657 most preferred first.
658 (The end which sends MSG1,MSG3 ends up choosing;
659 the ordering at the other end is irrelevant.)
662 The hash function used during setup.
663 .\" TODO clarify what we actually use it for!
667 The maximum lifetime of a session key in milliseconds.
668 The default is one hour.
672 The maximum number of times a key negotiation packet will be
673 transmitted before giving up.
678 The time between retransmissions of key negotiation packets, in milliseconds.
679 The default is one second.
683 The time to wait after a failed key setup before making another
684 attempt, in milliseconds.
689 The time after which a new session key will be negotiated, \fIif\fR
690 there is traffic on the link, in milliseconds.
691 It must not be greater than the \fBkey-lifetime\fR.
692 The default 5 minutes less than the key lifetime, unless the lifetime
693 is less than 10 minutes in which case the default is half the
698 If \fBtrue\fR then attempt to always maintain a live session key.
703 Types of event to log for this site.
707 Unexpected key setup packets (including late retransmissions).
710 Start of attempt to setup a session key.
713 Failure of attempt to setup a session key, through timeout.
716 Activation of a new session key.
719 Deletion of current session key through age.
722 Anything potentially suspicious.
725 Steps in the key setup protocol.
728 Whenever we throw away an outgoing packet.
731 Every key setup packet we see.
734 Failure of name resolution, internal errors.
737 Everything (too much!)
740 A \fIsite closure\fR defines one site to communicate with.
741 \fBsecnet\fR expects the (root) key \fBsite\fR to be a list of site
745 \fBsysbuffer(\fR[\fISIZE\fR[\fB, \fIOPTIONS\fR]]\fB)\fR => \fIbuffer closure\fR
749 The size of the buffer in bytes.
750 This must be between 64 and 131072.
755 Optional and presently unused.
756 .\" lockdown is accepted but ignored.
758 A \fIbuffer closure\fR is a means of buffering packets to send or that
762 \fBsyslog(\fIDICT\fB)\fR => \fIlog closure\fR
764 Valid keys in the \fIDICT\fR argument are:
768 The ident string to pass to \fBopenlog\fR(3); this value will appear
773 The facility to log as.
774 The possible values are \fBauthpriv\fR, \fBcron\fR, \fBdaemon\fR,
775 \fBkern\fR, \fBlocal0\fR-\fB7\fR, \fBlpr\fR, \fBmail\fR, \fBnews\fR,
776 \fBsyslog\fR, \fBuser\fR and \fBuucp\fR.
778 See also \fBlogfile\fR above.
781 \fBtun(\fIDICT\fB)\fR => \fInetlink closure\fR
783 \fBtun(\fIDICT\fB)\fR => \fIpure closure\fR
785 Valid keys in the \fIDICT\fR argument are those documented for
786 \fBnull-netlink\fR above, plus:
790 The type of TUN interface to use.
791 Possible values are \fBlinux\fR, \fBbsd\fR, \fBstreams\fR and \fBguess\fR.
792 The default is \fBguess\fR.
796 The path to the TUN/TAP device file.
797 The default is \fI/dev/net/tun\fR for the \fBlinux\fR flavour and
798 \fI/dev/tun\fR for the others.
802 The interface to use.
803 The default is to pick one automatically.
804 This cannot be used with the \fBstreams\fR flavour.
808 IP address of the host's tunnel interface.
809 .\" README says this belongs to netlink-null but actually it's
810 \" duplicated between slip & tun
814 The name of the \fBifconfig\fR command.
815 The default is simply "ifconfig".
819 The name of the \fBroute\fR command.
820 The default is simply "route".
824 The syntax expected by the \fBifconfig\fR command.
825 Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
826 \fBsolaris-2.5\fR and \fBguess\fR.
827 The default is \fBguess\fR.
831 The syntax expected by the \fBifconfig\fR command.
832 Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
833 \fBsolaris-2.5\fR and \fBguess\fR.
834 The default is \fBguess\fR.
837 A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
838 The buffer size must be at least 60 greater than the MTU.
839 .\" TODO rumour has is that buffers are sometimes shareable between
840 .\" netlink devices - document that if the conditions are reasonable
843 The \fBifconfig-type\fR and \fBroute-type\fR values determine how
844 those commands are executed.
845 If they are set to \fBioctl\fR then low-level system calls are used
846 directly instead of invoking the commands.
848 The netlink created by \fBtun\fR uses the \fBtun\fR device to
849 communicate with the host kernel.
852 \fBudp(\fIDICT\fB)\fR => \fIcomm closure\fR
854 Valid keys in the \fIDICT\fR argument are:
858 The IP address to bind on.
859 The default is 0.0.0.0, i.e. "any".
863 The port number to bind to.
864 The default is 0, i.e. the OS will choose one.
865 It is suggested that any given VPN agree a common port number.
868 A \fIbuffer closure\fR.
869 See the \fBsysbuffer\fR closure above.
873 The path to a helper program to bind the socket.
876 The program will be invoked with the address and port number as its
877 arguments, and with the socket to bind as file descriptor 0.
878 It should either bind the socket as requested, or exit with nonzero
881 A \fIcomm closure\fR is a means of sending and receiving messages via
883 It does not provide confidentiality, reliablity or availability.
886 \fBuserv-ipif(\fIDICT\fB)\fR => \fInetlink closure\fR
888 \fBuserv-ipif(\fIDICT\fB)\fR => \fIpure closure\fR
890 Valid keys in the \fIDICT\fR argument are those documented for
891 \fBnull-netlink\fR above, plus:
895 IP address of the host's SLIP interface.
896 .\" README says this belongs to netlink-null but actually it's
897 \" duplicated between SLIP & tun
901 Where to find \fBuserv\fR(1).
902 The default is \fB"userv"\fR.
906 The name of the user that owns the service.
907 The default is \fB"root"\fR.
911 The name of the service to request.
912 The default is \fB"ipif"\fR.
915 A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
917 The netlink created by \fBuserv-ipif\fR invokes the specified \fBuserv\fR service with pipes connected to its standard input and output.
918 It uses SLIP to communicate with the host kernel via these pipes.
922 .I /etc/secnet/secnet.conf