[hippotat] / README.config

-*- Fundamental -*-

Sections

  [<servername> - <clientaddr>]
  [<client>]
  [<servername>]      usually [SERVER]
  [DEFAULT]

Keys are looked up in that order.
<client> is the client's virtual address.
<servername> must not look like an address.

Exceptional settings:

  server
     Specifies <servername>.
     Is looked up in [SERVER] and [DEFAULT] 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.

  password
     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).

     The server queue packets for, and accept requests from, each
     putative client for which the config search yields a password.

     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 password.

Capped settings:

     Values in <servername> are a cap (maximum) on those from the
     other sections (including DEFAULT):

  max_batch_down
     Size limit for response payloads (server only) [65536 bytes]

  max_queue_time
     Discard downwards packets after this long (server only) [10 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]

  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]

Ordinary settings, used by client and server:

  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
          on server    <vaddr>        <vrelay>       <vnetwork>
          on client    <client>       <vaddr>        <vroutes>
     ["userv root ipif %(local)s,%(peer)s,%(mtu)s,slip %(rnets)s"]

  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.  (checked) [1500 bytes]

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.  [""]
Commit	Line	Data
abb06ac1 IJ	1	-- Fundamental --
	2
	3	Sections
	4
	5	[<servername> - <clientaddr>]
9e445690 IJ	6	[<client>]
9e445690 IJ	7	[<servername>] usually [SERVER]
abb06ac1 IJ	8	[DEFAULT]
abb06ac1 IJ	9
9e445690 IJ	10	Keys are looked up in that order.
	11	<client> is the client's virtual address.
	12	<servername> must not look like an address.
abb06ac1 IJ	13
	14	Exceptional settings:
	15
	16	server
abb06ac1 IJ	17	Specifies <servername>.
	18	Is looked up in [SERVER] and [DEFAULT] only.
	19	If not specified there, it is SERVER.
	20
9e445690 IJ	21	Used by server to select the appropriate parts of the
	22	rest of the configuration. Ignored by the client.
	23
abb06ac1	24	password
9e445690 IJ	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.
abb06ac1	28
9e445690 IJ	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).
abb06ac1	32
9e445690 IJ	33	The server queue packets for, and accept requests from, each
9e445690 IJ	34	putative client for which the config search yields a password.
abb06ac1	35
9e445690 IJ	36	Each client will create a local interface, and try to communicate
	37	with the server, for each possible pair (putative server,
	38	putative client) for which the config search yields a password.
abb06ac1 IJ	39
	40	Capped settings:
	41
	42	Values in <servername> are a cap (maximum) on those from the
	43	other sections (including DEFAULT):
	44
	45	max_batch_down
	46	Size limit for response payloads (server only) [65536 bytes]
	47
	48	max_queue_time
	49	Discard downwards packets after this long (server only) [10 s]
	50
	51	http_timeout
	52	(On server) return with empty payload any http request oustanding
	53	for this long
	54	(On client) give up on any http request outstanding for
	55	for this long plus http_timeout_grace
	56	Client's effective timeout must be at least server's (checked).
	57	[30 s]
	58
	59	target_requests_outstanding
	60	(On server) whenever number of outstanding requests for
	61	a client exceeds this, return oldest with empty payload
	62	(On client) try to keep this many requests outstanding.
	63	Must match between client and server (checked). [3]
	64
	65	Ordinary settings, used by client and server:
	66
	67	ipif
	68	Command to run to create and communicate with local network
	69	interface. Passed to sh -c. Must speak SLIP on stdin/stdout.
	70	The following additional interpolations aare substituted:
	71	%(local)s %(peer)s %(rnet)s
	72	on server <vaddr> <vrelay> <vnetwork>
	73	on client <client> <vaddr> <vroutes>
	74	["userv root ipif %(local)s,%(peer)s,%(mtu)s,slip %(rnets)s"]
	75
	76	addrs
	77	Public IP (v4 or v6) address(es) of the server;
	78	space-separated.
	79	(On server) mandatory; used for bind. No default.
	80	(On client) used only to construct default url.
	81
	82	vnetwork
	83	Private network range (<prefix>/<length>). Must contain all
	84	<client>s. Must contain <vaddr> and <vrelay>, and used
	85	to compute their defaults. [172.24.230.192/28]
	86
	87	vaddr
	88	Address of server's virtual interface.
	89
	90	vrelay
	91	Virtual point-to-point address used for tunnel routing
	92	(does not appear in packets).
	93	[first host entry in <vnetwork> other than <vaddr>,
	94	so 172.24.230.194]
	95
	96	port
	97	Public port number of the server. [80]
	98	(On server) used for bind.
	99	(On client) used only to construct default url.
	100
	101	mtu
	102	Must match exactly. (checked) [1500 bytes]
103
104	Ordinary settings, used by client only:
105
106	http_timeout_grace
107	See http_timeout. [5 s]
108
109	max_requests_outstanding
110	Client will hold off sending more requests than this to
111	server even if it has data to send. [6]
112
113	max_batch_up
114	Size limit for request payloads. [4000 bytes]
115
116	http_retry
117	If a request fails, wait this long before considering it
118	"finished" - to limit rate of futile requests. [5 s]
119
120	url
121	Public url of server.
122	[http://<first-entry-in-addrs>:<port>/]
123
124	vroutes
125	Virtual addresses (in CIDR syntax) to be found at the server
126	end, space-separated. Routes to those will be created on
127	the client. [""]