wip fixes

[hippotat] / README.config

-*- Fundamental -*-

Sections

  [<servername> - <client>]
  [<client>]
  [<servername>]      usually [SERVER]
  [DEFAULT]

Keys are looked up in that order, unless otherwise specified.
<client> is the client's virtual address.
<servername> must be a valid DNS hostname and not look like an address.

Exceptional settings:

  server
     Specifies <servername>.
     Is looked up in [SERVER] and [DEFAULT] 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.

  password
     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.

     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.

     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.

  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"]

     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 [<server> LIMIT] and [LIMIT] are a cap (maximum) on
     those from the other sections (including DEFAULT).

  max_batch_down
     Size limit for response payloads (used by server only)
     [65536 bytes; LIMIT: 262144 bytes]

  max_queue_time
     Discard downwards packets after this long (used by server only)
     [10 s; LIMIT: 121 s]

  http_timeout
     On server: return with empty payload any http request oustanding
      for this long
     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; LIMIT: 121]

  target_requests_outstanding   
     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; LIMIT: 10]

Ordinary settings, used by both, not client-specific:

    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.

  vnetwork
     Private network range (<prefix>/<length>).  Must contain all
     <client>s.  Must contain <vaddr> and <vrelay>, and used
     to compute their defaults.  [172.24.230.192/28]

  vaddr
     Address of server's virtual interface.

  vrelay
     Virtual point-to-point address used for tunnel routing
     (does not appear in packets).
     [first host entry in <vnetwork> other than <vaddr>,
      so 172.24.230.194]

  port
     Public port number of the server.  [80]
     On server: used for bind.
     On client: used only to construct default url.

  mtu
     Must match exactly.  (checked) [1500 bytes]

Ordinary settings, used by client only:

  http_timeout_grace
     See http_timeout.  [5 s]

  max_requests_outstanding
     Client will hold off sending more requests than this to
     server even if it has data to send.  [6]

  max_batch_up
     Size limit for request payloads. [4000 bytes]

  http_retry
     If a request fails, wait this long before considering it
     "finished" - to limit rate of futile requests.  [5 s]

  url
     Public url of server.
     [http://<first-entry-in-addrs>:<port>/]

  vroutes
     Virtual addresses (in CIDR syntax) to be found at the server
     end, space-separated.  Routes to those will be created on
     the client.  [""]