ansible-collection-nameserver/roles/knot/meta/argument_specs.yml

---

argument_specs:

  main:
    version_added: "0.0.1"
    short_description: Install and configure Knot.
    description:
      - Install and configure the L(Knot,https://knot.readthedocs.io/en/latest/index.html) authoritative namesever.
      - Zones are configured through YAML hostvars, rather than simply deploying zone files.
      - "Execution of this role can be limited using the following tags:"
      - "C(role::knot:install): Install knot from distribution packages or upstream repositories."
      - "C(role::knot:config): Render the Knot configuration file."
      - "C(role::knot:zones): Render the zone files for which Knot is authoritative."
      - "C(role::knot): Apply all of the above."
    author: s3lph
    options:
      knot_repository_install:
        description:
          - If true, install knot from the L(upstream repositories,https://deb.knot-dns.cz/knot/).
          - If false, install knot from the default system repositories.
        type: bool
        default: false
      knot_repository_url:
        description: URL of the upstream repository.
        type: str
        default: https://deb.knot-dns.cz/knot/
      knot_repository_distribution:
        description:
          - Suite name (distribution codename) of the upstream repository.
          - Defaults to the value of C(ansible_facts.distribution_release).
        type: str

      knot_server_rundir:
        description: Runtime directory where Knot should e.g. write its control socket to.
        type: str
        default: /run/knot
      knot_server_user:
        description: The user to run knot as.
        type: str
        default: knot
      knot_server_group:
        description: The group to run knot as.
        type: str
        default: knot
      knot_server_identity:
        description:
          - Response to a C(id.server. CH TXT) or C(hostname.bind. CH TXT) query.
          - Set to an empty value to disable.
          - Defaults to C(ansible_facts.hostname).
        type: str
      knot_server_nsid:
        description:
          - The RFC 5001 NSID to include in responses when requested by the resolver.
          - Set to an empty value to disable.
          - Defaults to C(ansible_facts.hostname).
        type: str
      knot_server_version:
        description:
          - Response to a C(version.server. CH TXT) or C(version.bind. CH TXT) query.
          - Set to an empty value to disable.
          - Defaults to C(ansible_facts.hostname).
        type: str
      knot_server_listen:
        description:
          - The list of interfaces to listen on.
          - Host and port are separated with an C(@) sign.
        type: list
        elements: str
        default: ["::@53", "0.0.0.0@53"]
      knot_dns_addresses:
        description:
          - Addresses under which the nameserver is reachable externally.
          - Used for zone replication and notification and for KSK submission checks.
          - Required to be set for all members of a replicated setup.
        type: list
        elements: str
        default: []

      knot_log_targets:
        description:
          - Logging configuration of Knot.
          - Every entry is a dict consisting of at least a C(target) key.
          - >-
            Details on logging configuration can be found in the
            U(upstream documentation,https://knot.readthedocs.io/en/latest/reference.html#log-section)
        type: list
        elements: dict
        default:
          - target: syslog
            level: info

      knot_zone_master_storage_path:
        description: Location from where Knot should read zonefiles for which it is the primary server.
        type: str
        default: /var/lib/knot/master
      knot_zone_replica_storage_path:
        description: Location where Knot should store replicated zonefiles.
        type: str
        default: /var/lib/knot/replica
      knot_zone_semantic_checks:
        description: If set to C(on), Knot will perform additional zonefile checks.
        type: str
        default: 'on'
      knot_zone_dnssec_signing:
        description:
          - If set to C(on), Knot will automatically configure DNSSEC zone signing.
          - If set to C(off), Knot will not sign zones automatically.
        type: str
        default: 'on'

      knot_dnssec_policy_algorithm:
        description: The DNSSEC signing algorithm to use.
        type: str
        default: ed25519
      knot_dnssec_policy_nsec3:
        description:
          - If set to C(on), C(NSEC3) is used instead of C(NSEC).
          - If set to C(off), C(NSEC) is used, which allows full zone enumeration.
        type: str
        default: 'on'
      knot_dnssec_policy_nsec3_salt_length:
        description:
          - Length of the NSEC3 salt field.
          - >-
            Use of a NSEC3 salt is discouraged by
            U(RFC 9276,https://datatracker.ietf.org/doc/html/rfc9276#section-3.1).
        type: int
        default: 0
      knot_dnssec_policy_ksk_size:
        description:
          - Size (in bits) of the KSK.
          - >-
            Permitted values in combination with O(knot_dnssec_policy_algorithm) are documented in the
            U(upstream documentation,https://knot.readthedocs.io/en/latest/reference.html#ksk-size).
        type: int
        default: 256
      knot_dnssec_policy_zsk_size:
        description:
          - Size (in bits) of the KSK.
          - >-
            Permitted values in combination with O(knot_dnssec_policy_algorithm) are documented in the
            U(upstream documentation,https://knot.readthedocs.io/en/latest/reference.html#ksk-size).
        type: int
        default: 256
      knot_dnssec_policy_zsk_lifetime:
        description: Time after which the ZSK should be rotated automatically.
        type: str
        default: 30d
      knot_dnssec_policy_ksk_lifetime:
        description: Time after which the KSK should be rotated automatically.
        type: str
        default: "0"
      knot_dnssec_policy_cds_publish:
        description:
          - If and when to publish C(CDS) and C(CDNSKEY) records.
          - >-
            Supported values and their meaning are documented in the
            U(upstream documentation,https://knot.readthedocs.io/en/latest/reference.html#cds-cdnskey-publish)
          - Do not use the C(double-ds) policy when performing automated KSK rollovers.  It will break the chain of trust.
        type: str
        default: 'always'
      knot_dnssec_policy_propagation_delay:
        description: Additional time to wait before continuing with each step of a key rollover.
        type: str
        default: 1h

      knot_dnssec_submission_check_interval:
        description: How often during a KSK rollover Knot should check submission nameservers for the new DS RRSet.
        type: str
        default: 1h
      knot_dnssec_submission_timeout:
        description:
          - >-
            Time after which a KSK submission to the parent nameserver should automatically be considered successful,
            even if the new DS RRSet has not been found on the submussion nameserver.
        type: str
        default: "0"

      knot_tsig_key:
        description:
          - The TSIG key used by this host for zone transfers or updates.
          - >-
            This shared key will be configured automatically for all zones involving this host in
            O(replicas) or O(updaters).
        type: dict
        default: null
        options:
          name:
            description:
              - The name of the key.
              - Should be a FQDN including the trailing C(.), e.g. C(tsig.hostname.example.org.).
            type: str
            required: true
          algorithm:
            description: The key algorithm, e.g. C(hmac-sha384).
            type: str
            required: true
          secret:
            description:
              - The shared secret of this key.
              - Generate a new key with e.g. C(keymgr -t tsig.foo.example.org. hmac-sha384).
              - This is a secret.  Protect it e.g. with C(ansible-vault)!
            type: str
            required: true

      knot_zone_*:
        description:
          - Zone configurations, one top-level dict per zone.
          - >-
            Recomendation: You can use an arbitrary string after C(knot_zone_), but we recommend to use the zone name
            with C(.) replaced by (_).
          - "Recommendation: Keep one file per zone in C(group_vars/nameservers/zones/zone_<zonename>.yml)."
        type: dict
        required: false
        options:
          name:
            description: Fully qualified name of the zone, including the trailing C(.).
            type: str
            required: true
          soa:
            description: Contains the values required to synthesize the C(SOA) record of the zone apex.
            type: dict
            required: true
            options:
              class:
                description: Class for the records in this zone, usually C(IN).
                type: str
                required: true
              primary:
                description:
                  - FQDN of the autoritative nameserver of the zone.
                  - Also known as C(MNAME).
                type: str
                required: true
              rname:
                description:
                  - Email address of the administrator.
                  - The C(@) must be replaced with a C(.).
                  - C(.) in the localpart must be escaled as C(\.).
                type: str
                required: true
              refresh:
                description:
                  - How often (in seconds) replicas should query the primary for SOA changes.
                type: int
                required: true
              retry:
                description:
                  - How long (in seconds) replicas should wait to retry a failed zone transfer.
                type: int
                required: true
              expire:
                description:
                  - How long after the last update (in seconds) replicas should stop serving a zone.
                type: int
                required: true
              ttl:
                description:
                  - Default TTL (in seconds) for all entries in the zone, and TTL of the SOA record.
                type: int
                required: true
              min_ttl:
                description:
                  - TTL (in seconds) of negative responses.
                type: int
                required: true
          records:
            description:
              - All the records in this zone go here.
            type: list
            elements: dict
            options:
              name:
                description:
                  - Name of the record.
                  - Records without a trailing C(.) are relative to the zone apex.
                  - Use C(@) to refer to the zone apex itself.
                type: str
                required: true
              ttl:
                description:
                  - TTL of this record.
                  - If omitted, defaults to the zone TTL set in the O(soa) section.
                type: int
              class:
                description:
                  - Class of this record.
                  - If omitted, defaults to the class set in the O(soa) section.
                type: str
              type:
                description: Type of the record, e.g. C(AAAA), C(A) or C(CNAME).
                type: str
                required: true
              value:
                description:
                  - Value of the record.
                  - >-
                    Length restrictions for TXT records apply. Subdivide them with single-quoted double quotes
                    e.g. C('"first part of the txt record " "second part of the txt record"')
                type: str
                required: true
          masters:
            description:
              - Hostnames of servers which should act as a primary for this zone.
              - Zonefile will be deployed to hosts whose C(inventory_hostname) is contained in this list.
            type: list
            default: []
          replicas:
            description:
              - Hostnames of servers which should at as a replica for this zone.
              - >-
                Hosts whose C(inventory_hostname) is contained in this list are automatically configured
                to replicate this zone.
          updaters:
            description:
              - Hostnames of servers which should be permitted to submit TSIG zone updates for this zone.
              - >-
                The O(knot_tsig_key)s of hosts whose C(inventory_hostname) is contained in this list are configured as
                permitted TSIG updaters for this zone.
              - The inventory entry for this host can be a dummy.  Its hostvars are only used to fetch the key.
          parents:
            description:
              - Hostnames of servers which should be checked for KSK submissions.
              - >-
                The O(knot_dns_addresses) of hosts whose C(inventory_hostname) is contained in this list are configured
                as KSK submission servers, which are regularly checked to verify the upstream DS RRSet.
              - The inventory entry for this host can be a dummy.  Its hostvars are only used to hold its IPs.
          algorithm:
            description: Zone-specific override for O(knot_dnssec_policy_algorithm).
            type: str
          ksk_size:
            description: Zone-specific override for O(knot_dnssec_policy_ksk_size).
            type: str
          zsk_size:
            description: Zone-specific override for O(knot_dnssec_policy_zsk_size).
            type: str
          ksk_lifetime:
            description: Zone-specific override for O(knot_dnssec_policy_ksk_lifetime).
            type: str
          zsk_lifetime:
            description: Zone-specific override for O(knot_dnssec_policy_zsk_lifetime).
            type: str
          propagation_delay:
            description: Zone-specific override for O(knot_dnssec_policy_propagation_delay).
            type: str
          cds_cdnskey_publish:
            description: Zone-specific override for O(knot_dnssec_policy_cds_publish).
            type: str
          sign_on_secondary:
            description:
              - Whether Knot should sign this zone even if it is not the primary nameserver.
              - Useful if Knot is used with a hidden primary that does not support DNSSEC.
            type: bool
            default: false
          replicate:
            description:
              - >-
                Note: This option is used for more complex replication hierarchies. Chances are you want to use
                O(replicas) instead.
              - Configure further replication to other nameservers even if the server is already a replica itself.
              - This works in addition to the replication configured through O(masters)/O(replicas).
              - Takes a dict where each upstream is mapped to a list of downstreams.
            type: dict
            default: {}