README.config

   1 -*- Fundamental -*-
   2
   3 Sections
   4
   5   [<servername> <client>]
   6   [<servername> LIMIT]
   7   [<client>]
   8   [<servername>]      often [SERVER]
   9   [LIMIT]
  10   [COMMON]
  11   [DEFAULT]
  12
  13 Keys are looked up in that order, unless otherwise specified.
  14 <client> is the client's virtual address.
  15 <servername> must be a valid lowercase DNS hostname and not look like
  16 an address, or be COMMON, DEFAULT or SERVER.
  17
  18 Things not in a section are an error.
  19
  20
  21 Both client and server read the files
  22   /etc/hippotat/main.cfg
  23   /etc/hippotat/config.d/*
  24   /etc/hippotat/secrets.d/*
  25 and in each case if it's a directory, all contained files whose
  26 names consists of only ascii alphanumerics plus '-' and '_'.
  27
  28 The ini file format sections from these files are all unioned.
  29 Later files (in the list above, or alphabetically later) can
  30 override settings from earlier ones.
  31
  32 Note that although it is conventional for information for a particular
  33 server or client to be in a file named after that endpoint, there is
  34 no semantic link: all the files are always read and the appropriate
  35 section from each is applied to every endpoint.
  36
  37 (If main.cfg does not exist, master.cfg will be tried for backward
  38 compatibility reasons.)
  39
  40
  41 Exceptional settings:
  42
  43   server
  44      Specifies <servername>.
  45      Is looked up in [SERVER] and [COMMON] only.
  46      If not specified there, it is SERVER.
  47
  48      Used by server to select the appropriate parts of the
  49      rest of the configuration.  Ignored by the client.
  50
  51   secret
  52      Looked up in the usual way, but used by client and server to
  53      determine which possible peerings to try to set up, and which to
  54      ignore.
  55
  56      We define the sets of putative clients and servers, as follows:
  57      all those, for which there is any section (even an empty one)
  58      whose name is based on <client> or <servername> (as applicable).
  59      (LIMIT sections do not count.)
  60
  61      The server queue packets for, and accept requests from, each
  62      putative client for which the config search yields a secret.
  63
  64      Each client will create a local interface, and try to communicate
  65      with the server, for each possible pair (putative server,
  66      putative client) for which the config search yields a secret.
  67
  68   ipif
  69      Command to run to create and communicate with local network
  70      interface.  Passed to sh -c.  Must speak SLIP on stdin/stdout.
  71      The following additional interpolations aare substituted:
  72                        %(local)s  %(peer)s  %(rnet)s    %(ifname)s
  73           on server    <vaddr>    <vrelay>  <vnetwork>  <ifname_server>
  74           on client    <client>   <vaddr>   <vroutes>   <ifname_client>
  75      ["userv root ipif %(local)s,%(peer)s,%(mtu)s,slip %(rnets)s"]
  76
  77      On server: applies to all clients; not looked up in
  78       client-specific sections.
  79      On client: may be different for different servers.
  80
  81 Capped settings:
  82
  83      Values in [<server> LIMIT] and [LIMIT] are a cap (maximum) on
  84      those from the other sections (including COMMON).
  85
  86   max_batch_down
  87      Size limit for response payloads (used by server only)
  88      [65536 bytes; LIMIT: 262144 bytes]
  89
  90   max_queue_time
  91      Discard packets after they have been queued this long waiting
  92      for http.
  93      On server: setting applies to downward packets, and is capped
  94       by LIMIT values.
  95      On client: setting applies to upward packets, and is
  96       not affected by LIMIT values.
  97      [10 s; LIMIT: 121 s]
  98
  99   http_timeout
 100      On server: return with empty payload any http request oustanding
 101       for this long
 102      On client: give up on any http request outstanding for
 103       for this long plus http_timeout_grace
 104      Client's effective timeout must be at least server's (checked).
 105      [30 s; LIMIT: 121]
 106
 107   target_requests_outstanding
 108      On server: whenever number of outstanding requests for
 109       a client exceeds this, return oldest with empty payload
 110      On client: try to keep this many requests outstanding.
 111      Must match between client and server (checked).
 112      [3; LIMIT: 10]
 113
 114 Ordinary settings, used by both, not client-specific:
 115
 116     These are not looked up in the client-specific config sections.
 117
 118   addrs
 119      Public IP (v4 or v6) address(es) of the server;
 120      space-separated.
 121      On server: mandatory; used for bind.  No default.
 122      On client: used only to construct default url.
 123
 124   vnetwork
 125      Private network range (<prefix>/<length>).  Must contain all
 126      <client>s.  Must contain <vaddr> and <vrelay>, and used
 127      to compute their defaults.  [172.24.230.192/28]
 128
 129   vaddr
 130      Address of server's virtual interface.
 131
 132   vrelay
 133      Virtual point-to-point address used for tunnel routing
 134      (does not appear in packets).
 135      [first host entry in <vnetwork> other than <vaddr>,
 136       so 172.24.230.194]
 137
 138   port
 139      Public port number of the server.  [80]
 140      On server: used for bind.
 141      On client: used only to construct default url.
 142
 143   mtu
 144      Must match exactly.  (UNCHECKED) [1500 bytes]
 145
 146   ifname_server
 147      Virtual interface name on the server.  [shippo%d]
 148   ifname_client
 149      Virtual interface name on the client.  [hippo%d]
 150      Any %d is interpolated (by the kernel).
 151
 152 Ordinary settings, used by server only:
 153
 154   max_clock_skew
 155      Permissible clock skew between client and server.
 156      hippotat will not work if clock skew is more than this.
 157      Conversely: when moving client from one public network to
 158      another, the first network can deny service to the client for
 159      this period after the client leaves the first network.
 160      [300s]
 161
 162 Ordinary settings, used by client only:
 163
 164   http_timeout_grace
 165      See http_timeout.  [5 s]
 166
 167   max_requests_outstanding
 168      Client will hold off sending more requests than this to
 169      server even if it has data to send.  [6]
 170
 171   max_batch_up
 172      Size limit for request payloads. [4000 bytes]
 173
 174   http_retry
 175      If a request fails, wait this long before considering it
 176      "finished" - to limit rate of futile requests.  [5 s]
 177
 178   url
 179      Public url of server.
 180      [http://<first-entry-in-addrs>:<port>/]
 181
 182   vroutes
 183      Virtual addresses (in CIDR syntax) to be found at the server
 184      end, space-separated.  Routes to those will be created on
 185      the client.  [""]