--- /dev/null
+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:
+ <time_t in hex with no leading 0s> <hmac in base64>
+(separated by a single space). The hmac is
+ HMAC(secret, <time_t in hex>)
+
+
+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
--- /dev/null
+-*- Fundamental -*-
+
+Sections
+
+ [<servername> - <client>]
+ [<client>]
+ [<servername>] often [SERVER]
+ [COMMON]
+
+Keys are looked up in that order, unless otherwise specified.
+<client> is the client's virtual address.
+<servername> must be a valid DNS hostname and not look like an address.
+
+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 additional interpolations aare substituted:
+ %(local)s %(peer)s %(rnet)s %(ifname)s
+ on server <vaddr> <vrelay> <vnetwork> <ifname_server>
+ on client <client> <vaddr> <vroutes> <ifname_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 [<server> 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 (<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.
+
+ 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
+ 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://<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. [""]