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()