docs/config.rst

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