docs/settings.rst

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