docs/config.rst

   1 Configuration scheme
   2 ====================
   3
   4 Configuration is in an INI-like format.  Sections start with lines
   5 ``[...]``.  Every setting must be in a section.  ``#`` and ``;``
   6 comment lines are supported.  Settings ``nmae = value``.  Whitespace
   7 around the name and value is ignored.
   8
   9 The configuration files are resolved to a configuration for each
  10 pairwise link between a client and a server.
  11
  12 Sections
  13 --------
  14
  15 The same config key may appear in multiple sections; for example, in a
  16 section specific to a link, as well as one for all links to a server.
  17
  18 Unless otherwise specified, any particular config setting for a
  19 particular link is the value from the first of the following
  20 applicable sections, or failing that the built-in default:
  21
  22   * ``[<servername> <client>]``
  23   * ``[<client>]``
  24   * ``[<servername>]`` (often ``[SERVER]``)
  25   * ``[COMMON]``
  26
  27 ``<client>`` is the client's virtual address in IPv4 or IPv6 literal
  28 syntax (without any surrounding ``[..]``.
  29
  30 ``<servername>`` must be in the syntrax of a valid lowercase DNS
  31 hostname (and not look like an address), or be literally ``SERVER``.
  32
  33 There are also these special sections:
  34
  35  * ``[<servername> LIMIT]``
  36  * ``[LIMIT]``
  37
  38 Files
  39 -----
  40
  41 Both client and server read the files
  42
  43  * ``/etc/hippotat/main.cfg`` (if it exists)
  44  * ``/etc/hippotat/config.d/*``
  45  * ``/etc/hippotat/secrets.d/*``
  46
  47 Here ``*`` means all contained files whose names consists of only
  48 ascii alphanumerics plus ``-`` and ``_``.
  49
  50 The ``--config`` option can be used to override the directory (usually
  51 ``/etc/hippotat``).  Additonally each ``--extra-config`` option names
  52 an existing file or directory to be processed analagously.
  53
  54 The ini file format sections from these files are all unioned.  Later
  55 files (in the list above, or alphabetically later) can override
  56 settings from earlier ones.
  57
  58 Note that although it is conventional for information for a particular
  59 server or client to be in a file named after that endpoint, there is
  60 no semantic link: all the files are always read and the appropriate
  61 section from each is applied to every link.
  62
  63 (If ``main.cfg`` does not exist, ``master.cfg`` will be tried for
  64 backward compatibility reasons.)