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