docs/settings.md

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