chiark / gitweb /
slip: Report unexpected kinds of death from userv
[secnet.git] / README
diff --git a/README b/README
index 3c1df8b..4d6f4e5 100644 (file)
--- a/README
+++ b/README
@@ -2,15 +2,10 @@ secnet - flexible VPN software
 
 * Copying
 
-secnet is Copyright (C) 1995--2001 Stephen Early <steve@greenend.org.uk>
+secnet is Copyright (C) 1995--2003 Stephen Early <steve@greenend.org.uk>
 It is distributed under the terms of the GNU General Public License,
 version 2 or later.  See the file COPYING for more information.
 
-The portable snprintf implementation in snprintf.c is Copyright (C)
-1999 Mark Martinec <mark.martinec@ijs.si> and is distributed under the
-terms of the Frontier Artistic License.  You can find the standard
-version of snprintf.c at http://www.ijs.si/software/snprintf/
-
 The IP address handling library in ipaddr.py is Copyright (C)
 1996--2000 Cendio Systems AB, and is distributed under the terms of
 the GPL.
@@ -121,12 +116,6 @@ f is a dictionary:
 
 Note that f/g/e is NOT 4.
 
-In a future version of secnet it will also be permissible to list
-other dictionaries before a dictionary definition,
-eg. <defaults,otherdefaults>{definitions}.  These will be searched in
-order for keys, before the lexical parent.  (This is not yet
-implemented)
-
 Elements that are lists are inserted into lists in definitions, not
 referenced by them (i.e. you can't have lists of lists).
 
@@ -140,11 +129,14 @@ closure { definitions } is short for closure({definitions}).
 The main body of secnet, and all the additional modules, predefine
 some keys in the root dictionary.  The main ones are:
 
-  yes, true, True, TRUE:   the boolean value True
-  no, false, False, FALSE: the boolean value False
+  yes, true, True, TRUE, on:   the boolean value True
+  no, false, False, FALSE, off: the boolean value False
   makelist:   turns a dictionary (arg1) into a list of definitions
               (ignoring the keys)
   readfile:   reads a file (arg1) and returns it as a string
+  map:        applies the closure specified as arg1 to each of the
+              remaining elements in the list in turn.  Returns a list
+              made up of the outputs of the closure.
 
 Keys defined by modules are described below, in the module
 documentation.
@@ -202,6 +194,7 @@ Defines:
   udp (closure => comm closure)
 
 udp: dict argument
+  address (string list): IPv6 or IPv4 addresses to listen and send on
   port (integer): UDP port to listen and send on
   buffer (buffer closure): buffer for incoming packets
   authbind (string): optional, path to authbind-helper program
@@ -272,27 +265,35 @@ site: dict argument
   local-name (string): this site's name for itself
   name (string): the name of the site's peer
   link (netlink closure)
-  comm (comm closure)
+  comm (one or more comm closures): if there is more than one, the
+   first one will be used for any key setups initiated by us using the
+   configured address.  Others are only used if our peer talks to
+   them.
   resolver (resolver closure)
   random (randomsrc closure)
   local-key (rsaprivkey closure)
-  address (string): optional, DNS name used to find our peer
+  address (string list): optional, DNS name(s) used to find our peer;
+    address literals are supported too if enclosed in `[' `]'.
   port (integer): mandatory if 'address' is specified: the port used
     to contact our peer
   key (rsapubkey closure): our peer's public key
   transform (transform closure): how to mangle packets sent between sites
   dh (dh closure)
   hash (hash closure)
-  key-lifetime (integer): max lifetime of a session key, in ms [one hour]
+  key-lifetime (integer): max lifetime of a session key, in ms
+    [one hour; mobile: 2 days]
   setup-retries (integer): max number of times to transmit a key negotiation
-    packet [5]
+    packet [5; mobile: 30]
   setup-timeout (integer): time between retransmissions of key negotiation
-    packets, in ms [1000]
+    packets, in ms [2000; mobile: 1000]
   wait-time (integer): after failed key setup, wait this long (in ms) before
-    allowing another attempt [20000]
+    allowing another attempt [20000; mobile: 10000]
   renegotiate-time (integer): if we see traffic on the link after this time
