chiark / gitweb /
document that nonce-based authentication is for the future
[hippotat.git] / README.config
1 -*- Fundamental -*-
2
3 Sections
4
5   [<servername> - <client>]
6   [<client>]
7   [<servername>]      often [SERVER]
8   [COMMON]
9
10 Keys are looked up in that order, unless otherwise specified.
11 <client> is the client's virtual address.
12 <servername> must be a valid DNS hostname and not look like an address.
13
14 Exceptional settings:
15
16   server
17      Specifies <servername>.
18      Is looked up in [SERVER] and [COMMON] only.
19      If not specified there, it is SERVER.
20
21      Used by server to select the appropriate parts of the
22      rest of the configuration.  Ignored by the client.
23
24   password
25      Looked up in the usual way, but used by client and server to
26      determine which possible peerings to try to set up, and which to
27      ignore.
28
29      We define the sets of putative clients and servers, as follows:
30      all those, for which there is any section (even an empty one)
31      whose name is based on <client> or <servername> (as applicable).
32      (LIMIT sections do not count.)
33
34      The server queue packets for, and accept requests from, each
35      putative client for which the config search yields a password.
36
37      Each client will create a local interface, and try to communicate
38      with the server, for each possible pair (putative server,
39      putative client) for which the config search yields a password.
40
41   ipif
42      Command to run to create and communicate with local network
43      interface.  Passed to sh -c.  Must speak SLIP on stdin/stdout.
44      The following additional interpolations aare substituted:
45                        %(local)s  %(peer)s  %(rnet)s    %(ifname)s
46           on server    <vaddr>    <vrelay>  <vnetwork>  <ifname_server>
47           on client    <client>   <vaddr>   <vroutes>   <ifname_client>
48      ["userv root ipif %(local)s,%(peer)s,%(mtu)s,slip %(rnets)s"]
49
50      On server: applies to all clients; not looked up in
51       client-specific sections.
52      On client: may be different for different servers.
53
54 Capped settings:
55
56      Values in [<server> LIMIT] and [LIMIT] are a cap (maximum) on
57      those from the other sections (including COMMON).
58
59   max_batch_down
60      Size limit for response payloads (used by server only)
61      [65536 bytes; LIMIT: 262144 bytes]
62
63   max_queue_time
64      Discard packets after they have been queued this long waiting
65      for http.
66      On server: setting applies to downward packets, and is capped
67       by LIMIT values.
68      On client: setting applies to upward packets, and is
69       not affected by LIMIT values.
70      [10 s; LIMIT: 121 s]
71
72   http_timeout
73      On server: return with empty payload any http request oustanding
74       for this long
75      On client: give up on any http request outstanding for
76       for this long plus http_timeout_grace
77      Client's effective timeout must be at least server's (checked).
78      [30 s; LIMIT: 121]
79
80   target_requests_outstanding   
81      On server: whenever number of outstanding requests for
82       a client exceeds this, return oldest with empty payload
83      On client: try to keep this many requests outstanding.
84      Must match between client and server (checked).
85      [3; LIMIT: 10]
86
87 Ordinary settings, used by both, not client-specific:
88
89     These are not looked up in the client-specific config sections.
90
91   addrs
92      Public IP (v4 or v6) address(es) of the server;
93      space-separated.
94      On server: mandatory; used for bind.  No default.
95      On client: used only to construct default url.
96
97   vnetwork
98      Private network range (<prefix>/<length>).  Must contain all
99      <client>s.  Must contain <vaddr> and <vrelay>, and used
100      to compute their defaults.  [172.24.230.192/28]
101
102   vaddr
103      Address of server's virtual interface.
104
105   vrelay
106      Virtual point-to-point address used for tunnel routing
107      (does not appear in packets).
108      [first host entry in <vnetwork> other than <vaddr>,
109       so 172.24.230.194]
110
111   port
112      Public port number of the server.  [80]
113      On server: used for bind.
114      On client: used only to construct default url.
115
116   mtu
117      Must match exactly.  (UNCHECKED) [1500 bytes]
118
119   ifname_server
120      Virtual interface name on the server.  [shippo%d]
121   ifname_client
122      Virtual interface name on the client.  [hippo%d]
123      Any %d is interpolated (by the kernel).
124
125 Ordinary settings, used by client only:
126
127   http_timeout_grace
128      See http_timeout.  [5 s]
129
130   max_requests_outstanding
131      Client will hold off sending more requests than this to
132      server even if it has data to send.  [6]
133
134   max_batch_up
135      Size limit for request payloads. [4000 bytes]
136
137   http_retry
138      If a request fails, wait this long before considering it
139      "finished" - to limit rate of futile requests.  [5 s]
140
141   url
142      Public url of server.
143      [http://<first-entry-in-addrs>:<port>/]
144
145   vroutes
146      Virtual addresses (in CIDR syntax) to be found at the server
147      end, space-separated.  Routes to those will be created on
148      the client.  [""]