WIP DNS bugfixes

[secnet.git] / README

diff --git a/README b/README
index 3736b89bbf5dfe1b8f81574d098e456709058e4e..12a8469fdfd33e3ee792cd7e1d906918cd1283f1 100644 (file)
--- a/README
+++ b/README
@@ -201,9 +201,18 @@ Defines:
 udp: dict argument
   address (string): IP address to listen and send on
   port (integer): UDP port to listen and send on
+  resolver (resolver closure)
   buffer (buffer closure): buffer for incoming packets
   authbind (string): optional, path to authbind-helper program
 
+ udp looks up the following keys in its calling closure (usually, this
+ is a site closure) when a peer needs to be found:
+
+  address (string): optional, DNS name used to find our peer
+  port (integer): mandatory if 'address' is specified: the port used
+    to contact our peer
+
+
 ** log
 
 Defines:
@@ -270,27 +279,28 @@ 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)
-  resolver (resolver 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.
   random (randomsrc closure)
   local-key (rsaprivkey closure)
-  address (string): optional, DNS name used to find our peer
-  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 [2000]
+    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 (in ms)
-    [half key-lifetime, or key-lifetime minus 5 mins, whichever is longer].
+    [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
@@ -322,6 +332,20 @@ site: dict argument
   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]
+  Plus further keys depending on the first comm.
+
+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