NAME
secnet - VPN router daemon
SYNOPSIS
secnet [OPTIONS]
DESCRIPTION
secnet allows virtual private networks to be constructed spanning mul-
tiple separate sites.
OPTIONS
--verbose, -v
Enable extra diagnostics.
--nowarnings, -w
Suppress warnings.
--help Display usage message.
--version
Display version string.
--nodetach, -n
Don't go into background. The default behaviour is to become a
daemon during startup.
--silent, --quiet, -f
Suppress error messages.
--debug, -d
Enable debug messages.
--config, -c PATH
Specify configuration file. The default is /etc/secnet/sec-
net.conf.
--just-check-config, -j
Check configuration and exit.
--sites-key, -s KEY
Configuration file key defining active sites. The default is
sites.
CONFIGURATION FILE
Overview
The default configuration file is /etc/secnet/secnet.conf. This can be
overridden with the --config option.
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 path, which is
the sequence of keys necessary to reach it from the root, separated by
"/" characters. See Paths below for how this is used.
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 site must contain the resolver key, but in a
typical configuration there is no value in having different resolvers
for each site. Therefore resolver is defined at the root and thus
automatically incorporated into all sites.
Whitespace
Whitespace, including newlines, is ignored except to the extent that it
bounds other symbols.
Comment begin with "#" and continues to the end of the line. Comments
are ignored.
Inclusion
A file may be recursively included into the configuration file using a
line of the form:
include PATH
This is handled at a higher level than the main parser and so precludes
the possibility of using the string include for any other purpose.
Assignments
The configuration file contains one or more assigments. Each assign-
ment is written:
key [=] list;
i.e. the equals sign is optional. The semicolon is mandatory in all
contexts.
Keys start with a letter or "_" and continue with any numbers of let-
ters, digits, "_" and "-".
Each key is a list of one or more values, separated by commas. Possi-
ble values types are boolean, string, number, dictionary, path and clo-
sure evaluation.
Strings
Strings are contained within "double quotes". There is (currently) no
escape syntax and no way to include quotes inside strings.
Example:
filename "/var/log/secnet";
Numbers
Numbers are encoded in decimal and do not include a sign. Numbers must
lie in the range 0 to 4294967295.
Example:
mtu 1400;
Dictionaries
Dictionaries consist of one or more assignments, in the same syntax as
given above, enclosed in "{" and "}".
Example:
system {
userid "secnet";
pidfile "/var/run/secnet.pid";
};
Paths
Paths allow a key already defined in the configuration to be aliased.
Paths consist of a sequence of keys separated by "/". If the path
starts with a "/" then it is an absolute path and the search starts at
the root of the configuration. Otherwise it is a relative path 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 fur-
thest from the root "wins".
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 con-
sisting of two lists.
It is not possible to refer to a later key using a path.
Example:
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;
Here, each of vpn/test/kakajou, vpn/test/araminta and vpn/test/deodand
are defined as aliases to values defined elsewhere. vpn/tests/all-
sites is defined as the list of all three of those values, and all-
sites is then defined to be an alias for that.
Booleans
The (single-element) paths false, no and nowise are predefined and
refer to a boolean false value. Similarly true, yes and verily point
at a boolean true value.
In all six cases, variants with just the first letter capitalized, and
with all letters capitalized, are also provided.
Example:
random randomfile("/dev/urandom",no);
Closure Evaluation
Closure evaluation uses the following syntax:
CLOSURE ( ARGUMENTS )
CLOSURE may be a path referring to a closure, or may itself be a clo-
sure evaluation.
ARGUMENTS is a list of zero or more values, separated by commas. As a
shortcut, if the arguments consist of a single dictionary, the paren-
theses may be ommitted:
CLOSURE { ... }
Example:
sites map(site, vpn/test/all-sites);
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 clo-
sures is given below.
Mandatory Keys
Two keys are mandatory. system must be a dictionary in which the fol-
lowing keys can be looked up:
log A log closure; see the logfile documentation below. The desti-
nation for log messages. Mandatory.
userid A string. The userid to run as after dropping privilege.
Optional.
pidfile
A string. The path to write a pidfile. Optional.
sites should be a list of site closures; see the site documentation
below. This defines the collection of tunnel endpoints that secnet
will communicate with.
Recall the recursive lookup logic described in Overview above: if (for
instance) log is defined in the top level dictionary but not in system,
it will nevertheless be found when looked up in the latter.
CLOSURES
secnet contains a collection of built-in closures with names (i.e. sin-
gle-element paths) given below.
Most of them return anonymous closures of various types, which are
described contextually.
adns
adns(DICT) => resolver closure
DICT This either be empty or contain the single key config, with a
string value giving configuration to supply to ADNS. This might
be read from a file using readfile.
A resolver closure is a means of converting hostnames into network
addresses.
diffie-hellman
diffie-hellman(MODULUS, GENERATOR[, CHECK]) => dh closure
MODULUS
String. The prime modulus p in hex.
GENERATOR
String. The generator g in hex.
CHECK Boolean. If true (the default) then check if p is prime.
A dh closure defines a group to be used for key exchange. The same
group must be used by all sites in the VPN.
logfile
logfile(DICT) => log closure
Valid keys in the DICT argument are:
filename
The path to log to.
class A list of strings defining which classes of message to log. The
possible message classes are debug-config, debug-phase, debug,
info, notice, warning, error, security and fatal.
all-debug is the union of all the debug... classes. default is
equivalent to warning, error, security, fatal. verbose is
equivalent to info, notice, warning, error, security, fatal.
quiet is equivalent to fatal.
A log closure is a means of saving log messages. See also syslog
below.
makelist
makelist(DICT) => LIST
Returns the (flattened) list of values from the dictionary, discarding
the keys.
map
map(CLOSURE, INPUT...) => LIST
Applies CLOSURE to all its additional input arguments and returns the
resulting list.
md5
md5 is a hash closure implementing the MD5 algorithm.
null-netlink
null-netlink(DICT) => netlink closure
null-netlink(DICT) => pure closure
Valid keys in the DICT argument are:
name String. The name for the netlink device. The default is null-
netlink.
networks
List of strings. The networks on the host side of the netlink
device.
remote-networks
List of strings. Networks that may be claimed by remote sites
using this netlink device.
secnet-address
String. IP address of this netlink. Incompatible with ptp-
address.
ptp-address
String. IP address of the other end of a point-to-point link.
Incompatible with secnet-address.
mtu Number. The MTU of the netlink device. The default is 1000.
If ptp-address is used then the result is a netlink closure. This can
be used directly with the link key in the sites closure (see below).
If secnet-address is used then the result is a pure closure. This must
be evaluated to yield a netlink closure, using a dictionary argument
with the following keys:
routes String list. networks reachable via this tunnel, in
address/bits format.
options
String list. A list of options:
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).
soft Remove these routes from the host routing table when the
link quality is 0.
mtu Number. Default MTU over this link. The default is inherited
from the pure closure.
priority
Number. The priority of this link. Higher values beat lower
values. The default is 0.
A netlink closure is a virtual IP link, and is supplied to the link key
of a site closure.
The netlink created by null-netlink has no connection to the host. See
tun and userv-ipif below for more useful alternatives.
randomfile
randomfile(FILENAME[, BLOCKING]) => randomsource closure
FILENAME
String. Path to random device, e.g. /dev/urandom.
BLOCKING
Boolean. True if this is a blocking device and false otherwise
(the default). Blocking device support is not implemented so
this must always be False or absent.
A randomsource closure is a source of random numbers.
readfile
readfile(PATH) => STRING
Read the contents of the file PATH (a string) and return it as a
string.
serpent256-cbc
serpent256-cbc(DICT) => transform closure
Valid keys in the DICT argument are:
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.
A transform closure is a reversible means of transforming messages for
transmission over a (presumably) insecure network. It is responsible
for both confidentiality and integrity.
rsa-private
rsa-private(PATH[, CHECK]) => rsaprivkey closure
PATH String. The path to a file containing an RSA private key in SSH
format (version 1). There must be no passphrase.
CHECK Boolean. If true (the default) then check that the key is
valid.
rsa-public
rsa-public(KEY, MODULUS) => rsapubkey closure
KEY String. The public key exponent (e), in decimal.
MODULUS
String. The modulus (n), in decimal.
sha1
sha1 is a hash closure implementing the SHA-1 algorithm.
site
site(DICT) => site closure
Valid keys in the DICT argument are:
local-name
String. The site's name for itself.
name String. The name of the site's peer.
link A netlink closure.
comm A comm closure.
resolver
A resolver closure.
random A randomsource closure.
local-key
An rsaprivkey closure. The key used to prove our identity to
the peer.
address
String. The DNS name of the peer. Optional, but if it is miss-
ing then it will not be possible to initiate new connections to
the peer.
port Number. The port to contact the peer.
key An rsapubkey closure. The key used to verify the peer's iden-
tity.
transform
A transform closure. Used to protect packets exchanged with the
peer.
dh A dh closure. The group to use in key exchange.
hash The hash function used during setup.
key-lifetime
Number. The maximum lifetime of a session key in milliseconds.
The default is one hour.
setup-retries
Number. The maximum number of times a key negotiation packet
will be transmitted before giving up. The default is 5.
setup-timeout
Number. The time between retransmissions of key negotiation
packets, in milliseconds. The default is one second.
wait-time
Number. The time to wait after a failed key setup before making
another attempt, in milliseconds. The default is 20s.
renegotiate-time
Number. The time after which a new session key will be negoti-
ated, if there is traffic on the link, in milliseconds. It must
not be greater than the key-lifetime. 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.
keepalive
Boolean. If true then attempt to always maintain a live session
key. Not implemented.
log-events
String list. Types of event to log for this site.
unexpected
Unexpected key setup packets (including late retransmis-
sions).
setup-init
Start of attempt to setup a session key.
setup-timeout
Failure of attempt to setup a session key, through time-
out.
activate-key
Activation of a new session key.
timeout-key
Deletion of current session key through age.
security
Anything potentially suspicious.
state-change
Steps in the key setup protocol.
packet-drop
Whenever we throw away an outgoing packet.
dump-packets
Every key setup packet we see.
errors Failure of name resolution, internal errors.
all Everything (too much!)
A site closure defines one site to communicate with. secnet expects
the (root) key site to be a list of site closures.
sysbuffer
sysbuffer([SIZE[, OPTIONS]]) => buffer closure
SIZE Number. The size of the buffer in bytes. This must be between
64 and 131072. The default is 4096.
OPTIONS
Dictionary. Optional and presently unused.
A buffer closure is a means of buffering packets to send or that have
been received.
syslog
syslog(DICT) => log closure
Valid keys in the DICT argument are:
ident String. The ident string to pass to openlog(3); this value will
appear in each message.
facility
String. The facility to log as. The possible values are auth-
priv, cron, daemon, kern, local0-7, lpr, mail, news, syslog,
user and uucp.
See also logfile above.
tun
tun(DICT) => netlink closure
tun(DICT) => pure closure
Valid keys in the DICT argument are those documented for null-netlink
above, plus:
flavour
String. The type of TUN interface to use. Possible values are
linux, bsd, streams and guess. The default is guess.
device String. The path to the TUN/TAP device file. The default is
/dev/net/tun for the linux flavour and /dev/tun for the others.
interface
String. The interface to use. The default is to pick one auto-
matically. This cannot be used with the streams flavour.
local-address
String. IP address of the host's tunnel interface.
ifconfig-path
String. The name of the ifconfig command. The default is sim-
ply "ifconfig".
route-path
String. The name of the route command. The default is simply
"route".
ifconfig-type
String. The syntax expected by the ifconfig command. Possible
values are linux, bsd, ioctl, solaris-2.5 and guess. The
default is guess.
route-type
String. The syntax expected by the ifconfig command. Possible
values are linux, bsd, ioctl, solaris-2.5 and guess. The
default is guess.
buffer A buffer closure to use for packets transferred from the host to
secnet. The buffer size must be at least 60 greater than the
MTU.
The ifconfig-type and route-type values determine how those commands
are executed. If they are set to ioctl then low-level system calls are
used directly instead of invoking the commands.
The netlink created by tun uses the tun device to communicate with the
host kernel.
udp
udp(DICT) => comm closure
Valid keys in the DICT argument are:
address
String. The IP address to bind on. The default is 0.0.0.0,
i.e. "any".
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.
buffer A buffer closure. See the sysbuffer closure above.
authbind
String. The path to a helper program to bind the socket.
Optional.
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.
A comm closure is a means of sending and receiving messages via a net-
work. It does not provide confidentiality, reliablity or availability.
userv-ipif
userv-ipif(DICT) => netlink closure
userv-ipif(DICT) => pure closure
Valid keys in the DICT argument are those documented for null-netlink
above, plus:
local-address
String. IP address of the host's SLIP interface.
userv-path
String. Where to find userv(1). The default is "userv".
service-user
String. The name of the user that owns the service. The
default is "root".
service-name
String. The name of the service to request. The default is
"ipif".
buffer A buffer closure to use for packets transferred from the host to
secnet.
The netlink created by userv-ipif invokes the specified userv service
with pipes connected to its standard input and output. It uses SLIP to
communicate with the host kernel via these pipes.
FILES
/etc/secnet/secnet.conf
Configuration file.
SEE ALSO
userv(1)