~evilham/cdist-evilham

59a1842be66a0f16c425ab4fedd76b2f63a7dd42 — Evilham 4 months ago d9d3444
[__knot*] Add documentation for all Knot-related types \o/
M type/__evilham_knot_dns/man.rst => type/__evilham_knot_dns/man.rst +5 -0
@@ 10,6 10,11 @@ DESCRIPTION
-----------
This (singleton) type installs and configures the Knot DNS authoritative server.

The way this type works is that it must run after all pieces of configuration
have been setup in `${ETC_DIR}/knot/conf.d/SECTION/ITEM` as described in
`__knot_dns_section_item(7)`, then it compiles those into
`${ETC_DIR}/knot/knot.conf`.

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

A type/__evilham_knot_dns_add_zone/man.rst => type/__evilham_knot_dns_add_zone/man.rst +151 -0
@@ 0,0 1,151 @@
cdist-type__evilham_knot_dns_add_zone(7)
========================================

NAME
----
cdist-type__evilham_knot_dns_add_zone - Setup and configure a zone for Knot DNS


DESCRIPTION
-----------
This type manages a Zone configuration within Knot DNS and takes care of
bootstrapping it, that is, creating the zone file with a valid and sane SOA as
necessary.

You still have full control and can use this type from other types for special
kinds of zones. Indeed, that's what `__evilham_knot_dns_ptr(7)` does.


BOOLEAN PARAMETERS
------------------
dont-create-zone-file
    Do not actually create the zone file, just configure Knot to handle the
    zone.
    This can be useful, e.g. if the zone will be transferred from another
    server.


OPTIONAL PARAMETERS
-------------------
admin-email
    Used for the SOA.
    Required unless `--dont-create-zone-file` or `--zone-file-contents` is used.
    The provided email will be escaped as necessary and used for the zone's SOA.

template
    The template to use.
    Unless you have created your own with `__evilham_knot_dns_section_item(7)`,
    this should be one of `default`, `secondary` or `signed`.
    If missing, knot will use the `default` template.
    If using the `default` template and this type determines that the server is
    secondary to some other server (see: `--transfer-remote`), the `secondary`
    template will be used instead.
    Has no effect if `--source` is used.

source
    Path to the file containing the zone configuration to be deployed.
    If `-`, the standard input will be used.
    If present, the zone configuration will not be created automatically,
    and the parameters `--template`, `--acl`, `--module`,
    `--notify-remote`, `--transfer-remote` have no effect.

state
    Whether or not Knot will handle the zone.
    Must be one of `present` or `absent`.
    This type currently does not remove the zone file, just the configuration.

zone-file-contents
    The contents of the zone file to be deployed verbatim if it doesn't exist
    yet.


OPTIONAL MULTIPLE PARAMETERS
----------------------------
acl
    The `ID` of an ACL to use for this zone.
    It must have been created with `__evilham_knot_dns_section_item acl/ID`.
    Has no effect if `--source` is used.

name-server
    Used for the SOA. A Name Server responsible for the zone.
    If missing, `${__target_host}` will be listed as the primary (and only) Name
    Server.
    If provided multiple times, the first Name Server will be the primary one.
    Has no effect if `--dont-create-zone-file` or `--zone-file-contents` are
    used.

module
    A Knot DNS module to use in the zone.
    Has no effect if `--source` is used.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#module-section

notify-remote
    The `ID` of a remote that receives a `notify` message when the zone changes.
    It must have been created with `__evilham_knot_dns_section_item remote/ID`
    Has no effect if `--source` is used.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#notify

transfer-remote
    The `ID` of a remote that can send us a `notify` message when the zone
    changes, which will imply a `transfer` operation.
    It must have been created with `__evilham_knot_dns_section_item remote/ID`
    Has no effect if `--source` is used.
    See: https://www.knot-dns.cz/docs/3.0/html/reference.html#master


EXAMPLES
--------

.. code-block:: sh
    # Setup a remote for the secondary DNS server
    __evilham_knot_dns_section_item "remote/ns4.exo.cat" \
       --source "-" <<EOF
    remote:
      - id: ns4.exo.cat
        address: [ 2a0f:de00:ffff::11, 45.150.187.208 ]
    EOF
    export require="${require} __evilham_knot_dns_section_item/remote/ns4.exo.cat"
    # Setup the necessary ACLs for the secondary DNS server
    __evilham_knot_dns_section_item "acl/ns4.exo.cat" \
       --source "-" <<EOF
    acl:
      - id: ns4.exo.cat
        remote: ns4.exo.cat
        action: transfer
    EOF
    export require="${require} __evilham_knot_dns_section_item/acl/ns4.exo.cat"
    # Setup the DNS zone to notify the secondary server
    __evilham_knot_dns_add_zone exo.cat \
        --admin-email info@exo.cat \
        --notify-remote ns4.exo.cat --acl ns4.exo.cat
    export require="${require} __evilham_knot_dns_add_zone/exo.cat"
    # Setup a custom DNS zone
    __evilham_knot_dns_add_zone example.org \
        --dont-create-zone \
        --source '-' <<EOF
    zone:
      - domain: example.org
        template: custom
        serial-policy: increment
    EOF
    # Setup the Knot DNS Authoritative server to listen on any addresses.
    __evilham_knot_dns --listen-address '[ 0.0.0.0@53, ::@53 ]'


