From: Ian Jackson Date: Wed, 21 Jul 2021 21:49:08 +0000 (+0100) Subject: Import docs from Python program X-Git-Tag: hippotat/1.0.0~526 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?a=commitdiff_plain;h=74d464d2d74f6552e8a3a52a1e503bf5f7a057bb;p=hippotat.git Import docs from Python program We are aiming to be compatible with this. Copied these files from d5100ea6b9bb1d0d858c5475469f9cc4e3200b3a verbatim. We'll free to hack them here, though. Signed-off-by: Ian Jackson --- diff --git a/PROTOCOL b/PROTOCOL new file mode 100644 index 0000000..e18cf0e --- /dev/null +++ b/PROTOCOL @@ -0,0 +1,42 @@ +Server maintains a queue of outbound packets for each user + +Packets which are older than the applicable max_queue_time are discarded + +Each incoming request to the server takes up to max_batch_down bytes +from the queue and returns them as the POST response body payload + +Each incoming request contains up to max_batch_up bytes of payload. +It's a multipart/form-data. + +Authentication: clock-based lifetime-limited bearer tokens. + +Encryption and integrity checking: none. Use a real VPN over this! + +Routing assistance: none in hippotat; can be requested on client + from userv-ipif via `vroutes' parameter. Use with secnet polypath + ideally uses the special support in secnet 0.4.x. + +Client form parameters (multipart/form-data): + m metadata, newline-separated list (text file) of + client ip address (textual) + token + target_requests_outstanding + http_timeout + d data (SLIP format, with SLIP_ESC and `-' swapped) + + +Authentication token is: + +(separated by a single space). The hmac is + HMAC(secret, ) + + +Possible future nonce-based authentication: + +server keeps big nonce counter for each client +meaning is: + nonce counter is most recent nonce client has sent +also server keeps bitmap of the previous ?64 nonces, + whether client has sent them + +client picks.... xxx diff --git a/README.config b/README.config new file mode 100644 index 0000000..842573c --- /dev/null +++ b/README.config @@ -0,0 +1,158 @@ +-*- Fundamental -*- + +Sections + + [ - ] + [] + [] often [SERVER] + [COMMON] + +Keys are looked up in that order, unless otherwise specified. + is the client's virtual address. + must be a valid DNS hostname and not look like an address. + +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 additional interpolations aare substituted: + %(local)s %(peer)s %(rnet)s %(ifname)s + on server + on client + ["userv root ipif %(local)s,%(peer)s,%(mtu)s,slip %(rnets)s"] + + 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 (used by server only) + [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, and is capped + by LIMIT values. + On client: setting applies to upward packets, and is + not affected by LIMIT values. + [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 + Client's effective timeout must be at least server's (checked). + [30 s; LIMIT: 121] + + 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. + + 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 + Must match exactly. (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] + + 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. [""]