~evilham/cdist-evilham

d9d3444c43b275fc1da03ae787c32d7cd4b709db — Evilham 4 months ago efdc29a
[__knot_dns] Add documentation, default statistics-timer to 5m.

This also starts paving the road for a seamless migration to 3.0.
A type/__evilham_knot_dns/man.rst => type/__evilham_knot_dns/man.rst +120 -0
@@ 0,0 1,120 @@
cdist-type__evilham_knot_dns(7)
===============================

NAME
----
cdist-type__evilham_knot_dns - Setup the Knot DNS authoritative server


DESCRIPTION
-----------
This (singleton) type installs and configures the Knot DNS authoritative server.

DNS Zones must be created / setup with `__knot_dns_add_zone(7)` or another type
that uses that (like `__knot_dns_ptr(7)`).
Changing the DNS Zones can be done either manually (not recommended) or with
`__knotc`, which will apply zone changes on the server.

All parameters are optional, but you will really benefit from setting
`--server-listen`.
Make sure you only change it after you have reviewed your setup and are ready
for public traffic.


OPTIONAL PARAMETERS
-------------------
log-target
    Where logging output will go to.
    Must be one of: `stdout`, `stderr`, `syslog`, `FILENAME`.
    Defaults to `syslog`
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#target

log-server
    If present, the minimum severity level for messages related to general
    operation of the server to be logged.
    Must be one of: `critical`, `error`, `warning`, `notice`, `info`, `debug`.
    Not set by default.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#server

log-control
    If present, the minimum severity level for messages related to server
    control to be logged.
    Must be one of: `critical`, `error`, `warning`, `notice`, `info`, `debug`.
    Not set by default.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#control

log-zone
    Minimum severity level for messages related to zones to be logged.
    Must be one of: `critical`, `error`, `warning`, `notice`, `info`, `debug`.
    Not set by default.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#zone

log-any
    Minimum severity level for all message types to be logged.
    Must be one of: `critical`, `error`, `warning`, `notice`, `info`, `debug`.
    Defaults to `info`.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#any

control-listen
    A UNIX socket path where the server listens for control commands.
    This type keeps the OS defaults, likely `${KNOT_RUNDIR}/knot.sock`.
    Where `${KNOT_RUNDIR}` is OS dependent.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#control-listen

control-timeout
    Maximum time (in seconds) the control socket operations can take.
    Set to 0 for infinity. This type respects Knot's defaults.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#control-timeout

server-listen
    One or more IP addresses where the server listens for incoming queries.
    Defaults to `[ 127.0.0.1@53, ::1@53 ]`.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#server-listen

statistics-timer
    A period after which all available statistics metrics will be writetn to
    the file.
    This type sets it up to `300` seconds (5 minutes) by default.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#timer

statistics-file
    A file path of statistics output in the YAML format.
    This type keeps the OS defaults, likely `${KNOT_RUNDIR}/stats.yaml`.
    Where `${KNOT_RUNDIR}` is OS dependent.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#statistics-file

statistics-append
    If enabled, the statistics output will be appended to `--statistics-file`
    instead of file replacement.
    One of: `on` or `off`. Defaults to `off`.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#append


EXAMPLES
--------

.. code-block:: sh

    # Setup the Knot DNS Authoritative server to listen on any addresses.
    __evilham_knot_dns --listen-address '[ 0.0.0.0@53, ::@53 ]'
    # Setup a local-listening DNS server with debug logs
    __evilham_knot_dns --log-any 'debug'


SEE ALSO
--------
- `__knot_dns_section_item(7)`
- `__knot_dns_add_zone(7)`
- `__knot_dns_ptr(7)`
- `__knotc(7)`
- https://www.knot-dns.cz/


AUTHORS
-------
Evilham <contact@evilham.com>


COPYING
-------
Copyright \(C) 2021 Evilham.

A type/__evilham_knot_dns/parameter/default/statistics-timer => type/__evilham_knot_dns/parameter/default/statistics-timer +1 -0
@@ 0,0 1,1 @@
300