SEE ALSO
--------
- `__knot_dns(7)`
- `__knot_dns_section_item(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_ptr/man.rst => type/__evilham_knot_dns_ptr/man.rst +88 -0
@@ 0,0 1,88 @@
cdist-type__evilham_knot_dns_ptr(7)
===================================

NAME
----
cdist-type__evilham_knot_dns_ptr - Setup and configure a PTR zone for Knot DNS


DESCRIPTION
-----------
This type manages a PTR Zone configuration within Knot DNS and takes care of
bootstrapping it, that is, creating all zone files for all subnets with valid
and sane SOAs as necessary.
It sets up both forward (`*.ip6.arpa` and `*.in-addr.arpa` or `IP.ZONE` to IP)
and reverse zones (IP to domain name).

The `${__object_id}` is only used as an internal identifier.

NOTE: This type requires `sipcalc` on the controller machine in order to split
      subnets properly.


BOOLEAN PARAMETERS
------------------
ipv4
    This has an effect on how the subnet is split for the zones.
    If absent, it will be treated as an IPv6 subnet and split on `/32`
    boundaries.
    If present, it will be treated as an IPv4 subnet and split on `/24`
    boundaries.
    See:
    https://www.ripe.net/manage-ips-and-asns/db/support/configuring-reverse-dns


OPTIONAL PARAMETERS
-------------------
state
    Whether or not Knot will handle the zones involved with this subnet.
    Must be one of `present` or `absent`.
    Defaults to `present`.

ptr-zone
    The zone that will be used to generate the PTRs on the fly.

subnet
    The IPv6 or IPv4 subnet for which PTR will be managed.

zone-parameters
    This text will be passed verbatim as parameters to
    `__evilham_knot_dns_add_zone(7)`.
    You should not specify `--state` (it will be passed from this type) or the
    `__object_id` which will also be determined by this type.
    You must specify things like `--admin-email` and the like.
    See `__evilham_knot_dns_add_zone(7)` for more information.


EXAMPLES
--------

.. code-block:: sh
    __evilham_knot_dns_ptr \
        --subnet "2a0f:de00::/29" \
        --ptr-zone "ipv6.at.exonet.cat" \
        --zone-parameters \
          "--admin-email info@exo.cat --notify-remote ns4.exo.cat" \
        "exo_ripe1_ipv6"
    export require="__evilham_knot_dns_ptr/exo_ripe1_ipv6"
    # Setup the Knot DNS Authoritative server to listen on any addresses.
    __evilham_knot_dns --listen-address '[ 0.0.0.0@53, ::@53 ]'


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


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


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

M type/__evilham_knot_dns_ptr/manifest => type/__evilham_knot_dns_ptr/manifest +8 -0
@@ 5,6 5,14 @@ SUBNET="$(cat "${__object}/parameter/subnet")"
ZONE="$(cat "${__object}/parameter/ptr-zone")"
STATE="$(cat "${__object}/parameter/state")"

if ! which -s sipcalc; then
	cat >> /dev/stderr <<EOF
This type requires sipcalc on your device.
It is likely packaged and just one command away.
Try something like apt search sipcalc or pkg search sipcalc.
EOF
	exit 1
fi

if [ -f "${__object}/parameter/ipv4" ]; then
    LEGACY="YES"

A type/__evilham_knot_dns_section_item/man.rst => type/__evilham_knot_dns_section_item/man.rst +98 -0
@@ 0,0 1,98 @@
cdist-type__evilham_knot_dns_section_item(7)
============================================

NAME
----
cdist-type__evilham_knot_dns_section_item - Setup a config section for Knot DNS


DESCRIPTION
-----------
This type manages the different pieces of configuration for the Knot DNS
authoritative server before they are compiled into a single config file
by `__knot_dns(7)`.

The `${__object_id}` MUST be in form `SECTION[/SUBSECTION]/ITEM`.
The `SUBSECTION` is optional and mostly used for the `module` `SECTION`.

With `SECTION` being one of:
- `key`
- `module`
- `acl`
- `remote`
- `template`
- `zone`
- `keystore`


BOOLEAN PARAMETERS
------------------
regen-key
    Only accepted if `SECTION` as described above is `key`.
    If present, a regeneration of the `key` will be forced regardless of
    whether or not it already exists.


OPTIONAL PARAMETERS
-------------------
source
    This parameter is required unless `SECTION` is `key`.
    Path to the file with the piece of configuration.
    If `-`, the type's standard input will be used.
    The contents of the file must be the full valid YAML configuration with
    correct indentation as per the official documentation.
    See the examples.

state
    Whether or not this configuration will be used.
    Must be either `present` or `absent`.
    Defaults to `present`.


EXAMPLES
--------

.. code-block:: sh
    # Setup a remote for the secondary DNS server
    __evilham_knot_dns_section_item "remote/ns4.exo.cat" \
       --source "-" <<EOF
    remote:
      - id: ns4.exo.cat
        address: [ 2a0f:de00:ffff::11, 45.150.187.208 ]
    EOF
    export require="${require} __evilham_knot_dns_section_item/remote/ns4.exo.cat"
    # Setup the necessary ACLs for the secondary DNS server
    __evilham_knot_dns_section_item "acl/ns4.exo.cat" \
       --source "-" <<EOF
    acl:
      - id: ns4.exo.cat
        remote: ns4.exo.cat
        action: transfer
    EOF
    export require="${require} __evilham_knot_dns_section_item/acl/ns4.exo.cat"
    # Setup the DNS zone to notify the secondary server
    __evilham_knot_dns_add_zone exo.cat \
        --admin-email info@exo.cat \
        --notify-remote ns4.exo.cat --acl ns4.exo.cat
    export require="${require} __evilham_knot_dns_add_zone/exo.cat"
    # Setup the Knot DNS Authoritative server to listen on any addresses.
    __evilham_knot_dns --listen-address '[ 0.0.0.0@53, ::@53 ]'


SEE ALSO
--------
- `__knot_dns(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.

M type/__evilham_knot_dns_section_item/manifest => type/__evilham_knot_dns_section_item/manifest +1 -1
@@ 40,7 40,7 @@ case "${SECTION}" in
    ;;
    module|acl|remote|template|zone|keystore)
        if [ -f "${__object}/parameter/regen-key" ]; then
            echo "Parameter --key-regen is not supported for section ${SECTION}." > /dev/stderr
            echo "Parameter --regen-key is not supported for section ${SECTION}." > /dev/stderr
            exit 1
        fi
        if [ ! -f "${__object}/parameter/source" ]; then

