-Configuration
-=============
+Configuration scheme
+====================
+Configuration is in an INI-like format. Sections start with lines
+``[...]``. Every setting must be in a section. ``#`` and ``;``
+comment lines are supported. Settings ``nmae = value``. Whitespace
+around the name and value is ignored.
+
+The configuration files are resolved to a configuration for each
+pairwise link between a client and a server.
Sections
+--------
+
+The same config key may appear in multiple sections; for example, in a
+section specific to a link, as well as one for all links to a server.
- [<servername> <client>]
- [<client>]
- [<servername>] often [SERVER]
- [COMMON]
+Unless otherwise specified, any particular config setting for a
+particular link is the value from the first of the following
+applicable sections, or failing that the built-in default:
-Keys are looked up in that order, unless otherwise specified.
-<client> is the client's virtual address.
-<servername> must be a valid lowercase DNS hostname and not look like
-an address, or SERVER.
+ * ``[<servername> <client>]``
+ * ``[<client>]``
+ * ``[<servername>]`` (often ``[SERVER]``)
+ * ``[COMMON]``
-There are also:
+``<client>`` is the client's virtual address in IPv4 or IPv6 literal
+syntax (without any surrounding ``[..]``.
- [<servername> LIMIT]
- [LIMIT]
+``<servername>`` must be in the syntrax of a valid lowercase DNS
+hostname (and not look like an address), or be literally ``SERVER``.
-Things not in a section are an error.
+There are also these special sections:
+ * ``[<servername> LIMIT]``
+ * ``[LIMIT]``
+
+Files
+-----
Both client and server read the files
- /etc/hippotat/main.cfg
- /etc/hippotat/config.d/*
- /etc/hippotat/secrets.d/*
-and in each case if it's a directory, all contained files whose
-names consists of only ascii alphanumerics plus '-' and '_'.
-The ini file format sections from these files are all unioned.
-Later files (in the list above, or alphabetically later) can
-override settings from earlier ones.
+ * ``/etc/hippotat/main.cfg`` (if it exists)
+ * ``/etc/hippotat/config.d/*``
+ * ``/etc/hippotat/secrets.d/*``
+
+Here ``*`` means all contained files whose names consists of only
+ascii alphanumerics plus ``-`` and ``_``.
+
+The ``--config`` option can be used to override the directory (usually
+``/etc/hippotat``). Additonally each ``--extra-config`` option names
+an existing file or directory to be processed analagously.
+
+The ini file format sections from these files are all unioned. Later
+files (in the list above, or alphabetically later) can override
+settings from earlier ones.
Note that although it is conventional for information for a particular
server or client to be in a file named after that endpoint, there is
no semantic link: all the files are always read and the appropriate
-section from each is applied to every endpoint.
-
-(If main.cfg does not exist, master.cfg will be tried for backward
-compatibility reasons.)
-
-
-Exceptional settings:
-
- server
- Specifies <servername>.
- Is looked up in [SERVER] and [COMMON] only.
- If not specified there, it is SERVER.
-
- Used by server to select the appropriate parts of the
- rest of the configuration. Ignored by the client.
-
- secret
- Looked up in the usual way, but used by client and server to
- determine which possible peerings to try to set up, and which to
- ignore.
-
- We define the sets of putative clients and servers, as follows:
- all those, for which there is any section (even an empty one)
- whose name is based on <client> or <servername> (as applicable).
- (LIMIT sections do not count.)
-
- The server queue packets for, and accept requests from, each
- putative client for which the config search yields a secret.
-
- Each client will create a local interface, and try to communicate
- with the server, for each possible pair (putative server,
- putative client) for which the config search yields a secret.
-
- ipif
- Command to run to create and communicate with local network
- interface. Passed to sh -c. Must speak SLIP on stdin/stdout.
- The following interpolations aare substituted:
- %{local} %{peer} %{rnets} %{ifname}
- on server <vaddr> <vrelay> <vnetwork> <ifname_server>
- on client <client> <vaddr> <vroutes> <ifname_client>
- Plus %{mtu} and %% to indicate a literal %.
- (For compatibility with older hippotat, %(var)s is supported too
- but this is deprecated since the extra `s` is confusing.)
- ["userv root ipif %{local},%{peer},%{mtu},slip '%{rnets}'"]
-
- On server: applies to all clients; not looked up in
- client-specific sections.
- On client: may be different for different servers.
-
-Capped settings:
-
- Values in [<server> LIMIT] and [LIMIT] are a cap (maximum) on
- those from the other sections (including COMMON).
-
- max_batch_down
- Size limit for response payloads.
- On client, incoming response bodies are limited to this plus
- a fixed constant metadata overhead of 10000 bytes.
- Server uses minim of client and server value (old servers
- just uses server's value).
- [65536 bytes; LIMIT: 262144 bytes]
-
- max_queue_time
- Discard packets after they have been queued this long waiting
- for http.
- On server: setting applies to downward packets.
- On client: setting applies to upward packets.
- [10 s; LIMIT: 121 s]
-
- http_timeout
- On server: return with empty payload any http request oustanding
- for this long
- On client: give up on any http request outstanding for
- for this long plus http_timeout_grace
- Warning messages about link problems, printed by the client,
- are rate limited to no more than one per effective timeout.
- Client's effective timeout must be at least server's (checked).
- [30 s; LIMIT: 121s]
-
- target_requests_outstanding
- On server: whenever number of outstanding requests for
- a client exceeds this, return oldest with empty payload
- On client: try to keep this many requests outstanding.
- Must match between client and server (checked).
- [3; LIMIT: 10]
-
-Ordinary settings, used by both, not client-specific:
-
- These are not looked up in the client-specific config sections.
-
- addrs
- Public IP (v4 or v6) address(es) of the server;
- space-separated.
- On server: mandatory; used for bind. No default.
- On client: used only to construct default url.
-
- vnetwork
- Private network range (<prefix>/<length>). Must contain all
- <client>s. Must contain <vaddr> and <vrelay>, and used
- to compute their defaults. [172.24.230.192/28]
-
- vaddr
- Address of server's virtual interface.
- [first host entry in <vnetwork>, so 172.24.230.193]
-
- vrelay
- Virtual point-to-point address used for tunnel routing
- (does not appear in packets).
- [first host entry in <vnetwork> other than <vaddr>,
- so 172.24.230.194]
-
- port
- Public port number of the server. [80]
- On server: used for bind.
- On client: used only to construct default url.
-
- mtu
- Of virtual interface. Must match exactly at each end.
- (UNCHECKED) [1500 bytes]
-
- ifname_server
- Virtual interface name on the server. [shippo%d]
- ifname_client
- Virtual interface name on the client. [hippo%d]
- Any %d is interpolated (by the kernel).
-
-Ordinary settings, used by server only:
-
- max_clock_skew
- Permissible clock skew between client and server.
- hippotat will not work if clock skew is more than this.
- Conversely: when moving client from one public network to
- another, the first network can deny service to the client for
- this period after the client leaves the first network.
- [300s]
-
-Ordinary settings, used by client only:
-
- http_timeout_grace
- See http_timeout. [5 s]
-
- max_requests_outstanding
- Client will hold off sending more requests than this to
- server even if it has data to send. [6]
-
- max_batch_up
- Size limit for request payloads. [4000 bytes]
-
- success_report_interval
- If nonzero, report success periodically. Otherwise just
- report it when we first have success. [3600 s]
-
- http_retry
- If a request fails, wait this long before considering it
- "finished" - to limit rate of futile requests. [5 s]
-
- url
- Public url of server.
- [http://<first-entry-in-addrs>:<port>/]
-
- vroutes
- Virtual addresses (in CIDR syntax) to be found at the server
- end, space-separated. Routes to those will be created on
- the client. [""]
+section from each is applied to every link.
+
+(If ``main.cfg`` does not exist, ``master.cfg`` will be tried for
+backward compatibility reasons.)
--- /dev/null
+Configuration settings
+======================
+
+Exceptional settings
+--------------------
+
+``server``
+ Specifies ``<servername>``.
+ Is looked up in ``[SERVER]`` and ``[COMMON]`` only.
+ If not specified there, it is ``SERVER``.
+
+ Used by server to select the appropriate parts of the
+ rest of the configuration. Ignored by the client.
+
+``secret``
+ Looked up in the usual way, but used by client and server to
+ determine which possible peerings to try to set up, and which to
+ ignore.
+
+ We define the sets of putative clients and servers, as follows:
+ all those, for which there is any section (even an empty one)
+ whose name is based on ``<client>`` or ``<servername>`` (as applicable).
+ (``LIMIT`` sections do not count.)
+
+ The server queue packets for, and accept requests from, each
+ putative client for which the config search yields a secret.
+
+ Each client will create a local interface, and try to communicate
+ with the server, for each possible pair (putative server,
+ putative client) for which the config search yields a secret.
+
+ The value is a string, fed directly into HMAC.
+
+``ipif``
+ Command to run to create and communicate with local network
+ interface. Passed to sh -c. Must speak SLIP on stdin/stdout.
+ The following interpolations aare substituted:
+
+ ============== ============ ============ =============== =================
+ Input ``%{local}`` ``%{peer}`` ``%{rnets}`` ``%{ifname}``
+ ============== ============ ============ =============== =================
+ **on server** ``vaddr`` ``vrelay`` ``vnetwork`` ``ifname_server``
+ **on client** ``client`` ``vaddr`` ``vroutes`` ``ifname_client``
+ ============== ============ ============ =============== =================
+
+ **Always:** ``%{mtu}``, and ``%%`` to indicate a literal ``%``.
+
+ (For compatibility with older hippotat, ``%(var)s`` is supported too
+ but this is deprecated since the extra ``s`` is confusing.)
+
+ On server: applies to all clients; not looked up in client-specific sections.
+ On client: may be different for different servers.
+
+ [string; ``userv root ipif %{local},%{peer},%{mtu},slip '%{rnets}'``]
+
+
+Capped settings
+---------------
+
+Values in ``[<server> LIMIT]`` and ``[LIMIT]`` are a cap (maximum) on
+those from the other sections (including ``COMMON``). If a larger
+value is obtained, it is (silently) reduced to the limit value.
+
+
+``max_batch_down``
+ Size limit for response payloads.
+
+ On client, incoming response bodies are limited to this plus
+ a fixed constant metadata overhead of 10000 bytes.
+ Server uses minimum of client and server value (old servers
+ just uses server's value).
+
+ [``65536`` (bytes); ``LIMIT``: ``262144``]
+
+``max_queue_time``
+ Discard packets after they have been queued this long
+ waiting for http.
+
+ On server: setting applies to downward packets.
+ On client: setting applies to upward packets.
+
+ [``10`` (s); ``LIMIT``: ``121``]
+
+``http_timeout``
+ On server: return with empty payload any http request oustanding
+ for this long.
+
+ On client: give up on any http request outstanding for
+ for this long plus ``http_timeout_grace``.
+
+ Warning messages about link problems, printed by the client,
+ are rate limited to no more than one per effective timeout.
+
+ Client's effective timeout must be at least server's (checked).
+
+ [``30`` (s); ``LIMIT``: ``121``]
+
+target_requests_outstanding
+ On client: try to keep this many requests outstanding, to
+ allow for downbound data transfer.
+ On server: whenever number of outstanding requests for
+ a client exceeds this, returns oldest with empty payload.
+ Must match between client and server (checked).
+ [``3``; ``LIMIT``: ``10``]
+
+
+Ordinary settings, used by both, not client-specific
+----------------------------------------------------
+
+These are not looked up in the client-specific config sections.
+
+``addrs``
+ Public IP (v4 or v6) address(es) of the server; space-separated.
+ On server: mandatory; used for bind.
+ On client: used only to construct default ``url``.
+ No default.
+
+``vnetwork``
+ Private network range. Must contain all
+ ``<client>``s. Must contain ``vaddr`` and ``vrelay``, and is used
+ to compute their defaults. [CIDR syntax (``<prefix>/<length>``);
+ ``172.24.230.192/28``]
+
+``vaddr``
+ Address of server's virtual interface.
+ [default: first host entry in ``vnetwork``, so ``172.24.230.193``]
+
+``vrelay``
+ Virtual point-to-point address used for tunnel routing
+ (does not appear in packets).
+ [default: first host entry in ``vnetwork`` other than ``vaddr``,
+ so ``172.24.230.194``]
+
+``port``
+ Public port number of the server.
+ On server: used for bind.
+ On client: used only to construct default url.
+ [``80``]
+
+``mtu``
+ Of virtual interface.
+ Must match exactly at each end - *this is not checked*.
+ [``1500`` (bytes)]
+
+``ifname_server``
+ | Virtual interface name on the server. [``shippo%d``]
+ | Any ``%d`` is interpolated (by the kernel).
+
+``ifname_client``
+ | Virtual interface name on the client. [``hippo%d``]
+ | Any ``%d`` is interpolated (by the kernel).
+
+
+Ordinary settings, used by server only
+--------------------------------------
+
+``max_clock_skew``
+ Permissible clock skew between client and server.
+ Hippotat will not work if clock skew is more than this.
+ Conversely: when moving client from one public network to
+ another, the first network can deny service to the client for
+ this period after the client leaves the first network.
+ [``300`` (s)]
+
+
+Ordinary settings, used by client only
+--------------------------------------
+
+``http_timeout_grace``
+ See ``http_timeout``. [``5`` (s)]
+
+``max_requests_outstanding``
+ Client will hold off sending more requests than this to
+ server even if it has data to send. [``6``]
+
+``max_batch_up``
+ Size limit for request upbound payloads. [``4000`` (bytes)]
+
+``success_report_interval``
+ If nonzero, report success periodically. Otherwise just
+ report it when we first have success. [``3600`` (s)]
+
+``http_retry``
+ If a request fails, wait this long before considering it
+ "finished" - to limit rate of futile requests (and also
+ to limit rate of moaning on stderr). [``5`` s]
+
+``url``
+ Public url of server.
+ [``http://<first-entry-in-addrs>:<port>/``]
+
+``vroutes``
+ Additional virtual addresses to be found at the server
+ end, space-separated. Routes to those will be created on
+ the client. ``vrelay`` is included implicitly.
+ [CIDR syntax, space separated; default: none]
~ian / hippotat.git / commitdiff