README.config

   1 -*- Fundamental -*-
   2
   3 Sections
   4
   5   [<servername> - <client>]
   6   [<client>]
   7   [<servername>]      usually [SERVER]
   8   [DEFAULT]
   9
  10 Keys are looked up in that order, unless otherwise specified.
  11 <client> is the client's virtual address.
  12 <servername> must be a valid DNS hostname and not look like an address.
  13
  14 Exceptional settings:
  15
  16   server
  17      Specifies <servername>.
  18      Is looked up in [SERVER] and [DEFAULT] only.
  19      If not specified there, it is SERVER.
  20
  21      Used by server to select the appropriate parts of the
  22      rest of the configuration.  Ignored by the client.
  23
  24   password
  25      Looked up in the usual way, but used by client and server to
  26      determine which possible peerings to try to set up, and which to
  27      ignore.
  28
  29      We define the sets of putative clients and servers, as follows:
  30      all those, for which there is any section (even an empty one)
  31      whose name is based on <client> or <servername> (as applicable).
  32      (LIMIT sections do not count.)
  33
  34      The server queue packets for, and accept requests from, each
  35      putative client for which the config search yields a password.
  36
  37      Each client will create a local interface, and try to communicate
  38      with the server, for each possible pair (putative server,
  39      putative client) for which the config search yields a password.
  40
  41   ipif
  42      Command to run to create and communicate with local network
  43      interface.  Passed to sh -c.  Must speak SLIP on stdin/stdout.
  44      The following additional interpolations aare substituted:
  45                        %(local)s      %(peer)s       %(rnet)s
  46           on server    <vaddr>        <vrelay>       <vnetwork>
  47           on client    <client>       <vaddr>        <vroutes>
  48      ["userv root ipif %(local)s,%(peer)s,%(mtu)s,slip %(rnets)s"]
  49
  50      On server: applies to all clients; not looked up in
  51       client-specific sections.
  52      On client: may be different for different servers.
  53
  54 Capped settings:
  55
  56      Values in [<server> LIMIT] and [LIMIT] are a cap (maximum) on
  57      those from the other sections (including DEFAULT).
  58
  59   max_batch_down
  60      Size limit for response payloads (used by server only)
  61      [65536 bytes; LIMIT: 262144 bytes]
  62
  63   max_queue_time
  64      Discard downwards packets after this long (used by server only)
  65      [10 s; LIMIT: 121 s]
  66
  67   http_timeout
  68      On server: return with empty payload any http request oustanding
  69       for this long
  70      On client: give up on any http request outstanding for
  71       for this long plus http_timeout_grace
  72      Client's effective timeout must be at least server's (checked).
  73      [30 s; LIMIT: 121]
  74
  75   target_requests_outstanding
  76      On server: whenever number of outstanding requests for
  77       a client exceeds this, return oldest with empty payload
  78      On client: try to keep this many requests outstanding.
  79      Must match between client and server (checked).
  80      [3; LIMIT: 10]
  81
  82 Ordinary settings, used by both, not client-specific:
  83
  84     These are not looked up in the client-specific config sections.
  85
  86   addrs
  87      Public IP (v4 or v6) address(es) of the server;
  88      space-separated.
  89      On server: mandatory; used for bind.  No default.
  90      On client: used only to construct default url.
  91
  92   vnetwork
  93      Private network range (<prefix>/<length>).  Must contain all
  94      <client>s.  Must contain <vaddr> and <vrelay>, and used
  95      to compute their defaults.  [172.24.230.192/28]
  96
  97   vaddr
  98      Address of server's virtual interface.
  99
 100   vrelay
 101      Virtual point-to-point address used for tunnel routing
 102      (does not appear in packets).
 103      [first host entry in <vnetwork> other than <vaddr>,
 104       so 172.24.230.194]
 105
 106   port
 107      Public port number of the server.  [80]
 108      On server: used for bind.
 109      On client: used only to construct default url.
 110
 111   mtu
 112      Must match exactly.  (checked) [1500 bytes]
 113
 114 Ordinary settings, used by client only:
 115
 116   http_timeout_grace
 117      See http_timeout.  [5 s]
 118
 119   max_requests_outstanding
 120      Client will hold off sending more requests than this to
 121      server even if it has data to send.  [6]
 122
 123   max_batch_up
 124      Size limit for request payloads. [4000 bytes]
 125
 126   http_retry
 127      If a request fails, wait this long before considering it
 128      "finished" - to limit rate of futile requests.  [5 s]
 129
 130   url
 131      Public url of server.
 132      [http://<first-entry-in-addrs>:<port>/]
 133
 134   vroutes
 135      Virtual addresses (in CIDR syntax) to be found at the server
 136      end, space-separated.  Routes to those will be created on
 137      the client.  [""]