M type/__evilham_knotc/gencode-remote => type/__evilham_knotc/gencode-remote +1 -9
@@ 5,15 5,7 @@ if [ "${source}" = "-" ]; then
    source="${__object}/stdin"
fi

if [ -n "${source}" ]; then
    SCRIPT="$(cat "${source}")"
else
    if [ ! -f "${__object}/parameter/pseudo-script" ]; then
        exit 0
    fi
    echo "This is still not supported" > /dev/stderr
    exit 1
fi
SCRIPT="$(cat "${source}")"

cat <<EOF
knotc <<eof

A type/__evilham_knotc/man.rst => type/__evilham_knotc/man.rst +78 -0
@@ 0,0 1,78 @@
cdist-type__evilham_knotc(7)
============================

NAME
----
cdist-type__evilham_knotc - Manage the contents of a Zone fine in Knot DNS


DESCRIPTION
-----------
This is currently a very basic type that does the job, but generates remote code
on every run.

It uses `knotc` on the remote host and a provided script to modify the zone
`${__object_id}`.


REQUIRED PARAMETERS
-------------------
source
    Path to the file containing the knotc script for the zone.
    If `-`, the standard input will be used.
    If you write this script carefully, it can assert idempotency.
    See: examples and `knotc(8)`.


EXAMPLES
--------

.. code-block:: sh
    # Ensure the zone is configured in Knot DNS
    __evilham_knot_dns_add_zone exo.cat \
        --admin-email info@exo.cat \
        --notify-remote ns4.exo.cat --acl ns4.exo.cat
    export require="__evilham_knot_dns_add_zone/exo.cat"
    # Setup the Knot DNS Authoritative server to listen on any addresses.
    __evilham_knot_dns --listen-address '[ 0.0.0.0@53, ::@53 ]'
    # Propagate zone changes to the authoritative server
    require="__evilham_knot_dns" __evilham_knotc "exo.cat" \
       --source "-" <<EOF
    # Wrap in a transaction
    zone-begin  exo.cat
    # Remove the A and AAAA records first, to replace them with something else
    # Internally, knot will only operate this actually results in changes.
    zone-unset  exo.cat @            A
    zone-unset  exo.cat @            AAAA
    # The new A and AAAA records
    zone-set    exo.cat @    172800  A     192.168.0.1
    zone-set    exo.cat @    172800  AAAA  fe80::1
    # Same for www, but in that case remove ALL records.
    # We dont' do that for '@' since that's the root of the zone and we'd
    # have to manage the SOA here manually and that's dealt with by knot.
    zone-unset  exo.cat www
    # Notice the trailing dot for the CNAME, otherwise it means exo.cat.exo.cat.
    zone-set    exo.cat www  172800  CNAME exo.cat.
    # Commit the zone transaction
    zone-commit exo.cat
    EOF


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


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


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

R type/__evilham_knotc/parameter/optional => type/__evilham_knotc/parameter/required +0 -1
@@ 1,2 1,1 @@
source
pseudo-script