logging: if logevent_is_boringtwisted fails, print why when we print the exception

[hippotat.git] / README.config

diff --git a/README.config b/README.config
index fc2bbf808a1e4e955835c872df95499e21ef7129..81f791d836b1417a48067d843d3540e34983079e 100644 (file)
--- a/README.config
+++ b/README.config
@@ -2,14 +2,14 @@
 
 Sections
 
-  [<servername> - <clientaddr>]
+  [<servername> - <client>]
   [<client>]
-  [<servername>]      usually [SERVER]
+  [<servername>]      often [SERVER]
   [DEFAULT]
 
-Keys are looked up in that order.
+Keys are looked up in that order, unless otherwise specified.
 <client> is the client's virtual address.
-<servername> must not look like an address.
+<servername> must be a valid DNS hostname and not look like an address.
 
 Exceptional settings:
 
@@ -29,6 +29,7 @@ Exceptional settings:
      We define the sets of putative clients and servers, as follows:
      all those, for which there is any section (even an empty one)
      whose name is based on <client> or <servername> (as applicable).
+     (LIMIT sections do not count.)
 
      The server queue packets for, and accept requests from, each
      putative client for which the config search yields a password.
@@ -37,47 +38,61 @@ Exceptional settings:
      with the server, for each possible pair (putative server,
      putative client) for which the config search yields a password.
 
+  ipif
+     Command to run to create and communicate with local network
+     interface.  Passed to sh -c.  Must speak SLIP on stdin/stdout.
+     The following additional interpolations aare substituted:
+                       %(local)s  %(peer)s  %(rnet)s    %(ifname)s
+          on server    <vaddr>    <vrelay>  <vnetwork>  <ifname_server>
+          on client    <client>   <vaddr>   <vroutes>   <ifname_client>
+     ["userv root ipif %(local)s,%(peer)s,%(mtu)s,slip %(rnets)s"]
+
+     On server: applies to all clients; not looked up in
+      client-specific sections.
+     On client: may be different for different servers.
+
 Capped settings:
 
-     Values in <servername> are a cap (maximum) on those from the
-     other sections (including DEFAULT):
+     Values in [<server> LIMIT] and [LIMIT] are a cap (maximum) on
+     those from the other sections (including DEFAULT).
 
   max_batch_down
-     Size limit for response payloads (server only) [65536 bytes]
+     Size limit for response payloads (used by server only)
+     [65536 bytes; LIMIT: 262144 bytes]
 
   max_queue_time
-     Discard downwards packets after this long (server only) [10 s]
+     Discard packets after they have been queued this long waiting
+     for http.
+     On server: setting applies to downward packets, and is capped
+      by LIMIT values.
+     On client: setting applies to upward packets, and is
+      not affected by LIMIT values.
+     [10 s; LIMIT: 121 s]
 
   http_timeout
-     (On server) return with empty payload any http request oustanding
+     On server: return with empty payload any http request oustanding
       for this long
-     (On client) give up on any http request outstanding for
+     On client: give up on any http request outstanding for
       for this long plus http_timeout_grace
      Client's effective timeout must be at least server's (checked).
-     [30 s]
+     [30 s; LIMIT: 121]
 
   target_requests_outstanding   
-     (On server) whenever number of outstanding requests for
+     On server: whenever number of outstanding requests for
       a client exceeds this, return oldest with empty payload
-     (On client) try to keep this many requests outstanding.
-     Must match between client and server (checked).  [3]
+     On client: try to keep this many requests outstanding.
+     Must match between client and server (checked).
+     [3; LIMIT: 10]
 
-Ordinary settings, used by client and server:
+Ordinary settings, used by both, not client-specific:
 
-  ipif
-     Command to run to create and communicate with local network
-     interface.  Passed to sh -c.  Must speak SLIP on stdin/stdout.
-     The following additional interpolations aare substituted:
-                       %(local)s      %(peer)s       %(rnet)s
-          on server    <vaddr>        <vrelay>       <vnetwork>
-          on client    <client>       <vaddr>        <vroutes>
-     ["userv root ipif %(local)s,%(peer)s,%(mtu)s,slip %(rnets)s"]
+    These are not looked up in the client-specific config sections.
 
   addrs
      Public IP (v4 or v6) address(es) of the server;
      space-separated.
-     (On server) mandatory; used for bind.  No default.
-     (On client) used only to construct default url.
+     On server: mandatory; used for bind.  No default.
+     On client: used only to construct default url.
 
   vnetwork
      Private network range (<prefix>/<length>).  Must contain all
@@ -95,11 +110,17 @@ Ordinary settings, used by client and server:
 
   port
      Public port number of the server.  [80]
-     (On server) used for bind.
-     (On client) used only to construct default url.
+     On server: used for bind.
+     On client: used only to construct default url.
 
   mtu
-     Must match exactly.  (checked) [1500 bytes]
+     Must match exactly.  (UNCHECKED) [1500 bytes]
+
+  ifname_server
+     Virtual interface name on the server.  [shippo%d]
+  ifname_client
+     Virtual interface name on the client.  [hippo%d]
+     Any %d is interpolated (by the kernel).
 
 Ordinary settings, used by client only: