ResponseConsumer: move _resp initialisation to superclass constructor (nfc)

[hippotat.git] / README.config

diff --git a/README.config b/README.config
index fc2bbf808a1e4e955835c872df95499e21ef7129..842573cd6a153ca9d9f1e1f7041a2c066e8ea468 100644 (file)
--- a/README.config
+++ b/README.config
@@ -2,26 +2,26 @@
 
 Sections
 
 
 Sections
 

-  [<servername> - <clientaddr>]
+  [<servername> - <client>]

   [<client>]
   [<client>]

-  [<servername>]      usually [SERVER]
-  [DEFAULT]
+  [<servername>]      often [SERVER]
+  [COMMON]

 
 

-Keys are looked up in that order.
+Keys are looked up in that order, unless otherwise specified.

 <client> is the client's virtual address.
 <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:
 
   server
      Specifies <servername>.
 
 Exceptional settings:
 
   server
      Specifies <servername>.

-     Is looked up in [SERVER] and [DEFAULT] only.
+     Is looked up in [SERVER] and [COMMON] only.

      If not specified there, it is SERVER.
 
      Used by server to select the appropriate parts of the
      rest of the configuration.  Ignored by the client.
 
      If not specified there, it is SERVER.
 
      Used by server to select the appropriate parts of the
      rest of the configuration.  Ignored by the client.
 

-  password
+  secret

      Looked up in the usual way, but used by client and server to
      determine which possible peerings to try to set up, and which to
      ignore.
      Looked up in the usual way, but used by client and server to
      determine which possible peerings to try to set up, and which to
      ignore.


@@ -29,55 +29,70 @@ 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).
      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
 
      The server queue packets for, and accept requests from, each

-     putative client for which the config search yields a password.
+     putative client for which the config search yields a secret.

 
      Each client will create a local interface, and try to communicate
      with the server, for each possible pair (putative server,
 
      Each client will create a local interface, and try to communicate
      with the server, for each possible pair (putative server,

-     putative client) for which the config search yields a password.
+     putative client) for which the config search yields a secret.
+
+  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:
 
 
 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 COMMON).

 
   max_batch_down
 
   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
 
   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
 
   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
       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).
       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   
 
   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
       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.
 
   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
 
   vnetwork
      Private network range (<prefix>/<length>).  Must contain all


@@ -95,11 +110,27 @@ Ordinary settings, used by client and server:
 
   port
      Public port number of the server.  [80]
 
   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
 
   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 server only:
+
+  max_clock_skew
+     Permissible clock skew between client and server.
+     hippotat will not work if clock skew is more than this.
+     Conversely: when moving client from one public network to
+     another, the first network can deny service to the client for
+     this period after the client leaves the first network.
+     [300s]

 
 Ordinary settings, used by client only:
 
 
 Ordinary settings, used by client only: