README.config

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