+.TH secnet 8
+
+.SH NAME
+secnet \- VPN router daemon
+
+.SH SYNOPSIS
+\fBsecnet\fR [\fIOPTIONS\fR]
+
+.SH DESCRIPTION
+\fBsecnet\fR allows virtual private networks to be constructed
+spanning multiple separate sites.
+
+.SH OPTIONS
+.TP
+.B --verbose\fR, \fB-v
+Enable extra diagnostics.
+.TP
+.B --nowarnings\fR, \fB-w
+Suppress warnings.
+.TP
+.B --help
+Display usage message.
+.TP
+.B --version
+Display version string.
+.TP
+.B --nodetach\fR, \fB-n
+Don't go into background.
+The default behaviour is to become a daemon during startup.
+.TP
+.B --silent\fR, \fB--quiet\fR, \fB-f
+Suppress error messages.
+.TP
+.B --debug\fR, \fB-d
+Enable debug messages.
+.TP
+.B --config\fR, \fB-c \fIPATH
+Specify configuration file.
+The default is \fI/etc/secnet/secnet.conf\fR.
+.TP
+.B --just-check-config\fR, \fB-j
+Check configuration and exit.
+.TP
+.B --sites-key\fR, \fB-s \fIKEY
+Configuration file key defining active sites.
+The default is \fBsites\fR.
+
+.SH "CONFIGURATION FILE"
+.SS Overview
+The default configuration file is \fI/etc/secnet/secnet.conf\fR.
+This can be overridden with the \fB--config\fR option.
+.PP
+The configuration file defines a dictionary (a mapping from keys to
+values) of configuration information for secnet.
+It is recursive in nature, i.e. values may themselves include dictionaries.
+Any node in the nested structure thus defined can be identified by a
+\fIpath\fR, which is the sequence of keys necessary to reach it from
+the root, separated by "/" characters.
+See \fBPaths\fR below for how this is used.
+.PP
+Furthermore, when a key is looked up in a dictionary, if it cannot be
+found, it is sought in the parent dictionary, and so on back to the
+root.
+For instance, each \fIsite\fR must contain the \fBresolver\fR key, but
+in a typical configuration there is no value in having different
+resolvers for each site.
+Therefore \fBresolver\fR is defined at the root and thus automatically
+incorporated into all sites.
+.SS Whitespace
+Whitespace, including newlines, is ignored except to the extent that
+it bounds other symbols.
+.PP
+Comment begin with "#" and continues to the end of the line.
+Comments are ignored.
+.SS Inclusion
+A file may be recursively included into the configuration file using a
+line of the form:
+.IP
+\fBinclude \fIPATH
+.PP
+This is handled at a higher level than the main parser and so
+precludes the possibility of using the string \fBinclude\fR for any
+other purpose.
+.\" check if this is true. it's probably a bug!
+.SS Assignments
+The configuration file contains one or more assigments.
+Each assignment is written:
+.IP
+\fIkey\fR [\fB=\fR] \fIlist\fR\fB;\fR
+.PP
+i.e. the equals sign is optional.
+The semicolon is mandatory in all contexts.
+.PP
+Keys start with a letter or "_" and continue with any numbers of
+letters, digits, "_" and "-".
+.PP
+Each \fIkey\fR is a list of one or more \fIvalues\fR, separated by commas.
+Possible values types are \fIboolean\fR, \fIstring\fR, \fInumber\fR,
+\fIdictionary\fR, \fIpath\fR and \fIclosure evaluation\fR.
+.\" This man page draws a distinction between a closure (the thing
+.\" evaluated) and a closure evaluation (the closure plus is
+.\" arguments).
+.SS "Strings"
+Strings are contained within "double quotes".
+There is (currently) no escape syntax and no way to include quotes
+inside strings.
+.PP
+Example:
+.nf
+ filename "/var/log/secnet";
+.fi
+.SS "Numbers"
+Numbers are encoded in decimal and do not include a sign.
+Numbers must lie in the range 0 to 4294967295.
+.PP
+Example:
+.nf
+ mtu 1400;
+.fi
+.SS "Dictionaries"
+.\" In conffile.y dictionaries can be preceded by a search path, but
+.\" this is not implemented elsewhere, so not documented here.
+Dictionaries consist of one or more assignments, in the same syntax as
+given above, enclosed in "{" and "}".
+.PP
+Example:
+.nf
+ system {
+ userid "secnet";
+ pidfile "/var/run/secnet.pid";
+ };
+.fi
+.SS "Paths"
+Paths allow a key already defined in the configuration to be aliased.
+.PP
+Paths consist of a sequence of keys separated by "/".
+If the path starts with a "/" then it is an \fIabsolute path\fR and
+the search starts at the root of the configuration.
+Otherwise it is a \fIrelative path\fR and starts in the containing
+dictionary or in any of its parents, down to and including the root.
+If there is more than one match, the one furthest from the root "wins".
+.PP
+The value of a path is the list assigned to the key it refers to.
+Lists are flattened; for example if a key is defined as a list of two
+paths, and each of those refers to a list of two integers, the
+original key is therefore defined to be a list of four integers, not
+a list consisting of two lists.
+.PP
+It is not possible to refer to a \fIlater\fR key using a path.
+.PP
+Example:
+.nf
+ vpn {
+ test {
+ kakajou vpn-data/test/kakajou/kakajou;
+ araminta vpn-data/test/araminta/araminta;
+ deodand vpn-data/test/deodand/deodand;
+ all-sites kakajou,araminta,deodand;
+ };
+ };
+ all-sites vpn/test/all-sites;
+.fi
+.PP
+Here, each of \fBvpn/test/kakajou\fR, \fBvpn/test/araminta\fR and
+\fBvpn/test/deodand\fR are defined as aliases to values defined
+elsewhere.
+\fBvpn/tests/all-sites\fR is defined as the list of all three of those
+values, and \fBall-sites\fR is then defined to be an alias for that.
+.SS "Booleans"
+The (single-element) paths \fBfalse\fR, \fBno\fR and \fBnowise\fR are
+predefined and refer to a boolean false value.
+Similarly \fBtrue\fR, \fByes\fR and \fBverily\fR point at a boolean
+true value.
+.PP
+In all six cases, variants with just the first letter capitalized, and
+with all letters capitalized, are also provided.
+.PP
+Example:
+.nf
+ random randomfile("/dev/urandom",no);
+.fi
+.SS "Closure Evaluation"
+Closure evaluation uses the following syntax:
+.IP
+\fICLOSURE \fB( \fIARGUMENTS \fB)
+.PP
+\fICLOSURE\fR may be a path referring to a closure, or may itself be a
+closure evaluation.
+.PP
+\fIARGUMENTS\fR is a list of zero or more values, separated by commas.
+As a shortcut, if the arguments consist of a single dictionary, the
+parentheses may be ommitted:
+.IP
+\fICLOSURE \fB{ \fR... \fB}
+.PP
+Example:
+.nf
+ sites map(site, vpn/test/all-sites);
+.fi
+.PP
+When a closure is evaluated it returns a value (a list, much as above)
+and may also have side effects (which may be immediate or may be
+deferred to some later phase of execution).
+A list of built-in closures is given below.
+.SS "Mandatory Keys"
+Two keys are mandatory.
+\fBsystem\fR must be a dictionary in which the following keys can be
+looked up:
+.TP
+.B log
+A \fIlog closure\fR; see the \fBlogfile\fR documentation below.
+The destination for log messages.
+Mandatory.
+.TP
+.B userid
+A string.
+The userid to run as after dropping privilege.
+Optional.
+.TP
+.B pidfile
+A string.
+The path to write a pidfile.
+Optional.
+.PP
+\fBsites\fR should be a list of \fIsite closures\fR; see the \fBsite\fR documentation below.
+This defines the collection of tunnel endpoints that \fBsecnet\fR will
+communicate with.
+.PP
+Recall the recursive lookup logic described in \fBOverview\fR above:
+if (for instance) \fBlog\fR is defined in the top level dictionary but
+not in \fBsystem\fR, it will nevertheless be found when looked up in
+the latter.
+
+.SH CLOSURES
+\fBsecnet\fR contains a collection of built-in closures
+with names (i.e. single-element paths) given below.
+.PP
+Most of them return anonymous closures of various types,
+which are described contextually.
+
+.SS adns
+\fBadns(\fIDICT\fB)\fR => \fIresolver closure\fR
+.TP
+.I DICT
+This either be empty or contain the single key \fBconfig\fR, with a
+string value giving configuration to supply to ADNS.
+This might be read from a file using \fBreadfile\fR.
+.PP
+A \fIresolver closure\fR is a means of converting hostnames into
+network addresses.
+
+.SS diffie-hellman
+.PP
+\fBdiffie-hellman(\fIMODULUS\fB, \fIGENERATOR\fR[\fB, \fICHECK\fR]\fB)\fR => \fIdh closure\fR
+.TP
+.I MODULUS
+String.
+The prime modulus \fIp\fR in hex.
+.TP
+.I GENERATOR
+String.
+The generator \fIg\fR in hex.
+.TP
+.I CHECK
+Boolean.
+If \fBtrue\fR (the default) then check if \fIp\fR is prime.
+.PP
+A \fIdh closure\fR defines a group to be used for key exchange.
+The same group must be used by all sites in the VPN.
+
+.SS logfile
+\fBlogfile(\fIDICT\fB)\fR => \fIlog closure\fR
+.PP
+Valid keys in the \fIDICT\fR argument are:
+.TP
+.B filename
+The path to log to.
+.TP
+.B class
+A list of strings defining which classes of message to log.
+The possible message classes are \fBdebug-config\fR,
+\fBdebug-phase\fR, \fBdebug\fR, \fBinfo\fR, \fBnotice\fR,
+\fBwarning\fR, \fBerror\fR, \fBsecurity\fR and \fBfatal\fR.
+.IP
+\fBall-debug\fR is the union of all the \fBdebug\fR... classes.
+\fBdefault\fR is equivalent to \fBwarning, error, security, fatal\fR.
+\fBverbose\fR is equivalent to \fBinfo, notice, warning, error,
+security, fatal\fR.
+\fBquiet\fR is equivalent to \fBfatal\fR.
+.PP
+A \fIlog closure\fR is a means of saving log messages.
+See also \fBsyslog\fR below.
+
+.SS makelist
+\fBmakelist(\fIDICT\fB)\fR => \fILIST\fR
+.PP
+Returns the (flattened) list of values from the dictionary, discarding
+the keys.
+
+.SS map
+\fBmap(\fICLOSURE\fB, \fIINPUT\fR...\fB)\fR => \fILIST\fR
+.PP
+Applies \fICLOSURE\fR to all its additional input arguments and
+returns the resulting list.
+
+.SS md5
+\fBmd5\fR is a \fIhash closure\fR implementing the MD5 algorithm.
+
+.SS null-netlink
+\fBnull-netlink(\fIDICT\fB)\fR => \fInetlink closure\fR
+.br
+\fBnull-netlink(\fIDICT\fB)\fR => \fIpure closure\fR
+.\" TODO pure closure is what it's called internally but this is a
+.\" very opaque name to use in docs
+.PP
+Valid keys in the \fIDICT\fR argument are:
+.TP
+.B name
+String.
+The name for the netlink device.
+The default is \fBnull-netlink\fR.
+.TP
+.B networks
+List of strings.
+The networks on the host side of the netlink device.
+.TP
+.B remote-networks
+List of strings.
+Networks that may be claimed by remote sites using this netlink device.
+.TP
+.B secnet-address
+String.
+IP address of this netlink.
+Incompatible with \fBptp-address\fR.
+.TP
+.B ptp-address
+String.
+IP address of the other end of a point-to-point link.
+Incompatible with \fBsecnet-address\fR.
+.TP
+.B mtu
+Number.
+The MTU of the netlink device.
+The default is 1000.
+.PP
+If \fBptp-address\fR is used then the result is a \fInetlink closure\fR.
+This can be used directly with the \fBlink\fR key in the \fBsites\fR
+closure (see below).
+.PP
+If \fBsecnet-address\fR is used then the result is a \fIpure
+closure\fR.
+This must be evaluated to yield a \fInetlink closure\fR, using a
+dictionary argument with the following keys:
+.TP
+.B routes
+String list.
+networks reachable via this tunnel, in \fIaddress\fB/\fIbits\fR format.
+.TP
+.B options
+String list.
+A list of options:
+.RS
+.TP
+.B allow-route
+Allow packets received via this tunnel to be routed down other tunnels
+(without this option only packets from the host will be routed).
+.TP
+.B soft
+Remove these routes from the host routing table when the link quality
+is 0.
+.RE
+.TP
+.B mtu
+Number.
+Default MTU over this link.
+The default is inherited from the \fIpure closure\fR.
+.TP
+.B priority
+Number.
+The priority of this link.
+Higher values beat lower values.
+The default is 0.
+
+.\" TODO ptp-address turns up in sites.conf, but why? I think this
+.\" is a bug in make-secnet-sites; it is not used by
+ \" netlink_inst_create.
+
+.PP
+A \fInetlink closure\fR is a virtual IP link, and is supplied to the
+\fBlink\fR key of a \fIsite\fR closure.
+.PP
+The netlink created by \fBnull-netlink\fR has no connection to the
+host.
+See \fBtun\fR and \fBuserv-ipif\fR below for more useful alternatives.
+
+
+
+.SS randomfile
+\fBrandomfile(\fIFILENAME\fR[\fB, \fIBLOCKING\fR]\fB)\fR => \fIrandomsource closure\fR
+.TP
+.I FILENAME
+String.
+Path to random device, e.g. \fI/dev/urandom\fR.
+.TP
+.I BLOCKING
+Boolean.
+\fBTrue\fR if this is a blocking device and \fBfalse\fR otherwise (the default).
+Blocking device support is not implemented so this must always be
+\fBFalse\fR or absent.
+.PP
+A \fIrandomsource closure\fR is a source of random numbers.
+
+.SS readfile
+\fBreadfile(\fIPATH\fB)\fR => \fISTRING\fR
+.PP
+Read the contents of the file \fIPATH\fR (a string) and return it as a string.
+
+.SS serpent256-cbc
+\fBserpent256-cbc(\fIDICT\fB)\fR => \fItransform closure\fR
+.PP
+Valid keys in the \fIDICT\fR argument are:
+.TP
+.B max-sequence-skew
+The maximum acceptable difference between the sequence number in a
+received, decrypted message and the previous one.
+The default is 10.
+It may be necessary to increase this is if connectivity is poor.
+.PP
+A \fItransform closure\fR is a reversible means of transforming
+messages for transmission over a (presumably) insecure network.
+It is responsible for both confidentiality and integrity.
+
+.SS rsa-private
+\fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR
+.TP
+.I PATH
+String.
+The path to a file containing an RSA private key in SSH format
+(version 1).
+There must be no passphrase.
+.TP
+.I CHECK
+Boolean.
+If \fBtrue\fR (the default) then check that the key is valid.
+
+.SS rsa-public
+\fBrsa-public(\fIKEY\fB, \fIMODULUS\fB)\fR => \fIrsapubkey closure\fR
+.TP
+.I KEY
+String.
+The public key exponent (\fIe\fR), in decimal.
+.TP
+.I MODULUS
+String.
+The modulus (\fIn\fR), in decimal.
+
+.SS sha1
+\fBsha1\fR is a \fIhash closure\fR implementing the SHA-1 algorithm.
+
+.SS site
+\fBsite(\fIDICT\fB)\fR => \fIsite closure\fR
+.PP
+Valid keys in the \fIDICT\fR argument are:
+.TP
+.B local-name
+String.
+The site's name for itself.
+.TP
+.B name
+String.
+The name of the site's peer.
+.TP
+.B link
+A \fInetlink closure\fR.
+.TP
+.B comm
+A \fIcomm closure\fR.
+.TP
+.B resolver
+A \fIresolver closure\fR.
+.TP
+.B random
+A \fIrandomsource closure\fR.
+.TP
+.B local-key
+An \fIrsaprivkey closure\fR.
+The key used to prove our identity to the peer.
+.TP
+.B address
+String.
+The DNS name of the peer.
+Optional, but if it is missing then it will not be possible to
+initiate new connections to the peer.
+.TP
+.B port
+Number.
+The port to contact the peer.
+.TP
+.B key
+An \fIrsapubkey closure\fR.
+The key used to verify the peer's identity.
+.TP
+.B transform
+A \fItransform closure\fR.
+Used to protect packets exchanged with the peer.
+.TP
+.B dh
+A \fIdh closure\fR.
+The group to use in key exchange.
+.TP
+.B hash
+The hash function used during setup.
+.\" TODO clarify what we actually use it for!
+.TP
+.B key-lifetime
+Number.
+The maximum lifetime of a session key in milliseconds.
+The default is one hour.
+.TP
+.B setup-retries
+Number.
+The maximum number of times a key negotiation packet will be
+transmitted before giving up.
+The default is 5.
+.TP
+.B setup-timeout
+Number.
+The time between retransmissions of key negotiation packets, in milliseconds.
+The default is one second.
+.TP
+.B wait-time
+Number.
+The time to wait after a failed key setup before making another
+attempt, in milliseconds.
+The default is 20s.
+.TP
+.B renegotiate-time
+Number.
+The time after which a new session key will be negotiated, \fIif\fR
+there is traffic on the link, in milliseconds.
+It must not be greater than the \fBkey-lifetime\fR.
+The default 5 minutes less than the key lifetime, unless the lifetime
+is less than 10 minutes in which case the default is half the
+lifetime.
+.TP
+.B keepalive
+Boolean.
+If \fBtrue\fR then attempt to always maintain a live session key.
+Not implemented.
+.TP
+.B log-events
+String list.
+Types of event to log for this site.
+.RS
+.TP
+.B unexpected
+Unexpected key setup packets (including late retransmissions).
+.TP
+.B setup-init
+Start of attempt to setup a session key.
+.TP
+.B setup-timeout
+Failure of attempt to setup a session key, through timeout.
+.TP
+.B activate-key
+Activation of a new session key.
+.TP
+.B timeout-key
+Deletion of current session key through age.
+.TP
+.B security
+Anything potentially suspicious.
+.TP
+.B state-change
+Steps in the key setup protocol.
+.TP
+.B packet-drop
+Whenever we throw away an outgoing packet.
+.TP
+.B dump-packets
+Every key setup packet we see.
+.TP
+.B errors
+Failure of name resolution, internal errors.
+.TP
+.B all
+Everything (too much!)
+.RE
+.PP
+A \fIsite closure\fR defines one site to communicate with.
+\fBsecnet\fR expects the (root) key \fBsite\fR to be a list of site
+closures.
+
+.SS sysbuffer
+\fBsysbuffer(\fR[\fISIZE\fR[\fB, \fIOPTIONS\fR]]\fB)\fR => \fIbuffer closure\fR
+.TP
+.I SIZE
+Number.
+The size of the buffer in bytes.
+This must be between 64 and 131072.
+The default is 4096.
+.TP
+.I OPTIONS
+Dictionary.
+Optional and presently unused.
+.\" lockdown is accepted but ignored.
+.PP
+A \fIbuffer closure\fR is a means of buffering packets to send or that
+have been received.
+
+.SS syslog
+\fBsyslog(\fIDICT\fB)\fR => \fIlog closure\fR
+.PP
+Valid keys in the \fIDICT\fR argument are:
+.TP
+.B ident
+String.
+The ident string to pass to \fBopenlog\fR(3); this value will appear
+in each message.
+.TP
+.B facility
+String.
+The facility to log as.
+The possible values are \fBauthpriv\fR, \fBcron\fR, \fBdaemon\fR,
+\fBkern\fR, \fBlocal0\fR-\fB7\fR, \fBlpr\fR, \fBmail\fR, \fBnews\fR,
+\fBsyslog\fR, \fBuser\fR and \fBuucp\fR.
+.PP
+See also \fBlogfile\fR above.
+
+.SS tun
+\fBtun(\fIDICT\fB)\fR => \fInetlink closure\fR
+.br
+\fBtun(\fIDICT\fB)\fR => \fIpure closure\fR
+.PP
+Valid keys in the \fIDICT\fR argument are those documented for
+\fBnull-netlink\fR above, plus:
+.TP
+.B flavour
+String.
+The type of TUN interface to use.
+Possible values are \fBlinux\fR, \fBbsd\fR, \fBstreams\fR and \fBguess\fR.
+The default is \fBguess\fR.
+.TP
+.B device
+String.
+The path to the TUN/TAP device file.
+The default is \fI/dev/net/tun\fR for the \fBlinux\fR flavour and
+\fI/dev/tun\fR for the others.
+.TP
+.B interface
+String.
+The interface to use.
+The default is to pick one automatically.
+This cannot be used with the \fBstreams\fR flavour.
+.TP
+.B local-address
+String.
+IP address of the host's tunnel interface.
+.\" README says this belongs to netlink-null but actually it's
+ \" duplicated between slip & tun
+.TP
+.B ifconfig-path
+String.
+The name of the \fBifconfig\fR command.
+The default is simply "ifconfig".
+.TP
+.B route-path
+String.
+The name of the \fBroute\fR command.
+The default is simply "route".
+.TP
+.B ifconfig-type
+String.
+The syntax expected by the \fBifconfig\fR command.
+Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
+\fBsolaris-2.5\fR and \fBguess\fR.
+The default is \fBguess\fR.
+.TP
+.B route-type
+String.
+The syntax expected by the \fBifconfig\fR command.
+Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR,
+\fBsolaris-2.5\fR and \fBguess\fR.
+The default is \fBguess\fR.
+.TP
+.B buffer
+A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
+The buffer size must be at least 60 greater than the MTU.
+.\" TODO rumour has is that buffers are sometimes shareable between
+.\" netlink devices - document that if the conditions are reasonable
+.\" ones.
+.PP
+The \fBifconfig-type\fR and \fBroute-type\fR values determine how
+those commands are executed.
+If they are set to \fBioctl\fR then low-level system calls are used
+directly instead of invoking the commands.
+.PP
+The netlink created by \fBtun\fR uses the \fBtun\fR device to
+communicate with the host kernel.
+
+.SS udp
+\fBudp(\fIDICT\fB)\fR => \fIcomm closure\fR
+.PP
+Valid keys in the \fIDICT\fR argument are:
+.TP
+.B address
+String.
+The IP address to bind on.
+The default is 0.0.0.0, i.e. "any".
+.TP
+.B port
+Number.
+The port number to bind to.
+The default is 0, i.e. the OS will choose one.
+It is suggested that any given VPN agree a common port number.
+.TP
+.B buffer
+A \fIbuffer closure\fR.
+See the \fBsysbuffer\fR closure above.
+.TP
+.B authbind
+String.
+The path to a helper program to bind the socket.
+Optional.
+.IP
+The program will be invoked with the address and port number as its
+arguments, and with the socket to bind as file descriptor 0.
+It should either bind the socket as requested, or exit with nonzero
+status.
+.PP
+A \fIcomm closure\fR is a means of sending and receiving messages via
+a network.
+It does not provide confidentiality, reliablity or availability.
+
+.SS userv-ipif
+\fBuserv-ipif(\fIDICT\fB)\fR => \fInetlink closure\fR
+.br
+\fBuserv-ipif(\fIDICT\fB)\fR => \fIpure closure\fR
+.PP
+Valid keys in the \fIDICT\fR argument are those documented for
+\fBnull-netlink\fR above, plus:
+.TP
+.B local-address
+String.
+IP address of the host's SLIP interface.
+.\" README says this belongs to netlink-null but actually it's
+ \" duplicated between SLIP & tun
+.TP
+.B userv-path
+String.
+Where to find \fBuserv\fR(1).
+The default is \fB"userv"\fR.
+.TP
+.B service-user
+String.
+The name of the user that owns the service.
+The default is \fB"root"\fR.
+.TP
+.B service-name
+String.
+The name of the service to request.
+The default is \fB"ipif"\fR.
+.TP
+.B buffer
+A \fIbuffer closure\fR to use for packets transferred from the host to secnet.
+.PP
+The netlink created by \fBuserv-ipif\fR invokes the specified \fBuserv\fR service with pipes connected to its standard input and output.
+It uses SLIP to communicate with the host kernel via these pipes.
+
+.SH FILES
+.TP
+.I /etc/secnet/secnet.conf
+Configuration file.
+
+.SH "SEE ALSO"
+\fBuserv\fR(1)
~ian / secnet.git / commitdiff