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