From 5c9b4f3163e05f64b97d04cba2c17ef59d682830 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ayd=C4=B1n=20Mercan?= Date: Fri, 13 Jun 2025 18:30:34 +0300 Subject: [PATCH] Remove build requirements from building arm The meson build switched to generating the file grammars and using meson to build the manpages/ARM. This is because meson doesn't work well when writing files outside the build directory. However, this has been suboptimal when someone only wants to build the documentation (like RTD). Sphinx can now be used outside meson like it was with autoconf. Grammars are now updated by the developer with CI checking if one is needed or not, like clang-format. --- .gitlab-ci.yml | 13 +- doc/arm/_ext/mergegrammar.py | 8 +- doc/arm/_ext/rndcconf.py | 4 +- doc/arm/conf.py | 12 +- doc/ext/configblock.py | 9 +- doc/meson.build | 2 +- doc/misc/forward.zoneopt | 6 + doc/misc/hint.zoneopt | 6 + doc/misc/in-view.zoneopt | 3 + doc/misc/mirror.zoneopt | 47 +++ doc/misc/options | 695 +++++++++++++++++++++++++++++++++++ doc/misc/primary.zoneopt | 68 ++++ doc/misc/redirect.zoneopt | 16 + doc/misc/rndc.grammar | 21 ++ doc/misc/secondary.zoneopt | 70 ++++ doc/misc/static-stub.zoneopt | 14 + doc/misc/stub.zoneopt | 28 ++ meson.build | 2 + 18 files changed, 1001 insertions(+), 23 deletions(-) create mode 100644 doc/misc/forward.zoneopt create mode 100644 doc/misc/hint.zoneopt create mode 100644 doc/misc/in-view.zoneopt create mode 100644 doc/misc/mirror.zoneopt create mode 100644 doc/misc/options create mode 100644 doc/misc/primary.zoneopt create mode 100644 doc/misc/redirect.zoneopt create mode 100644 doc/misc/rndc.grammar create mode 100644 doc/misc/secondary.zoneopt create mode 100644 doc/misc/static-stub.zoneopt create mode 100644 doc/misc/stub.zoneopt diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 84688b08ea..cdae394fb5 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -474,13 +474,16 @@ stages: junit: junit.xml .docs: &docs_job - variables: - DOC_BUILD_TARGET: man stage: docs script: - *configure - - meson compile -C build ${DOC_BUILD_TARGET} + - meson compile -C build arm man - find build/man/ -maxdepth 2 -name "*.[0-9]" -exec mandoc -T lint "{}" \; | ( ! grep -v -e "skipping paragraph macro. sp after" -e "unknown font, skipping request. ft C" -e "input text line longer than 80 bytes" ) + - test -z "${DOC_CHECK_MISC_CHANGE}" || ninja -C build doc-misc + - test -z "${DOC_CHECK_MISC_CHANGE}" || cp build/doc/misc/options build/doc/misc/rndc.grammar build/doc/misc/*.zoneopt doc/misc/ + - test -z "${DOC_CHECK_MISC_CHANGE}" || git diff > doc-misc.patch + - test -z "${DOC_CHECK_MISC_CHANGE}" || if test "$(git status --porcelain --untracked-files=no | wc -l)" -gt "0"; then git status --short; exit 1; fi + .respdiff: &respdiff_job stage: system @@ -662,7 +665,6 @@ changelog: GIT_AUTHOR_EMAIL: $GITLAB_USER_EMAIL GIT_COMMITTER_NAME: $GITLAB_USER_NAME GIT_COMMITTER_EMAIL: $GITLAB_USER_EMAIL - DOC_BUILD_TARGET: arm man before_script: - echo -e "$CI_MERGE_REQUEST_TITLE\n" > commitmsg - sed -i 's/^Draft:\s*//' commitmsg @@ -695,9 +697,12 @@ docs: <<: *default_triggering_rules <<: *base_image <<: *docs_job + variables: + DOC_CHECK_MISC_CHANGE: 1 needs: [] artifacts: untracked: true + when: always docs:tarball: <<: *default_triggering_rules diff --git a/doc/arm/_ext/mergegrammar.py b/doc/arm/_ext/mergegrammar.py index 0628be64a1..42fb502265 100644 --- a/doc/arm/_ext/mergegrammar.py +++ b/doc/arm/_ext/mergegrammar.py @@ -13,17 +13,13 @@ # Depends on CWD - Sphinx plugin -import os import json from pathlib import Path import parsegrammar -buildroot = os.getenv("BIND_BUILD_ROOT") -if buildroot is None: - raise RuntimeError("Running outside meson?") -misc_path = Path(buildroot) / "doc" / "misc" +misc_path = Path(__file__).resolve().parent.parent.parent / "misc" options_path = misc_path / "options" @@ -47,7 +43,7 @@ def read_zone(): def read_main(): - with Path(options_path).open(encoding="ascii") as fp: + with options_path.open(encoding="ascii") as fp: optgrammar = parsegrammar.parse_mapbody(fp) return optgrammar diff --git a/doc/arm/_ext/rndcconf.py b/doc/arm/_ext/rndcconf.py index bc7bd7846b..b09dfcf4be 100644 --- a/doc/arm/_ext/rndcconf.py +++ b/doc/arm/_ext/rndcconf.py @@ -15,7 +15,6 @@ Sphinx domain "rndcconf". See iscconf.py for details. """ -import os from pathlib import Path from docutils import nodes @@ -23,8 +22,7 @@ from docutils import nodes import iscconf import parsegrammar -buildroot = os.getenv("BIND_BUILD_ROOT") -grammar_path = Path(buildroot) / "doc" / "misc" / "rndc.grammar" +grammar_path = Path(__file__).resolve().parent.parent.parent / "misc" / "rndc.grammar" class ToBeReplacedStatementList(nodes.General, nodes.Element): diff --git a/doc/arm/conf.py b/doc/arm/conf.py index dedada00ca..fc122c1bf7 100644 --- a/doc/arm/conf.py +++ b/doc/arm/conf.py @@ -11,8 +11,8 @@ # information regarding copyright ownership. ############################################################################ -import os import sys +import re from pathlib import Path from typing import List, Tuple @@ -151,7 +151,15 @@ project = "BIND 9" copyright = "2023, Internet Systems Consortium" author = "Internet Systems Consortium" -version = os.getenv("BIND_PROJECT_VERSION") +meson_path = Path(__file__).resolve().parent.parent.parent / "meson.build" +with meson_path.open(encoding="utf-8") as meson_build: + pattern = re.compile(r" version: '(?P.*)',") + for line in meson_build: + match = pattern.match(line) + if match: + version = match.group("version") + assert version.startswith("9.") + break release = version diff --git a/doc/ext/configblock.py b/doc/ext/configblock.py index cc34a77ce7..368df5ba18 100644 --- a/doc/ext/configblock.py +++ b/doc/ext/configblock.py @@ -9,7 +9,6 @@ # See the COPYRIGHT file distributed with this work for additional # information regarding copyright ownership. -import os from pathlib import Path from docutils import nodes @@ -19,18 +18,14 @@ from sphinx.util.docutils import SphinxDirective from sphinx.util.typing import ExtensionMetadata -BIND_BUILD_ROOT = os.getenv("BIND_BUILD_ROOT") -if BIND_BUILD_ROOT is None: - raise RuntimeError("running outside meson?") - -miscpath = Path(BIND_BUILD_ROOT) / "doc" / "misc" +misc_path = Path(__file__).resolve().parent.parent.parent / "misc" class ConfigBlockDirective(SphinxDirective): required_arguments = 1 def run(self) -> list[nodes.Node]: - target = miscpath / self.arguments[0] + target = misc_path / self.arguments[0] block = "{}" if not target.exists() else target.read_text() diff --git a/doc/meson.build b/doc/meson.build index 3c30d254a1..2faef3bf03 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -11,6 +11,7 @@ # Manpages can be build without sphinx subdir('man') +subdir('misc') if not sphinx_build.found() subdir_done() @@ -18,4 +19,3 @@ endif subdir('arm') subdir('dnssec-guide') -subdir('misc') diff --git a/doc/misc/forward.zoneopt b/doc/misc/forward.zoneopt new file mode 100644 index 0000000000..af060cf347 --- /dev/null +++ b/doc/misc/forward.zoneopt @@ -0,0 +1,6 @@ +zone [ ] { + type forward; + forward ( first | only ); + forwarders [ port ] [ tls ] { ( | ) [ port ] [ tls ]; ... }; + template ; +}; diff --git a/doc/misc/hint.zoneopt b/doc/misc/hint.zoneopt new file mode 100644 index 0000000000..260db7fb5f --- /dev/null +++ b/doc/misc/hint.zoneopt @@ -0,0 +1,6 @@ +zone [ ] { + type hint; + check-names ( fail | warn | ignore ); + file ; + template ; +}; diff --git a/doc/misc/in-view.zoneopt b/doc/misc/in-view.zoneopt new file mode 100644 index 0000000000..c63c4273e5 --- /dev/null +++ b/doc/misc/in-view.zoneopt @@ -0,0 +1,3 @@ +zone [ ] { + in-view ; +}; diff --git a/doc/misc/mirror.zoneopt b/doc/misc/mirror.zoneopt new file mode 100644 index 0000000000..aa193235a7 --- /dev/null +++ b/doc/misc/mirror.zoneopt @@ -0,0 +1,47 @@ +zone [ ] { + type mirror; + allow-notify { ; ... }; + allow-query { ; ... }; + allow-query-on { ; ... }; + allow-transfer [ port ] [ transport ] { ; ... }; + allow-update-forwarding { ; ... }; + also-notify [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + check-names ( fail | warn | ignore ); + database ; + file ; + ixfr-from-differences ; + journal ; + masterfile-format ( raw | text ); + masterfile-style ( full | relative ); + max-ixfr-ratio ( unlimited | ); + max-journal-size ( default | unlimited | ); + max-records ; + max-records-per-type ; + max-refresh-time ; + max-retry-time ; + max-transfer-idle-in ; + max-transfer-idle-out ; + max-transfer-time-in ; + max-transfer-time-out ; + max-types-per-name ; + min-refresh-time ; + min-retry-time ; + min-transfer-rate-in ; + multi-master ; + notify ( explicit | master-only | primary-only | ); + notify-defer ; + notify-delay ; + notify-source ( | * ); + notify-source-v6 ( | * ); + primaries [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + provide-zoneversion ; + request-expire ; + request-ixfr ; + request-ixfr-max-diffs ; + template ; + transfer-source ( | * ); + transfer-source-v6 ( | * ); + try-tcp-refresh ; + zero-no-soa-ttl ; + zone-statistics ( full | terse | none | ); +}; diff --git a/doc/misc/options b/doc/misc/options new file mode 100644 index 0000000000..3215fc7af7 --- /dev/null +++ b/doc/misc/options @@ -0,0 +1,695 @@ +acl { ; ... }; // may occur multiple times + +controls { + inet ( | | * ) [ port ( | * ) ] allow { ; ... } [ keys { ; ... } ] [ read-only ]; // may occur multiple times + unix perm owner group [ keys { ; ... } ] [ read-only ]; // may occur multiple times +}; // may occur multiple times + +dlz { + database ; + search ; +}; // may occur multiple times + +dnssec-policy { + cdnskey ; + cds-digest-types { ; ... }; + dnskey-ttl ; + inline-signing ; + keys { ( csk | ksk | zsk ) [ key-directory | key-store ] lifetime algorithm [ tag-range ] [ ]; ... }; + max-zone-ttl ; + nsec3param [ iterations ] [ optout ] [ salt-length ]; + offline-ksk ; + parent-ds-ttl ; + parent-propagation-delay ; + publish-safety ; + purge-keys ; + retire-safety ; + signatures-jitter ; + signatures-refresh ; + signatures-validity ; + signatures-validity-dnskey ; + zone-propagation-delay ; +}; // may occur multiple times + +dyndb { }; // may occur multiple times + +http { + endpoints { ; ... }; + listener-clients ; + streams-per-connection ; +}; // optional (only available if configured), may occur multiple times + +key { + algorithm ; + secret ; +}; // may occur multiple times + +key-store { + directory ; + pkcs11-uri ; +}; // may occur multiple times + +logging { + category { ; ... }; // may occur multiple times + channel { + buffered ; + file [ versions ( unlimited | ) ] [ size ] [ suffix ( increment | timestamp ) ]; + null; + print-category ; + print-severity ; + print-time ( iso8601 | iso8601-utc | iso8601-tzinfo | local | ); + severity ; + stderr; + syslog [ ]; + }; // may occur multiple times +}; + +options { + allow-new-zones ; + allow-notify { ; ... }; + allow-proxy { ; ... }; // experimental + allow-proxy-on { ; ... }; // experimental + allow-query { ; ... }; + allow-query-cache { ; ... }; + allow-query-cache-on { ; ... }; + allow-query-on { ; ... }; + allow-recursion { ; ... }; + allow-recursion-on { ; ... }; + allow-transfer [ port ] [ transport ] { ; ... }; + allow-update { ; ... }; + allow-update-forwarding { ; ... }; + also-notify [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + answer-cookie ; + attach-cache ; + auth-nxdomain ; + automatic-interface-scan ; + bindkeys-file ; // test only + blackhole { ; ... }; + catalog-zones { zone [ default-primaries [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... } ] [ zone-directory ] [ in-memory ] [ min-update-interval ]; ... }; + check-dup-records ( fail | warn | ignore ); + check-integrity ; + check-mx ( fail | warn | ignore ); + check-mx-cname ( fail | warn | ignore ); + check-names ( primary | master | secondary | slave | response ) ( fail | warn | ignore ); // may occur multiple times + check-sibling ; + check-spf ( warn | ignore ); + check-srv-cname ( fail | warn | ignore ); + check-svcb ; + check-wildcard ; + clients-per-query ; + cookie-algorithm ( siphash24 ); + cookie-secret ; // may occur multiple times + deny-answer-addresses { ; ... } [ except-from { ; ... } ]; + deny-answer-aliases { ; ... } [ except-from { ; ... } ]; + directory ; + disable-algorithms { ; ... }; // may occur multiple times + disable-ds-digests { ; ... }; // may occur multiple times + disable-empty-zone ; // may occur multiple times + dns64 { + break-dnssec ; + clients { ; ... }; + exclude { ; ... }; + mapped { ; ... }; + recursive-only ; + suffix ; + }; // may occur multiple times + dns64-contact ; + dns64-server ; + dnskey-sig-validity ; // obsolete + dnsrps-enable ; // obsolete + dnsrps-library ; // obsolete + dnsrps-options { }; // obsolete + dnssec-accept-expired ; + dnssec-dnskey-kskonly ; // obsolete + dnssec-loadkeys-interval ; + dnssec-policy ; + dnssec-secure-to-insecure ; // obsolete + dnssec-update-mode ( maintain | no-resign ); // obsolete + dnssec-validation ( yes | no | auto ); + dnstap { ( all | auth | client | forwarder | resolver | update ) [ ( query | response ) ]; ... }; // optional (only available if configured) + dnstap-identity ( | none | hostname ); // optional (only available if configured) + dnstap-output ( file | unix ) [ size ( unlimited | ) ] [ versions ( unlimited | ) ] [ suffix ( increment | timestamp ) ]; // optional (only available if configured) + dnstap-version ( | none ); // optional (only available if configured) + dual-stack-servers [ port ] { ( [ port ] | [ port ] | [ port ] ); ... }; + dump-file ; + edns-udp-size ; + empty-contact ; + empty-server ; + empty-zones-enable ; + fetch-quota-params ; + fetches-per-server [ ( drop | fail ) ]; + fetches-per-zone [ ( drop | fail ) ]; + flush-zones-on-shutdown ; + forward ( first | only ); + forwarders [ port ] [ tls ] { ( | ) [ port ] [ tls ]; ... }; + fstrm-set-buffer-hint ; // optional (only available if configured) + fstrm-set-flush-timeout ; // optional (only available if configured) + fstrm-set-input-queue-size ; // optional (only available if configured) + fstrm-set-output-notify-threshold ; // optional (only available if configured) + fstrm-set-output-queue-model ( mpsc | spsc ); // optional (only available if configured) + fstrm-set-output-queue-size ; // optional (only available if configured) + fstrm-set-reopen-interval ; // optional (only available if configured) + geoip-directory ( | none ); + hostname ( | none ); + http-listener-clients ; // optional (only available if configured) + http-port ; // optional (only available if configured) + http-streams-per-connection ; // optional (only available if configured) + https-port ; // optional (only available if configured) + interface-interval ; + ipv4only-contact ; + ipv4only-enable ; + ipv4only-server ; + ixfr-from-differences ( primary | master | secondary | slave | ); + keep-response-order { ; ... }; // obsolete + key-directory ; + lame-ttl ; + listen-on [ port ] [ proxy ] [ tls ] [ http ] { ; ... }; // may occur multiple times + listen-on-v6 [ port ] [ proxy ] [ tls ] [ http ] { ; ... }; // may occur multiple times + lmdb-mapsize ; // optional (only available if configured) + managed-keys-directory ; + masterfile-format ( raw | text ); + masterfile-style ( full | relative ); + match-mapped-addresses ; + max-cache-size ( default | unlimited | | ); + max-cache-ttl ; + max-clients-per-query ; + max-ixfr-ratio ( unlimited | ); + max-journal-size ( default | unlimited | ); + max-ncache-ttl ; + max-query-count ; + max-query-restarts ; + max-records ; + max-records-per-type ; + max-recursion-depth ; + max-recursion-queries ; + max-refresh-time ; + max-retry-time ; + max-rsa-exponent-size ; + max-stale-ttl ; + max-transfer-idle-in ; + max-transfer-idle-out ; + max-transfer-time-in ; + max-transfer-time-out ; + max-types-per-name ; + max-udp-size ; + max-validation-failures-per-fetch ; // experimental + max-validations-per-fetch ; // experimental + max-zone-ttl ( unlimited | ); // deprecated + memstatistics ; + memstatistics-file ; + message-compression ; + min-cache-ttl ; + min-ncache-ttl ; + min-refresh-time ; + min-retry-time ; + min-transfer-rate-in ; + minimal-any ; + minimal-responses ( no-auth | no-auth-recursive | ); + multi-master ; + new-zones-directory ; + no-case-compress { ; ... }; + nocookie-udp-size ; + notify ( explicit | master-only | primary-only | ); + notify-defer ; + notify-delay ; + notify-rate ; + notify-source ( | * ); + notify-source-v6 ( | * ); + notify-to-soa ; + nsec3-test-zone ; // test only + nta-lifetime ; + nta-recheck ; + nxdomain-redirect ; + parental-source ( | * ); + parental-source-v6 ( | * ); + pid-file ( | none ); + port ; + preferred-glue ; + prefetch [ ]; + provide-ixfr ; + provide-zoneversion ; + qname-minimization ( strict | relaxed | disabled | off ); + query-source [ address ] ( | * | none ); + query-source-v6 [ address ] ( | * | none ); + querylog ; + rate-limit { + all-per-second ; + errors-per-second ; + exempt-clients { ; ... }; + ipv4-prefix-length ; + ipv6-prefix-length ; + log-only ; + max-table-size ; + min-table-size ; + nodata-per-second ; + nxdomains-per-second ; + qps-scale ; + referrals-per-second ; + responses-per-second ; + slip ; + window ; + }; + recursing-file ; + recursion ; + recursive-clients ; + request-expire ; + request-ixfr ; + request-ixfr-max-diffs ; + request-nsid ; + request-zoneversion ; + require-server-cookie ; + resolver-query-timeout ; + resolver-use-dns64 ; + response-padding { ; ... } block-size ; + response-policy { zone [ add-soa ] [ log ] [ max-policy-ttl ] [ min-update-interval ] [ policy ( cname | disabled | drop | given | no-op | nodata | nxdomain | passthru | tcp-only ) ] [ recursive-only ] [ nsip-enable ] [ nsdname-enable ] [ ede ]; ... } [ add-soa ] [ break-dnssec ] [ max-policy-ttl ] [ min-update-interval ] [ min-ns-dots ] [ nsip-wait-recurse ] [ nsdname-wait-recurse ] [ qname-wait-recurse ] [ recursive-only ] [ nsip-enable ] [ nsdname-enable ] [ dnsrps-enable ] [ dnsrps-options { } ]; + responselog ; + reuseport ; + root-key-sentinel ; + rrset-order { [ class ] [ type ] [ name ] ; ... }; + secroots-file ; + send-cookie ; + send-report-channel ; + serial-query-rate ; + serial-update-method ( date | increment | unixtime ); + server-id ( | none | hostname ); + servfail-ttl ; + session-keyalg ; + session-keyfile ( | none ); + session-keyname ; + sig-signing-nodes ; + sig-signing-signatures ; + sig-signing-type ; + sig-validity-interval [ ]; // obsolete + sig0checks-quota ; // experimental + sig0checks-quota-exempt { ; ... }; // experimental + sig0key-checks-limit ; + sig0message-checks-limit ; + stale-answer-client-timeout ( disabled | off | ); + stale-answer-enable ; + stale-answer-ttl ; + stale-cache-enable ; + stale-refresh-time ; + startup-notify-rate ; + statistics-file ; + synth-from-dnssec ; + tcp-advertised-timeout ; + tcp-clients ; + tcp-idle-timeout ; + tcp-initial-timeout ; + tcp-keepalive-timeout ; + tcp-listen-queue ; + tcp-primaries-timeout ; + tcp-receive-buffer ; + tcp-send-buffer ; + tkey-domain ; + tkey-gssapi-credential ; + tkey-gssapi-keytab ; + tls-port ; + transfer-format ( many-answers | one-answer ); + transfer-message-size ; + transfer-source ( | * ); + transfer-source-v6 ( | * ); + transfers-in ; + transfers-out ; + transfers-per-ns ; + trust-anchor-telemetry ; + try-tcp-refresh ; + udp-receive-buffer ; + udp-send-buffer ; + update-check-ksk ; // obsolete + update-quota ; + v6-bias ; + validate-except { ; ... }; + version ( | none ); + zero-no-soa-ttl ; + zero-no-soa-ttl-cache ; + zone-statistics ( full | terse | none | ); +}; + +plugin ( query ) [ { } ]; // may occur multiple times + +remote-servers [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; // may occur multiple times + +server { + bogus ; + edns ; + edns-udp-size ; + edns-version ; + keys ; + max-udp-size ; + notify-source ( | * ); + notify-source-v6 ( | * ); + padding ; + provide-ixfr ; + query-source [ address ] ( | * ); + query-source-v6 [ address ] ( | * ); + request-expire ; + request-ixfr ; + request-ixfr-max-diffs ; + request-nsid ; + request-zoneversion ; + require-cookie ; + send-cookie ; + tcp-keepalive ; + tcp-only ; + transfer-format ( many-answers | one-answer ); + transfer-source ( | * ); + transfer-source-v6 ( | * ); + transfers ; +}; // may occur multiple times + +statistics-channels { + inet ( | | * ) [ port ( | * ) ] [ allow { ; ... } ]; // may occur multiple times +}; // optional (only available if configured), may occur multiple times + +template { + allow-notify { ; ... }; + allow-query { ; ... }; + allow-query-on { ; ... }; + allow-transfer [ port ] [ transport ] { ; ... }; + allow-update { ; ... }; + allow-update-forwarding { ; ... }; + also-notify [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + check-dup-records ( fail | warn | ignore ); + check-integrity ; + check-mx ( fail | warn | ignore ); + check-mx-cname ( fail | warn | ignore ); + check-names ( fail | warn | ignore ); + check-sibling ; + check-spf ( warn | ignore ); + check-srv-cname ( fail | warn | ignore ); + check-svcb ; + check-wildcard ; + checkds ( explicit | ); + database ; + dlz ; + dnskey-sig-validity ; // obsolete + dnssec-dnskey-kskonly ; // obsolete + dnssec-loadkeys-interval ; + dnssec-policy ; + dnssec-secure-to-insecure ; // obsolete + dnssec-update-mode ( maintain | no-resign ); // obsolete + file ; + forward ( first | only ); + forwarders [ port ] [ tls ] { ( | ) [ port ] [ tls ]; ... }; + initial-file ; + inline-signing ; + ixfr-from-differences ; + journal ; + key-directory ; + log-report-channel ; + masterfile-format ( raw | text ); + masterfile-style ( full | relative ); + max-ixfr-ratio ( unlimited | ); + max-journal-size ( default | unlimited | ); + max-records ; + max-records-per-type ; + max-refresh-time ; + max-retry-time ; + max-transfer-idle-in ; + max-transfer-idle-out ; + max-transfer-time-in ; + max-transfer-time-out ; + max-types-per-name ; + max-zone-ttl ( unlimited | ); // deprecated + min-refresh-time ; + min-retry-time ; + min-transfer-rate-in ; + multi-master ; + notify ( explicit | master-only | primary-only | ); + notify-defer ; + notify-delay ; + notify-source ( | * ); + notify-source-v6 ( | * ); + notify-to-soa ; + nsec3-test-zone ; // test only + parental-agents [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + parental-source ( | * ); + parental-source-v6 ( | * ); + primaries [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + provide-zoneversion ; + request-expire ; + request-ixfr ; + request-ixfr-max-diffs ; + send-report-channel ; + serial-update-method ( date | increment | unixtime ); + server-addresses { ( | ); ... }; + server-names { ; ... }; + sig-signing-nodes ; + sig-signing-signatures ; + sig-signing-type ; + sig-validity-interval [ ]; // obsolete + transfer-source ( | * ); + transfer-source-v6 ( | * ); + try-tcp-refresh ; + type ( primary | master | secondary | slave | mirror | forward | hint | redirect | static-stub | stub ); + update-check-ksk ; // obsolete + update-policy ( local | { ( deny | grant ) ( 6to4-self | external | krb5-self | krb5-selfsub | krb5-subdomain | krb5-subdomain-self-rhs | ms-self | ms-selfsub | ms-subdomain | ms-subdomain-self-rhs | name | self | selfsub | selfwild | subdomain | tcp-self | wildcard | zonesub ) [ ] ; ... } ); + zero-no-soa-ttl ; + zone-statistics ( full | terse | none | ); +}; // may occur multiple times + +tls { + ca-file ; + cert-file ; + cipher-suites ; + ciphers ; + dhparam-file ; + key-file ; + prefer-server-ciphers ; + protocols { ; ... }; + remote-hostname ; + session-tickets ; +}; // may occur multiple times + +trust-anchors { ( static-key | initial-key | static-ds | initial-ds ) ; ... }; // may occur multiple times + +view [ ] { + allow-new-zones ; + allow-notify { ; ... }; + allow-proxy { ; ... }; // experimental + allow-proxy-on { ; ... }; // experimental + allow-query { ; ... }; + allow-query-cache { ; ... }; + allow-query-cache-on { ; ... }; + allow-query-on { ; ... }; + allow-recursion { ; ... }; + allow-recursion-on { ; ... }; + allow-transfer [ port ] [ transport ] { ; ... }; + allow-update { ; ... }; + allow-update-forwarding { ; ... }; + also-notify [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + attach-cache ; + auth-nxdomain ; + catalog-zones { zone [ default-primaries [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... } ] [ zone-directory ] [ in-memory ] [ min-update-interval ]; ... }; + check-dup-records ( fail | warn | ignore ); + check-integrity ; + check-mx ( fail | warn | ignore ); + check-mx-cname ( fail | warn | ignore ); + check-names ( primary | master | secondary | slave | response ) ( fail | warn | ignore ); // may occur multiple times + check-sibling ; + check-spf ( warn | ignore ); + check-srv-cname ( fail | warn | ignore ); + check-svcb ; + check-wildcard ; + clients-per-query ; + deny-answer-addresses { ; ... } [ except-from { ; ... } ]; + deny-answer-aliases { ; ... } [ except-from { ; ... } ]; + disable-algorithms { ; ... }; // may occur multiple times + disable-ds-digests { ; ... }; // may occur multiple times + disable-empty-zone ; // may occur multiple times + dlz { + database ; + search ; + }; // may occur multiple times + dns64 { + break-dnssec ; + clients { ; ... }; + exclude { ; ... }; + mapped { ; ... }; + recursive-only ; + suffix ; + }; // may occur multiple times + dns64-contact ; + dns64-server ; + dnskey-sig-validity ; // obsolete + dnsrps-enable ; // obsolete + dnsrps-options { }; // obsolete + dnssec-accept-expired ; + dnssec-dnskey-kskonly ; // obsolete + dnssec-loadkeys-interval ; + dnssec-policy ; + dnssec-secure-to-insecure ; // obsolete + dnssec-update-mode ( maintain | no-resign ); // obsolete + dnssec-validation ( yes | no | auto ); + dnstap { ( all | auth | client | forwarder | resolver | update ) [ ( query | response ) ]; ... }; // optional (only available if configured) + dual-stack-servers [ port ] { ( [ port ] | [ port ] | [ port ] ); ... }; + dyndb { }; // may occur multiple times + edns-udp-size ; + empty-contact ; + empty-server ; + empty-zones-enable ; + fetch-quota-params ; + fetches-per-server [ ( drop | fail ) ]; + fetches-per-zone [ ( drop | fail ) ]; + forward ( first | only ); + forwarders [ port ] [ tls ] { ( | ) [ port ] [ tls ]; ... }; + ipv4only-contact ; + ipv4only-enable ; + ipv4only-server ; + ixfr-from-differences ( primary | master | secondary | slave | ); + key { + algorithm ; + secret ; + }; // may occur multiple times + key-directory ; + lame-ttl ; + lmdb-mapsize ; // optional (only available if configured) + masterfile-format ( raw | text ); + masterfile-style ( full | relative ); + match-clients { ; ... }; + match-destinations { ; ... }; + match-recursive-only ; + max-cache-size ( default | unlimited | | ); + max-cache-ttl ; + max-clients-per-query ; + max-ixfr-ratio ( unlimited | ); + max-journal-size ( default | unlimited | ); + max-ncache-ttl ; + max-query-count ; + max-query-restarts ; + max-records ; + max-records-per-type ; + max-recursion-depth ; + max-recursion-queries ; + max-refresh-time ; + max-retry-time ; + max-stale-ttl ; + max-transfer-idle-in ; + max-transfer-idle-out ; + max-transfer-time-in ; + max-transfer-time-out ; + max-types-per-name ; + max-udp-size ; + max-validation-failures-per-fetch ; // experimental + max-validations-per-fetch ; // experimental + max-zone-ttl ( unlimited | ); // deprecated + message-compression ; + min-cache-ttl ; + min-ncache-ttl ; + min-refresh-time ; + min-retry-time ; + min-transfer-rate-in ; + minimal-any ; + minimal-responses ( no-auth | no-auth-recursive | ); + multi-master ; + new-zones-directory ; + no-case-compress { ; ... }; + nocookie-udp-size ; + notify ( explicit | master-only | primary-only | ); + notify-defer ; + notify-delay ; + notify-source ( | * ); + notify-source-v6 ( | * ); + notify-to-soa ; + nsec3-test-zone ; // test only + nta-lifetime ; + nta-recheck ; + nxdomain-redirect ; + parental-source ( | * ); + parental-source-v6 ( | * ); + plugin ( query ) [ { } ]; // may occur multiple times + preferred-glue ; + prefetch [ ]; + provide-ixfr ; + provide-zoneversion ; + qname-minimization ( strict | relaxed | disabled | off ); + query-source [ address ] ( | * | none ); + query-source-v6 [ address ] ( | * | none ); + rate-limit { + all-per-second ; + errors-per-second ; + exempt-clients { ; ... }; + ipv4-prefix-length ; + ipv6-prefix-length ; + log-only ; + max-table-size ; + min-table-size ; + nodata-per-second ; + nxdomains-per-second ; + qps-scale ; + referrals-per-second ; + responses-per-second ; + slip ; + window ; + }; + recursion ; + request-expire ; + request-ixfr ; + request-ixfr-max-diffs ; + request-nsid ; + request-zoneversion ; + require-server-cookie ; + resolver-query-timeout ; + resolver-use-dns64 ; + response-padding { ; ... } block-size ; + response-policy { zone [ add-soa ] [ log ] [ max-policy-ttl ] [ min-update-interval ] [ policy ( cname | disabled | drop | given | no-op | nodata | nxdomain | passthru | tcp-only ) ] [ recursive-only ] [ nsip-enable ] [ nsdname-enable ] [ ede ]; ... } [ add-soa ] [ break-dnssec ] [ max-policy-ttl ] [ min-update-interval ] [ min-ns-dots ] [ nsip-wait-recurse ] [ nsdname-wait-recurse ] [ qname-wait-recurse ] [ recursive-only ] [ nsip-enable ] [ nsdname-enable ] [ dnsrps-enable ] [ dnsrps-options { } ]; + root-key-sentinel ; + rrset-order { [ class ] [ type ] [ name ] ; ... }; + send-cookie ; + send-report-channel ; + serial-update-method ( date | increment | unixtime ); + server { + bogus ; + edns ; + edns-udp-size ; + edns-version ; + keys ; + max-udp-size ; + notify-source ( | * ); + notify-source-v6 ( | * ); + padding ; + provide-ixfr ; + query-source [ address ] ( | * ); + query-source-v6 [ address ] ( | * ); + request-expire ; + request-ixfr ; + request-ixfr-max-diffs ; + request-nsid ; + request-zoneversion ; + require-cookie ; + send-cookie ; + tcp-keepalive ; + tcp-only ; + transfer-format ( many-answers | one-answer ); + transfer-source ( | * ); + transfer-source-v6 ( | * ); + transfers ; + }; // may occur multiple times + servfail-ttl ; + sig-signing-nodes ; + sig-signing-signatures ; + sig-signing-type ; + sig-validity-interval [ ]; // obsolete + sig0key-checks-limit ; + sig0message-checks-limit ; + stale-answer-client-timeout ( disabled | off | ); + stale-answer-enable ; + stale-answer-ttl ; + stale-cache-enable ; + stale-refresh-time ; + synth-from-dnssec ; + transfer-format ( many-answers | one-answer ); + transfer-source ( | * ); + transfer-source-v6 ( | * ); + trust-anchor-telemetry ; + trust-anchors { ( static-key | initial-key | static-ds | initial-ds ) ; ... }; // may occur multiple times + try-tcp-refresh ; + update-check-ksk ; // obsolete + v6-bias ; + validate-except { ; ... }; + zero-no-soa-ttl ; + zero-no-soa-ttl-cache ; + zone-statistics ( full | terse | none | ); +}; // may occur multiple times + diff --git a/doc/misc/primary.zoneopt b/doc/misc/primary.zoneopt new file mode 100644 index 0000000000..dd1b94756b --- /dev/null +++ b/doc/misc/primary.zoneopt @@ -0,0 +1,68 @@ +zone [ ] { + type primary; + allow-query { ; ... }; + allow-query-on { ; ... }; + allow-transfer [ port ] [ transport ] { ; ... }; + allow-update { ; ... }; + also-notify [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + check-dup-records ( fail | warn | ignore ); + check-integrity ; + check-mx ( fail | warn | ignore ); + check-mx-cname ( fail | warn | ignore ); + check-names ( fail | warn | ignore ); + check-sibling ; + check-spf ( warn | ignore ); + check-srv-cname ( fail | warn | ignore ); + check-svcb ; + check-wildcard ; + checkds ( explicit | ); + database ; + dlz ; + dnskey-sig-validity ; // obsolete + dnssec-dnskey-kskonly ; // obsolete + dnssec-loadkeys-interval ; + dnssec-policy ; + dnssec-secure-to-insecure ; // obsolete + dnssec-update-mode ( maintain | no-resign ); // obsolete + file ; + forward ( first | only ); + forwarders [ port ] [ tls ] { ( | ) [ port ] [ tls ]; ... }; + initial-file ; + inline-signing ; + ixfr-from-differences ; + journal ; + key-directory ; + log-report-channel ; + masterfile-format ( raw | text ); + masterfile-style ( full | relative ); + max-ixfr-ratio ( unlimited | ); + max-journal-size ( default | unlimited | ); + max-records ; + max-records-per-type ; + max-transfer-idle-out ; + max-transfer-time-out ; + max-types-per-name ; + max-zone-ttl ( unlimited | ); // deprecated + notify ( explicit | master-only | primary-only | ); + notify-defer ; + notify-delay ; + notify-source ( | * ); + notify-source-v6 ( | * ); + notify-to-soa ; + nsec3-test-zone ; // test only + parental-agents [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + parental-source ( | * ); + parental-source-v6 ( | * ); + provide-zoneversion ; + send-report-channel ; + serial-update-method ( date | increment | unixtime ); + sig-signing-nodes ; + sig-signing-signatures ; + sig-signing-type ; + sig-validity-interval [ ]; // obsolete + template ; + update-check-ksk ; // obsolete + update-policy ( local | { ( deny | grant ) ( 6to4-self | external | krb5-self | krb5-selfsub | krb5-subdomain | krb5-subdomain-self-rhs | ms-self | ms-selfsub | ms-subdomain | ms-subdomain-self-rhs | name | self | selfsub | selfwild | subdomain | tcp-self | wildcard | zonesub ) [ ] ; ... } ); + zero-no-soa-ttl ; + zone-statistics ( full | terse | none | ); +}; diff --git a/doc/misc/redirect.zoneopt b/doc/misc/redirect.zoneopt new file mode 100644 index 0000000000..e338b6e231 --- /dev/null +++ b/doc/misc/redirect.zoneopt @@ -0,0 +1,16 @@ +zone [ ] { + type redirect; + allow-query { ; ... }; + allow-query-on { ; ... }; + dlz ; + file ; + masterfile-format ( raw | text ); + masterfile-style ( full | relative ); + max-records ; + max-records-per-type ; + max-types-per-name ; + max-zone-ttl ( unlimited | ); // deprecated + primaries [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + template ; + zone-statistics ( full | terse | none | ); +}; diff --git a/doc/misc/rndc.grammar b/doc/misc/rndc.grammar new file mode 100644 index 0000000000..9d5604f98a --- /dev/null +++ b/doc/misc/rndc.grammar @@ -0,0 +1,21 @@ +key { + algorithm ; + secret ; +}; // may occur multiple times + +options { + default-key ; + default-port ; + default-server ; + default-source-address ( | * ); + default-source-address-v6 ( | * ); +}; + +server { + addresses { ( [ port ] | [ port ] | [ port ] ); ... }; + key ; + port ; + source-address ( | * ); + source-address-v6 ( | * ); +}; // may occur multiple times + diff --git a/doc/misc/secondary.zoneopt b/doc/misc/secondary.zoneopt new file mode 100644 index 0000000000..7529112a33 --- /dev/null +++ b/doc/misc/secondary.zoneopt @@ -0,0 +1,70 @@ +zone [ ] { + type secondary; + allow-notify { ; ... }; + allow-query { ; ... }; + allow-query-on { ; ... }; + allow-transfer [ port ] [ transport ] { ; ... }; + allow-update-forwarding { ; ... }; + also-notify [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + check-names ( fail | warn | ignore ); + checkds ( explicit | ); + database ; + dlz ; + dnskey-sig-validity ; // obsolete + dnssec-dnskey-kskonly ; // obsolete + dnssec-loadkeys-interval ; + dnssec-policy ; + dnssec-update-mode ( maintain | no-resign ); // obsolete + file ; + forward ( first | only ); + forwarders [ port ] [ tls ] { ( | ) [ port ] [ tls ]; ... }; + inline-signing ; + ixfr-from-differences ; + journal ; + key-directory ; + log-report-channel ; + masterfile-format ( raw | text ); + masterfile-style ( full | relative ); + max-ixfr-ratio ( unlimited | ); + max-journal-size ( default | unlimited | ); + max-records ; + max-records-per-type ; + max-refresh-time ; + max-retry-time ; + max-transfer-idle-in ; + max-transfer-idle-out ; + max-transfer-time-in ; + max-transfer-time-out ; + max-types-per-name ; + min-refresh-time ; + min-retry-time ; + min-transfer-rate-in ; + multi-master ; + notify ( explicit | master-only | primary-only | ); + notify-defer ; + notify-delay ; + notify-source ( | * ); + notify-source-v6 ( | * ); + notify-to-soa ; + nsec3-test-zone ; // test only + parental-agents [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + parental-source ( | * ); + parental-source-v6 ( | * ); + primaries [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + provide-zoneversion ; + request-expire ; + request-ixfr ; + request-ixfr-max-diffs ; + send-report-channel ; + sig-signing-nodes ; + sig-signing-signatures ; + sig-signing-type ; + sig-validity-interval [ ]; // obsolete + template ; + transfer-source ( | * ); + transfer-source-v6 ( | * ); + try-tcp-refresh ; + update-check-ksk ; // obsolete + zero-no-soa-ttl ; + zone-statistics ( full | terse | none | ); +}; diff --git a/doc/misc/static-stub.zoneopt b/doc/misc/static-stub.zoneopt new file mode 100644 index 0000000000..14928922dd --- /dev/null +++ b/doc/misc/static-stub.zoneopt @@ -0,0 +1,14 @@ +zone [ ] { + type static-stub; + allow-query { ; ... }; + allow-query-on { ; ... }; + forward ( first | only ); + forwarders [ port ] [ tls ] { ( | ) [ port ] [ tls ]; ... }; + max-records ; + max-records-per-type ; + max-types-per-name ; + server-addresses { ( | ); ... }; + server-names { ; ... }; + template ; + zone-statistics ( full | terse | none | ); +}; diff --git a/doc/misc/stub.zoneopt b/doc/misc/stub.zoneopt new file mode 100644 index 0000000000..4d25095484 --- /dev/null +++ b/doc/misc/stub.zoneopt @@ -0,0 +1,28 @@ +zone [ ] { + type stub; + allow-query { ; ... }; + allow-query-on { ; ... }; + check-names ( fail | warn | ignore ); + database ; + file ; + forward ( first | only ); + forwarders [ port ] [ tls ] { ( | ) [ port ] [ tls ]; ... }; + masterfile-format ( raw | text ); + masterfile-style ( full | relative ); + max-records ; + max-records-per-type ; + max-refresh-time ; + max-retry-time ; + max-transfer-idle-in ; + max-transfer-time-in ; + max-types-per-name ; + min-refresh-time ; + min-retry-time ; + min-transfer-rate-in ; + multi-master ; + primaries [ port ] [ source ( | * ) ] [ source-v6 ( | * ) ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + template ; + transfer-source ( | * ); + transfer-source-v6 ( | * ); + zone-statistics ( full | terse | none | ); +}; diff --git a/meson.build b/meson.build index 154820dfdb..8d6b9c77a9 100644 --- a/meson.build +++ b/meson.build @@ -1619,6 +1619,8 @@ alias_target('system-test-dependencies', system_test_targets) ### Documentation +alias_target('doc-misc', doc_misc_targets) + if doc_opt.allowed() man_srcconf = man_srcset.apply(config, strict: false) foreach man : man_srcconf.sources()