From 67ec27f8fa11e2ad1a84ef0b24c17c7289ddcf2e Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 5 Aug 2021 21:12:40 +0100 Subject: [PATCH] rework and reformat docs, mark up in rst Signed-off-by: Ian Jackson --- docs/config.rst | 234 ++++++++++------------------------------------ docs/index.rst | 1 + docs/settings.rst | 196 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 245 insertions(+), 186 deletions(-) create mode 100644 docs/settings.rst diff --git a/docs/config.rst b/docs/config.rst index a9c2b49..08d5d77 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -1,202 +1,64 @@ -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. - [ ] - [] - [] 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. - is the client's virtual address. - must be a valid lowercase DNS hostname and not look like -an address, or SERVER. + * ``[ ]`` + * ``[]`` + * ``[]`` (often ``[SERVER]``) + * ``[COMMON]`` -There are also: +```` is the client's virtual address in IPv4 or IPv6 literal +syntax (without any surrounding ``[..]``. - [ LIMIT] - [LIMIT] +```` 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: + * ``[ 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 . - 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 or (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 - on 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 [ 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 (/). Must contain all - s. Must contain and , and used - to compute their defaults. [172.24.230.192/28] - - vaddr - Address of server's virtual interface. - [first host entry in , so 172.24.230.193] - - vrelay - Virtual point-to-point address used for tunnel routing - (does not appear in packets). - [first host entry in other than , - 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://:/] - - 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.) diff --git a/docs/index.rst b/docs/index.rst index 13d8e7f..31973fa 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,7 @@ Hippotat - Asinine IP over HTTP README config.rst + settings.rst Indices and tables ================== diff --git a/docs/settings.rst b/docs/settings.rst new file mode 100644 index 0000000..e4cef04 --- /dev/null +++ b/docs/settings.rst @@ -0,0 +1,196 @@ +Configuration settings +====================== + +Exceptional settings +-------------------- + +``server`` + Specifies ````. + 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 ```` or ```` (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 ``[ 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 + ````s. Must contain ``vaddr`` and ``vrelay``, and is used + to compute their defaults. [CIDR syntax (``/``); + ``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://:/``] + +``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] -- 2.30.2