-    then renegotiate another session key immediately [depends on key-lifetime]
-  keepalive (bool): if True then attempt always to keep a valid session key
+    then renegotiate another session key immediately (in ms)
+    [half key-lifetime, or key-lifetime minus 5 mins (mobile: 12 hours),
+     whichever is longer].
+  keepalive (bool): if True then attempt always to keep a valid session key.
+    Not actually currently implemented. [false]
   log-events (string list): types of events to log for this site
     unexpected: unexpected key setup packets (may be late retransmissions)
     setup-init: start of attempt to setup a session key
@@ -304,9 +305,61 @@ site: dict argument
     packet-drop: whenever we throw away an outgoing packet
     dump-packets: every key setup packet we see
     errors: failure of name resolution, internal errors
+    peer-addrs: changes to sets of peer addresses (interesting for mobile peers)
     all: everything (too much!)
+  mobile (bool): if True then peer is "mobile" ie we assume it may
+    change its apparent IP address and port number without either it
+    or us being aware of the change; so, we remember the last several
+    port/addr pairs we've seen and send packets to all of them
+    (subject to a timeout).  We maintain one set of addresses for key
+    setup exchanges, and another for data traffic. Two communicating
+    peers must not each regard the other as mobile, or all the traffic
+    in each direction will be triplicated (strictly, transmitted
+    mobile-peers-max times) and anyway two peers whose public contact
+    address may suddenly change couldn't communicate reliably because
+    their contact addresses might both change at once. [false]
+  mobile-peers-max (integer): Maximum number of peer port/addr pairs we
+    remember and send to.  Must be at least 1 and no more than 5.
+    [4 if any address is configured, otherwise 3]
+  static-peers-max (integer): Maximum number of peer port/addr pairs
+    we can try for a static site.  Must be at least 1 and no more
+    than 5.  [4 or 3, as above]
+  mobile-peer-expiry (integer): For "mobile" peers only, the length
+    of time (in seconds) for which we will keep sending to multiple
+    address/ports from which we have not seen incoming traffic. [120]
+  local-mobile (bool): if True then other peers have been told we are
+    "mobile".  This should be True iff the peers' site configurations
+    for us have "mobile True" (and if we find a site configuration for
+    ourselves in the config, we insist on this).  The effect is to
+    check that there are no links both ends of which are allegedly
+    mobile (which is not supported, so those links are ignored) and
+    to change some of the tuning parameter defaults. [false]
+  mtu-target (integer): Desired value of the inter-site MTU for this
+    peering.  This value will be advertised to the peer (which ought
+    to affect incoming packets), and if the peer advertises an MTU its
+    value will be combined with this setting to compute the inter-site
+    MTU.  (secnet will still accept packets which exceed the
+    (negotiated or assumed) inter-site MTU.)  Setting a lower
+    inter-site MTU can be used to try to restrict the sizes of the
+    packets sent over the underlying public network (e.g. to work
+    around network braindamage).  It is not normally useful to set a
+    larger value for mtu-target than the VPN's general MTU (which
+    should be reflected in the local private interface MTU, ie the mtu
+    parameter to netlink).  If this parameter is not set, or is set
+    to 0, the default is to use the local private link mtu.
+
+Links involving mobile peers have some different tuning parameter
+default values, which are generally more aggressive about retrying key
+setup but more relaxed about using old keys.  These are noted with
+"mobile:", above, and apply whether the mobile peer is local or
+remote.
+
+** transform-eax
 
-** transform
+Defines:
+   eax-serpent (closure => transform closure)
+
+** transform-cbcmac
 
 Defines:
   serpent256-cbc (closure => transform closure)
@@ -319,8 +372,8 @@ Defines:
 null-netlink: dict argument
   name (string): name for netlink device, used in log messages
   networks (string list): networks on the host side of the netlink device
-  exclude-remote-networks (string list): networks that may never be claimed
-    by any remote site using this netlink device
+  remote-networks (string list): networks that may be claimed
+    by the remote site using this netlink device
   local-address (string): IP address of host's tunnel interface
   secnet-address (string): IP address of this netlink device
   ptp-address (string): IP address of the other end of a point-to-point link
@@ -338,9 +391,9 @@ a netlink closure:
   options (string list):
     allow-route: allow packets coming from this tunnel to be routed to
       other tunnels as well as the host (used for mobile devices like laptops)
-    soft-route: remove these routes from the host's routing table when
+    soft: remove these routes from the host's routing table when
       the tunnel link quality is zero
-  mtu (integer): default MTU over this link; may be updated by tunnel code
+  mtu (integer): MTU of host's tunnel interface
 
 Netlink will dump its current routing table to the system/log on
 receipt of SIGUSR1.