README.config

   1 -*- Fundamental -*-
   2
   3 Sections
   4
   5   [<servername> - <client>]
   6   [<client>]
   7   [<servername>]      often [SERVER]
   8   [COMMON]
   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
  15 Both client and server read all files
  16   /etc/hippotat/main.cfg
  17   /etc/hippotat/config.d
  18   /etc/hippotat/server.d
  19 and in each case if it's a directory, all contained files whose
  20 names consists of only ascii alphanumerics plus '-' and '_'.
  21 The ini file format sections from these files are all unioned.
  22
  23 (If main.cfg does not exist, master.cfg will be tried for backward
  24 compatibility reasons.)
  25
  26
  27 Exceptional settings:
  28
  29   server
  30      Specifies <servername>.
  31      Is looked up in [SERVER] and [COMMON] only.
  32      If not specified there, it is SERVER.
  33
  34      Used by server to select the appropriate parts of the
  35      rest of the configuration.  Ignored by the client.
  36
  37   secret
  38      Looked up in the usual way, but used by client and server to
  39      determine which possible peerings to try to set up, and which to
  40      ignore.
  41
  42      We define the sets of putative clients and servers, as follows:
  43      all those, for which there is any section (even an empty one)
  44      whose name is based on <client> or <servername> (as applicable).
  45      (LIMIT sections do not count.)
  46
  47      The server queue packets for, and accept requests from, each
  48      putative client for which the config search yields a secret.
  49
  50      Each client will create a local interface, and try to communicate
  51      with the server, for each possible pair (putative server,
  52      putative client) for which the config search yields a secret.
  53
  54   ipif
  55      Command to run to create and communicate with local network
  56      interface.  Passed to sh -c.  Must speak SLIP on stdin/stdout.
  57      The following additional interpolations aare substituted:
  58                        %(local)s  %(peer)s  %(rnet)s    %(ifname)s
  59           on server    <vaddr>    <vrelay>  <vnetwork>  <ifname_server>
  60           on client    <client>   <vaddr>   <vroutes>   <ifname_client>
  61      ["userv root ipif %(local)s,%(peer)s,%(mtu)s,slip %(rnets)s"]
  62
  63      On server: applies to all clients; not looked up in
  64       client-specific sections.
  65      On client: may be different for different servers.
  66
  67 Capped settings:
  68
  69      Values in [<server> LIMIT] and [LIMIT] are a cap (maximum) on
  70      those from the other sections (including COMMON).
  71
  72   max_batch_down
  73      Size limit for response payloads (used by server only)
  74      [65536 bytes; LIMIT: 262144 bytes]
  75
  76   max_queue_time
  77      Discard packets after they have been queued this long waiting
  78      for http.
  79      On server: setting applies to downward packets, and is capped
  80       by LIMIT values.
  81      On client: setting applies to upward packets, and is
  82       not affected by LIMIT values.
  83      [10 s; LIMIT: 121 s]
  84
  85   http_timeout
  86      On server: return with empty payload any http request oustanding
  87       for this long
  88      On client: give up on any http request outstanding for
  89       for this long plus http_timeout_grace
  90      Client's effective timeout must be at least server's (checked).
  91      [30 s; LIMIT: 121]
  92
  93   target_requests_outstanding
  94      On server: whenever number of outstanding requests for
  95       a client exceeds this, return oldest with empty payload
  96      On client: try to keep this many requests outstanding.
  97      Must match between client and server (checked).
  98      [3; LIMIT: 10]
  99
 100 Ordinary settings, used by both, not client-specific:
 101
 102     These are not looked up in the client-specific config sections.
 103
 104   addrs
 105      Public IP (v4 or v6) address(es) of the server;
 106      space-separated.
 107      On server: mandatory; used for bind.  No default.
 108      On client: used only to construct default url.
 109
 110   vnetwork
 111      Private network range (<prefix>/<length>).  Must contain all
 112      <client>s.  Must contain <vaddr> and <vrelay>, and used
 113      to compute their defaults.  [172.24.230.192/28]
 114
 115   vaddr
 116      Address of server's virtual interface.
 117
 118   vrelay
 119      Virtual point-to-point address used for tunnel routing
 120      (does not appear in packets).
 121      [first host entry in <vnetwork> other than <vaddr>,
 122       so 172.24.230.194]
 123
 124   port
 125      Public port number of the server.  [80]
 126      On server: used for bind.
 127      On client: used only to construct default url.
 128
 129   mtu
 130      Must match exactly.  (UNCHECKED) [1500 bytes]
 131
 132   ifname_server
 133      Virtual interface name on the server.  [shippo%d]
 134   ifname_client
 135      Virtual interface name on the client.  [hippo%d]
 136      Any %d is interpolated (by the kernel).
 137
 138 Ordinary settings, used by server only:
 139
 140   max_clock_skew
 141      Permissible clock skew between client and server.
 142      hippotat will not work if clock skew is more than this.
 143      Conversely: when moving client from one public network to
 144      another, the first network can deny service to the client for
 145      this period after the client leaves the first network.
 146      [300s]
 147
 148 Ordinary settings, used by client only:
 149
 150   http_timeout_grace
 151      See http_timeout.  [5 s]
 152
 153   max_requests_outstanding
 154      Client will hold off sending more requests than this to
 155      server even if it has data to send.  [6]
 156
 157   max_batch_up
 158      Size limit for request payloads. [4000 bytes]
 159
 160   http_retry
 161      If a request fails, wait this long before considering it
 162      "finished" - to limit rate of futile requests.  [5 s]
 163
 164   url
 165      Public url of server.
 166      [http://<first-entry-in-addrs>:<port>/]
 167
 168   vroutes
 169      Virtual addresses (in CIDR syntax) to be found at the server
 170      end, space-separated.  Routes to those will be created on
 171      the client.  [""]