From 0335817ced71e8355806ea0445aa3b105a22364c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 12 Sep 2024 06:45:07 +0200 Subject: Adding upstream version 3.4.0. Signed-off-by: Daniel Baumann --- doc/Makefile.am | 109 +- doc/Makefile.in | 275 ++--- doc/appendices.rst | 21 - doc/conf.py | 5 +- doc/configuration.rst | 75 +- doc/installation.rst | 5 +- doc/introduction.rst | 4 +- doc/man/kcatalogprint.8 | 81 ++ doc/man/kcatalogprint.8in | 80 -- doc/man/kdig.1 | 465 +++++++ doc/man/kdig.1in | 464 ------- doc/man/keymgr.8 | 390 ++++++ doc/man/keymgr.8in | 389 ------ doc/man/khost.1 | 157 +++ doc/man/khost.1in | 156 --- doc/man/kjournalprint.8 | 118 ++ doc/man/kjournalprint.8in | 120 -- doc/man/knot.conf.5 | 2957 +++++++++++++++++++++++++++++++++++++++++++++ doc/man/knot.conf.5in | 2887 ------------------------------------------- doc/man/knotc.8 | 447 +++++++ doc/man/knotc.8in | 440 ------- doc/man/knotd.8 | 94 ++ doc/man/knotd.8in | 93 -- doc/man/knsec3hash.1 | 108 ++ doc/man/knsec3hash.1in | 96 -- doc/man/knsupdate.1 | 252 ++++ doc/man/knsupdate.1in | 218 ---- doc/man/kxdpgun.8 | 299 +++++ doc/man/kxdpgun.8in | 278 ----- doc/man/kzonecheck.1 | 95 ++ doc/man/kzonecheck.1in | 94 -- doc/man/kzonesign.1 | 96 ++ doc/man/kzonesign.1in | 95 -- doc/man_kcatalogprint.rst | 3 +- doc/man_kdig.rst | 9 +- doc/man_keymgr.rst | 3 +- doc/man_khost.rst | 3 +- doc/man_kjournalprint.rst | 6 +- doc/man_knotc.rst | 15 +- doc/man_knotd.rst | 3 +- doc/man_knsec3hash.rst | 12 + doc/man_knsupdate.rst | 74 +- doc/man_kxdpgun.rst | 25 +- doc/man_kzonecheck.rst | 3 +- doc/man_kzonesign.rst | 3 +- doc/migration.rst | 90 +- doc/operation.rst | 34 +- doc/reference.rst | 114 +- doc/requirements.rst | 8 +- 49 files changed, 6072 insertions(+), 5796 deletions(-) create mode 100644 doc/man/kcatalogprint.8 delete mode 100644 doc/man/kcatalogprint.8in create mode 100644 doc/man/kdig.1 delete mode 100644 doc/man/kdig.1in create mode 100644 doc/man/keymgr.8 delete mode 100644 doc/man/keymgr.8in create mode 100644 doc/man/khost.1 delete mode 100644 doc/man/khost.1in create mode 100644 doc/man/kjournalprint.8 delete mode 100644 doc/man/kjournalprint.8in create mode 100644 doc/man/knot.conf.5 delete mode 100644 doc/man/knot.conf.5in create mode 100644 doc/man/knotc.8 delete mode 100644 doc/man/knotc.8in create mode 100644 doc/man/knotd.8 delete mode 100644 doc/man/knotd.8in create mode 100644 doc/man/knsec3hash.1 delete mode 100644 doc/man/knsec3hash.1in create mode 100644 doc/man/knsupdate.1 delete mode 100644 doc/man/knsupdate.1in create mode 100644 doc/man/kxdpgun.8 delete mode 100644 doc/man/kxdpgun.8in create mode 100644 doc/man/kzonecheck.1 delete mode 100644 doc/man/kzonecheck.1in create mode 100644 doc/man/kzonesign.1 delete mode 100644 doc/man/kzonesign.1in (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index b26e298..71d561c 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,18 +1,3 @@ -MANPAGES_IN = \ - man/knot.conf.5in \ - man/knotc.8in \ - man/knotd.8in \ - man/kcatalogprint.8in \ - man/keymgr.8in \ - man/kjournalprint.8in \ - man/kdig.1in \ - man/khost.1in \ - man/knsupdate.1in \ - man/knsec3hash.1in \ - man/kzonecheck.1in \ - man/kzonesign.1in \ - man/kxdpgun.8in - MANPAGES_RST = \ reference.rst \ man_knotc.rst \ @@ -44,7 +29,6 @@ EXTRA_DIST = \ troubleshooting.rst \ utilities.rst \ \ - $(MANPAGES_IN) \ $(MANPAGES_RST) \ \ logo.pdf \ @@ -66,27 +50,26 @@ SPHINXBUILDDIR = $(builddir)/_build _SPHINXOPTS = -c $(srcdir) \ -a \ - $(SPHINX_V) - -ALLSPHINXOPTS = $(_SPHINXOPTS) \ + $(SPHINX_V) \ -D version="$(VERSION)" \ -D today="$(RELEASE_DATE)" \ - -D release="$(VERSION)" \ + -D release="$(VERSION)" + +ALLSPHINXOPTS = $(_SPHINXOPTS) \ $(SPHINXOPTS) \ $(srcdir) man_SPHINXOPTS = $(_SPHINXOPTS) \ - -D version="@""VERSION@" \ - -D today="@""RELEASE_DATE@" \ - -D release="@""VERSION@" \ -D extensions="ignore_panels" \ $(SPHINXOPTS) \ $(srcdir) -.PHONY: html-local singlehtml pdf-local info-local epub man install-html-local install-singlehtml install-pdf-local install-info-local install-epub +.PHONY: html-local singlehtml pdf-local epub man install-html-local install-singlehtml install-pdf-local install-epub man_MANS = +if HAVE_DOCS + if HAVE_DAEMON man_MANS += \ man/knot.conf.5 \ @@ -115,43 +98,8 @@ man_MANS += man/kxdpgun.8 endif # ENABLE_XDP endif # HAVE_UTILS -man/knot.conf.5: man/knot.conf.5in -man/knotc.8: man/knotc.8in -man/knotd.8: man/knotd.8in -man/kcatalogprint.8: man/kcatalogprint.8in -man/keymgr.8: man/keymgr.8in -man/kjournalprint.8: man/kjournalprint.8in -man/kdig.1: man/kdig.1in -man/khost.1: man/khost.1in -man/knsupdate.1: man/knsupdate.1in -man/knsec3hash.1: man/knsec3hash.1in -man/kzonecheck.1: man/kzonecheck.1in -man/kzonesign.1: man/kzonesign.1in -man/kxdpgun.8: man/kxdpgun.8in - -man_SUBST = $(AM_V_GEN)mkdir -p man; \ - sed -e 's,[@]VERSION@,$(VERSION),' \ - -e 's,[@]RELEASE_DATE@,$(RELEASE_DATE),' \ - -e 's,[@]config_dir@,$(config_dir),' \ - -e 's,[@]storage_dir@,$(storage_dir),' \ - -e 's,[@]run_dir@,$(run_dir),' \ - -e 's,[@]conf_mapsize@,$(conf_mapsize),' \ - $< > $@ - -.1in.1: - $(man_SUBST) - -.5in.5: - $(man_SUBST) - -.8in.8: - $(man_SUBST) - -if HAVE_DOCS - -if HAVE_SPHINXBUILD html-local: - $(AM_V_SPHINX)$(SPHINXBUILD) -b html -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html + $(AM_V_SPHINX)$(SPHINXBUILD) -b html -d $(SPHINXBUILDDIR)/doctrees/html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html @echo "The HTML documentation has been built in $(SPHINXBUILDDIR)/html/" install-html-local: @@ -161,7 +109,7 @@ install-html-local: $(INSTALL_DATA) $(SPHINXBUILDDIR)/html/_static/* $(DESTDIR)/$(docdir)/_static/ singlehtml: - $(AM_V_SPHINX)$(SPHINXBUILD) -b singlehtml -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/singlehtml + $(AM_V_SPHINX)$(SPHINXBUILD) -b singlehtml -d $(SPHINXBUILDDIR)/doctrees/singlehtml $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/singlehtml @echo "The single HTML documentation has been built in $(SPHINXBUILDDIR)/singlehtml/" install-singlehtml: singlehtml @@ -170,7 +118,7 @@ install-singlehtml: singlehtml $(INSTALL_DATA) $(SPHINXBUILDDIR)/singlehtml/_static/* $(DESTDIR)/$(docdir)/_static/ epub: - $(AM_V_SPHINX)$(SPHINXBUILD) -b epub -A today=$(RELEASE_DATE) -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/epub + $(AM_V_SPHINX)$(SPHINXBUILD) -b epub -A today=$(RELEASE_DATE) -d $(SPHINXBUILDDIR)/doctrees/epub $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/epub @echo "The EPUB documentation has been built in $(SPHINXBUILDDIR)/epub/" install-epub: @@ -179,7 +127,7 @@ install-epub: if HAVE_PDFLATEX pdf-local: - $(AM_V_SPHINX)$(SPHINXBUILD) -b latex -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/latex + $(AM_V_SPHINX)$(SPHINXBUILD) -b latex -d $(SPHINXBUILDDIR)/doctrees/latex $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/latex $(MAKE) -C $(SPHINXBUILDDIR)/latex all-pdf @echo "The PDF documentation has been built in $(SPHINXBUILDDIR)/latex/" @@ -192,37 +140,26 @@ pdf-local install-pdf-local: @echo "Install 'pdflatex' and re-run configure to be able to generate PDF documentation!" endif # HAVE_PDFLATEX -if HAVE_MAKEINFO -info-local: - $(AM_V_SPHINX)$(SPHINXBUILD) -b texinfo -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/texinfo - $(MAKE) -C $(SPHINXBUILDDIR)/texinfo info - @echo "The Info pages have been built in $(SPHINXBUILDDIR)/texinfo/" - -install-info-local: - $(INSTALL) -d $(DESTDIR)/$(infodir) - $(INSTALL_DATA) $(SPHINXBUILDDIR)/texinfo/knot.info $(DESTDIR)/$(infodir)/ - -else -info-local install-info-local: - @echo "Install 'texinfo' and re-run configure to be able to generate Info pages!" -endif # HAVE_MAKEINFO - -.NOTPARALLEL: man man: $(man_MANS) -$(MANPAGES_IN): $(MANPAGES_RST) - $(AM_V_SPHINX)$(SPHINXBUILD) -b man -d $(SPHINXBUILDDIR)/doctrees $(man_SPHINXOPTS) $(SPHINXBUILDDIR)/man - @mkdir -p $(srcdir)/man +$(man_MANS)&: $(MANPAGES_RST) + $(AM_V_SPHINX)$(SPHINXBUILD) -b man -d $(SPHINXBUILDDIR)/doctrees/man $(man_SPHINXOPTS) $(SPHINXBUILDDIR)/man + @mkdir -p man @for f in $(SPHINXBUILDDIR)/man/*; do \ - sed -e '/^\.TP$$/ {' -e 'n' -e 's/^\.B //' -e '}' "$$f" > "$(srcdir)/man/$$(basename $$f)in"; \ + sed -e 's,[@]config_dir@,$(config_dir),' \ + -e 's,[@]storage_dir@,$(storage_dir),' \ + -e 's,[@]run_dir@,$(run_dir),' \ + -e 's,[@]conf_mapsize@,$(conf_mapsize),' "$$f" > "man/$$(basename $$f)"; \ done else -html-local singlehtml pdf-local info-local epub man install-html-local install-singlehtml install-pdf-local install-info-local install-epub: +html-local singlehtml pdf-local epub man install-html-local install-singlehtml install-pdf-local install-epub: @echo "Install 'sphinx-build' and re-run configure to be able to generate documentation!" -endif # HAVE_SPHINXBUILD endif # HAVE_DOCS +EXTRA_DIST += \ + $(man_MANS) + clean-local: -rm -rf $(SPHINXBUILDDIR) - -rm -f man/*.1 man/*.5 man/*.8 + -rm -rf man diff --git a/doc/Makefile.in b/doc/Makefile.in index 5642629..a7bacd9 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -87,25 +87,25 @@ PRE_UNINSTALL = : POST_UNINSTALL = : build_triplet = @build@ host_triplet = @host@ -@HAVE_DAEMON_TRUE@am__append_1 = \ -@HAVE_DAEMON_TRUE@ man/knot.conf.5 \ -@HAVE_DAEMON_TRUE@ man/knotc.8 \ -@HAVE_DAEMON_TRUE@ man/knotd.8 - -@HAVE_DAEMON_TRUE@@HAVE_UTILS_TRUE@am__append_2 = \ -@HAVE_DAEMON_TRUE@@HAVE_UTILS_TRUE@ man/kcatalogprint.8 \ -@HAVE_DAEMON_TRUE@@HAVE_UTILS_TRUE@ man/keymgr.8 \ -@HAVE_DAEMON_TRUE@@HAVE_UTILS_TRUE@ man/kjournalprint.8 \ -@HAVE_DAEMON_TRUE@@HAVE_UTILS_TRUE@ man/kzonecheck.1 \ -@HAVE_DAEMON_TRUE@@HAVE_UTILS_TRUE@ man/kzonesign.1 - -@HAVE_UTILS_TRUE@am__append_3 = \ -@HAVE_UTILS_TRUE@ man/kdig.1 \ -@HAVE_UTILS_TRUE@ man/khost.1 \ -@HAVE_UTILS_TRUE@ man/knsupdate.1 \ -@HAVE_UTILS_TRUE@ man/knsec3hash.1 - -@ENABLE_XDP_TRUE@@HAVE_UTILS_TRUE@am__append_4 = man/kxdpgun.8 +@HAVE_DAEMON_TRUE@@HAVE_DOCS_TRUE@am__append_1 = \ +@HAVE_DAEMON_TRUE@@HAVE_DOCS_TRUE@ man/knot.conf.5 \ +@HAVE_DAEMON_TRUE@@HAVE_DOCS_TRUE@ man/knotc.8 \ +@HAVE_DAEMON_TRUE@@HAVE_DOCS_TRUE@ man/knotd.8 + +@HAVE_DAEMON_TRUE@@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@am__append_2 = \ +@HAVE_DAEMON_TRUE@@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@ man/kcatalogprint.8 \ +@HAVE_DAEMON_TRUE@@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@ man/keymgr.8 \ +@HAVE_DAEMON_TRUE@@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@ man/kjournalprint.8 \ +@HAVE_DAEMON_TRUE@@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@ man/kzonecheck.1 \ +@HAVE_DAEMON_TRUE@@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@ man/kzonesign.1 + +@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@am__append_3 = \ +@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@ man/kdig.1 \ +@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@ man/khost.1 \ +@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@ man/knsupdate.1 \ +@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@ man/knsec3hash.1 + +@ENABLE_XDP_TRUE@@HAVE_DOCS_TRUE@@HAVE_UTILS_TRUE@am__append_4 = man/kxdpgun.8 subdir = doc ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/ax_check_compile_flag.m4 \ @@ -312,6 +312,8 @@ infodir = @infodir@ install_sh = @install_sh@ libbpf_CFLAGS = @libbpf_CFLAGS@ libbpf_LIBS = @libbpf_LIBS@ +libdbus_CFLAGS = @libdbus_CFLAGS@ +libdbus_LIBS = @libdbus_LIBS@ libdir = @libdir@ libdnssec_SONAME = @libdnssec_SONAME@ libdnssec_SOVERSION = @libdnssec_SOVERSION@ @@ -323,8 +325,6 @@ libfstrm_CFLAGS = @libfstrm_CFLAGS@ libfstrm_LIBS = @libfstrm_LIBS@ libidn2_CFLAGS = @libidn2_CFLAGS@ libidn2_LIBS = @libidn2_LIBS@ -libidn_CFLAGS = @libidn_CFLAGS@ -libidn_LIBS = @libidn_LIBS@ libknot_SONAME = @libknot_SONAME@ libknot_SOVERSION = @libknot_SOVERSION@ libknot_VERSION_INFO = @libknot_VERSION_INFO@ @@ -342,7 +342,6 @@ libprotobuf_c_CFLAGS = @libprotobuf_c_CFLAGS@ libprotobuf_c_LIBS = @libprotobuf_c_LIBS@ liburcu_CFLAGS = @liburcu_CFLAGS@ liburcu_LIBS = @liburcu_LIBS@ -liburcu_PKGCONFIG = @liburcu_PKGCONFIG@ libxdp_CFLAGS = @libxdp_CFLAGS@ libxdp_LIBS = @libxdp_LIBS@ libzscanner_SONAME = @libzscanner_SONAME@ @@ -378,21 +377,6 @@ target_alias = @target_alias@ top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ -MANPAGES_IN = \ - man/knot.conf.5in \ - man/knotc.8in \ - man/knotd.8in \ - man/kcatalogprint.8in \ - man/keymgr.8in \ - man/kjournalprint.8in \ - man/kdig.1in \ - man/khost.1in \ - man/knsupdate.1in \ - man/knsec3hash.1in \ - man/kzonecheck.1in \ - man/kzonesign.1in \ - man/kxdpgun.8in - MANPAGES_RST = \ reference.rst \ man_knotc.rst \ @@ -408,31 +392,11 @@ MANPAGES_RST = \ man_kzonesign.rst \ man_kxdpgun.rst -EXTRA_DIST = \ - conf.py \ - \ - appendices.rst \ - configuration.rst \ - index.rst \ - installation.rst \ - introduction.rst \ - migration.rst \ - modules.rst.in \ - operation.rst \ - reference.rst \ - requirements.rst \ - troubleshooting.rst \ - utilities.rst \ - \ - $(MANPAGES_IN) \ - $(MANPAGES_RST) \ - \ - logo.pdf \ - logo.svg \ - \ - ext/ignore_panels.py \ - theme_html - +EXTRA_DIST = conf.py appendices.rst configuration.rst index.rst \ + installation.rst introduction.rst migration.rst modules.rst.in \ + operation.rst reference.rst requirements.rst \ + troubleshooting.rst utilities.rst $(MANPAGES_RST) logo.pdf \ + logo.svg ext/ignore_panels.py theme_html $(man_MANS) SPHINX_V = $(SPHINX_V_@AM_V@) SPHINX_V_ = $(SPHINX_V_@AM_DEFAULT_V@) SPHINX_V_0 = -q @@ -443,38 +407,25 @@ AM_V_SPHINX_0 = @echo " SPHINX $@"; SPHINXBUILDDIR = $(builddir)/_build _SPHINXOPTS = -c $(srcdir) \ -a \ - $(SPHINX_V) - -ALLSPHINXOPTS = $(_SPHINXOPTS) \ + $(SPHINX_V) \ -D version="$(VERSION)" \ -D today="$(RELEASE_DATE)" \ - -D release="$(VERSION)" \ + -D release="$(VERSION)" + +ALLSPHINXOPTS = $(_SPHINXOPTS) \ $(SPHINXOPTS) \ $(srcdir) man_SPHINXOPTS = $(_SPHINXOPTS) \ - -D version="@""VERSION@" \ - -D today="@""RELEASE_DATE@" \ - -D release="@""VERSION@" \ -D extensions="ignore_panels" \ $(SPHINXOPTS) \ $(srcdir) man_MANS = $(am__append_1) $(am__append_2) $(am__append_3) \ $(am__append_4) -man_SUBST = $(AM_V_GEN)mkdir -p man; \ - sed -e 's,[@]VERSION@,$(VERSION),' \ - -e 's,[@]RELEASE_DATE@,$(RELEASE_DATE),' \ - -e 's,[@]config_dir@,$(config_dir),' \ - -e 's,[@]storage_dir@,$(storage_dir),' \ - -e 's,[@]run_dir@,$(run_dir),' \ - -e 's,[@]conf_mapsize@,$(conf_mapsize),' \ - $< > $@ - all: all-am .SUFFIXES: -.SUFFIXES: .1 .1in .5 .5in .8 .8in $(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ @@ -718,21 +669,11 @@ maintainer-clean-generic: @echo "This command is intended for maintainers to use" @echo "it deletes files that may require special tools to rebuild." @HAVE_DOCS_FALSE@html-local: -@HAVE_SPHINXBUILD_FALSE@html-local: -@HAVE_DOCS_FALSE@info-local: -@HAVE_MAKEINFO_FALSE@info-local: -@HAVE_SPHINXBUILD_FALSE@info-local: @HAVE_DOCS_FALSE@install-html-local: -@HAVE_SPHINXBUILD_FALSE@install-html-local: -@HAVE_DOCS_FALSE@install-info-local: -@HAVE_MAKEINFO_FALSE@install-info-local: -@HAVE_SPHINXBUILD_FALSE@install-info-local: @HAVE_DOCS_FALSE@install-pdf-local: @HAVE_PDFLATEX_FALSE@install-pdf-local: -@HAVE_SPHINXBUILD_FALSE@install-pdf-local: @HAVE_DOCS_FALSE@pdf-local: @HAVE_PDFLATEX_FALSE@pdf-local: -@HAVE_SPHINXBUILD_FALSE@pdf-local: clean: clean-am clean-am: clean-generic clean-libtool clean-local mostlyclean-am @@ -751,7 +692,7 @@ html-am: html-local info: info-am -info-am: info-local +info-am: install-data-am: install-man @@ -767,7 +708,7 @@ install-html-am: install-html-local install-info: install-info-am -install-info-am: install-info-local +install-info-am: install-man: install-man1 install-man5 install-man8 @@ -806,11 +747,10 @@ uninstall-man: uninstall-man1 uninstall-man5 uninstall-man8 .PHONY: all all-am check check-am clean clean-generic clean-libtool \ clean-local cscopelist-am ctags-am distclean distclean-generic \ distclean-libtool distdir dvi dvi-am html html-am html-local \ - info info-am info-local install install-am install-data \ - install-data-am install-dvi install-dvi-am install-exec \ - install-exec-am install-html install-html-am \ - install-html-local install-info install-info-am \ - install-info-local install-man install-man1 install-man5 \ + info info-am install install-am install-data install-data-am \ + install-dvi install-dvi-am install-exec install-exec-am \ + install-html install-html-am install-html-local install-info \ + install-info-am install-man install-man1 install-man5 \ install-man8 install-pdf install-pdf-am install-pdf-local \ install-ps install-ps-am install-strip installcheck \ installcheck-am installdirs maintainer-clean \ @@ -822,97 +762,64 @@ uninstall-man: uninstall-man1 uninstall-man5 uninstall-man8 .PRECIOUS: Makefile -.PHONY: html-local singlehtml pdf-local info-local epub man install-html-local install-singlehtml install-pdf-local install-info-local install-epub - -man/knot.conf.5: man/knot.conf.5in -man/knotc.8: man/knotc.8in -man/knotd.8: man/knotd.8in -man/kcatalogprint.8: man/kcatalogprint.8in -man/keymgr.8: man/keymgr.8in -man/kjournalprint.8: man/kjournalprint.8in -man/kdig.1: man/kdig.1in -man/khost.1: man/khost.1in -man/knsupdate.1: man/knsupdate.1in -man/knsec3hash.1: man/knsec3hash.1in -man/kzonecheck.1: man/kzonecheck.1in -man/kzonesign.1: man/kzonesign.1in -man/kxdpgun.8: man/kxdpgun.8in - -.1in.1: - $(man_SUBST) - -.5in.5: - $(man_SUBST) - -.8in.8: - $(man_SUBST) - -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@html-local: -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b html -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ @echo "The HTML documentation has been built in $(SPHINXBUILDDIR)/html/" - -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@install-html-local: -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL) -d $(DESTDIR)/$(docdir) $(DESTDIR)/$(docdir)/_static $(DESTDIR)/$(docdir)/_sources -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL) -D $(SPHINXBUILDDIR)/html/*.html $(DESTDIR)/$(docdir)/ -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/html/_sources/* $(DESTDIR)/$(docdir)/_sources/ -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/html/_static/* $(DESTDIR)/$(docdir)/_static/ - -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@singlehtml: -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b singlehtml -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/singlehtml -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ @echo "The single HTML documentation has been built in $(SPHINXBUILDDIR)/singlehtml/" - -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@install-singlehtml: singlehtml -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL) -d $(DESTDIR)/$(docdir) $(DESTDIR)/$(docdir)/_static -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/singlehtml/*.html $(DESTDIR)/$(docdir)/ -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/singlehtml/_static/* $(DESTDIR)/$(docdir)/_static/ - -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@epub: -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b epub -A today=$(RELEASE_DATE) -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/epub -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ @echo "The EPUB documentation has been built in $(SPHINXBUILDDIR)/epub/" - -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@install-epub: -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL) -d $(DESTDIR)/$(docdir) -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/epub/KnotDNS.epub $(DESTDIR)/$(docdir)/ - -@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@@HAVE_SPHINXBUILD_TRUE@pdf-local: -@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b latex -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/latex -@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(MAKE) -C $(SPHINXBUILDDIR)/latex all-pdf -@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@@HAVE_SPHINXBUILD_TRUE@ @echo "The PDF documentation has been built in $(SPHINXBUILDDIR)/latex/" - -@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@@HAVE_SPHINXBUILD_TRUE@install-pdf-local: -@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL) -d $(DESTDIR)/$(docdir) -@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/latex/KnotDNS.pdf $(DESTDIR)/$(docdir)/ - -@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_FALSE@@HAVE_SPHINXBUILD_TRUE@pdf-local install-pdf-local: -@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_FALSE@@HAVE_SPHINXBUILD_TRUE@ @echo "Install 'pdflatex' and re-run configure to be able to generate PDF documentation!" - -@HAVE_DOCS_TRUE@@HAVE_MAKEINFO_TRUE@@HAVE_SPHINXBUILD_TRUE@info-local: -@HAVE_DOCS_TRUE@@HAVE_MAKEINFO_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b texinfo -d $(SPHINXBUILDDIR)/doctrees $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/texinfo -@HAVE_DOCS_TRUE@@HAVE_MAKEINFO_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(MAKE) -C $(SPHINXBUILDDIR)/texinfo info -@HAVE_DOCS_TRUE@@HAVE_MAKEINFO_TRUE@@HAVE_SPHINXBUILD_TRUE@ @echo "The Info pages have been built in $(SPHINXBUILDDIR)/texinfo/" - -@HAVE_DOCS_TRUE@@HAVE_MAKEINFO_TRUE@@HAVE_SPHINXBUILD_TRUE@install-info-local: -@HAVE_DOCS_TRUE@@HAVE_MAKEINFO_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL) -d $(DESTDIR)/$(infodir) -@HAVE_DOCS_TRUE@@HAVE_MAKEINFO_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/texinfo/knot.info $(DESTDIR)/$(infodir)/ - -@HAVE_DOCS_TRUE@@HAVE_MAKEINFO_FALSE@@HAVE_SPHINXBUILD_TRUE@info-local install-info-local: -@HAVE_DOCS_TRUE@@HAVE_MAKEINFO_FALSE@@HAVE_SPHINXBUILD_TRUE@ @echo "Install 'texinfo' and re-run configure to be able to generate Info pages!" - -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@.NOTPARALLEL: man -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@man: $(man_MANS) -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@$(MANPAGES_IN): $(MANPAGES_RST) -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b man -d $(SPHINXBUILDDIR)/doctrees $(man_SPHINXOPTS) $(SPHINXBUILDDIR)/man -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ @mkdir -p $(srcdir)/man -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ @for f in $(SPHINXBUILDDIR)/man/*; do \ -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ sed -e '/^\.TP$$/ {' -e 'n' -e 's/^\.B //' -e '}' "$$f" > "$(srcdir)/man/$$(basename $$f)in"; \ -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_TRUE@ done - -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_FALSE@html-local singlehtml pdf-local info-local epub man install-html-local install-singlehtml install-pdf-local install-info-local install-epub: -@HAVE_DOCS_TRUE@@HAVE_SPHINXBUILD_FALSE@ @echo "Install 'sphinx-build' and re-run configure to be able to generate documentation!" +.PHONY: html-local singlehtml pdf-local epub man install-html-local install-singlehtml install-pdf-local install-epub + +@HAVE_DOCS_TRUE@html-local: +@HAVE_DOCS_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b html -d $(SPHINXBUILDDIR)/doctrees/html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html +@HAVE_DOCS_TRUE@ @echo "The HTML documentation has been built in $(SPHINXBUILDDIR)/html/" + +@HAVE_DOCS_TRUE@install-html-local: +@HAVE_DOCS_TRUE@ $(INSTALL) -d $(DESTDIR)/$(docdir) $(DESTDIR)/$(docdir)/_static $(DESTDIR)/$(docdir)/_sources +@HAVE_DOCS_TRUE@ $(INSTALL) -D $(SPHINXBUILDDIR)/html/*.html $(DESTDIR)/$(docdir)/ +@HAVE_DOCS_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/html/_sources/* $(DESTDIR)/$(docdir)/_sources/ +@HAVE_DOCS_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/html/_static/* $(DESTDIR)/$(docdir)/_static/ + +@HAVE_DOCS_TRUE@singlehtml: +@HAVE_DOCS_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b singlehtml -d $(SPHINXBUILDDIR)/doctrees/singlehtml $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/singlehtml +@HAVE_DOCS_TRUE@ @echo "The single HTML documentation has been built in $(SPHINXBUILDDIR)/singlehtml/" + +@HAVE_DOCS_TRUE@install-singlehtml: singlehtml +@HAVE_DOCS_TRUE@ $(INSTALL) -d $(DESTDIR)/$(docdir) $(DESTDIR)/$(docdir)/_static +@HAVE_DOCS_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/singlehtml/*.html $(DESTDIR)/$(docdir)/ +@HAVE_DOCS_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/singlehtml/_static/* $(DESTDIR)/$(docdir)/_static/ + +@HAVE_DOCS_TRUE@epub: +@HAVE_DOCS_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b epub -A today=$(RELEASE_DATE) -d $(SPHINXBUILDDIR)/doctrees/epub $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/epub +@HAVE_DOCS_TRUE@ @echo "The EPUB documentation has been built in $(SPHINXBUILDDIR)/epub/" + +@HAVE_DOCS_TRUE@install-epub: +@HAVE_DOCS_TRUE@ $(INSTALL) -d $(DESTDIR)/$(docdir) +@HAVE_DOCS_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/epub/KnotDNS.epub $(DESTDIR)/$(docdir)/ + +@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@pdf-local: +@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b latex -d $(SPHINXBUILDDIR)/doctrees/latex $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/latex +@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@ $(MAKE) -C $(SPHINXBUILDDIR)/latex all-pdf +@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@ @echo "The PDF documentation has been built in $(SPHINXBUILDDIR)/latex/" + +@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@install-pdf-local: +@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@ $(INSTALL) -d $(DESTDIR)/$(docdir) +@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_TRUE@ $(INSTALL_DATA) $(SPHINXBUILDDIR)/latex/KnotDNS.pdf $(DESTDIR)/$(docdir)/ + +@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_FALSE@pdf-local install-pdf-local: +@HAVE_DOCS_TRUE@@HAVE_PDFLATEX_FALSE@ @echo "Install 'pdflatex' and re-run configure to be able to generate PDF documentation!" + +@HAVE_DOCS_TRUE@man: $(man_MANS) +@HAVE_DOCS_TRUE@$(man_MANS)&: $(MANPAGES_RST) +@HAVE_DOCS_TRUE@ $(AM_V_SPHINX)$(SPHINXBUILD) -b man -d $(SPHINXBUILDDIR)/doctrees/man $(man_SPHINXOPTS) $(SPHINXBUILDDIR)/man +@HAVE_DOCS_TRUE@ @mkdir -p man +@HAVE_DOCS_TRUE@ @for f in $(SPHINXBUILDDIR)/man/*; do \ +@HAVE_DOCS_TRUE@ sed -e 's,[@]config_dir@,$(config_dir),' \ +@HAVE_DOCS_TRUE@ -e 's,[@]storage_dir@,$(storage_dir),' \ +@HAVE_DOCS_TRUE@ -e 's,[@]run_dir@,$(run_dir),' \ +@HAVE_DOCS_TRUE@ -e 's,[@]conf_mapsize@,$(conf_mapsize),' "$$f" > "man/$$(basename $$f)"; \ +@HAVE_DOCS_TRUE@ done + +@HAVE_DOCS_FALSE@html-local singlehtml pdf-local epub man install-html-local install-singlehtml install-pdf-local install-epub: +@HAVE_DOCS_FALSE@ @echo "Install 'sphinx-build' and re-run configure to be able to generate documentation!" clean-local: -rm -rf $(SPHINXBUILDDIR) - -rm -f man/*.1 man/*.5 man/*.8 + -rm -rf man # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. diff --git a/doc/appendices.rst b/doc/appendices.rst index 309bb20..1012623 100644 --- a/doc/appendices.rst +++ b/doc/appendices.rst @@ -103,24 +103,3 @@ support. A command similar to the following may be used to verify what algorithms are supported: ``$ pkcs11-tool --modul /usr/lib64/pkcs11/libsofthsm2.so -M``. .. [#fn-utimaco] Requires setting the number of background workers to 1! - -The following table summarizes supported DNSSEC algorithm numbers and minimal -GnuTLS library version required. Any algorithm may work with older library, -however the supported operations may be limited (e.g. private key import). - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - - * - - - `Numbers `_ - - GnuTLS version - * - ED25519 - - 15 - - 3.6.0 or newer - * - ECDSA - - 13, 14 - - 3.4.8 or newer - * - RSA - - 5, 7, 8, 10 - - 3.4.6 or newer diff --git a/doc/conf.py b/doc/conf.py index ec821d6..4b1c8e9 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -248,10 +248,7 @@ man_pages = [ # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) -texinfo_documents = [ - ('index', 'knot', 'Knot DNS Documentation', author, - 'KnotDNS', 'Knot Authoritative DNS Server', 'Miscellaneous') -] +#texinfo_documents = [] # Documents to append as an appendix to all manuals. #texinfo_appendices = [] diff --git a/doc/configuration.rst b/doc/configuration.rst index a29521b..982031b 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -377,6 +377,19 @@ which must be used for the transaction security:: - domain: example.net. acl: owner_rule3_net +.. _Handling CNAME and DNAME-related updates: + +Handling CNAME and DNAME-related updates +---------------------------------------- + +In general, no RR must exist beside a CNAME or below a DNAME. Whenever +such a CNAME or DNAME-related semantic rule is vialoated by an RR addition +in DDNS (this means addition of a CNAME beside an existing record, addition of +another record beside a CNAME, addition of a DNAME above an existing record, +addition of another record below a DNAME), such an RR addition is silently ignored. +However, other RRs from the same DDNS update are processed normally. This is slightly +non-compliant with RFC 6672 (in particular, no RR occlusion takes place). + .. _dnssec: Automatic DNSSEC signing @@ -826,7 +839,7 @@ of the used certificate: .. code-block:: console ... info: binding to QUIC interface ::1@853 - ... info: QUIC, certificate public key 0xtdayWpnJh4Py8goi8cei/gXGD4kJQ+HEqcxS++DBw= + ... info: QUIC/TLS, certificate public key 0xtdayWpnJh4Py8goi8cei/gXGD4kJQ+HEqcxS++DBw= .. TIP:: @@ -861,10 +874,10 @@ Using :doc:`kdig` we can verify that the server responds over QUIC: ;; version.server. CH TXT ;; ANSWER SECTION: - version.server. 0 CH TXT "Knot DNS 3.3.0" + version.server. 0 CH TXT "Knot DNS 3.4.0" ;; Received 468 B - ;; Time 2023-08-15 15:04:36 CEST + ;; Time 2024-06-21 08:30:12 CEST ;; From ::1@853(QUIC) in 1.1 ms In this case, :rfc:`opportunistic authentication<9103#section-9.3.1>` was @@ -1074,6 +1087,62 @@ This mode is recommended if possible. Knot DNS uses certificate public key pinning. This approach has much lower overhead and in most cases simplifies configuration and certificate management. +.. _DNS_over_TLS: + +DNS over TLS +============ + +TLS is an encrypted internet transport protocol. +Knot DNS supports DNS over TLS (DoT) (:rfc:`7858`), including zone transfers (XoT). +By default, the TCP port `853` is used for DNS over TLS. + +There are the same requirements for TLS key and certificate as for :ref:`DNS_over_QUIC`. + +In order to listen for incoming requests over TLS, :ref:`interface` +must be configured. + +An example of configuration of listening for DNS over TLS on the loopback interface: + +.. code-block:: console + + server: + listen-tls: ::1 + +When the server is started, it logs some interface details and public key pin +of the used certificate: + +.. code-block:: console + + ... info: binding to TLS interface ::1@853 + ... info: QUIC/TLS, certificate public key 0xtdayWpnJh4Py8goi8cei/gXGD4kJQ+HEqcxS++DBw= + +Using :doc:`kdig` we can verify that the server responds over TLS: + +.. code-block:: console + + $ kdig @::1 ch txt version.server +tls + ;; TLS session (TLS1.3)-(ECDHE-X25519)-(EdDSA-Ed25519)-(AES-256-GCM) + ;; ->>HEADER<<- opcode: QUERY; status: NOERROR; id: 0 + ;; Flags: qr rd; QUERY: 1; ANSWER: 1; AUTHORITY: 0; ADDITIONAL: 1 + + ;; EDNS PSEUDOSECTION: + ;; Version: 0; flags: ; UDP size: 1232 B; ext-rcode: NOERROR + ;; PADDING: 370 B + + ;; QUESTION SECTION: + ;; version.server. CH TXT + + ;; ANSWER SECTION: + version.server. 0 CH TXT "Knot DNS 3.4.0" + + ;; Received 468 B + ;; Time 2024-06-21 08:31:13 CEST + ;; From ::1@853(TLS) in 9.1 ms + +Zone transfer configuration and authentication profiles are almost identical +to :ref:`DNS_over_QUIC`, with the only difference being the enabling of +:ref:`remote_tls` for the corresponding remotes. + .. _query-modules: Query modules diff --git a/doc/installation.rst b/doc/installation.rst index f89f439..8eebaa3 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -34,10 +34,7 @@ The build process relies on these standard tools: * autoconf >= 2.65 * python-sphinx (optional, for documentation building) -GCC >= 4.1 is mandatory for atomic built-ins, but the latest -available version is recommended. Another requirement is ``_GNU_SOURCE`` -and C99 support, otherwise it adapts to the available compiler features. -LLVM clang compiler since version 2.9 can be used as well. +A GCC or LLVM Clang compiler with C11 support. Getting the source code ----------------------- diff --git a/doc/introduction.rst b/doc/introduction.rst index 398d0d4..f472b85 100644 --- a/doc/introduction.rst +++ b/doc/introduction.rst @@ -29,7 +29,7 @@ DNS features: * Primary and secondary server operation * Internet (IN) and Chaos (CH) classes * DNS extension (EDNS0, EDE, EXPIRE) -* UDP, TCP, and QUIC protocols +* UDP, TCP, TLS 1.3, and QUIC protocols * Zone catalog generation and interpretation * Minimal responses * Dynamic zone updates @@ -73,7 +73,7 @@ Remarkable module extensions: Remarkable supported networking features: * TCP Fast Open (client and server) -* Opportunistic, strict, and mutual authentication profiles over QUIC +* Opportunistic, strict, and mutual authentication profiles over TLS 1.3 or QUIC * High-performance UDP, TCP, and QUIC through AF_XDP processing (on Linux 4.18+) * SO_REUSEPORT (on Linux) or SO_REUSEPORT_LB (on FreeBSD 12.0+) on UDP and by choice on TCP * Binding to non-local addresses (IP_FREEBIND on Linux, IP_BINDANY/IPV6_BINDANY on FreeBSD) diff --git a/doc/man/kcatalogprint.8 b/doc/man/kcatalogprint.8 new file mode 100644 index 0000000..f9d9fc9 --- /dev/null +++ b/doc/man/kcatalogprint.8 @@ -0,0 +1,81 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KCATALOGPRINT" "8" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +kcatalogprint \- Knot DNS catalog print utility +.SH SYNOPSIS +.sp +\fBkcatalogprint\fP [\fIconfig_option\fP] [\fIoptions\fP] +.SH DESCRIPTION +.sp +The program prints zone catalog stored in a catalog database. +.SS Config options +.INDENT 0.0 +.TP +\fB\-c\fP, \fB\-\-config\fP \fIfile\fP +Use a textual configuration file (default is \fB/usr/local/etc/knot/knot.conf\fP). +.TP +\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP +Use a binary configuration database directory (default is \fB/usr/local/var/lib/knot/confdb\fP). +The default configuration database, if exists, has a preference to the default +configuration file. +.TP +\fB\-D\fP, \fB\-\-dir\fP \fIpath\fP +Use specified catalog database path and default configuration. +.UNINDENT +.SS Options +.INDENT 0.0 +.TP +\fB\-a\fP, \fB\-\-catalog\fP +Filter the output by catalog zone name. +.TP +\fB\-m\fP, \fB\-\-member\fP +Filter the output by member zone name. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH SEE ALSO +.sp +\fBknotd(8)\fP, \fBknot.conf(5)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/kcatalogprint.8in b/doc/man/kcatalogprint.8in deleted file mode 100644 index da964d8..0000000 --- a/doc/man/kcatalogprint.8in +++ /dev/null @@ -1,80 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KCATALOGPRINT" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -kcatalogprint \- Knot DNS catalog print utility -.SH SYNOPSIS -.sp -\fBkcatalogprint\fP [\fIconfig_option\fP] [\fIoptions\fP] -.SH DESCRIPTION -.sp -The program prints zone catalog stored in a catalog database. -.SS Config options -.INDENT 0.0 -.TP -\fB\-c\fP, \fB\-\-config\fP \fIfile\fP -Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). -.TP -\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP -Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). -The default configuration database, if exists, has a preference to the default -configuration file. -.TP -\fB\-D\fP, \fB\-\-dir\fP \fIpath\fP -Use specified catalog database path and default configuration. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-a\fP, \fB\-\-catalog\fP -Filter the output by catalog zone name. -.TP -\fB\-m\fP, \fB\-\-member\fP -Filter the output by member zone name. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.UNINDENT -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH SEE ALSO -.sp -\fBknotd(8)\fP, \fBknot.conf(5)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/kdig.1 b/doc/man/kdig.1 new file mode 100644 index 0000000..207c8c8 --- /dev/null +++ b/doc/man/kdig.1 @@ -0,0 +1,465 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KDIG" "1" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +kdig \- Advanced DNS lookup utility +.SH SYNOPSIS +.sp +\fBkdig\fP [\fIcommon\-settings\fP] [\fIquery\fP [\fIsettings\fP]]... +.sp +\fBkdig\fP \fB\-h\fP +.SH DESCRIPTION +.sp +This utility sends one or more DNS queries to a nameserver. Each query can have +individual \fIsettings\fP, or it can be specified globally via \fIcommon\-settings\fP, +which must precede \fIquery\fP specification. +.SS Parameters +.INDENT 0.0 +.TP +.B \fIquery\fP +\fIname\fP | \fB\-q\fP \fIname\fP | \fB\-x\fP \fIaddress\fP | \fB\-G\fP \fItapfile\fP +.TP +.B \fIcommon\-settings\fP, \fIsettings\fP +[\fIquery_class\fP] [\fIquery_type\fP] [\fB@\fP\fIserver\fP]... [\fIoptions\fP] +.TP +.B \fIname\fP +Is a domain name that is to be looked up. +.TP +.B \fIserver\fP +Is a domain name or an IPv4 or IPv6 address of the nameserver to send a query +to. An additional port can be specified using address:port ([address]:port +for IPv6 address), address@port, or address#port notation. A value which begins +with \(aq/\(aq character is considered an absolute UNIX socket path. If no server is +specified, the servers from \fB/etc/resolv.conf\fP are used. +.UNINDENT +.sp +If no arguments are provided, \fBkdig\fP sends NS query for the root +zone. +.SS Query classes +.sp +A \fIquery_class\fP can be either a DNS class name (IN, CH) or generic class +specification \fBCLASS\fP\fIXXXXX\fP where \fIXXXXX\fP is a corresponding decimal +class number. The default query class is IN. +.SS Query types +.sp +A \fIquery_type\fP can be either a DNS resource record type +(A, AAAA, NS, SOA, DNSKEY, ANY, etc.) or one of the following: +.INDENT 0.0 +.TP +\fBTYPE\fP\fIXXXXX\fP +Generic query type specification where \fIXXXXX\fP is a corresponding decimal +type number. +.TP +\fBAXFR\fP +Full zone transfer request. +.TP +\fBIXFR=\fP\fIserial\fP +Incremental zone transfer request for specified SOA serial number +(i.e. all zone updates since the specified zone version are to be returned). +.TP +\fBNOTIFY=\fP\fIserial\fP +Notify message with a SOA serial hint specified. +.TP +\fBNOTIFY\fP +Notify message with a SOA serial hint unspecified. +.UNINDENT +.sp +The default query type is A. +.SS Options +.INDENT 0.0 +.TP +\fB\-4\fP +Use the IPv4 protocol only. +.TP +\fB\-6\fP +Use the IPv6 protocol only. +.TP +\fB\-b\fP \fIaddress\fP +Set the source IP address of the query to \fIaddress\fP\&. The address must be a +valid address for local interface or :: or 0.0.0.0. An optional port +can be specified in the same format as the \fIserver\fP value. +.TP +\fB\-c\fP \fIclass\fP +An explicit \fIquery_class\fP specification. See possible values above. +.TP +\fB\-d\fP +Enable debug messages. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-k\fP \fIkeyfile\fP +Use the TSIG key stored in a file \fIkeyfile\fP to authenticate the request. The +file must contain the key in the same format as accepted by the +\fB\-y\fP option. +.TP +\fB\-p\fP \fIport\fP +Set the nameserver port number or service name to send a query to. The default +port is 53. +.TP +\fB\-q\fP \fIname\fP +Set the query name. An explicit variant of \fIname\fP specification. If no \fIname\fP +is provided, empty question section is set. +.TP +\fB\-t\fP \fItype\fP +An explicit \fIquery_type\fP specification. See possible values above. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.TP +\fB\-x\fP \fIaddress\fP +Send a reverse (PTR) query for IPv4 or IPv6 \fIaddress\fP\&. The correct name, class +and type is set automatically. +.TP +\fB\-y\fP [\fIalg\fP:]\fIname\fP:\fIkey\fP +Use the TSIG key named \fIname\fP to authenticate the request. The \fIalg\fP +part specifies the algorithm (the default is hmac\-sha256) and \fIkey\fP specifies +the shared secret encoded in Base64. +.TP +\fB\-E\fP \fItapfile\fP +Export a dnstap trace of the query and response messages received to the +file \fItapfile\fP\&. +.TP +\fB\-G\fP \fItapfile\fP +Generate message output from a previously saved dnstap file \fItapfile\fP\&. +.TP +\fB+\fP[\fBno\fP]\fBmultiline\fP +Wrap long records to more lines and improve human readability. +.TP +\fB+\fP[\fBno\fP]\fBshort\fP +Show record data only. +.TP +\fB+\fP[\fBno\fP]\fBgeneric\fP +Use the generic representation format when printing resource record types +and data. +.TP +\fB+\fP[\fBno\fP]\fBcrypto\fP +Display the DNSSEC keys and signatures values in base64, instead of omitting them. +.TP +\fB+\fP[\fBno\fP]\fBaaflag\fP +Set the AA flag. +.TP +\fB+\fP[\fBno\fP]\fBtcflag\fP +Set the TC flag. +.TP +\fB+\fP[\fBno\fP]\fBrdflag\fP +Set the RD flag. +.TP +\fB+\fP[\fBno\fP]\fBrecurse\fP +Same as \fB+\fP[\fBno\fP]\fBrdflag\fP +.TP +\fB+\fP[\fBno\fP]\fBraflag\fP +Set the RA flag. +.TP +\fB+\fP[\fBno\fP]\fBzflag\fP +Set the zero flag bit. +.TP +\fB+\fP[\fBno\fP]\fBadflag\fP +Set the AD flag. +.TP +\fB+\fP[\fBno\fP]\fBcdflag\fP +Set the CD flag. +.TP +\fB+\fP[\fBno\fP]\fBdnssec\fP +Set the DO flag. +.TP +\fB+\fP[\fBno\fP]\fBall\fP +Show all packet sections. +.TP +\fB+\fP[\fBno\fP]\fBqr\fP +Show the query packet. +.TP +\fB+\fP[\fBno\fP]\fBheader\fP +Show the packet header. +.TP +\fB+\fP[\fBno\fP]\fBcomments\fP +Show commented section names. +.TP +\fB+\fP[\fBno\fP]\fBopt\fP +Show the EDNS pseudosection. +.TP +\fB+\fP[\fBno\fP]\fBopttext\fP +Try to show unknown EDNS options as text. +.TP +\fB+\fP[\fBno\fP]\fBoptpresent\fP +Show EDNS in presentation format according to the specification in version +\fI\%draft\-peltan\-edns\-presentation\-format\-01\fP\&. +.TP +\fB+\fP[\fBno\fP]\fBquestion\fP +Show the question section. +.TP +\fB+\fP[\fBno\fP]\fBanswer\fP +Show the answer section. +.TP +\fB+\fP[\fBno\fP]\fBauthority\fP +Show the authority section. +.TP +\fB+\fP[\fBno\fP]\fBadditional\fP +Show the additional section. +.TP +\fB+\fP[\fBno\fP]\fBtsig\fP +Show the TSIG pseudosection. +.TP +\fB+\fP[\fBno\fP]\fBstats\fP +Show trailing packet statistics. +.TP +\fB+\fP[\fBno\fP]\fBclass\fP +Show the DNS class. +.TP +\fB+\fP[\fBno\fP]\fBttl\fP +Show the TTL value. +.TP +\fB+\fP[\fBno\fP]\fBtcp\fP +Use the TCP protocol (default is UDP for standard query and TCP for AXFR/IXFR). +.TP +\fB+\fP[\fBno\fP]\fBfastopen\fP +Use TCP Fast Open. +.TP +\fB+\fP[\fBno\fP]\fBignore\fP +Don\(aqt use TCP automatically if a truncated reply is received. +.TP +\fB+\fP[\fBno\fP]\fBkeepopen\fP +Keep TCP connection open for the following query if it has the same connection +configuration. This applies to +tcp, +tls, and +https operations. The connection +is considered in the context of a single kdig call only. +.TP +\fB+\fP[\fBno\fP]\fBtls\fP +Use TLS with the Opportunistic privacy profile (\fI\%RFC 7858#section\-4.1\fP). +.TP +\fB+\fP[\fBno\fP]\fBtls\-ca\fP[=\fIFILE\fP] +Use TLS with a certificate validation. Certification authority certificates +are loaded from the specified PEM file (default is system certificate storage +if no argument is provided). +Can be specified multiple times. If the +tls\-hostname option is not provided, +the name of the target server (if specified) is used for strict authentication. +.TP +\fB+\fP[\fBno\fP]\fBtls\-pin\fP=\fIBASE64\fP +Use TLS with the Out\-of\-Band key\-pinned privacy profile (\fI\%RFC 7858#section\-4.2\fP). +The PIN must be a Base64 encoded SHA\-256 hash of the X.509 SubjectPublicKeyInfo. +Can be specified multiple times. +.TP +\fB+\fP[\fBno\fP]\fBtls\-hostname\fP=\fISTR\fP +Use TLS with a remote server hostname check. +.TP +\fB+\fP[\fBno\fP]\fBtls\-sni\fP=\fISTR\fP +Use TLS with a Server Name Indication. +.TP +\fB+\fP[\fBno\fP]\fBtls\-keyfile\fP=\fIFILE\fP +Use TLS with a client keyfile. +.TP +\fB+\fP[\fBno\fP]\fBtls\-certfile\fP=\fIFILE\fP +Use TLS with a client certfile. +.TP +\fB+\fP[\fBno\fP]\fBtls\-ocsp\-stapling\fP[=\fIH\fP] +Use TLS with a valid stapled OCSP response for the server certificate +(%u or specify hours). OCSP responses older than the specified period are +considered invalid. +.TP +\fB+\fP[\fBno\fP]\fBhttps\fP[=\fIURL\fP] +Use HTTPS (DNS\-over\-HTTPS) in wire format (\fI\%RFC 1035#section\-4.2.1\fP). +It is also possible to specify URL=[authority][/path] where request +will be sent to. Any leading scheme and authority indicator (i.e. //) are ignored. +Authority might also be specified as the \fIserver\fP (using the parameter \fI@\fP). +If \fIpath\fP is specified and \fIauthority\fP is missing, then the \fIserver\fP +is used as authority together with the specified \fIpath\fP\&. +Library \fIlibnghttp2\fP is required. +.TP +\fB+\fP[\fBno\fP]\fBhttps\-get\fP +Use HTTPS with HTTP/GET method instead of the default HTTP/POST method. +Library \fIlibnghttp2\fP is required. +.TP +\fB+\fP[\fBno\fP]\fBquic\fP +Use QUIC (DNS\-over\-QUIC). +.TP +\fB+\fP[\fBno\fP]\fBnsid\fP +Request the nameserver identifier (NSID). +.TP +\fB+\fP[\fBno\fP]\fBbufsize\fP=\fIB\fP +Set EDNS buffer size in bytes (default is 1232 bytes). +.TP +\fB+\fP[\fBno\fP]\fBpadding\fP[=\fIB\fP] +Use EDNS(0) padding option to pad queries, optionally to a specific +size. The default is to pad queries with a sensible amount when using ++tls, and not to pad at all when queries are sent without TLS. With +no argument (i.e., just +padding) pad every query with a sensible +amount regardless of the use of TLS. With +nopadding, never pad. +.TP +\fB+\fP[\fBno\fP]\fBalignment\fP[=\fIB\fP] +Align the query to B\-byte\-block message using the EDNS(0) padding option +(default is no or 128 if no argument is specified). +.TP +\fB+\fP[\fBno\fP]\fBsubnet\fP=\fISUBN\fP +Set EDNS(0) client subnet SUBN=addr/prefix. +.TP +\fB+\fP[\fBno\fP]\fBedns\fP[=\fIN\fP] +Use EDNS version (default is 0). EDNS(0) is enabled by default. +.TP +\fB+\fP[\fBno\fP]\fBtimeout\fP=\fIT\fP +Set the wait\-for\-reply interval in seconds (default is 5 seconds). This timeout +applies to each query attempt. Zero value or \fInotimeout\fP is interpreted as +infinity. +.TP +\fB+\fP[\fBno\fP]\fBretry\fP=\fIN\fP +Set the number (>=0) of UDP retries (default is 2). This doesn\(aqt apply to +AXFR/IXFR. +.TP +\fB+\fP[\fBno\fP]\fBexpire\fP +Sets the EXPIRE EDNS option. +.TP +\fB+\fP[\fBno\fP]\fBcookie\fP[=\fIHEX\fP] +Attach EDNS(0) cookie to the query. +.TP +\fB+\fP[\fBno\fP]\fBbadcookie\fP +Repeat a query with the correct cookie. +.TP +\fB+\fP[\fBno\fP]\fBednsopt\fP[=\fICODE\fP[:\fIHEX\fP]] +Send custom EDNS option. The \fICODE\fP is EDNS option code in decimal, \fIHEX\fP +is an optional hex encoded string to use as EDNS option value. This argument +can be used multiple times. +noednsopt clears all EDNS options specified by ++ednsopt. +.TP +\fB+\fP[\fBno\fP]\fBproxy\fP=\fISRC_ADDR\fP[#\fISRC_PORT\fP]\-\fIDST_ADDR\fP[#\fIDST_PORT\fP] +Add PROXYv2 header with the specified source and destination addresses to the query. +The default source port is 0 and destination port 53. +.TP +\fB+\fP[\fBno\fP]\fBjson\fP +Use JSON for output encoding (RFC 8427). +.TP +\fB+noidn\fP +Disable the IDN transformation to ASCII and vice versa. IDN support depends +on libidn2 availability during project building! If used in \fIcommon\-settings\fP, +all IDN transformations are disabled. If used in the individual query \fIsettings\fP, +transformation from ASCII is disabled on output for the particular query. Note +that IDN transformation does not preserve domain name letter case. +.UNINDENT +.SH NOTES +.sp +Options \fB\-k\fP and \fB\-y\fP can not be used simultaneously. +.sp +Dnssec\-keygen keyfile format is not supported. Use \fBkeymgr(8)\fP instead. +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH EXAMPLES +.INDENT 0.0 +.IP 1. 3 +Get A records for example.com: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kdig example.com A +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 2. 3 +Perform AXFR for zone example.com from the server 192.0.2.1: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kdig example.com \-t AXFR @192.0.2.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 3. 3 +Get A records for example.com from 192.0.2.1 and reverse lookup for address +2001:DB8::1 from 192.0.2.2. Both using the TCP protocol: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kdig +tcp example.com \-t A @192.0.2.1 \-x 2001:DB8::1 @192.0.2.2 +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 4. 3 +Get SOA record for example.com, use TLS, use system certificates, check +for specified hostname, check for certificate pin, and print additional +debug info: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kdig \-d @185.49.141.38 +tls\-ca +tls\-host=getdnsapi.net \e + +tls\-pin=foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9S= soa example.com +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 5. 3 +DNS over HTTPS examples (various DoH implementations): +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kdig @1.1.1.1 +https example.com. +$ kdig @193.17.47.1 +https=/doh example.com. +$ kdig @8.8.4.4 +https +https\-get example.com. +$ kdig @8.8.8.8 +https +tls\-hostname=dns.google +fastopen example.com. +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 6. 3 +More queries share one DoT connection: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kdig @1.1.1.1 +tls +keepopen abc.example.com A mail.example.com AAAA +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SH FILES +.sp +\fB/etc/resolv.conf\fP +.SH SEE ALSO +.sp +\fBkhost(1)\fP, \fBknsupdate(1)\fP, \fBkeymgr(8)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/kdig.1in b/doc/man/kdig.1in deleted file mode 100644 index 99745c9..0000000 --- a/doc/man/kdig.1in +++ /dev/null @@ -1,464 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KDIG" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -kdig \- Advanced DNS lookup utility -.SH SYNOPSIS -.sp -\fBkdig\fP [\fIcommon\-settings\fP] [\fIquery\fP [\fIsettings\fP]]... -.sp -\fBkdig\fP \fB\-h\fP -.SH DESCRIPTION -.sp -This utility sends one or more DNS queries to a nameserver. Each query can have -individual \fIsettings\fP, or it can be specified globally via \fIcommon\-settings\fP, -which must precede \fIquery\fP specification. -.SS Parameters -.INDENT 0.0 -.TP -\fIquery\fP -\fIname\fP | \fB\-q\fP \fIname\fP | \fB\-x\fP \fIaddress\fP | \fB\-G\fP \fItapfile\fP -.TP -\fIcommon\-settings\fP, \fIsettings\fP -[\fIquery_class\fP] [\fIquery_type\fP] [\fB@\fP\fIserver\fP]... [\fIoptions\fP] -.TP -\fIname\fP -Is a domain name that is to be looked up. -.TP -\fIserver\fP -Is a domain name or an IPv4 or IPv6 address of the nameserver to send a query -to. An additional port can be specified using address:port ([address]:port -for IPv6 address), address@port, or address#port notation. A value which begins -with \(aq/\(aq character is considered an absolute UNIX socket path. If no server is -specified, the servers from \fB/etc/resolv.conf\fP are used. -.UNINDENT -.sp -If no arguments are provided, \fBkdig\fP sends NS query for the root -zone. -.SS Query classes -.sp -A \fIquery_class\fP can be either a DNS class name (IN, CH) or generic class -specification \fBCLASS\fP\fIXXXXX\fP where \fIXXXXX\fP is a corresponding decimal -class number. The default query class is IN. -.SS Query types -.sp -A \fIquery_type\fP can be either a DNS resource record type -(A, AAAA, NS, SOA, DNSKEY, ANY, etc.) or one of the following: -.INDENT 0.0 -.TP -\fBTYPE\fP\fIXXXXX\fP -Generic query type specification where \fIXXXXX\fP is a corresponding decimal -type number. -.TP -\fBAXFR\fP -Full zone transfer request. -.TP -\fBIXFR=\fP\fIserial\fP -Incremental zone transfer request for specified SOA serial number -(i.e. all zone updates since the specified zone version are to be returned). -.TP -\fBNOTIFY=\fP\fIserial\fP -Notify message with a SOA serial hint specified. -.TP -\fBNOTIFY\fP -Notify message with a SOA serial hint unspecified. -.UNINDENT -.sp -The default query type is A. -.SS Options -.INDENT 0.0 -.TP -\fB\-4\fP -Use the IPv4 protocol only. -.TP -\fB\-6\fP -Use the IPv6 protocol only. -.TP -\fB\-b\fP \fIaddress\fP -Set the source IP address of the query to \fIaddress\fP\&. The address must be a -valid address for local interface or :: or 0.0.0.0. An optional port -can be specified in the same format as the \fIserver\fP value. -.TP -\fB\-c\fP \fIclass\fP -An explicit \fIquery_class\fP specification. See possible values above. -.TP -\fB\-d\fP -Enable debug messages. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-k\fP \fIkeyfile\fP -Use the TSIG key stored in a file \fIkeyfile\fP to authenticate the request. The -file must contain the key in the same format as accepted by the -\fB\-y\fP option. -.TP -\fB\-p\fP \fIport\fP -Set the nameserver port number or service name to send a query to. The default -port is 53. -.TP -\fB\-q\fP \fIname\fP -Set the query name. An explicit variant of \fIname\fP specification. If no \fIname\fP -is provided, empty question section is set. -.TP -\fB\-t\fP \fItype\fP -An explicit \fIquery_type\fP specification. See possible values above. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.TP -\fB\-x\fP \fIaddress\fP -Send a reverse (PTR) query for IPv4 or IPv6 \fIaddress\fP\&. The correct name, class -and type is set automatically. -.TP -\fB\-y\fP [\fIalg\fP:]\fIname\fP:\fIkey\fP -Use the TSIG key named \fIname\fP to authenticate the request. The \fIalg\fP -part specifies the algorithm (the default is hmac\-sha256) and \fIkey\fP specifies -the shared secret encoded in Base64. -.TP -\fB\-E\fP \fItapfile\fP -Export a dnstap trace of the query and response messages received to the -file \fItapfile\fP\&. -.TP -\fB\-G\fP \fItapfile\fP -Generate message output from a previously saved dnstap file \fItapfile\fP\&. -.TP -\fB+\fP[\fBno\fP]\fBmultiline\fP -Wrap long records to more lines and improve human readability. -.TP -\fB+\fP[\fBno\fP]\fBshort\fP -Show record data only. -.TP -\fB+\fP[\fBno\fP]\fBgeneric\fP -Use the generic representation format when printing resource record types -and data. -.TP -\fB+\fP[\fBno\fP]\fBcrypto\fP -Display the DNSSEC keys and signatures values in base64, instead of omitting them. -.TP -\fB+\fP[\fBno\fP]\fBaaflag\fP -Set the AA flag. -.TP -\fB+\fP[\fBno\fP]\fBtcflag\fP -Set the TC flag. -.TP -\fB+\fP[\fBno\fP]\fBrdflag\fP -Set the RD flag. -.TP -\fB+\fP[\fBno\fP]\fBrecurse\fP -Same as \fB+\fP[\fBno\fP]\fBrdflag\fP -.TP -\fB+\fP[\fBno\fP]\fBraflag\fP -Set the RA flag. -.TP -\fB+\fP[\fBno\fP]\fBzflag\fP -Set the zero flag bit. -.TP -\fB+\fP[\fBno\fP]\fBadflag\fP -Set the AD flag. -.TP -\fB+\fP[\fBno\fP]\fBcdflag\fP -Set the CD flag. -.TP -\fB+\fP[\fBno\fP]\fBdnssec\fP -Set the DO flag. -.TP -\fB+\fP[\fBno\fP]\fBall\fP -Show all packet sections. -.TP -\fB+\fP[\fBno\fP]\fBqr\fP -Show the query packet. -.TP -\fB+\fP[\fBno\fP]\fBheader\fP -Show the packet header. -.TP -\fB+\fP[\fBno\fP]\fBcomments\fP -Show commented section names. -.TP -\fB+\fP[\fBno\fP]\fBopt\fP -Show the EDNS pseudosection. -.TP -\fB+\fP[\fBno\fP]\fBopttext\fP -Try to show unknown EDNS options as text. -.TP -\fB+\fP[\fBno\fP]\fBoptpresent\fP -Show EDNS in presentation format according to the specification in version -\fI\%draft\-peltan\-edns\-presentation\-format\-01\fP\&. -.TP -\fB+\fP[\fBno\fP]\fBquestion\fP -Show the question section. -.TP -\fB+\fP[\fBno\fP]\fBanswer\fP -Show the answer section. -.TP -\fB+\fP[\fBno\fP]\fBauthority\fP -Show the authority section. -.TP -\fB+\fP[\fBno\fP]\fBadditional\fP -Show the additional section. -.TP -\fB+\fP[\fBno\fP]\fBtsig\fP -Show the TSIG pseudosection. -.TP -\fB+\fP[\fBno\fP]\fBstats\fP -Show trailing packet statistics. -.TP -\fB+\fP[\fBno\fP]\fBclass\fP -Show the DNS class. -.TP -\fB+\fP[\fBno\fP]\fBttl\fP -Show the TTL value. -.TP -\fB+\fP[\fBno\fP]\fBtcp\fP -Use the TCP protocol (default is UDP for standard query and TCP for AXFR/IXFR). -.TP -\fB+\fP[\fBno\fP]\fBfastopen\fP -Use TCP Fast Open. -.TP -\fB+\fP[\fBno\fP]\fBignore\fP -Don\(aqt use TCP automatically if a truncated reply is received. -.TP -\fB+\fP[\fBno\fP]\fBkeepopen\fP -Keep TCP connection open for the following query if it has the same connection -configuration. This applies to +tcp, +tls, and +https operations. The connection -is considered in the context of a single kdig call only. -.TP -\fB+\fP[\fBno\fP]\fBtls\fP -Use TLS with the Opportunistic privacy profile (\fI\%RFC 7858#section\-4.1\fP). -.TP -\fB+\fP[\fBno\fP]\fBtls\-ca\fP[=\fIFILE\fP] -Use TLS with a certificate validation. Certification authority certificates -are loaded from the specified PEM file (default is system certificate storage -if no argument is provided). -Can be specified multiple times. If the +tls\-hostname option is not provided, -the name of the target server (if specified) is used for strict authentication. -.TP -\fB+\fP[\fBno\fP]\fBtls\-pin\fP=\fIBASE64\fP -Use TLS with the Out\-of\-Band key\-pinned privacy profile (\fI\%RFC 7858#section\-4.2\fP). -The PIN must be a Base64 encoded SHA\-256 hash of the X.509 SubjectPublicKeyInfo. -Can be specified multiple times. -.TP -\fB+\fP[\fBno\fP]\fBtls\-hostname\fP=\fISTR\fP -Use TLS with a remote server hostname check. -.TP -\fB+\fP[\fBno\fP]\fBtls\-sni\fP=\fISTR\fP -Use TLS with a Server Name Indication. -.TP -\fB+\fP[\fBno\fP]\fBtls\-keyfile\fP=\fIFILE\fP -Use TLS with a client keyfile. -.TP -\fB+\fP[\fBno\fP]\fBtls\-certfile\fP=\fIFILE\fP -Use TLS with a client certfile. -.TP -\fB+\fP[\fBno\fP]\fBtls\-ocsp\-stapling\fP[=\fIH\fP] -Use TLS with a valid stapled OCSP response for the server certificate -(%u or specify hours). OCSP responses older than the specified period are -considered invalid. -.TP -\fB+\fP[\fBno\fP]\fBhttps\fP[=\fIURL\fP] -Use HTTPS (DNS\-over\-HTTPS) in wire format (\fI\%RFC 1035#section\-4.2.1\fP). -It is also possible to specify URL=[authority][/path] where request -will be sent to. Any leading scheme and authority indicator (i.e. //) are ignored. -Authority might also be specified as the \fIserver\fP (using the parameter \fI@\fP). -If \fIpath\fP is specified and \fIauthority\fP is missing, then the \fIserver\fP -is used as authority together with the specified \fIpath\fP\&. -Library \fIlibnghttp2\fP is required. -.TP -\fB+\fP[\fBno\fP]\fBhttps\-get\fP -Use HTTPS with HTTP/GET method instead of the default HTTP/POST method. -Library \fIlibnghttp2\fP is required. -.TP -\fB+\fP[\fBno\fP]\fBquic\fP -Use QUIC (DNS\-over\-QUIC). -.TP -\fB+\fP[\fBno\fP]\fBnsid\fP -Request the nameserver identifier (NSID). -.TP -\fB+\fP[\fBno\fP]\fBbufsize\fP=\fIB\fP -Set EDNS buffer size in bytes (default is 4096 bytes). -.TP -\fB+\fP[\fBno\fP]\fBpadding\fP[=\fIB\fP] -Use EDNS(0) padding option to pad queries, optionally to a specific -size. The default is to pad queries with a sensible amount when using -+tls, and not to pad at all when queries are sent without TLS. With -no argument (i.e., just +padding) pad every query with a sensible -amount regardless of the use of TLS. With +nopadding, never pad. -.TP -\fB+\fP[\fBno\fP]\fBalignment\fP[=\fIB\fP] -Align the query to B\-byte\-block message using the EDNS(0) padding option -(default is no or 128 if no argument is specified). -.TP -\fB+\fP[\fBno\fP]\fBsubnet\fP=\fISUBN\fP -Set EDNS(0) client subnet SUBN=addr/prefix. -.TP -\fB+\fP[\fBno\fP]\fBedns\fP[=\fIN\fP] -Use EDNS version (default is 0). -.TP -\fB+\fP[\fBno\fP]\fBtimeout\fP=\fIT\fP -Set the wait\-for\-reply interval in seconds (default is 5 seconds). This timeout -applies to each query attempt. Zero value or \fInotimeout\fP is interpreted as -infinity. -.TP -\fB+\fP[\fBno\fP]\fBretry\fP=\fIN\fP -Set the number (>=0) of UDP retries (default is 2). This doesn\(aqt apply to -AXFR/IXFR. -.TP -\fB+\fP[\fBno\fP]\fBexpire\fP -Sets the EXPIRE EDNS option. -.TP -\fB+\fP[\fBno\fP]\fBcookie\fP[=\fIHEX\fP] -Attach EDNS(0) cookie to the query. -.TP -\fB+\fP[\fBno\fP]\fBbadcookie\fP -Repeat a query with the correct cookie. -.TP -\fB+\fP[\fBno\fP]\fBednsopt\fP[=\fICODE\fP[:\fIHEX\fP]] -Send custom EDNS option. The \fICODE\fP is EDNS option code in decimal, \fIHEX\fP -is an optional hex encoded string to use as EDNS option value. This argument -can be used multiple times. +noednsopt clears all EDNS options specified by -+ednsopt. -.TP -\fB+\fP[\fBno\fP]\fBproxy\fP=\fISRC_ADDR\fP[#\fISRC_PORT\fP]\-\fIDST_ADDR\fP[#\fIDST_PORT\fP] -Add PROXYv2 header with the specified source and destination addresses to the query. -The default source port is 0 and destination port 53. -.TP -\fB+\fP[\fBno\fP]\fBjson\fP -Use JSON for output encoding (RFC 8427). -.TP -\fB+noidn\fP -Disable the IDN transformation to ASCII and vice versa. IDN support depends -on libidn availability during project building! If used in \fIcommon\-settings\fP, -all IDN transformations are disabled. If used in the individual query \fIsettings\fP, -transformation from ASCII is disabled on output for the particular query. Note -that IDN transformation does not preserve domain name letter case. -.UNINDENT -.SH NOTES -.sp -Options \fB\-k\fP and \fB\-y\fP can not be used simultaneously. -.sp -Dnssec\-keygen keyfile format is not supported. Use \fBkeymgr(8)\fP instead. -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH EXAMPLES -.INDENT 0.0 -.IP 1. 3 -Get A records for example.com: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ kdig example.com A -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 2. 3 -Perform AXFR for zone example.com from the server 192.0.2.1: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ kdig example.com \-t AXFR @192.0.2.1 -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 3. 3 -Get A records for example.com from 192.0.2.1 and reverse lookup for address -2001:DB8::1 from 192.0.2.2. Both using the TCP protocol: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ kdig +tcp example.com \-t A @192.0.2.1 \-x 2001:DB8::1 @192.0.2.2 -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 4. 3 -Get SOA record for example.com, use TLS, use system certificates, check -for specified hostname, check for certificate pin, and print additional -debug info: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ kdig \-d @185.49.141.38 +tls\-ca +tls\-host=getdnsapi.net \e - +tls\-pin=foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9S= soa example.com -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 5. 3 -DNS over HTTPS examples (various DoH implementations): -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ kdig @1.1.1.1 +https example.com. -$ kdig @193.17.47.1 +https=/doh example.com. -$ kdig @8.8.4.4 +https +https\-get example.com. -$ kdig @8.8.8.8 +https +tls\-hostname=dns.google +fastopen example.com. -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 6. 3 -More queries share one DoT connection: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ kdig @1.1.1.1 +tls +keepopen abc.example.com A mail.example.com AAAA -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SH FILES -.sp -\fB/etc/resolv.conf\fP -.SH SEE ALSO -.sp -\fBkhost(1)\fP, \fBknsupdate(1)\fP, \fBkeymgr(8)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/keymgr.8 b/doc/man/keymgr.8 new file mode 100644 index 0000000..a963df3 --- /dev/null +++ b/doc/man/keymgr.8 @@ -0,0 +1,390 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KEYMGR" "8" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +keymgr \- Knot DNS key management utility +.SH SYNOPSIS +.sp +\fBkeymgr\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIzone_name\fP \fIcommand\fP +.sp +\fBkeymgr\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIkeystore_id\fP \fIcommand\fP +.sp +\fBkeymgr\fP [\fIconfig_option\fP] [\-j] \fB\-l\fP +.sp +\fBkeymgr\fP \fB\-t\fP \fIparameter\fP\&... +.SH DESCRIPTION +.sp +The \fBkeymgr\fP utility serves for manual key management in Knot DNS server. +.sp +Functions for DNSSEC keys and KASP (Key And Signature Policy) +management are provided. +.sp +The DNSSEC and KASP configuration is stored in a so called KASP database. +The database is backed by LMDB. +.SS Parameters +.INDENT 0.0 +.TP +.B \fIzone_name\fP +Name of the zone the command is executed for. +.UNINDENT +.SS Config options +.INDENT 0.0 +.TP +\fB\-c\fP, \fB\-\-config\fP \fIfile\fP +Use a textual configuration file (default is \fB/usr/local/etc/knot/knot.conf\fP). +.TP +\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP +Use a binary configuration database directory (default is \fB/usr/local/var/lib/knot/confdb\fP). +The default configuration database, if exists, has a preference to the default +configuration file. +.TP +\fB\-D\fP, \fB\-\-dir\fP \fIpath\fP +Use specified KASP database path and default configuration. +.UNINDENT +.SS Options +.INDENT 0.0 +.TP +\fB\-t\fP, \fB\-\-tsig\fP \fItsig_name\fP [\fItsig_algorithm\fP [\fItsig_bits\fP]] +Generates a TSIG key for the given name. Optionally the key algorithm can +be specified by its \fI\%name\fP (default: hmac\-sha256) and +a bit length of the key (default: optimal length given by algorithm). +The generated TSIG key is only displayed on \fIstdout\fP: +the command does not create a file, nor include the key in a keystore. +.TP +\fB\-e\fP, \fB\-\-extended\fP +Extended output (listing of keys with full description). +.TP +\fB\-j\fP, \fB\-\-json\fP +Print the zones or keys in JSON format. +.TP +\fB\-l\fP, \fB\-\-list\fP +Print the list of zones that have at least one key stored in the configured KASP +database. +.TP +\fB\-x\fP, \fB\-\-mono\fP +Don\(aqt generate colorized output. +.TP +\fB\-X\fP, \fB\-\-color\fP +Force colorized output in the normal mode. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Keymgr runs with the same user privileges as configured for \fI\%knotd\fP\&. +For example, if keymgr is run as \fBroot\fP, but the configured \fI\%user\fP +is \fBknot\fP, it won\(aqt be able to read files (PEM files, KASP database, ...) readable +only by \fBroot\fP\&. +.UNINDENT +.UNINDENT +.SS Commands +.INDENT 0.0 +.TP +\fBlist\fP [\fItimestamp_format\fP] +Prints the list of key IDs and parameters of keys belonging to the zone. +.TP +\fBgenerate\fP [\fIarguments\fP\&...] +Generates new DNSSEC key and stores it in KASP database. Prints the key ID. +This action takes some number of arguments (see below). Values for unspecified arguments are taken +from corresponding policy (if \fI\-c\fP or \fI\-C\fP options used) or from Knot policy defaults. +.TP +\fBimport\-bind\fP \fIBIND_key_file\fP +Imports a BIND\-style key into KASP database (converting it to PEM format). +Takes one argument: path to BIND key file (private or public, but both MUST exist). +.TP +\fBimport\-pub\fP \fIBIND_pubkey_file\fP +Imports a public key into KASP database. This key won\(aqt be rolled over nor used for signing. +Takes one argument: path to BIND public key file. +.TP +\fBimport\-pem\fP \fIPEM_file\fP [\fIarguments\fP\&...] +Imports a DNSSEC key from PEM file. The key parameters (same as for the generate action) need to be +specified (mainly algorithm, timers...) because they are not contained in the PEM format. +.TP +\fBimport\-pkcs11\fP \fIkey_id\fP [\fIarguments\fP\&...] +Imports a DNSSEC key from PKCS #11 storage. The key parameters (same as for the generate action) need to be +specified (mainly algorithm, timers...) because they are not available. In fact, no key +data is imported, only KASP database metadata is created. +.TP +\fBnsec3\-salt\fP [\fInew_salt\fP] +Prints the current NSEC3 salt used for signing. If \fInew_salt\fP is specified, the salt is overwritten. +The salt is printed and expected in hexadecimal, or dash if empty. +.TP +\fBlocal\-serial\fP [\fInew_serial\fP] +Print SOA serial stored in KASP database when using on\-secondary DNSSEC signing. +If \fInew_serial\fP is specified, the serial is overwritten. After updating the serial, expire the zone +(\fBzone\-purge +expire +zonefile +journal\fP) if the server is running, or remove corresponding zone file +and journal contents if the server is stopped. +.TP +\fBmaster\-serial\fP [\fInew_serial\fP] +Print SOA serial of the remote master stored in KASP database when using on\-secondary DNSSEC signing. +If \fInew_serial\fP is specified, the serial is overwritten (not recommended). +.TP +\fBset\fP \fIkey_spec\fP [\fIarguments\fP\&...] +Changes a timing argument (or ksk/zsk) of an existing key to a new value. \fIKey_spec\fP is either the +key tag or a prefix of the key ID, with an optional \fI[id=|keytag=]\fP prefix; \fIarguments\fP +are like for \fBgenerate\fP, but just the related ones. +.TP +\fBds\fP [\fIkey_spec\fP] +Generate DS record (all digest algorithms together) for specified key. \fIKey_spec\fP +is like for \fBset\fP, if unspecified, all KSKs are used. +.TP +\fBdnskey\fP [\fIkey_spec\fP] +Generate DNSKEY record for specified key. \fIKey_spec\fP +is like for \fBds\fP, if unspecified, all KSKs are used. +.TP +\fBdelete\fP \fIkey_spec\fP +Remove the specified key from zone. If the key was not shared, it is also deleted from keystore. +.TP +\fBshare\fP \fIkey_ID\fP \fIzone_from\fP +Import a key (specified by full key ID) from another zone as shared. After this, the key is +owned by both zones equally. +.UNINDENT +.SS Keystore commands +.INDENT 0.0 +.TP +\fBkeystore\-test\fP +Conduct some tests on the specified keystore. For each algorithm, key generation, +import, removal, and use (signing and verification) are tested. +Use a configured \fIkeystore_id\fP or \fB\-\fP for the default. +.TP +\fBkeystore\-bench\fP [\fInum_threads\fP] +Conduct a signing benchmark on the specified keystore. +Random blocks of data are signed by the selected number of threads +(default is 1) in a loop, and the average number of signing operations per +second for each algorithm is returned. +Use a configured \fIkeystore_id\fP or \fB\-\fP for the default. +.UNINDENT +.SS Commands related to Offline KSK feature +.INDENT 0.0 +.TP +\fBpregenerate\fP [\fItimestamp\-from\fP] \fItimestamp\-to\fP +Pre\-generate ZSKs for use with offline KSK, for the specified period starting from now or specified time. +This function also applies to non\-offline KSK keys. +.TP +\fBshow\-offline\fP [\fItimestamp\-from\fP] [\fItimestamp\-to\fP] +Print pre\-generated offline key\-related records for specified time interval. If \fItimestamp_to\fP +is omitted, it will be to infinity. If \fItimestamp\-from\fP is omitted, it will start from the +beginning. +.TP +\fBdel\-offline\fP \fItimestamp\-from\fP \fItimestamp\-to\fP +Delete pre\-generated offline key\-related records in specified time interval. +.TP +\fBdel\-all\-old\fP +Delete old keys that are in state \(aqremoved\(aq. This function also applies to +non\-offline KSK keys. +.TP +\fBgenerate\-ksr\fP [\fItimestamp\-from\fP] \fItimestamp\-to\fP +Print to stdout KeySigningRequest based on pre\-generated ZSKs for specified time period. +If \fItimestamp\-from\fP is omitted, timestamp of the last offline records set is used +or now if no records available. +.TP +\fBsign\-ksr\fP \fIksr_file\fP +Read KeySigningRequest from a text file, sign it using local keyset and print SignedKeyResponse to stdout. +.TP +\fBvalidate\-skr\fP \fIskr_file\fP +Read SignedKeyResponse from a text file and validate the RRSIGs in it if not corrupt. +.TP +\fBimport\-skr\fP \fIskr_file\fP +Read SignedKeyResponse from a text file and import the signatures for later use in zone. If some +signatures have already been imported, they will be deleted for the period from beginning of the SKR +to infinity. +.UNINDENT +.SS Generate arguments +.sp +Arguments are separated by space, each of them is in format \(aqname=value\(aq. +.INDENT 0.0 +.TP +\fBalgorithm\fP +Either an algorithm number (e.g. 14) or \fI\%algorithm name\fP +without dashes (e.g. ECDSAP384SHA384). +.TP +\fBsize\fP +Key length in bits. +.TP +\fBksk\fP +If set to \fByes\fP, the key will be used for signing DNSKEY rrset. The generated key will also +have the Secure Entry Point flag set to 1. +.TP +\fBzsk\fP +If set to \fByes\fP, the key will be used for signing zone (except DNSKEY rrset). This flag can +be set concurrently with the \fBksk\fP flag. +.TP +\fBsep\fP +Overrides the standard setting of the Secure Entry Point flag. +.UNINDENT +.sp +The following arguments are timestamps of key lifetime (see \fI\%DNSSEC key states\fP): +.INDENT 0.0 +.TP +\fBpre_active\fP +Key started to be used for signing, not published (only for algorithm rollover). +.TP +\fBpublish\fP +Key published. +.TP +\fBready\fP +Key is waiting for submission (only for KSK). +.TP +\fBactive\fP +Key used for signing. +.TP +\fBretire_active\fP +Key still used for signing, but another key is active (only for KSK or algorithm rollover). +.TP +\fBretire\fP +Key still published, but no longer used for signing. +.TP +\fBpost_active\fP +Key no longer published, but still used for signing (only for algorithm rollover). +.TP +\fBrevoke\fP +Key revoked according to \fI\%RFC 5011\fP trust anchor roll\-over. +.TP +\fBremove\fP +Key deleted. +.UNINDENT +.SS Timestamps +.INDENT 0.0 +.TP +.B 0 +Zero timestamp means infinite future. +.TP +.B \fIUNIX_time\fP +Positive number of seconds since 1970 UTC. +.TP +.B \fIYYYYMMDDHHMMSS\fP +Date and time in this format without any punctuation. +.TP +.B \fIrelative_timestamp\fP +A sign character (\fB+\fP, \fB\-\fP), a number, and an optional time unit +(\fBy\fP, \fBmo\fP, \fBd\fP, \fBh\fP, \fBmi\fP, \fBs\fP). The default unit is one second. +E.g. +1mi, \-2mo. +.UNINDENT +.SS Output timestamp formats +.INDENT 0.0 +.TP +.B (none) +The timestamps are printed as UNIX timestamp. +.TP +\fBhuman\fP +The timestamps are printed relatively to now using time units (e.g. \-2y5mo, +1h13s). +.TP +\fBiso\fP +The timestamps are printed in the ISO8601 format (e.g. 2016\-12\-31T23:59:00). +.UNINDENT +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH EXAMPLES +.INDENT 0.0 +.IP 1. 3 +Generate new TSIG key: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ keymgr \-t my_name hmac\-sha384 +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 2. 3 +Generate new DNSSEC key: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \e + ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 3. 3 +Import a DNSSEC key from BIND: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ keymgr example.com. import\-bind ~/bind/Kharbinge4d5.+007+63089.key +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 4. 3 +Configure key timing: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 5. 3 +Share a KSK from another zone: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another\-zone.com. +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fI\%RFC 6781\fP \- DNSSEC Operational Practices. +\fI\%RFC 7583\fP \- DNSSEC Key Rollover Timing Considerations. +.sp +\fBknot.conf(5)\fP, +\fBknotc(8)\fP, +\fBknotd(8)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/keymgr.8in b/doc/man/keymgr.8in deleted file mode 100644 index 020d854..0000000 --- a/doc/man/keymgr.8in +++ /dev/null @@ -1,389 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KEYMGR" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -keymgr \- Knot DNS key management utility -.SH SYNOPSIS -.sp -\fBkeymgr\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIzone_name\fP \fIcommand\fP -.sp -\fBkeymgr\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIkeystore_id\fP \fIcommand\fP -.sp -\fBkeymgr\fP [\fIconfig_option\fP] [\-j] \fB\-l\fP -.sp -\fBkeymgr\fP \fB\-t\fP \fIparameter\fP\&... -.SH DESCRIPTION -.sp -The \fBkeymgr\fP utility serves for manual key management in Knot DNS server. -.sp -Functions for DNSSEC keys and KASP (Key And Signature Policy) -management are provided. -.sp -The DNSSEC and KASP configuration is stored in a so called KASP database. -The database is backed by LMDB. -.SS Parameters -.INDENT 0.0 -.TP -\fIzone_name\fP -Name of the zone the command is executed for. -.UNINDENT -.SS Config options -.INDENT 0.0 -.TP -\fB\-c\fP, \fB\-\-config\fP \fIfile\fP -Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). -.TP -\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP -Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). -The default configuration database, if exists, has a preference to the default -configuration file. -.TP -\fB\-D\fP, \fB\-\-dir\fP \fIpath\fP -Use specified KASP database path and default configuration. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-t\fP, \fB\-\-tsig\fP \fItsig_name\fP [\fItsig_algorithm\fP [\fItsig_bits\fP]] -Generates a TSIG key for the given name. Optionally the key algorithm can -be specified by its \fI\%name\fP (default: hmac\-sha256) and -a bit length of the key (default: optimal length given by algorithm). -The generated TSIG key is only displayed on \fIstdout\fP: -the command does not create a file, nor include the key in a keystore. -.TP -\fB\-e\fP, \fB\-\-extended\fP -Extended output (listing of keys with full description). -.TP -\fB\-j\fP, \fB\-\-json\fP -Print the zones or keys in JSON format. -.TP -\fB\-l\fP, \fB\-\-list\fP -Print the list of zones that have at least one key stored in the configured KASP -database. -.TP -\fB\-x\fP, \fB\-\-mono\fP -Don\(aqt generate colorized output. -.TP -\fB\-X\fP, \fB\-\-color\fP -Force colorized output in the normal mode. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Keymgr runs with the same user privileges as configured for \fI\%knotd\fP\&. -For example, if keymgr is run as \fBroot\fP, but the configured \fI\%user\fP -is \fBknot\fP, it won\(aqt be able to read files (PEM files, KASP database, ...) readable -only by \fBroot\fP\&. -.UNINDENT -.UNINDENT -.SS Commands -.INDENT 0.0 -.TP -\fBlist\fP [\fItimestamp_format\fP] -Prints the list of key IDs and parameters of keys belonging to the zone. -.TP -\fBgenerate\fP [\fIarguments\fP\&...] -Generates new DNSSEC key and stores it in KASP database. Prints the key ID. -This action takes some number of arguments (see below). Values for unspecified arguments are taken -from corresponding policy (if \fI\-c\fP or \fI\-C\fP options used) or from Knot policy defaults. -.TP -\fBimport\-bind\fP \fIBIND_key_file\fP -Imports a BIND\-style key into KASP database (converting it to PEM format). -Takes one argument: path to BIND key file (private or public, but both MUST exist). -.TP -\fBimport\-pub\fP \fIBIND_pubkey_file\fP -Imports a public key into KASP database. This key won\(aqt be rolled over nor used for signing. -Takes one argument: path to BIND public key file. -.TP -\fBimport\-pem\fP \fIPEM_file\fP [\fIarguments\fP\&...] -Imports a DNSSEC key from PEM file. The key parameters (same as for the generate action) need to be -specified (mainly algorithm, timers...) because they are not contained in the PEM format. -.TP -\fBimport\-pkcs11\fP \fIkey_id\fP [\fIarguments\fP\&...] -Imports a DNSSEC key from PKCS #11 storage. The key parameters (same as for the generate action) need to be -specified (mainly algorithm, timers...) because they are not available. In fact, no key -data is imported, only KASP database metadata is created. -.TP -\fBnsec3\-salt\fP [\fInew_salt\fP] -Prints the current NSEC3 salt used for signing. If \fInew_salt\fP is specified, the salt is overwritten. -The salt is printed and expected in hexadecimal, or dash if empty. -.TP -\fBlocal\-serial\fP [\fInew_serial\fP] -Print SOA serial stored in KASP database when using on\-secondary DNSSEC signing. -If \fInew_serial\fP is specified, the serial is overwritten. After updating the serial, expire the zone -(\fBzone\-purge +expire +zonefile +journal\fP) if the server is running, or remove corresponding zone file -and journal contents if the server is stopped. -.TP -\fBmaster\-serial\fP [\fInew_serial\fP] -Print SOA serial of the remote master stored in KASP database when using on\-secondary DNSSEC signing. -If \fInew_serial\fP is specified, the serial is overwritten (not recommended). -.TP -\fBset\fP \fIkey_spec\fP [\fIarguments\fP\&...] -Changes a timing argument (or ksk/zsk) of an existing key to a new value. \fIKey_spec\fP is either the -key tag or a prefix of the key ID, with an optional \fI[id=|keytag=]\fP prefix; \fIarguments\fP -are like for \fBgenerate\fP, but just the related ones. -.TP -\fBds\fP [\fIkey_spec\fP] -Generate DS record (all digest algorithms together) for specified key. \fIKey_spec\fP -is like for \fBset\fP, if unspecified, all KSKs are used. -.TP -\fBdnskey\fP [\fIkey_spec\fP] -Generate DNSKEY record for specified key. \fIKey_spec\fP -is like for \fBds\fP, if unspecified, all KSKs are used. -.TP -\fBdelete\fP \fIkey_spec\fP -Remove the specified key from zone. If the key was not shared, it is also deleted from keystore. -.TP -\fBshare\fP \fIkey_ID\fP \fIzone_from\fP -Import a key (specified by full key ID) from another zone as shared. After this, the key is -owned by both zones equally. -.UNINDENT -.SS Keystore commands -.INDENT 0.0 -.TP -\fBkeystore\-test\fP -Conduct some tests on the specified keystore. For each algorithm, key generation, -import, removal, and use (signing and verification) are tested. -Use a configured \fIkeystore_id\fP or \fB\-\fP for the default. -.TP -\fBkeystore\-bench\fP [\fInum_threads\fP] -Conduct a signing benchmark on the specified keystore. -Random blocks of data are signed by the selected number of threads -(default is 1) in a loop, and the average number of signing operations per -second for each algorithm is returned. -Use a configured \fIkeystore_id\fP or \fB\-\fP for the default. -.UNINDENT -.SS Commands related to Offline KSK feature -.INDENT 0.0 -.TP -\fBpregenerate\fP [\fItimestamp\-from\fP] \fItimestamp\-to\fP -Pre\-generate ZSKs for use with offline KSK, for the specified period starting from now or specified time. -This function also applies to non\-offline KSK keys. -.TP -\fBshow\-offline\fP [\fItimestamp\-from\fP] [\fItimestamp\-to\fP] -Print pre\-generated offline key\-related records for specified time interval. If \fItimestamp_to\fP -is omitted, it will be to infinity. If \fItimestamp\-from\fP is omitted, it will start from the -beginning. -.TP -\fBdel\-offline\fP \fItimestamp\-from\fP \fItimestamp\-to\fP -Delete pre\-generated offline key\-related records in specified time interval. -.TP -\fBdel\-all\-old\fP -Delete old keys that are in state \(aqremoved\(aq. This function also applies to -non\-offline KSK keys. -.TP -\fBgenerate\-ksr\fP [\fItimestamp\-from\fP] \fItimestamp\-to\fP -Print to stdout KeySigningRequest based on pre\-generated ZSKs for specified time period. -If \fItimestamp\-from\fP is omitted, timestamp of the last offline records set is used -or now if no records available. -.TP -\fBsign\-ksr\fP \fIksr_file\fP -Read KeySigningRequest from a text file, sign it using local keyset and print SignedKeyResponse to stdout. -.TP -\fBvalidate\-skr\fP \fIskr_file\fP -Read SignedKeyResponse from a text file and validate the RRSIGs in it if not corrupt. -.TP -\fBimport\-skr\fP \fIskr_file\fP -Read SignedKeyResponse from a text file and import the signatures for later use in zone. If some -signatures have already been imported, they will be deleted for the period from beginning of the SKR -to infinity. -.UNINDENT -.SS Generate arguments -.sp -Arguments are separated by space, each of them is in format \(aqname=value\(aq. -.INDENT 0.0 -.TP -\fBalgorithm\fP -Either an algorithm number (e.g. 14) or \fI\%algorithm name\fP -without dashes (e.g. ECDSAP384SHA384). -.TP -\fBsize\fP -Key length in bits. -.TP -\fBksk\fP -If set to \fByes\fP, the key will be used for signing DNSKEY rrset. The generated key will also -have the Secure Entry Point flag set to 1. -.TP -\fBzsk\fP -If set to \fByes\fP, the key will be used for signing zone (except DNSKEY rrset). This flag can -be set concurrently with the \fBksk\fP flag. -.TP -\fBsep\fP -Overrides the standard setting of the Secure Entry Point flag. -.UNINDENT -.sp -The following arguments are timestamps of key lifetime (see \fI\%DNSSEC key states\fP): -.INDENT 0.0 -.TP -\fBpre_active\fP -Key started to be used for signing, not published (only for algorithm rollover). -.TP -\fBpublish\fP -Key published. -.TP -\fBready\fP -Key is waiting for submission (only for KSK). -.TP -\fBactive\fP -Key used for signing. -.TP -\fBretire_active\fP -Key still used for signing, but another key is active (only for KSK or algorithm rollover). -.TP -\fBretire\fP -Key still published, but no longer used for signing. -.TP -\fBpost_active\fP -Key no longer published, but still used for signing (only for algorithm rollover). -.TP -\fBrevoke\fP -Key revoked according to \fI\%RFC 5011\fP trust anchor roll\-over. -.TP -\fBremove\fP -Key deleted. -.UNINDENT -.SS Timestamps -.INDENT 0.0 -.TP -0 -Zero timestamp means infinite future. -.TP -\fIUNIX_time\fP -Positive number of seconds since 1970 UTC. -.TP -\fIYYYYMMDDHHMMSS\fP -Date and time in this format without any punctuation. -.TP -\fIrelative_timestamp\fP -A sign character (\fB+\fP, \fB\-\fP), a number, and an optional time unit -(\fBy\fP, \fBmo\fP, \fBd\fP, \fBh\fP, \fBmi\fP, \fBs\fP). The default unit is one second. -E.g. +1mi, \-2mo. -.UNINDENT -.SS Output timestamp formats -.INDENT 0.0 -.TP -(none) -The timestamps are printed as UNIX timestamp. -.TP -\fBhuman\fP -The timestamps are printed relatively to now using time units (e.g. \-2y5mo, +1h13s). -.TP -\fBiso\fP -The timestamps are printed in the ISO8601 format (e.g. 2016\-12\-31T23:59:00). -.UNINDENT -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH EXAMPLES -.INDENT 0.0 -.IP 1. 3 -Generate new TSIG key: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ keymgr \-t my_name hmac\-sha384 -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 2. 3 -Generate new DNSSEC key: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ keymgr example.com. generate algorithm=ECDSAP256SHA256 size=256 \e - ksk=true created=1488034625 publish=20170223205611 retire=+10mo remove=+1y -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 3. 3 -Import a DNSSEC key from BIND: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ keymgr example.com. import\-bind ~/bind/Kharbinge4d5.+007+63089.key -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 4. 3 -Configure key timing: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ keymgr example.com. set 4208 active=+2mi retire=+4mi remove=+5mi -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 5. 3 -Share a KSK from another zone: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ keymgr example.com. share e687cf927029e9db7184d2ece6d663f5d1e5b0e9 another\-zone.com. -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fI\%RFC 6781\fP \- DNSSEC Operational Practices. -\fI\%RFC 7583\fP \- DNSSEC Key Rollover Timing Considerations. -.sp -\fBknot.conf(5)\fP, -\fBknotc(8)\fP, -\fBknotd(8)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/khost.1 b/doc/man/khost.1 new file mode 100644 index 0000000..4cae5e9 --- /dev/null +++ b/doc/man/khost.1 @@ -0,0 +1,157 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KHOST" "1" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +khost \- Simple DNS lookup utility +.SH SYNOPSIS +.sp +\fBkhost\fP [\fIoptions\fP] \fIname\fP [\fIserver\fP] +.SH DESCRIPTION +.sp +This utility sends a DNS query for the \fIname\fP to the \fIserver\fP and prints a reply +in more user\-readable form. For more advanced DNS queries use \fI\%kdig\fP +instead. +.SS Parameters +.INDENT 0.0 +.TP +.B \fIname\fP +Is a domain name that is to be looked up. If the \fIname\fP is IPv4 or IPv6 +address the PTR query type is used. +.TP +.B \fIserver\fP +Is a name or an address of the nameserver to send a query to. The address +can be specified using [address]:port notation. If no server is specified, +the servers from \fB/etc/resolv.conf\fP are used. +.UNINDENT +.sp +If no arguments are provided, \fBkhost\fP prints a short help. +.SS Options +.INDENT 0.0 +.TP +\fB\-4\fP +Use the IPv4 protocol only. +.TP +\fB\-6\fP +Use the IPv6 protocol only. +.TP +\fB\-a\fP +Send ANY query with verbose mode. +.TP +\fB\-d\fP +Enable debug messages. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-r\fP +Disable recursion. +.TP +\fB\-T\fP +Use the TCP protocol. +.TP +\fB\-v\fP +Enable verbose output. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.TP +\fB\-w\fP +Wait forever for the reply. +.TP +\fB\-c\fP \fIclass\fP +Set the query class (e.g. CH, CLASS4). The default class is IN. +.TP +\fB\-t\fP \fItype\fP +Set the query type (e.g. NS, IXFR=12345, TYPE65535). The default is to send 3 +queries (A, AAAA and MX). +.TP +\fB\-R\fP \fIretries\fP +The number (>=0) of UDP retries to query a nameserver. The default is 1. +.TP +\fB\-W\fP \fIwait\fP +The time to wait for a reply in seconds. This timeout applies to each query +try. The default is 2 seconds. +.UNINDENT +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH EXAMPLES +.INDENT 0.0 +.IP 1. 3 +Get the A, AAAA and MX records for example.com: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ khost example.com +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 2. 3 +Get the reverse record for address 192.0.2.1: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ khost 192.0.2.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 3. 3 +Perform a verbose zone transfer for zone example.com: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ khost \-t AXFR \-v example.com +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SH FILES +.sp +\fB/etc/resolv.conf\fP +.SH SEE ALSO +.sp +\fBkdig(1)\fP, \fBknsupdate(1)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/khost.1in b/doc/man/khost.1in deleted file mode 100644 index 292f080..0000000 --- a/doc/man/khost.1in +++ /dev/null @@ -1,156 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KHOST" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -khost \- Simple DNS lookup utility -.SH SYNOPSIS -.sp -\fBkhost\fP [\fIoptions\fP] \fIname\fP [\fIserver\fP] -.SH DESCRIPTION -.sp -This utility sends a DNS query for the \fIname\fP to the \fIserver\fP and prints a reply -in more user\-readable form. For more advanced DNS queries use \fI\%kdig\fP -instead. -.SS Parameters -.INDENT 0.0 -.TP -\fIname\fP -Is a domain name that is to be looked up. If the \fIname\fP is IPv4 or IPv6 -address the PTR query type is used. -.TP -\fIserver\fP -Is a name or an address of the nameserver to send a query to. The address -can be specified using [address]:port notation. If no server is specified, -the servers from \fB/etc/resolv.conf\fP are used. -.UNINDENT -.sp -If no arguments are provided, \fBkhost\fP prints a short help. -.SS Options -.INDENT 0.0 -.TP -\fB\-4\fP -Use the IPv4 protocol only. -.TP -\fB\-6\fP -Use the IPv6 protocol only. -.TP -\fB\-a\fP -Send ANY query with verbose mode. -.TP -\fB\-d\fP -Enable debug messages. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-r\fP -Disable recursion. -.TP -\fB\-T\fP -Use the TCP protocol. -.TP -\fB\-v\fP -Enable verbose output. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.TP -\fB\-w\fP -Wait forever for the reply. -.TP -\fB\-c\fP \fIclass\fP -Set the query class (e.g. CH, CLASS4). The default class is IN. -.TP -\fB\-t\fP \fItype\fP -Set the query type (e.g. NS, IXFR=12345, TYPE65535). The default is to send 3 -queries (A, AAAA and MX). -.TP -\fB\-R\fP \fIretries\fP -The number (>=0) of UDP retries to query a nameserver. The default is 1. -.TP -\fB\-W\fP \fIwait\fP -The time to wait for a reply in seconds. This timeout applies to each query -try. The default is 2 seconds. -.UNINDENT -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH EXAMPLES -.INDENT 0.0 -.IP 1. 3 -Get the A, AAAA and MX records for example.com: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ khost example.com -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 2. 3 -Get the reverse record for address 192.0.2.1: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ khost 192.0.2.1 -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 3. 3 -Perform a verbose zone transfer for zone example.com: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ khost \-t AXFR \-v example.com -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SH FILES -.sp -\fB/etc/resolv.conf\fP -.SH SEE ALSO -.sp -\fBkdig(1)\fP, \fBknsupdate(1)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/kjournalprint.8 b/doc/man/kjournalprint.8 new file mode 100644 index 0000000..4c17e36 --- /dev/null +++ b/doc/man/kjournalprint.8 @@ -0,0 +1,118 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KJOURNALPRINT" "8" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +kjournalprint \- Knot DNS journal print utility +.SH SYNOPSIS +.sp +\fBkjournalprint\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIzone_name\fP +.sp +\fBkjournalprint\fP [\fIconfig_option\fP] \fB\-z\fP +.SH DESCRIPTION +.sp +The program prints zone history stored in a journal database. As default, +changes are colored for terminal. +.SS Parameters +.INDENT 0.0 +.TP +.B \fIzone_name\fP +A name of the zone to print the history for. +.UNINDENT +.SS Config options +.INDENT 0.0 +.TP +\fB\-c\fP, \fB\-\-config\fP \fIfile\fP +Use a textual configuration file (default is \fB/usr/local/etc/knot/knot.conf\fP). +.TP +\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP +Use a binary configuration database directory (default is \fB/usr/local/var/lib/knot/confdb\fP). +The default configuration database, if exists, has a preference to the default +configuration file. +.TP +\fB\-D\fP, \fB\-\-dir\fP \fIpath\fP +Use specified journal database path and default configuration. +.UNINDENT +.SS Options +.INDENT 0.0 +.TP +\fB\-z\fP, \fB\-\-zone\-list\fP +Instead of reading the journal, display the list of zones in the DB. +.TP +\fB\-l\fP, \fB\-\-limit\fP \fIlimit\fP +Limits the number of displayed changes. +.TP +\fB\-s\fP, \fB\-\-serial\fP \fIsoa\fP +Start at a specific SOA serial. +.TP +\fB\-H\fP, \fB\-\-check\fP +Enable additional journal semantic checks during printing. +.TP +\fB\-d\fP, \fB\-\-debug\fP +Debug mode brief output. +.TP +\fB\-x\fP, \fB\-\-mono\fP +Don\(aqt generate colorized output. +.TP +\fB\-X\fP, \fB\-\-color\fP +Force colorized output. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH EXAMPLES +.sp +Last (most recent) 5 changes without colors: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ kjournalprint \-nl 5 /var/lib/knot/journal example.com. +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBknotd(8)\fP, \fBknot.conf(5)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/kjournalprint.8in b/doc/man/kjournalprint.8in deleted file mode 100644 index 2a1303a..0000000 --- a/doc/man/kjournalprint.8in +++ /dev/null @@ -1,120 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KJOURNALPRINT" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -kjournalprint \- Knot DNS journal print utility -.SH SYNOPSIS -.sp -\fBkjournalprint\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIzone_name\fP -.sp -\fBkjournalprint\fP [\fIconfig_option\fP] \fB\-z\fP -.SH DESCRIPTION -.sp -The program prints zone history stored in a journal database. As default, -changes are colored for terminal. -.SS Parameters -.INDENT 0.0 -.TP -\fIzone_name\fP -A name of the zone to print the history for. -.UNINDENT -.SS Config options -.INDENT 0.0 -.TP -\fB\-c\fP, \fB\-\-config\fP \fIfile\fP -Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). -.TP -\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP -Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). -The default configuration database, if exists, has a preference to the default -configuration file. -.TP -\fB\-D\fP, \fB\-\-dir\fP \fIpath\fP -Use specified journal database path and default configuration. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-z\fP, \fB\-\-zone\-list\fP -Instead of reading the journal, display the list of zones in the DB. -.TP -\fB\-l\fP, \fB\-\-limit\fP \fIlimit\fP -Limits the number of displayed changes. -.TP -\fB\-s\fP, \fB\-\-serial\fP \fIsoa\fP -Start at a specific SOA serial. -.TP -\fB\-H\fP, \fB\-\-check\fP -Enable additional journal semantic checks during printing. -.TP -\fB\-d\fP, \fB\-\-debug\fP -Debug mode brief output. -.TP -\fB\-x\fP, \fB\-\-mono\fP -Don\(aqt generate colorized output. -.TP -\fB\-n\fP, \fB\-\-no\-color\fP -An alias for \fB\-x\fP\&. Use of this option is deprecated, it will be removed in the future. -.TP -\fB\-X\fP, \fB\-\-color\fP -Force colorized output. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.UNINDENT -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH EXAMPLES -.sp -Last (most recent) 5 changes without colors: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ kjournalprint \-nl 5 /var/lib/knot/journal example.com. -.ft P -.fi -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fBknotd(8)\fP, \fBknot.conf(5)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/knot.conf.5 b/doc/man/knot.conf.5 new file mode 100644 index 0000000..dc6fe4a --- /dev/null +++ b/doc/man/knot.conf.5 @@ -0,0 +1,2957 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KNOT.CONF" "5" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +knot.conf \- Knot DNS configuration file +.SH DESCRIPTION +.sp +Configuration files for Knot DNS use simplified YAML format. Simplified means +that not all of the features are supported. +.sp +For the description of configuration items, we have to declare a meaning of +the following symbols: +.INDENT 0.0 +.IP \(bu 2 +\fBINT\fP – Integer +.IP \(bu 2 +\fBSTR\fP – Textual string +.IP \(bu 2 +\fBHEXSTR\fP – Hexadecimal string (with \fB0x\fP prefix) +.IP \(bu 2 +\fBBOOL\fP – Boolean value (\fBon\fP/\fBoff\fP or \fBtrue\fP/\fBfalse\fP) +.IP \(bu 2 +\fBTIME\fP – Number of seconds, an integer with a possible time multiplier suffix +(\fBs\fP ~ 1, \fBm\fP ~ 60, \fBh\fP ~ 3600, \fBd\fP ~ 24 * 3600, \fBw\fP ~ 7 * 24 * 3600, +\fBM\fP ~ 30 * 24 * 3600, \fBy\fP ~ 365 * 24 * 3600) +.IP \(bu 2 +\fBSIZE\fP – Number of bytes, an integer with a possible size multiplier suffix +(\fBB\fP ~ 1, \fBK\fP ~ 1024, \fBM\fP ~ 1024^2 or \fBG\fP ~ 1024^3) +.IP \(bu 2 +\fBBASE64\fP – Base64 encoded string +.IP \(bu 2 +\fBADDR\fP – IPv4 or IPv6 address +.IP \(bu 2 +\fBDNAME\fP – Domain name +.IP \(bu 2 +\fB\&...\fP – Multi\-valued item, order of the values is preserved +.IP \(bu 2 +\fB[\fP \fB]\fP – Optional value +.IP \(bu 2 +\fB|\fP – Choice +.UNINDENT +.sp +The configuration consists of several fixed sections and optional module +sections. There are 17 fixed sections (\fBmodule\fP, \fBserver\fP, \fBxdp\fP, \fBcontrol\fP, +\fBlog\fP, \fBstatistics\fP, \fBdatabase\fP, \fBkeystore\fP, \fBkey\fP, \fBremote\fP, +\fBremotes\fP, \fBacl\fP, \fBsubmission\fP, \fBdnskey\-sync\fP, \fBpolicy\fP, \fBtemplate\fP, +\fBzone\fP). +Module sections are prefixed with the \fBmod\-\fP prefix (e.g. \fBmod\-stats\fP). +.sp +Most of the sections (e.g. \fBzone\fP) are sequences of settings blocks. Each +settings block begins with a unique identifier, which can be used as a reference +from other sections (such an identifier must be defined in advance). +.sp +A multi\-valued item can be specified either as a YAML sequence: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +address: [10.0.0.1, 10.0.0.2] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +or as more single\-valued items each on an extra line: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +address: 10.0.0.1 +address: 10.0.0.2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If an item value contains spaces or other special characters, it is necessary +to enclose such a value within double quotes \fB\(dq\fP \fB\(dq\fP\&. +.sp +If not specified otherwise, an item representing a file or a directory path may +be defined either as an absolute path (starting with \fB/\fP), or a path relative +to the same directory as the default value of the item. +.SH COMMENTS +.sp +A comment begins with a \fB#\fP character and is ignored during processing. +Also each configuration section or sequence block allows a permanent +comment using the \fBcomment\fP item which is stored in the server beside the +configuration. +.SH INCLUDING CONFIGURATION +.sp +Another configuration file or files, matching a pattern, can be included at +the top level in the current file. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +include: STR +.ft P +.fi +.UNINDENT +.UNINDENT +.SS include +.sp +A path or a matching pattern specifying one or more files that are included +at the place of the include option position in the configuration. +If the path is not absolute, then it is considered to be relative to the +current file. The pattern can be an arbitrary string meeting POSIX \fIglob\fP +requirements, e.g. dir/*.conf. Matching files are processed in sorted order. +.sp +\fIDefault:\fP not set +.SH CLEARING CONFIGURATION SECTIONS +.sp +It\(aqs possible to clear specified configuration sections at given phases +of the configuration parsing. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +clear: STR +.ft P +.fi +.UNINDENT +.UNINDENT +.SS clear +.sp +A matching pattern specifying configuration sections that are cleared when +this item is parsed. This allows overriding of existing configuration +in the configuration database when including a configuration file or +ensures that some configuration wasn\(aqt specified in previous includes. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +For the pattern matching the POSIX function +\fI\%fnmatch()\fP +is used. On Linux, the GNU extension +\fI\%FNM_EXTMATCH\fP +is enabled, which allows extended pattern matching. +Examples: +.INDENT 0.0 +.IP \(bu 2 +\fBclear: zone\fP – Clears the \fBzone\fP section. +.IP \(bu 2 +\fBclear: mod\-*\fP – Clears all module sections. +.IP \(bu 2 +\fBclear: \(dq[!z]*\(dq\fP – Clears all sections not beginning with letter \fBz\fP\&. +.IP \(bu 2 +\fBclear: !(zone)\fP – (GNU only) Clears all sections except the \fBzone\fP one. +.IP \(bu 2 +\fBclear: @(zone|template)\fP – (GNU only) Clears the \fBzone\fP and \fBtemplate\fP sections. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SH MODULE SECTION +.sp +Dynamic modules loading configuration. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If configured with non\-empty \fB\-\-with\-moduledir=path\fP parameter, all +shared modules in this directory will be automatically loaded. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +module: + \- id: STR + file: STR +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A module identifier in the form of the \fBmod\-\fP prefix and module name suffix. +.SS file +.sp +A path to a shared library file with the module implementation. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +If the path is not absolute, the library is searched in the set of +system directories. See \fBman dlopen\fP for more details. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB${libdir}/knot/modules\-${version}\fP/module_name.so +(or \fB${path}\fP/module_name.so if configured with \fB\-\-with\-moduledir=path\fP) +.SH SERVER SECTION +.sp +General options related to the server. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +server: + identity: [STR] + version: [STR] + nsid: [STR|HEXSTR] + rundir: STR + user: STR[:STR] + pidfile: STR + udp\-workers: INT + tcp\-workers: INT + background\-workers: INT + async\-start: BOOL + tcp\-idle\-timeout: TIME + tcp\-io\-timeout: INT + tcp\-remote\-io\-timeout: INT + tcp\-max\-clients: INT + tcp\-reuseport: BOOL + tcp\-fastopen: BOOL + quic\-max\-clients: INT + quic\-outbuf\-max\-size: SIZE + quic\-idle\-close\-timeout: TIME + remote\-pool\-limit: INT + remote\-pool\-timeout: TIME + remote\-retry\-delay: INT + socket\-affinity: BOOL + udp\-max\-payload: SIZE + udp\-max\-payload\-ipv4: SIZE + udp\-max\-payload\-ipv6: SIZE + key\-file: STR + cert\-file: STR + edns\-client\-subnet: BOOL + answer\-rotation: BOOL + automatic\-acl: BOOL + proxy\-allowlist: ADDR[/INT] | ADDR\-ADDR ... + dbus\-event: none | running | zone\-updated | ksk\-submission | dnssec\-invalid ... + dbus\-init\-delay: TIME + listen: ADDR[@INT] | STR ... + listen\-quic: ADDR[@INT] ... + listen\-tls: ADDR[@INT] ... +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBCAUTION:\fP +.INDENT 0.0 +.INDENT 3.5 +When you change configuration parameters dynamically or via configuration file +reload, some parameters in the Server section require restarting the Knot server +so that the changes take effect. See below for the details. +.UNINDENT +.UNINDENT +.SS identity +.sp +An identity of the server returned in the response to the query for TXT +record \fBid.server.\fP or \fBhostname.bind.\fP in the CHAOS class (\fI\%RFC 4892\fP). +Set to an empty value to disable. +.sp +\fIDefault:\fP FQDN hostname +.SS version +.sp +A version of the server software returned in the response to the query +for TXT record \fBversion.server.\fP or \fBversion.bind.\fP in the CHAOS +class (\fI\%RFC 4892\fP). Set to an empty value to disable. +.sp +\fIDefault:\fP server version +.SS nsid +.sp +A DNS name server identifier (\fI\%RFC 5001\fP). Set to an empty value to disable. +.sp +\fIDefault:\fP FQDN hostname at the moment of the daemon start +.SS rundir +.sp +A path for storing run\-time data (PID file, unix sockets, etc.). A non\-absolute +path is relative to the \fI\%knotd\fP startup directory. +.sp +Depending on the usage of this parameter, its change may require restart of the Knot +server to take effect. +.sp +\fIDefault:\fP \fB${localstatedir}/run/knot\fP (configured with \fB\-\-with\-rundir=path\fP) +.SS user +.sp +A system user with an optional system group (\fBuser:group\fP) under which the +server is run after starting and binding to interfaces. Linux capabilities +are employed if supported. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBroot:root\fP +.SS pidfile +.sp +A PID file \fI\%location\fP\&. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fI\%rundir\fP\fB/knot.pid\fP +.SS udp\-workers +.sp +A number of UDP workers (threads) used to process incoming queries +over UDP. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP equal to the number of online CPUs +.SS tcp\-workers +.sp +A number of TCP workers (threads) used to process incoming queries +over TCP. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP equal to the number of online CPUs, default value is at least 10 +.SS background\-workers +.sp +A number of workers (threads) used to execute background operations (zone +loading, zone updates, etc.). +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP equal to the number of online CPUs, default value is at most 10 +.SS async\-start +.sp +If enabled, server doesn\(aqt wait for the zones to be loaded and starts +responding immediately with SERVFAIL answers until the zone loads. +.sp +\fIDefault:\fP \fBoff\fP +.SS tcp\-idle\-timeout +.sp +Maximum idle time (in seconds) between requests on an inbound TCP connection. +It means if there is no activity on an inbound TCP connection during this limit, +the connection is closed by the server. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB10\fP +.SS tcp\-io\-timeout +.sp +Maximum time (in milliseconds) to receive or send one DNS message over an inbound +TCP connection. It means this limit applies to normal DNS queries and replies, +incoming DDNS, and \fBoutgoing zone transfers\fP\&. The timeout is measured since some +data is already available for processing. +Set to 0 for infinity. +.sp +\fIDefault:\fP \fB500\fP (milliseconds) +.sp +\fBCAUTION:\fP +.INDENT 0.0 +.INDENT 3.5 +In order to reduce the risk of Slow Loris attacks, it\(aqs recommended setting +this limit as low as possible on public servers. +.UNINDENT +.UNINDENT +.SS tcp\-remote\-io\-timeout +.sp +Maximum time (in milliseconds) to receive or send one DNS message over an outbound +TCP connection which has already been established to a configured remote server. +It means this limit applies to incoming zone transfers, sending NOTIFY, +DDNS forwarding, and DS check or push. This timeout includes the time needed +for a network round\-trip and for a query processing by the remote. +Set to 0 for infinity. +.sp +\fIDefault:\fP \fB5000\fP (milliseconds) +.SS tcp\-reuseport +.sp +If enabled, each TCP worker listens on its own socket and the OS kernel +socket load balancing is employed using SO_REUSEPORT (or SO_REUSEPORT_LB +on FreeBSD). Due to the lack of one shared socket, the server can offer +higher response rate processing over TCP. However, in the case of +time\-consuming requests (e.g. zone transfers of a TLD zone), enabled reuseport +may result in delayed or not being responded client requests. So it is +advisable to use this option on secondary servers. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBoff\fP +.SS tcp\-fastopen +.sp +If enabled, use TCP Fast Open for outbound TCP communication (client side): +incoming zone transfers, sending NOTIFY, and DDNS forwarding. This mode simplifies +TCP handshake and can result in better networking performance. TCP Fast Open +for inbound TCP communication (server side) isn\(aqt affected by this +configuration as it\(aqs enabled automatically if supported by OS. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The TCP Fast Open support must also be enabled on the OS level: +.INDENT 0.0 +.IP \(bu 2 +Linux/macOS: ensure kernel parameter \fBnet.ipv4.tcp_fastopen\fP is \fB2\fP or +\fB3\fP for server side, and \fB1\fP or \fB3\fP for client side. +.IP \(bu 2 +FreeBSD: ensure kernel parameter \fBnet.inet.tcp.fastopen.server_enable\fP +is \fB1\fP for server side, and \fBnet.inet.tcp.fastopen.client_enable\fP is +\fB1\fP for client side. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS quic\-max\-clients +.sp +A maximum number of QUIC clients connected in parallel. +.sp +See also \fI\%quic\fP\&. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIMinimum:\fP \fB128\fP +.sp +\fIDefault:\fP \fB10000\fP (ten thousand) +.SS quic\-outbuf\-max\-size +.sp +Maximum cumulative size of memory used for buffers of unACKed +sent messages. This limit is per one UDP worker. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Set low if little memory is available (together with \fI\%quic\-max\-clients\fP +since QUIC connections are memory\-heavy). Set to high value if outgoing zone +transfers of big zone over QUIC are expected. +.UNINDENT +.UNINDENT +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIMinimum:\fP \fB1M\fP (1 MiB) +.sp +\fIDefault:\fP \fB100M\fP (100 MiB) +.SS quic\-idle\-close\-timeout +.sp +Time in seconds, after which any idle QUIC connection is gracefully closed. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB4\fP +.SS remote\-pool\-limit +.sp +If nonzero, the server will keep up to this number of outgoing TCP connections +open for later use. This is an optimization to avoid frequent opening of +TCP connections to the same remote. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fB0\fP +.SS remote\-pool\-timeout +.sp +The timeout in seconds after which the unused kept\-open outgoing TCP connections +to remote servers are closed. +.sp +\fIDefault:\fP \fB5\fP +.SS remote\-retry\-delay +.sp +When a connection attempt times out to some remote address, this information will be +kept for this specified time (in milliseconds) and other connections to the same address won\(aqt +be attempted. This prevents repetitive waiting for timeout on an unreachable remote. +.sp +\fIDefault:\fP \fB0\fP +.SS socket\-affinity +.sp +If enabled and if SO_REUSEPORT is available on Linux, all configured network +sockets are bound to UDP and TCP workers in order to increase the networking performance. +This mode isn\(aqt recommended for setups where the number of network card queues +is lower than the number of UDP or TCP workers. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBoff\fP +.SS tcp\-max\-clients +.sp +A maximum number of TCP clients connected in parallel, set this below the file +descriptor limit to avoid resource exhaustion. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +It is advisable to adjust the maximum number of open files per process in your +operating system configuration. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP one half of the file descriptor limit for the server process +.SS udp\-max\-payload +.sp +Maximum EDNS0 UDP payload size default for both IPv4 and IPv6. +.sp +\fIDefault:\fP \fB1232\fP +.SS udp\-max\-payload\-ipv4 +.sp +Maximum EDNS0 UDP payload size for IPv4. +.sp +\fIDefault:\fP \fB1232\fP +.SS udp\-max\-payload\-ipv6 +.sp +Maximum EDNS0 UDP payload size for IPv6. +.sp +\fIDefault:\fP \fB1232\fP +.SS key\-file +.sp +Path to a server key PEM file which is used for DNS over QUIC/TLS communication. +A non\-absolute path of a user specified key file is relative to the +\fB/usr/local/etc/knot\fP directory. +.sp +\fIDefault:\fP auto\-generated key +.SS cert\-file +.sp +Path to a server certificate PEM file which is used for DNS over QUIC/TLS communication. +A non\-absolute path is relative to the \fB/usr/local/etc/knot\fP directory. +.sp +\fIDefault:\fP one\-time in\-memory certificate +.SS edns\-client\-subnet +.sp +Enable or disable EDNS Client Subnet support. If enabled, responses to queries +containing the EDNS Client Subnet option +always contain a valid EDNS Client Subnet option according to \fI\%RFC 7871\fP\&. +.sp +\fIDefault:\fP \fBoff\fP +.SS answer\-rotation +.sp +Enable or disable sorted\-rrset rotation in the answer section of normal replies. +The rotation shift is simply determined by a query ID. +.sp +\fIDefault:\fP \fBoff\fP +.SS automatic\-acl +.sp +If enabled, \fI\%automatic ACL\fP setting of +configured remotes is considered when evaluating authorized operations. +.sp +\fIDefault:\fP \fBoff\fP +.SS proxy\-allowlist +.sp +An ordered list of IP addresses, network subnets, or network ranges +which are allowed as a source address of proxied DNS traffic over UDP. +The supported proxy protocol is +\fI\%haproxy PROXY v2\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +TCP is not supported. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS dbus\-event +.sp +Specification of server or zone states which emit a D\-Bus signal on the system +bus. The bus name is \fBcz.nic.knotd\fP, the object path is \fB/cz/nic/knotd\fP, and +the interface name is \fBcz.nic.knotd.events\fP\&. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – No signal is emitted. +.IP \(bu 2 +\fBrunning\fP – There are two possible signals emitted: +.INDENT 2.0 +.IP \(bu 2 +\fBstarted\fP when the server is started and all configured zones (including +catalog zones and their members) are loaded or successfully bootstrapped. +.IP \(bu 2 +\fBstopped\fP when the server shutdown sequence is initiated. +.UNINDENT +.IP \(bu 2 +\fBzone\-updated\fP – The signal \fBzone_updated\fP is emitted when a zone has been updated; +the signal parameters are \fIzone name\fP and \fIzone SOA serial\fP\&. +.IP \(bu 2 +\fBkeys\-updated\fP \- The signal \fBkeys_updated\fP is emitted when a DNSSEC key set +is updated; the signal parameter is \fIzone name\fP\&. +.IP \(bu 2 +\fBksk\-submission\fP – The signal \fBzone_ksk_submission\fP is emitted if there is +a ready KSK present when the zone is signed; the signal parameters are +\fIzone name\fP, \fIKSK keytag\fP, and \fIKSK KASP id\fP\&. +.IP \(bu 2 +\fBdnssec\-invalid\fP – The signal \fBzone_dnssec_invalid\fP is emitted when DNSSEC +validation fails; the signal parameters are \fIzone name\fP, and \fIremaining seconds\fP +until an RRSIG expires. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This function requires systemd version at least 221 or libdbus. +.UNINDENT +.UNINDENT +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBnone\fP +.SS dbus\-init\-delay +.sp +Time in seconds which the server waits upon D\-Bus initialization to ensure +the D\-Bus client is ready to receive signals. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIMinimum:\fP \fB0\fP +.sp +\fIDefault:\fP \fB1\fP +.SS listen +.sp +One or more IP addresses where the server listens for incoming queries. +Optional port specification (default is 53) can be appended to each address +using \fB@\fP separator. Use \fB0.0.0.0\fP for all configured IPv4 addresses or +\fB::\fP for all configured IPv6 addresses. Filesystem path can be specified +for listening on local unix SOCK_STREAM socket. Non\-absolute path +(i.e. not starting with \fB/\fP) is relative to \fI\%rundir\fP\&. +Non\-local address binding is automatically enabled if supported by the operating system. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP not set +.SS listen\-quic +.sp +One or more IP addresses (and optionally ports) where the server listens +for incoming queries over QUIC protocol. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP not set +.SS listen\-tls +.sp +One or more IP addresses (and optionally ports) where the server listens +for incoming queries over TLS protocol (DoT). +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP not set +.SH XDP SECTION +.sp +Various options related to XDP listening, especially TCP. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +xdp: + listen: STR[@INT] | ADDR[@INT] ... + udp: BOOL + tcp: BOOL + quic: BOOL + quic\-port: INT + tcp\-max\-clients: INT + tcp\-inbuf\-max\-size: SIZE + tcp\-outbuf\-max\-size: SIZE + tcp\-idle\-close\-timeout: TIME + tcp\-idle\-reset\-timeout: TIME + tcp\-resend\-timeout: TIME + route\-check: BOOL + ring\-size: INT + busypoll\-budget: INT + busypoll\-timeout: INT +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBCAUTION:\fP +.INDENT 0.0 +.INDENT 3.5 +When you change configuration parameters dynamically or via configuration file +reload, some parameters in the XDP section require restarting the Knot server +so that the changes take effect. +.UNINDENT +.UNINDENT +.SS listen +.sp +One or more network device names (e.g. \fBens786f0\fP) on which the \fI\%Mode XDP\fP +is enabled. Alternatively, an IP address can be used instead of a device name, +but the server will still listen on all addresses belonging to the same interface! +Optional port specification (default is 53) can be appended to each device name +or address using \fB@\fP separator. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fBCAUTION:\fP +.INDENT 0.0 +.INDENT 3.5 +If XDP workers only process regular DNS traffic over UDP, it is strongly +recommended to also \fI\%listen\fP on the addresses which are +intended to offer the DNS service, at least to fulfil the DNS requirement for +working TCP. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Incoming \fI\%DDNS\fP over XDP isn\(aqt supported. +The server always responds with SERVFAIL. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS udp +.sp +If enabled, DNS over UDP is processed with XDP workers. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBon\fP +.SS tcp +.sp +If enabled, DNS over TCP traffic is processed with XDP workers. +.sp +The TCP stack limitations: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +Congestion control is not implemented. +.IP \(bu 2 +Lost packets that do not contain TCP payload may not be resend. +.IP \(bu 2 +Not optimized for transfers of non\-trivial zones. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBoff\fP +.SS quic +.sp +If enabled, DNS over QUIC is processed with XDP workers. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBoff\fP +.SS quic\-port +.sp +DNS over QUIC will listen on the interfaces configured by \fI\%listen\fP, +but on different port, configured by this option. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fB853\fP +.SS tcp\-max\-clients +.sp +A maximum number of TCP clients connected in parallel. +.sp +\fIMinimum:\fP \fB1024\fP +.sp +\fIDefault:\fP \fB1000000\fP (one million) +.SS tcp\-inbuf\-max\-size +.sp +Maximum cumulative size of memory used for buffers of incompletely +received messages. +.sp +\fIMinimum:\fP \fB1M\fP (1 MiB) +.sp +\fIDefault:\fP \fB100M\fP (100 MiB) +.SS tcp\-outbuf\-max\-size +.sp +Maximum cumulative size of memory used for buffers of unACKed +sent messages. +.sp +\fIMinimum:\fP \fB1M\fP (1 MiB) +.sp +\fIDefault:\fP \fB100M\fP (100 MiB) +.SS tcp\-idle\-close\-timeout +.sp +Time in seconds, after which any idle connection is gracefully closed. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB10\fP +.SS tcp\-idle\-reset\-timeout +.sp +Time in seconds, after which any idle connection is forcibly closed. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB20\fP +.SS tcp\-resend\-timeout +.sp +Resend outgoing data packets (with DNS response payload) if not ACKed +before this timeout (in seconds). +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB5\fP +.SS route\-check +.sp +If enabled, routing information from the operating system is considered +when processing every incoming DNS packet received over the XDP interface: +.INDENT 0.0 +.IP \(bu 2 +If the outgoing interface of the corresponding DNS response differs from +the incoming one, the packet is processed normally by UDP/TCP workers +(XDP isn\(aqt used). +.IP \(bu 2 +If the destination address is blackholed, unreachable, or prohibited, +the DNS packet is dropped without any response. +.IP \(bu 2 +The destination MAC address and possible VLAN tag for the response are taken +from the routing system. +.UNINDENT +.sp +If disabled, symmetrical routing is applied. It means that the query source +MAC address is used as a response destination MAC address. Possible VLAN tag +is preserved. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This mode requires forwarding enabled on the loopback interface +(\fBsysctl \-w net.ipv4.conf.lo.forwarding=1\fP and \fBsysctl \-w net.ipv6.conf.lo.forwarding=1\fP). +If forwarding is disabled, all incoming DNS packets are dropped! +.sp +Only VLAN 802.1Q is supported. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS ring\-size +.sp +Size of RX, FQ, TX, and CQ rings. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value should be at least as high as the configured RX size of the +network device in the XDP mode. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB2048\fP +.SS busypoll\-budget +.sp +If set to a positive value, preferred busy polling is enabled with the +specified budget. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Preferred busy polling also requires setting \fBnapi_defer_hard_irqs\fP and +\fBgro_flush_timeout\fP for the appropriate network interface. E.g.: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +echo 2 | sudo tee /sys/class/net//napi_defer_hard_irqs +echo 200000 | sudo tee /sys/class/net//gro_flush_timeout +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +A recommended value is between 8 and 64. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB0\fP (disabled) +.SS busypoll\-timeout +.sp +Timeout in microseconds of preferrred busy polling if enabled by +\fI\%busypoll\-budget\fP\&. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fB20\fP (20 microseconds) +.SH CONTROL SECTION +.sp +Configuration of the server control interface. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +control: + listen: STR + backlog: INT + timeout: TIME +.ft P +.fi +.UNINDENT +.UNINDENT +.SS listen +.sp +A UNIX socket \fI\%path\fP where the server listens for +control commands. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fI\%rundir\fP\fB/knot.sock\fP +.SS backlog +.sp +The control UNIX socket listen backlog size. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fB5\fP +.SS timeout +.sp +Maximum time (in seconds) the control socket operations can take. +Set to 0 for infinity. +.sp +\fIDefault:\fP \fB5\fP +.SH LOG SECTION +.sp +Server can be configured to log to the standard output, standard error +output, syslog (or systemd journal if systemd is enabled) or into an arbitrary +file. +.sp +There are 6 logging severity levels: +.INDENT 0.0 +.IP \(bu 2 +\fBcritical\fP – Non\-recoverable error resulting in server shutdown. +.IP \(bu 2 +\fBerror\fP – Recoverable error, action should be taken. +.IP \(bu 2 +\fBwarning\fP – Warning that might require user action. +.IP \(bu 2 +\fBnotice\fP – Server notice or hint. +.IP \(bu 2 +\fBinfo\fP – Informational message. +.IP \(bu 2 +\fBdebug\fP – Debug or detailed message. +.UNINDENT +.sp +In the case of a missing log section, \fBwarning\fP or more serious messages +will be logged to both standard error output and syslog. The \fBinfo\fP and +\fBnotice\fP messages will be logged to standard output. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +log: + \- target: stdout | stderr | syslog | STR + server: critical | error | warning | notice | info | debug + control: critical | error | warning | notice | info | debug + zone: critical | error | warning | notice | info | debug + quic: critical | error | warning | notice | info | debug + any: critical | error | warning | notice | info | debug +.ft P +.fi +.UNINDENT +.UNINDENT +.SS target +.sp +A logging output. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBstdout\fP – Standard output. +.IP \(bu 2 +\fBstderr\fP – Standard error output. +.IP \(bu 2 +\fBsyslog\fP – Syslog or systemd journal. +.IP \(bu 2 +\fIfile_name\fP – A specific file. +.UNINDENT +.sp +With \fBsyslog\fP target, syslog service is used. However, if Knot DNS has been compiled +with systemd support and operating system has been booted with systemd, systemd journal +is used for logging instead of syslog. +.sp +A \fIfile_name\fP may be specified as an absolute path or a path relative to the +\fI\%knotd\fP startup directory. +.SS server +.sp +Minimum severity level for messages related to general operation of the server to be +logged. +.sp +\fIDefault:\fP not set +.SS control +.sp +Minimum severity level for messages related to server control to be logged. +.sp +\fIDefault:\fP not set +.SS zone +.sp +Minimum severity level for messages related to zones to be logged. +.sp +\fIDefault:\fP not set +.SS quic +.sp +Minimum severity level for messages related to QUIC to be logged. +.sp +\fIDefault:\fP not set +.SS any +.sp +Minimum severity level for all message types, except \fBquic\fP, to be logged. +.sp +\fIDefault:\fP not set +.SH STATISTICS SECTION +.sp +Periodic server statistics dumping. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +statistics: + timer: TIME + file: STR + append: BOOL +.ft P +.fi +.UNINDENT +.UNINDENT +.SS timer +.sp +A period (in seconds) after which all available statistics metrics will by written to the +\fI\%file\fP\&. +.sp +\fIDefault:\fP not set +.SS file +.sp +A file \fI\%path\fP of statistics output in the YAML format. +.sp +\fIDefault:\fP \fI\%rundir\fP\fB/stats.yaml\fP +.SS append +.sp +If enabled, the output will be appended to the \fI\%file\fP +instead of file replacement. +.sp +\fIDefault:\fP \fBoff\fP +.SH DATABASE SECTION +.sp +Configuration of databases for zone contents, DNSSEC metadata, or event timers. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +database: + storage: STR + journal\-db: STR + journal\-db\-mode: robust | asynchronous + journal\-db\-max\-size: SIZE + kasp\-db: STR + kasp\-db\-max\-size: SIZE + timer\-db: STR + timer\-db\-max\-size: SIZE + catalog\-db: str + catalog\-db\-max\-size: SIZE +.ft P +.fi +.UNINDENT +.UNINDENT +.SS storage +.sp +A data directory for storing journal, KASP, and timer databases. A non\-absolute +path is relative to the \fI\%knotd\fP startup directory. +.sp +\fIDefault:\fP \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP) +.SS journal\-db +.sp +An explicit \fI\%specification\fP of the persistent journal database +directory. +.sp +\fIDefault:\fP \fI\%storage\fP\fB/journal\fP +.SS journal\-db\-mode +.sp +Specifies journal LMDB backend configuration, which influences performance +and durability. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBrobust\fP – The journal database disk synchronization ensures database +durability but is generally slower. +.IP \(bu 2 +\fBasynchronous\fP – The journal database disk synchronization is optimized for +better performance at the expense of lower database durability in the case of +a crash. This mode is recommended on secondary servers with many zones. +.UNINDENT +.sp +\fIDefault:\fP \fBrobust\fP +.SS journal\-db\-max\-size +.sp +The hard limit for the journal database maximum size. There is no cleanup logic +in journal to recover from reaching this limit. Journal simply starts refusing +changes across all zones. Decreasing this value has no effect if it is lower +than the actual database file size. +.sp +It is recommended to limit \fI\%journal\-max\-usage\fP +per\-zone instead of \fI\%journal\-db\-max\-size\fP +in most cases. Please keep this value larger than the sum of all zones\(aq +journal usage limits. See more details regarding +\fI\%journal behaviour\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value also influences server\(aqs usage of virtual memory. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB20G\fP (20 GiB), or \fB512M\fP (512 MiB) for 32\-bit +.SS kasp\-db +.sp +An explicit \fI\%specification\fP of the KASP database directory. +.sp +\fIDefault:\fP \fI\%storage\fP\fB/keys\fP +.SS kasp\-db\-max\-size +.sp +The hard limit for the KASP database maximum size. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value also influences server\(aqs usage of virtual memory. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB500M\fP (500 MiB) +.SS timer\-db +.sp +An explicit \fI\%specification\fP of the persistent timer +database directory. +.sp +\fIDefault:\fP \fI\%storage\fP\fB/timers\fP +.SS timer\-db\-max\-size +.sp +The hard limit for the timer database maximum size. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value also influences server\(aqs usage of virtual memory. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB100M\fP (100 MiB) +.SS catalog\-db +.sp +An explicit \fI\%specification\fP of the zone catalog +database directory. Only useful if \fI\%Catalog zones\fP are enabled. +.sp +\fIDefault:\fP \fI\%storage\fP\fB/catalog\fP +.SS catalog\-db\-max\-size +.sp +The hard limit for the catalog database maximum size. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value also influences server\(aqs usage of virtual memory. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB20G\fP (20 GiB), or \fB512M\fP (512 MiB) for 32\-bit +.SH KEYSTORE SECTION +.sp +DNSSEC keystore configuration. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +keystore: + \- id: STR + backend: pem | pkcs11 + config: STR + key\-label: BOOL +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A keystore identifier. +.SS backend +.sp +A key storage backend type. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBpem\fP – PEM files. +.IP \(bu 2 +\fBpkcs11\fP – PKCS #11 storage. +.UNINDENT +.sp +\fIDefault:\fP \fBpem\fP +.SS config +.sp +A backend specific configuration. A directory with PEM files (the path can +be specified as a relative path to \fI\%kasp\-db\fP) or +a configuration string for PKCS #11 storage (\fI \fP). +The PKCS #11 URI Scheme is defined in \fI\%RFC 7512\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Example configuration string for PKCS #11: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +\(dqpkcs11:token=knot;pin\-value=1234 /usr/lib64/pkcs11/libsofthsm2.so\(dq +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fI\%kasp\-db\fP\fB/keys\fP +.SS key\-label +.sp +If enabled in combination with the PKCS #11 \fI\%backend\fP, generated keys +are labeled in the form \fB KSK|ZSK\fP\&. +.sp +\fIDefault:\fP \fBoff\fP +.SH KEY SECTION +.sp +Shared TSIG keys used to authenticate communication with the server. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +key: + \- id: DNAME + algorithm: hmac\-md5 | hmac\-sha1 | hmac\-sha224 | hmac\-sha256 | hmac\-sha384 | hmac\-sha512 + secret: BASE64 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A key name identifier. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value MUST be exactly the same as the name of the TSIG key on the +opposite primary/secondary server(s). +.UNINDENT +.UNINDENT +.SS algorithm +.sp +A TSIG key algorithm. See +\fI\%TSIG Algorithm Numbers\fP\&. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBhmac\-md5\fP +.IP \(bu 2 +\fBhmac\-sha1\fP +.IP \(bu 2 +\fBhmac\-sha224\fP +.IP \(bu 2 +\fBhmac\-sha256\fP +.IP \(bu 2 +\fBhmac\-sha384\fP +.IP \(bu 2 +\fBhmac\-sha512\fP +.UNINDENT +.sp +\fIDefault:\fP not set +.SS secret +.sp +Shared key secret. +.sp +\fIDefault:\fP not set +.SH REMOTE SECTION +.sp +Definitions of remote servers for outgoing connections (source of a zone +transfer, target for a notification, etc.). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +remote: + \- id: STR + address: ADDR[@INT] | STR ... + via: ADDR[@INT] ... + quic: BOOL + tls: BOOL + key: key_id + cert\-key: BASE64 ... + block\-notify\-after\-transfer: BOOL + no\-edns: BOOL + automatic\-acl: BOOL +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A remote identifier. +.SS address +.sp +An ordered list of destination IP addresses or UNIX socket paths which are +used for communication with the remote server. Non\-absolute path +(i.e. not starting with \fB/\fP) is relative to \fI\%rundir\fP\&. +Optional destination port (default is 53 for UDP/TCP and 853 for QUIC) +can be appended to the address using \fB@\fP separator. +The addresses are tried in sequence until the +remote is reached. +.sp +\fIDefault:\fP not set +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If the remote is contacted and it refuses to perform requested action, +no more addresses will be tried for this remote. +.UNINDENT +.UNINDENT +.SS via +.sp +An ordered list of source IP addresses which are used as source addresses +for communication with the remote. For the N\-th \fI\%remote address\fP, +the last, but at most N\-th, specified \fI\%via address\fP +of the same family is used. +This option can help if the server listens on more addresses. +Optional source port (default is random) can be appended +to the address using \fB@\fP separator. +.sp +\fIDefault:\fP not set +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +For the following configuration: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +remote: + \- id: example + address: [198.51.100.10, 2001:db8::10, 198.51.100.20, 2001:db8::20] + via: [198.51.100.1, 198.51.100.2, 2001:db8::1] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +the (\fBvia\fP \-> \fBaddress\fP) mapping is: +.INDENT 0.0 +.IP \(bu 2 +\fB198.51.100.1\fP \-> \fB198.51.100.10\fP +.IP \(bu 2 +\fB2001:db8::1\fP \-> \fB2001:db8::10\fP +.IP \(bu 2 +\fB198.51.100.2\fP \-> \fB198.51.100.20\fP +.IP \(bu 2 +\fB2001:db8::1\fP \-> \fB2001:db8::20\fP +.UNINDENT +.UNINDENT +.UNINDENT +.SS quic +.sp +If this option is set, the QUIC protocol will be used for outgoing communication +with this remote. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +One connection per each remote is opened; \fI\%remote\-pool\-limit\fP +does not take effect for QUIC. However, fast QUIC handshakes utilizing obtained +session tickets are used for reopening connections to recently (up to 1 day) +queried remotes. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS tls +.sp +If this option is set, the TLS (DoT) protocol will be used for outgoing communication +with this remote. +.sp +\fIDefault:\fP \fBoff\fP +.SS key +.sp +A \fI\%reference\fP to the TSIG key which is used to authenticate +the communication with the remote server. +.sp +\fIDefault:\fP not set +.SS cert\-key +.sp +An ordered list of remote certificate public key PINs. If the list is non\-empty, +communication with the remote is possible only via QUIC protocol and +a peer certificate is required. The peer certificate key must match one of the +specified PINs. +.sp +A PIN is a unique identifier that represents the public key of the peer certificate. +It\(aqs a base64\-encoded SHA\-256 hash of the public key. This identifier +remains the same on a certificate renewal. +.sp +\fIDefault:\fP not set +.SS block\-notify\-after\-transfer +.sp +When incoming AXFR/IXFR from this remote (as a primary server), suppress +sending NOTIFY messages to all configured secondary servers. +.sp +\fIDefault:\fP \fBoff\fP +.SS no\-edns +.sp +If enabled, no OPT record (EDNS) is inserted to outgoing requests to this +remote server. This mode is necessary for communication with some broken +implementations (e.g. Windows Server 2016). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option effectively disables \fI\%zone expire\fP timer +updates via EDNS EXPIRE option specified in \fI\%RFC 7314\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS automatic\-acl +.sp +If enabled, some authorized operations for the remote are automatically allowed +based on the context: +.INDENT 0.0 +.IP \(bu 2 +Incoming NOTIFY is allowed from the remote if it\(aqs configured as a +\fI\%primary server\fP for the zone. +.IP \(bu 2 +Outgoing zone transfer is allowed to the remote if it\(aqs configured as a +\fI\%NOTIFY target\fP for the zone. +.UNINDENT +.sp +Automatic ACL rules are evaluated before explicit \fI\%zone ACL\fP configuration. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This functionality requires global activation via +\fI\%automatic\-acl\fP in the server section. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBon\fP +.SH REMOTES SECTION +.sp +Definitions of groups of remote servers. Remote grouping can simplify the +configuration. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +remotes: + \- id: STR + remote: remote_id ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A remote group identifier. +.SS remote +.sp +An ordered list of \fI\%references\fP to remote server definitions. +.sp +\fIDefault:\fP not set +.SH ACL SECTION +.sp +Access control list rule definitions. An ACL rule is a description of one +or more authorized actions (zone transfer request, zone change notification, +and dynamic DNS update) which are allowed to be processed or denied. Normal +DNS queries are always allowed. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +acl: + \- id: STR + address: ADDR[/INT] | ADDR\-ADDR | STR ... + key: key_id ... + cert\-key: BASE64 ... + remote: remote_id | remotes_id ... + action: query | notify | transfer | update ... + deny: BOOL + update\-type: STR ... + update\-owner: key | zone | name + update\-owner\-match: sub\-or\-equal | equal | sub | pattern + update\-owner\-name: STR ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +An ACL rule identifier. +.SS address +.sp +An ordered list of IP addresses, absolute UNIX socket paths, network subnets, +or network ranges. The query\(aqs +source address must match one of them. If this item is not set, address match is not +required. +.sp +\fIDefault:\fP not set +.SS key +.sp +An ordered list of \fI\%reference\fPs to TSIG keys. The query must +match one of them. If this item is not set, transaction authentication is not used. +.sp +\fIDefault:\fP not set +.SS cert\-key +.sp +An ordered list of remote certificate public key PINs. If the list is non\-empty, +communication with the remote is possible only via QUIC protocol and +a peer certificate is required. The peer certificate key must match one of the +specified PINs. +.sp +A PIN is a unique identifier that represents the public key of the peer certificate. +It\(aqs a base64\-encoded SHA\-256 hash of the public key. This identifier +remains the same on a certificate renewal. +.sp +\fIDefault:\fP not set +.SS remote +.sp +An ordered list of references \fI\%remote\fP and +\fI\%remotes\fP\&. The query must +match one of the remotes. Specifically, one of the remote\(aqs addresses and remote\(aqs +TSIG key if configured must match. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option cannot be specified along with the \fI\%address\fP or +\fI\%key\fP option at one ACL item. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS action +.sp +An ordered list of allowed, or denied, actions (request types). +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBquery\fP – Allow regular DNS query. As normal queries are always allowed, +this action is only useful in combination with \fI\%TSIG key\fP\&. +.IP \(bu 2 +\fBnotify\fP – Allow incoming notify (NOTIFY). +.IP \(bu 2 +\fBtransfer\fP – Allow zone transfer (AXFR, IXFR). +.IP \(bu 2 +\fBupdate\fP – Allow zone updates (DDNS). +.UNINDENT +.sp +\fIDefault:\fP \fBquery\fP +.SS deny +.sp +If enabled, instead of allowing, deny the specified \fI\%action\fP, +\fI\%address\fP, \fI\%key\fP, or combination if these +items. If no action is specified, deny all actions. +.sp +\fIDefault:\fP \fBoff\fP +.SS update\-type +.sp +A list of allowed types of Resource Records in a zone update. Every record in an update +must match one of the specified types. +.sp +\fIDefault:\fP not set +.SS update\-owner +.sp +This option restricts possible owners of Resource Records in a zone update by comparing +them to either the \fI\%TSIG key\fP identity, the current zone name, or to a list of +domain names given by the \fI\%update\-owner\-name\fP option. +The comparison method is given by the \fI\%update\-owner\-match\fP option. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBkey\fP — The owner of each updated RR must match the identity of the TSIG key if used. +.IP \(bu 2 +\fBname\fP — The owner of each updated RR must match at least one name in the +\fI\%update\-owner\-name\fP list. +.IP \(bu 2 +\fBzone\fP — The owner of each updated RR must match the current zone name. +.UNINDENT +.sp +\fIDefault:\fP not set +.SS update\-owner\-match +.sp +This option defines how the owners of Resource Records in an update are matched to the domain name(s) +set by the \fI\%update\-owner\fP option. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBsub\-or\-equal\fP — The owner of each RR in an update must either be equal to +or be a subdomain of at least one domain name set by \fI\%update\-owner\fP\&. +.IP \(bu 2 +\fBequal\fP — The owner of each updated RR must be equal to at least one domain +name set by \fI\%update\-owner\fP\&. +.IP \(bu 2 +\fBsub\fP — The owner of each updated RR must be a subdomain of, but MUST NOT +be equal to at least one domain name set by \fI\%update\-owner\fP\&. +.IP \(bu 2 +\fBpattern\fP — The owner of each updated RR must match a pattern specified by +\fI\%update\-owner\fP\&. The pattern can be an arbitrary FQDN or non\-FQDN +domain name. If a label consists of one \fB*\fP (asterisk) character, it +matches any label. More asterisk labels can be specified. +.UNINDENT +.sp +\fIDefault:\fP \fBsub\-or\-equal\fP +.SS update\-owner\-name +.sp +A list of allowed owners of RRs in a zone update used with \fI\%update\-owner\fP +set to \fBname\fP\&. Every listed owner name which is not FQDN (i.e. it doesn\(aqt end +in a dot) is considered as if it was appended with the target zone name. +Such a relative owner name specification allows better ACL rule reusability across +multiple zones. +.sp +\fIDefault:\fP not set +.SH SUBMISSION SECTION +.sp +Parameters of KSK submission checks. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +submission: + \- id: STR + parent: remote_id | remotes_id ... + check\-interval: TIME + timeout: TIME + parent\-delay: TIME +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A submission identifier. +.SS parent +.sp +A list of references \fI\%remote\fP and \fI\%remotes\fP +to parent\(aqs DNS servers to be checked for +presence of corresponding DS records in the case of KSK submission. All of them must +have a corresponding DS for the rollover to continue. If none is specified, the +rollover must be pushed forward manually. +.sp +\fIDefault:\fP not set +.sp +\fBTIP:\fP +.INDENT 0.0 +.INDENT 3.5 +A DNSSEC\-validating resolver can be set as a parent. +.UNINDENT +.UNINDENT +.SS check\-interval +.sp +Interval (in seconds) for periodic checks of DS presence on parent\(aqs DNS +servers, in the case of the KSK submission. +.sp +\fIDefault:\fP \fB1h\fP (1 hour) +.SS timeout +.sp +After this time period (in seconds) the KSK submission is automatically considered +successful, even if all the checks were negative or no parents are configured. +Set to 0 for infinity. +.sp +\fIDefault:\fP \fB0\fP +.SS parent\-delay +.sp +After successful parent DS check, wait for this period (in seconds) before +continuing the next key roll\-over step. This delay shall cover the propagation +delay of update in the parent zone. +.sp +\fIDefault:\fP \fB0\fP +.SH DNSKEY-SYNC SECTION +.sp +Parameters of DNSKEY dynamic\-update synchronization. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +dnskey\-sync: + \- id: STR + remote: remote_id | remotes_id ... + check\-interval: TIME +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A dnskey\-sync identifier. +.SS remote +.sp +A list of references \fI\%remote\fP and \fI\%remotes\fP +to other signers or common master, which the DDNS updates with +DNSKEY/CDNSKEY/CDS records shall be sent to. +.sp +\fIDefault:\fP not set +.SS check\-interval +.sp +If the last DNSKEY sync failed or resulted in any change, re\-check +the consistence after this interval (in seconds) and re\-try if needed. +.sp +\fIDefault:\fP \fB60\fP (1 minute) +.SH POLICY SECTION +.sp +DNSSEC policy configuration. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +policy: + \- id: STR + keystore: keystore_id + manual: BOOL + single\-type\-signing: BOOL + algorithm: rsasha1 | rsasha1\-nsec3\-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519 | ed448 + ksk\-size: SIZE + zsk\-size: SIZE + ksk\-shared: BOOL + dnskey\-ttl: TIME + zone\-max\-ttl: TIME + keytag\-modulo: INT/INT + ksk\-lifetime: TIME + zsk\-lifetime: TIME + delete\-delay: TIME + propagation\-delay: TIME + rrsig\-lifetime: TIME + rrsig\-refresh: TIME + rrsig\-pre\-refresh: TIME + reproducible\-signing: BOOL + nsec3: BOOL + nsec3\-iterations: INT + nsec3\-opt\-out: BOOL + nsec3\-salt\-length: INT + nsec3\-salt\-lifetime: TIME + signing\-threads: INT + ksk\-submission: submission_id + ds\-push: remote_id | remotes_id ... + cds\-cdnskey\-publish: none | delete\-dnssec | rollover | always | double\-ds + cds\-digest\-type: sha256 | sha384 + dnskey\-management: full | incremental + offline\-ksk: BOOL + unsafe\-operation: none | no\-check\-keyset | no\-update\-dnskey | no\-update\-nsec | no\-update\-expired ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A policy identifier. +.SS keystore +.sp +A \fI\%reference\fP to a keystore holding private key material +for zones. +.sp +\fIDefault:\fP an imaginary keystore with all default values +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +A configured keystore called \(dqdefault\(dq won\(aqt be used unless explicitly referenced. +.UNINDENT +.UNINDENT +.SS manual +.sp +If enabled, automatic key management is not used. +.sp +\fIDefault:\fP \fBoff\fP +.SS single\-type\-signing +.sp +If enabled, Single\-Type Signing Scheme is used in the automatic key management +mode. +.sp +\fIDefault:\fP \fBoff\fP (\fI\%module onlinesign\fP has default \fBon\fP) +.SS algorithm +.sp +An algorithm of signing keys and issued signatures. See +\fI\%DNSSEC Algorithm Numbers\fP\&. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBrsasha1\fP +.IP \(bu 2 +\fBrsasha1\-nsec3\-sha1\fP +.IP \(bu 2 +\fBrsasha256\fP +.IP \(bu 2 +\fBrsasha512\fP +.IP \(bu 2 +\fBecdsap256sha256\fP +.IP \(bu 2 +\fBecdsap384sha384\fP +.IP \(bu 2 +\fBed25519\fP +.IP \(bu 2 +\fBed448\fP +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Ed448 algorithm is only available if compiled with GnuTLS 3.6.12+ and Nettle 3.6+. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBecdsap256sha256\fP +.SS ksk\-size +.sp +A length of newly generated KSK or +CSK keys. +.sp +\fIDefault:\fP \fB2048\fP (rsa*), \fB256\fP (ecdsap256), \fB384\fP (ecdsap384), \fB256\fP (ed25519), +\fB456\fP (ed448) +.SS zsk\-size +.sp +A length of newly generated ZSK keys. +.sp +\fIDefault:\fP see default for \fI\%ksk\-size\fP +.SS ksk\-shared +.sp +If enabled, all zones with this policy assigned will share one or more KSKs. +More KSKs can be shared during a KSK rollover. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +As the shared KSK set is bound to the policy \fI\%id\fP, renaming the +policy breaks this connection and new shared KSK set is initiated when +a new KSK is needed. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS dnskey\-ttl +.sp +A TTL value for DNSKEY records added into zone apex. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Has influence over ZSK key lifetime. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Ensure all DNSKEYs with updated TTL are propagated before any subsequent +DNSKEY rollover starts. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP zone SOA TTL +.SS zone\-max\-ttl +.sp +Declare (override) maximal TTL value among all the records in zone. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +It\(aqs generally recommended to override the maximal TTL computation by setting this +explicitly whenever possible. It\(aqs required for \fI\%DNSSEC Offline KSK\fP and +really reasonable when records are generated dynamically +(e.g. by a \fI\%module\fP). +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP computed after zone is loaded +.SS keytag\-modulo +.sp +Specifies that the keytags of any generated keys shall be congruent by specified modulo. +The option value must be a string in the format \fBR/M\fP, where \fBR < M <= 256\fP are +positive integers. Whenever a DNSSEC key is generated, it is ensured +that \fBkeytag % M == R\fP\&. This prevents keytag conflict in \fI\%DNSSEC Offline KSK\fP +or \fI\%DNSSEC multi\-signer\fP (and possibly other) setups. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This only applies to newly generated keys when they are generated. Keys from +before this option and keys imported from elsewhere might not fulfill the policy. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB0/1\fP +.SS ksk\-lifetime +.sp +A period (in seconds) between KSK generation and the next rollover initiation. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +KSK key lifetime is also influenced by propagation\-delay, dnskey\-ttl, +and KSK submission delay. +.sp +Zero (aka infinity) value causes no KSK rollover as a result. +.sp +This applies for CSK lifetime if single\-type\-signing is enabled. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB0\fP (infinity) +.SS zsk\-lifetime +.sp +A period (in seconds) between ZSK activation and the next rollover initiation. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +More exactly, this period is measured since a ZSK is activated, +and after this, a new ZSK is generated to replace it within +following roll\-over. +.sp +As a consequence, in normal operation, this results in the period +of ZSK generation being \fIzsk\-lifetime + propagation\-delay + dnskey_ttl\fP\&. +.sp +Zero (aka infinity) value causes no ZSK rollover as a result. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB30d\fP (30 days) +.SS delete\-delay +.sp +Once a key (KSK or ZSK) is rolled\-over and removed from the zone, +keep it in the KASP database for at least this period (in seconds) before deleting +it completely. This might be useful in some troubleshooting cases when resurrection +is needed. +.sp +\fIDefault:\fP \fB0\fP +.SS propagation\-delay +.sp +An extra delay added for each key rollover step. This value (in seconds) +should be high enough to cover propagation of data from the primary server +to all secondary servers, as well as the duration of signing routine itself +and possible outages in signing and propagation infrastructure. In other +words, this delay should ensure that within this period of time after +planned change of the key set, all public\-facing secondaries will already +serve new DNSKEY RRSet for sure. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Has influence over ZSK key lifetime. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB1h\fP (1 hour) +.SS rrsig\-lifetime +.sp +A validity period (in seconds) of newly issued signatures. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The RRSIG\(aqs signature inception time is set to 90 minutes in the past. This +time period is not counted to the signature lifetime. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB14d\fP (14 days) +.SS rrsig\-refresh +.sp +A period (in seconds) how long at least before a signature expiration the signature +will be refreshed, in order to prevent expired RRSIGs on secondary servers or +resolvers\(aq caches. +.sp +\fIDefault:\fP 0.1 * \fI\%rrsig\-lifetime\fP + \fI\%propagation\-delay\fP + \fI\%zone\-max\-ttl\fP +.sp +If \fI\%dnssec\-validation\fP is enabled: +.sp +\fIDefault:\fP \fB1d\fP (1 day) +.SS rrsig\-pre\-refresh +.sp +A period (in seconds) how long at most before a signature refresh time the signature +might be refreshed, in order to refresh RRSIGs in bigger batches on a frequently updated +zone (avoid re\-sign event too often). +.sp +\fIDefault:\fP \fB1h\fP (1 hour) +.SS reproducible\-signing +.sp +For ECDSA algorithms, generate RRSIG signatures deterministically (\fI\%RFC 6979\fP). +Besides better theoretical cryptographic security, this mode allows significant +speed\-up of loading signed (by the same method) zones. However, the zone signing +is a bit slower. +.sp +\fIDefault:\fP \fBoff\fP +.SS nsec3 +.sp +Specifies if NSEC3 will be used instead of NSEC. +.sp +\fIDefault:\fP \fBoff\fP +.SS nsec3\-iterations +.sp +A number of additional times the hashing is performed. +.sp +\fIDefault:\fP \fB0\fP +.SS nsec3\-opt\-out +.sp +If set, NSEC3 records won\(aqt be created for insecure delegations. +This speeds up the zone signing and reduces overall zone size. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +NSEC3 with the Opt\-Out bit set no longer works as a proof of non\-existence +in this zone. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS nsec3\-salt\-length +.sp +A length of a salt field in octets, which is appended to the original owner +name before hashing. +.sp +\fIDefault:\fP \fB8\fP +.SS nsec3\-salt\-lifetime +.sp +A validity period (in seconds) of newly issued salt field. +.sp +Zero value means infinity. +.sp +Special value \fI\-1\fP triggers re\-salt every time when active ZSK changes. +This optimizes the number of big changes to the zone. +.sp +\fIDefault:\fP \fB30d\fP (30 days) +.SS signing\-threads +.sp +When signing zone or update, use this number of threads for parallel signing. +.sp +Those are extra threads independent of \fI\%Background workers\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Some steps of the DNSSEC signing operation are not parallelized. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB1\fP (no extra threads) +.SS ksk\-submission +.sp +A reference to \fI\%submission\fP section holding parameters of +KSK submission checks. +.sp +\fIDefault:\fP not set +.SS ds\-push +.sp +Optional references \fI\%remote\fP and \fI\%remotes\fP +to authoritative DNS server of the +parent\(aqs zone. The remote server must be configured to accept DS record +updates via DDNS. Whenever a CDS record in the local zone is changed, the +corresponding DS record is sent as a dynamic update (DDNS) to the parent +DNS server. All previous DS records are deleted within the DDNS message. +It\(aqs possible to manage both child and parent zones by the same Knot DNS server. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This feature requires \fI\%cds\-cdnskey\-publish\fP +not to be set to \fBnone\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The mentioned change to CDS record usually means that a KSK roll\-over is running +and the new key being rolled\-in is in \(dqready\(dq state already for the period of +\fI\%propagation\-delay\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Module \fI\%Onlinesign\fP doesn\(aqt support DS push. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +When turning this feature on while a KSK roll\-over is already running, it might +not take effect for the already\-running roll\-over. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS dnskey\-sync +.sp +A reference to \fI\%dnskey\-sync\fP section holding parameters +of DNSKEY synchronization. +.sp +\fIDefault:\fP not set +.SS cds\-cdnskey\-publish +.sp +Controls if and how shall the CDS and CDNSKEY be published in the zone. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – Never publish any CDS or CDNSKEY records in the zone. +.IP \(bu 2 +\fBdelete\-dnssec\fP – Publish special CDS and CDNSKEY records indicating turning off DNSSEC. +.IP \(bu 2 +\fBrollover\fP – Publish CDS and CDNSKEY records for ready and not yet active KSK (submission phase of KSK rollover). +.IP \(bu 2 +\fBalways\fP – Always publish one CDS and one CDNSKEY records for the current KSK. +.IP \(bu 2 +\fBdouble\-ds\fP – Always publish up to two CDS and two CDNSKEY records for ready and/or active KSKs. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If the zone keys are managed manually, the CDS and CDNSKEY rrsets may contain +more records depending on the keys available. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBdouble\-ds\fP value does not trigger double\-DS roll\-over method. That method is +only supported when performed manually, with unset \fI\%ksk\-submission\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBrollover\fP +.SS cds\-digest\-type +.sp +Specify digest type for published CDS records. +.sp +\fIDefault:\fP \fBsha256\fP +.SS dnskey\-management +.sp +Specify how the DNSKEY, CDNSKEY, and CDS RRSets at the zone apex are handled +when (re\-)signing the zone. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBfull\fP – Upon every zone (re\-)sign, delete all unknown DNSKEY, CDNSKEY, and CDS +records and keep just those that are related to the zone keys stored in the KASP database. +.IP \(bu 2 +\fBincremental\fP – Keep unknown DNSKEY, CDNSKEY, and CDS records in the zone, and +modify server\-managed records incrementally by employing changes in the KASP database. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Prerequisites for \fIincremental\fP: +.INDENT 0.0 +.IP \(bu 2 +The \fI\%Offline KSK\fP isn\(aqt supported. +.IP \(bu 2 +The \fI\%delete\-delay\fP is long enough to cover possible daemon +shutdown (e.g. due to server maintenance). +.IP \(bu 2 +Avoided manual deletion of keys with \fI\%keymgr\fP\&. +.UNINDENT +.sp +Otherwise there might remain some DNSKEY records in the zone, belonging to +deleted keys. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBfull\fP +.SS offline\-ksk +.sp +Specifies if \fI\%Offline KSK\fP feature is enabled. +.sp +\fIDefault:\fP \fBoff\fP +.SS unsafe\-operation +.sp +Turn off some DNSSEC safety features. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – Nothing disabled. +.IP \(bu 2 +\fBno\-check\-keyset\fP – Don\(aqt check active keys in present algorithms. This may +lead to violation of \fI\%RFC 4035#section\-2.2\fP\&. +.IP \(bu 2 +\fBno\-update\-dnskey\fP – Don\(aqt maintain/update DNSKEY, CDNSKEY, and CDS records +in the zone apex according to KASP database. Juste leave them as they are in the zone. +.IP \(bu 2 +\fBno\-update\-nsec\fP – Don\(aqt maintain/update NSEC/NSEC3 chain. Leave all the records +as they are in the zone. +.IP \(bu 2 +\fBno\-update\-expired\fP – Don\(aqt update expired RRSIGs. +.UNINDENT +.sp +Multiple values may be specified. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This mode is intended for DNSSEC experts who understand the corresponding consequences. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBnone\fP +.SH TEMPLATE SECTION +.sp +A template is shareable zone settings, which can simplify configuration by +reducing duplicates. A special default template (with the \fIdefault\fP identifier) +can be used for global zone configuration or as an implicit configuration +if a zone doesn\(aqt have another template specified. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +template: + \- id: STR + global\-module: STR/STR ... + # All zone options (excluding \(aqtemplate\(aq item) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If an item is explicitly specified both in the referenced template and +the zone, the template item value is overridden by the zone item value. +.UNINDENT +.UNINDENT +.SS id +.sp +A template identifier. +.SS global\-module +.sp +An ordered list of references to query modules in the form of \fImodule_name\fP or +\fImodule_name/module_id\fP\&. These modules apply to all queries. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is only available in the \fIdefault\fP template. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SH ZONE SECTION +.sp +Definition of zones served by the server. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone: + \- domain: DNAME + template: template_id + storage: STR + file: STR + master: remote_id | remotes_id ... + ddns\-master: remote_id + notify: remote_id | remotes_id ... + acl: acl_id ... + master\-pin\-tolerance: TIME + provide\-ixfr: BOOL + semantic\-checks: BOOL | soft + default\-ttl: TIME + zonefile\-sync: TIME + zonefile\-load: none | difference | difference\-no\-serial | whole + journal\-content: none | changes | all + journal\-max\-usage: SIZE + journal\-max\-depth: INT + ixfr\-benevolent: BOOL + ixfr\-by\-one: BOOL + ixfr\-from\-axfr: BOOL + zone\-max\-size : SIZE + adjust\-threads: INT + dnssec\-signing: BOOL + dnssec\-validation: BOOL + dnssec\-policy: policy_id + ds\-push: remote_id | remotes_id ... + zonemd\-verify: BOOL + zonemd\-generate: none | zonemd\-sha384 | zonemd\-sha512 | remove + serial\-policy: increment | unixtime | dateserial + serial\-modulo: INT/INT + reverse\-generate: DNAME + refresh\-min\-interval: TIME + refresh\-max\-interval: TIME + retry\-min\-interval: TIME + retry\-max\-interval: TIME + expire\-min\-interval: TIME + expire\-max\-interval: TIME + catalog\-role: none | interpret | generate | member + catalog\-template: template_id ... + catalog\-zone: DNAME + catalog\-group: STR + module: STR/STR ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS domain +.sp +A zone name identifier. +.SS template +.sp +A \fI\%reference\fP to a configuration template. +.sp +\fIDefault:\fP not set or \fBdefault\fP (if the template exists) +.SS storage +.sp +A data directory for storing zone files. A non\-absolute path is relative to +the \fI\%knotd\fP startup directory. +.sp +\fIDefault:\fP \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP) +.SS file +.sp +A \fI\%path\fP to the zone file. It is also possible to use +the following formatters: +.INDENT 0.0 +.IP \(bu 2 +\fB%c[\fP\fIN\fP\fB]\fP or \fB%c[\fP\fIN\fP\fB\-\fP\fIM\fP\fB]\fP – Means the \fIN\fPth +character or a sequence of characters beginning from the \fIN\fPth and ending +with the \fIM\fPth character of the textual zone name (see \fB%s\fP). The +indexes are counted from 0 from the left. All dots (including the terminal +one) are considered. If the character is not available, the formatter has no effect. +.IP \(bu 2 +\fB%l[\fP\fIN\fP\fB]\fP – Means the \fIN\fPth label of the textual zone name +(see \fB%s\fP). The index is counted from 0 from the right (0 ~ TLD). +If the label is not available, the formatter has no effect. +.IP \(bu 2 +\fB%s\fP – Means the current zone name in the textual representation. +The zone name doesn\(aqt include the terminating dot (the result for the root +zone is the empty string!). +.IP \(bu 2 +\fB%%\fP – Means the \fB%\fP character. +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Beware of special characters which are escaped or encoded in the \eDDD form +where DDD is corresponding decimal ASCII code. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fI\%storage\fP\fB/%s.zone\fP +.SS master +.sp +An ordered list of references \fI\%remote\fP and +\fI\%remotes\fP to zone primary servers +(formerly known as master servers). +Empty value is allowed for template value overriding. +.sp +\fIDefault:\fP not set +.SS ddns\-master +.sp +A \fI\%reference\fP to a zone primary master where DDNS messages +should be forwarded to. If not specified, the first \fI\%master\fP +server is used. +.sp +If set to the empty value (\(dq\(dq), incoming DDNS messages aren\(aqt forwarded but are applied +to the local zone instead, no matter if it is a secondary server. This is only allowed in +combination with \fI\%dnssec\-signing\fP enabled. +.sp +\fIDefault:\fP not set +.SS notify +.sp +An ordered list of references \fI\%remote\fP and +\fI\%remotes\fP to secondary servers to which notify +message is sent if the zone changes. +Empty value is allowed for template value overriding. +.sp +\fIDefault:\fP not set +.SS acl +.sp +An ordered list of \fI\%references\fP to ACL rules which can allow +or disallow zone transfers, updates or incoming notifies. +.sp +\fIDefault:\fP not set +.SS master\-pin\-tolerance +.sp +If set to a nonzero value on a secondary, always request AXFR/IXFR from the same +primary as the last time, effectively pinning one primary. Only when another +primary is updated and the current one lags behind for the specified amount of time +(defined by this option in seconds), change to the updated primary and force AXFR. +.sp +This option is useful when multiple primaries may have different zone history +in their journals, making it unsafe to combine interchanged IXFR +from different primaries. +.sp +\fIDefault:\fP \fB0\fP (disabled) +.SS provide\-ixfr +.sp +If disabled, the server is forced to respond with AXFR to IXFR queries. +If enabled, IXFR requests are responded normally. +.sp +\fIDefault:\fP \fBon\fP +.SS semantic\-checks +.sp +Selects if extra zone semantic checks are used or impacts of the mandatory checks. +.sp +There are several mandatory checks which are always enabled and cannot be turned +off. An error in a mandatory check causes the zone not to be loaded. Most of +the mandatory checks can be weakened by setting \fBsoft\fP, which allows the zone to +be loaded even if the check fails. +.sp +If enabled, extra checks are used. These checks don\(aqt prevent the zone from loading. +.sp +The mandatory checks are applied to zone files, zone transfers, and updates via +control interface. The extra checks are applied to zone files only! +.sp +Mandatory checks: +.INDENT 0.0 +.IP \(bu 2 +Missing SOA record at the zone apex (\fI\%RFC 1034\fP) (*) +.IP \(bu 2 +An extra record exists together with a CNAME record except for RRSIG and NSEC (\fI\%RFC 1034\fP) +.IP \(bu 2 +Multiple CNAME records with the same owner exist (\fI\%RFC 1034\fP) +.IP \(bu 2 +DNAME record having a record under it (\fI\%RFC 6672\fP) +.IP \(bu 2 +Multiple DNAME records with the same owner exist (\fI\%RFC 6672\fP) +.IP \(bu 2 +NS record exists together with a DNAME record (\fI\%RFC 6672\fP) +.IP \(bu 2 +DS record exists at the zone apex (\fI\%RFC 3658\fP) +.UNINDENT +.sp +(*) The marked check can\(aqt be weakened by the soft mode. All other mandatory checks +are subject to the optional soft mode. +.sp +Extra checks: +.INDENT 0.0 +.IP \(bu 2 +Missing NS record at the zone apex +.IP \(bu 2 +Missing glue A or AAAA record +.IP \(bu 2 +Invalid DS or NSEC3PARAM record +.IP \(bu 2 +CDS or CDNSKEY inconsistency +.IP \(bu 2 +All other DNSSEC checks executed during \fI\%dnssec\-validation\fP +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The soft mode allows the refresh event to ignore a CNAME response to a SOA +query (malformed message) and triggers a zone bootstrap instead. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS default\-ttl +.sp +The default TTL value if none is specified in a zone file or zone insertion +using the dynamic configuration. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +As changing this value can result in differently parsed zone file(s), +the corresponding zone SOA serial(s) should be incremented before +reloading or commiting the configuration. Alternatively, setting +\fI\%zonefile\-load\fP to \fBdifference\-no\-serial\fP ensures +the resulting zone(s) update is correct. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB3600\fP +.SS zonefile\-sync +.sp +The time in seconds after which the current zone in memory will be synced with +a zone file on the disk (see \fI\%file\fP). The server will serve the latest +zone even after a restart using zone journal, but the zone file on the disk will +only be synced after \fBzonefile\-sync\fP time has expired (or after manual zone +flush). This is applicable when the zone is updated via IXFR, DDNS or automatic +DNSSEC signing. In order to completely disable automatic zone file synchronization, +set the value to \-1. In that case, it is still possible to force a manual zone flush +using the \fB\-f\fP option. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If you are serving large zones with frequent updates where +the immediate sync with a zone file is not desirable, increase the value. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB0\fP (immediate) +.SS zonefile\-load +.sp +Selects how the zone file contents are applied during zone load. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – The zone file is not used at all. +.IP \(bu 2 +\fBdifference\fP – If the zone contents are already available during server start or reload, +the difference is computed between them and the contents of the zone file. This difference +is then checked for semantic errors and applied to the current zone contents. +.IP \(bu 2 +\fBdifference\-no\-serial\fP – Same as \fBdifference\fP, but the SOA serial in the zone file is +ignored, the server takes care of incrementing the serial automatically. +.IP \(bu 2 +\fBwhole\fP – Zone contents are loaded from the zone file. +.UNINDENT +.sp +When \fBdifference\fP is configured and there are no zone contents yet (cold start +and no zone contents in the journal), it behaves the same way as \fBwhole\fP\&. +.sp +\fIDefault:\fP \fBwhole\fP +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +See \fI\%Handling zone file, journal, changes, serials\fP for guidance on +configuring these and related options to ensure reliable operation. +.UNINDENT +.UNINDENT +.SS journal\-content +.sp +Selects how the journal shall be used to store zone and its changes. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – The journal is not used at all. +.IP \(bu 2 +\fBchanges\fP – Zone changes history is stored in journal. +.IP \(bu 2 +\fBall\fP – Zone contents and history is stored in journal. +.UNINDENT +.sp +\fIDefault:\fP \fBchanges\fP +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +When this option is changed, the journal still contains data respective to +the previous setting. For example, changing it to \fBnone\fP does not purge +the journal. Also, changing it from \fBall\fP to \fBchanges\fP +does not cause the deletion of the zone\-in\-journal and the behaviour of the +zone loading procedure might be different than expected. It is recommended +to consider purging the journal when this option is changed. +.UNINDENT +.UNINDENT +.SS journal\-max\-usage +.sp +Policy how much space in journal DB will the zone\(aqs journal occupy. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Journal DB may grow far above the sum of journal\-max\-usage across +all zones, because of DB free space fragmentation. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB100M\fP (100 MiB) +.SS journal\-max\-depth +.sp +Maximum history length of the journal. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Zone\-in\-journal changeset isn\(aqt counted to the limit. +.UNINDENT +.UNINDENT +.sp +\fIMinimum:\fP \fB2\fP +.sp +\fIDefault:\fP \fB20\fP +.SS ixfr\-benevolent +.sp +If enabled, incoming IXFR is applied even when it contains removals of non\-existing +or additions of existing records. +.sp +\fIDefault:\fP \fBoff\fP +.SS ixfr\-by\-one +.sp +Within incoming IXFR, process only one changeset at a time, not multiple together. +This preserves the complete history in the journal and prevents the merging of +changesets when multiple changesets are IXFRed simultaneously. However, this does not +prevent the merging (or deletion) of old changesets in the journal to save space, +as described in \fI\%journal behaviour\fP\&. +.sp +This option leads to increased server load when processing IXFR, including +network traffic. +.sp +\fIDefault:\fP \fBoff\fP +.SS ixfr\-from\-axfr +.sp +If a primary sends AXFR\-style\-IXFR upon an IXFR request, compute the difference +and process it as an incremental zone update (e.g. by storing the changeset in +the journal). +.sp +\fIDefault:\fP \fBoff\fP +.SS zone\-max\-size +.sp +Maximum size of the zone. The size is measured as size of the zone records +in wire format without compression. The limit is enforced for incoming zone +transfers and dynamic updates. +.sp +For incremental transfers (IXFR), the effective limit for the total size of +the records in the transfer is twice the configured value. However the final +size of the zone must satisfy the configured value. +.sp +\fIDefault:\fP unlimited +.SS adjust\-threads +.sp +Parallelize internal zone adjusting procedures by using specified number of +threads. This is useful with huge zones with NSEC3. Speedup observable at +server startup and while processing NSEC3 re\-salt. +.sp +\fIDefault:\fP \fB1\fP (no extra threads) +.SS dnssec\-signing +.sp +If enabled, automatic DNSSEC signing for the zone is turned on. +.sp +\fIDefault:\fP \fBoff\fP +.SS dnssec\-validation +.sp +If enabled, the zone contents are validated for being correctly signed +(including NSEC/NSEC3 chain) with DNSSEC signatures every time the zone +is loaded or changed (including AXFR/IXFR). +.sp +When the validation fails, the zone being loaded or update being applied +is cancelled with an error, and either none or previous zone state is published. +.sp +List of DNSSEC checks: +.INDENT 0.0 +.IP \(bu 2 +Every zone RRSet is correctly signed by at least one present DNSKEY. +.IP \(bu 2 +For every RRSIG there are at most 3 non\-matching DNSKEYs with the same keytag. +.IP \(bu 2 +DNSKEY RRSet is signed by KSK. +.IP \(bu 2 +NSEC(3) RR exists for each name (unless opt\-out) with correct bitmap. +.IP \(bu 2 +Every NSEC(3) RR is linked to the lexicographically next one. +.UNINDENT +.sp +The validation is not affected by \fI\%dnssec\-policy\fP configuration, +except for \fI\%signing\-threads\fP option, which specifies the number +of threads for parallel validation, and \fI\%rrsig\-refresh\fP, which +defines minimal allowed remaining RRSIG validity (otherwise a warning is +logged). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Redundant or garbage NSEC3 records are ignored. +.sp +This mode is not compatible with \fI\%dnssec\-signing\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS dnssec\-policy +.sp +A \fI\%reference\fP to DNSSEC signing policy. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +A configured policy called \(dqdefault\(dq won\(aqt be used unless explicitly referenced. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP an imaginary policy with all default values +.SS ds\-push +.sp +Per zone configuration of \fI\%ds\-push\fP\&. This option overrides possible +per policy option. Empty value is allowed for template value overriding. +.sp +\fIDefault:\fP not set +.SS zonemd\-verify +.sp +On each zone load/update, verify that ZONEMD is present in the zone and valid. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Zone digest calculation may take much time and CPU on large zones. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS zonemd\-generate +.sp +On each zone update, calculate ZONEMD and put it into the zone. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – No action regarding ZONEMD. +.IP \(bu 2 +\fBzonemd\-sha384\fP – Generate ZONEMD using SHA384 algorithm. +.IP \(bu 2 +\fBzonemd\-sha512\fP – Generate ZONEMD using SHA512 algorithm. +.IP \(bu 2 +\fBremove\fP – Remove any ZONEMD from the zone apex. +.UNINDENT +.sp +\fIDefault:\fP \fBnone\fP +.SS serial\-policy +.sp +Specifies how the zone serial is updated after a dynamic update or +automatic DNSSEC signing. If the serial is changed by the dynamic update, +no change is made. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBincrement\fP – The serial is incremented according to serial number arithmetic. +.IP \(bu 2 +\fBunixtime\fP – The serial is set to the current unix time. +.IP \(bu 2 +\fBdateserial\fP – The 10\-digit serial (YYYYMMDDnn) is incremented, the first +8 digits match the current iso\-date. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If the resulting serial for \fBunixtime\fP or \fBdateserial\fP is lower than or +equal to the current serial (this happens e.g. when migrating from other policy or +frequent updates), the serial is incremented instead. +.sp +To avoid user confusion, use \fBdateserial\fP only if you expect at most +100 updates per day per zone and \fBunixtime\fP only if you expect at most +one update per second per zone. +.sp +Generated catalog zones use \fBunixtime\fP only. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBincrement\fP (\fBunixtime\fP for generated catalog zones) +.SS serial\-modulo +.sp +Specifies that the zone serials shall be congruent by specified modulo. +The option value must be a string in the format \fBR/M\fP, where \fBR < M <= 256\fP are +positive integers. Whenever the zone serial is incremented, it is ensured +that \fBserial % M == R\fP\&. This can be useful in the case of multiple inconsistent +primaries, where distinct zone serial sequences prevent cross\-master\-IXFR +by any secondary. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +In order to ensure the congruent policy, this option is only allowed +with \fI\%DNSSEC signing enabled\fP and +\fI\%zonefile\-load\fP to be either \fBdifference\-no\-serial\fP or \fBnone\fP\&. +.sp +Because the zone serial effectively always increments by \fBM\fP instead of +\fB1\fP, it is not recommended to use \fBdateserial\fP \fI\%serial\-policy\fP +or even \fBunixtime\fP in case of rapidly updated zone. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB0/1\fP +.SS reverse\-generate +.sp +This option triggers the automatic generation of reverse PTR records based on +A/AAAA records in the specified zone. The entire generated zone is automatically +stored in the journal. +.sp +Current limitations: +.INDENT 0.0 +.IP \(bu 2 +Only one zone to be reversed can be specified. +.IP \(bu 2 +Is slow for large zones (even when changing a little). +.UNINDENT +.sp +\fIDefault:\fP none +.SS refresh\-min\-interval +.sp +Forced minimum zone refresh interval (in seconds) to avoid flooding primary server. +.sp +\fIMinimum:\fP \fB2\fP +.sp +\fIDefault:\fP \fB2\fP +.SS refresh\-max\-interval +.sp +Forced maximum zone refresh interval (in seconds). +.sp +\fIDefault:\fP not set +.SS retry\-min\-interval +.sp +Forced minimum zone retry interval (in seconds) to avoid flooding primary server. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB1\fP +.SS retry\-max\-interval +.sp +Forced maximum zone retry interval (in seconds). +.sp +\fIDefault:\fP not set +.SS expire\-min\-interval +.sp +Forced minimum zone expire interval (in seconds) to avoid flooding primary server. +.sp +\fIMinimum:\fP \fB3\fP +.sp +\fIDefault:\fP \fB3\fP +.SS expire\-max\-interval +.sp +Forced maximum zone expire interval (in seconds). +.sp +\fIDefault:\fP not set +.SS catalog\-role +.sp +Trigger zone catalog feature. Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – Not a catalog zone. +.IP \(bu 2 +\fBinterpret\fP – A catalog zone which is loaded from a zone file or XFR, +and member zones shall be configured based on its contents. +.IP \(bu 2 +\fBgenerate\fP – A catalog zone whose contents are generated according to +assigned member zones. +.IP \(bu 2 +\fBmember\fP – A member zone that is assigned to one generated catalog zone. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If set to \fBgenerate\fP, the \fI\%zonefile\-load\fP option has no effect +since a zone file is never loaded. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBnone\fP +.SS catalog\-template +.sp +For the catalog member zones, the specified configuration template will be applied. +.sp +Multiple catalog templates may be defined. The first one is used unless the member zone +has the \fIgroup\fP property defined, matching another catalog template. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option must be set if and only if \fI\%catalog\-role\fP is \fIinterpret\fP\&. +.sp +Nested catalog zones aren\(aqt supported. Therefore catalog templates can\(aqt +contain \fI\%catalog\-role\fP set to \fBinterpret\fP or \fBgenerate\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS catalog\-zone +.sp +Assign this member zone to specified generated catalog zone. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option must be set if and only if \fI\%catalog\-role\fP is \fImember\fP\&. +.sp +The referenced catalog zone must exist and have \fI\%catalog\-role\fP set to \fIgenerate\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS catalog\-group +.sp +Assign this member zone to specified catalog group (configuration template). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option has effect if and only if \fI\%catalog\-role\fP is \fImember\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS module +.sp +An ordered list of references to query modules in the form of \fImodule_name\fP or +\fImodule_name/module_id\fP\&. These modules apply only to the current zone queries. +.sp +\fIDefault:\fP not set +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/knot.conf.5in b/doc/man/knot.conf.5in deleted file mode 100644 index d091d15..0000000 --- a/doc/man/knot.conf.5in +++ /dev/null @@ -1,2887 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KNOT.CONF" "5" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -knot.conf \- Knot DNS configuration file -.SH DESCRIPTION -.sp -Configuration files for Knot DNS use simplified YAML format. Simplified means -that not all of the features are supported. -.sp -For the description of configuration items, we have to declare a meaning of -the following symbols: -.INDENT 0.0 -.IP \(bu 2 -\fBINT\fP – Integer -.IP \(bu 2 -\fBSTR\fP – Textual string -.IP \(bu 2 -\fBHEXSTR\fP – Hexadecimal string (with \fB0x\fP prefix) -.IP \(bu 2 -\fBBOOL\fP – Boolean value (\fBon\fP/\fBoff\fP or \fBtrue\fP/\fBfalse\fP) -.IP \(bu 2 -\fBTIME\fP – Number of seconds, an integer with possible time multiplier suffix -(\fBs\fP ~ 1, \fBm\fP ~ 60, \fBh\fP ~ 3600 or \fBd\fP ~ 24 * 3600) -.IP \(bu 2 -\fBSIZE\fP – Number of bytes, an integer with possible size multiplier suffix -(\fBB\fP ~ 1, \fBK\fP ~ 1024, \fBM\fP ~ 1024^2 or \fBG\fP ~ 1024^3) -.IP \(bu 2 -\fBBASE64\fP – Base64 encoded string -.IP \(bu 2 -\fBADDR\fP – IPv4 or IPv6 address -.IP \(bu 2 -\fBDNAME\fP – Domain name -.IP \(bu 2 -\fB\&...\fP – Multi\-valued item, order of the values is preserved -.IP \(bu 2 -\fB[\fP \fB]\fP – Optional value -.IP \(bu 2 -\fB|\fP – Choice -.UNINDENT -.sp -The configuration consists of several fixed sections and optional module -sections. There are 17 fixed sections (\fBmodule\fP, \fBserver\fP, \fBxdp\fP, \fBcontrol\fP, -\fBlog\fP, \fBstatistics\fP, \fBdatabase\fP, \fBkeystore\fP, \fBkey\fP, \fBremote\fP, -\fBremotes\fP, \fBacl\fP, \fBsubmission\fP, \fBdnskey\-sync\fP, \fBpolicy\fP, \fBtemplate\fP, -\fBzone\fP). -Module sections are prefixed with the \fBmod\-\fP prefix (e.g. \fBmod\-stats\fP). -.sp -Most of the sections (e.g. \fBzone\fP) are sequences of settings blocks. Each -settings block begins with a unique identifier, which can be used as a reference -from other sections (such an identifier must be defined in advance). -.sp -A multi\-valued item can be specified either as a YAML sequence: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -address: [10.0.0.1, 10.0.0.2] -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -or as more single\-valued items each on an extra line: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -address: 10.0.0.1 -address: 10.0.0.2 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -If an item value contains spaces or other special characters, it is necessary -to enclose such a value within double quotes \fB\(dq\fP \fB\(dq\fP\&. -.sp -If not specified otherwise, an item representing a file or a directory path may -be defined either as an absolute path (starting with \fB/\fP), or a path relative -to the same directory as the default value of the item. -.SH COMMENTS -.sp -A comment begins with a \fB#\fP character and is ignored during processing. -Also each configuration section or sequence block allows a permanent -comment using the \fBcomment\fP item which is stored in the server beside the -configuration. -.SH INCLUDING CONFIGURATION -.sp -Another configuration file or files, matching a pattern, can be included at -the top level in the current file. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -include: STR -.ft P -.fi -.UNINDENT -.UNINDENT -.SS include -.sp -A path or a matching pattern specifying one or more files that are included -at the place of the include option position in the configuration. -If the path is not absolute, then it is considered to be relative to the -current file. The pattern can be an arbitrary string meeting POSIX \fIglob\fP -requirements, e.g. dir/*.conf. Matching files are processed in sorted order. -.sp -\fIDefault:\fP not set -.SH CLEARING CONFIGURATION SECTIONS -.sp -It\(aqs possible to clear specified configuration sections at given phases -of the configuration parsing. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -clear: STR -.ft P -.fi -.UNINDENT -.UNINDENT -.SS clear -.sp -A matching pattern specifying configuration sections that are cleared when -this item is parsed. This allows overriding of existing configuration -in the configuration database when including a configuration file or -ensures that some configuration wasn\(aqt specified in previous includes. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -For the pattern matching the POSIX function -\fI\%fnmatch()\fP -is used. On Linux, the GNU extension -\fI\%FNM_EXTMATCH\fP -is enabled, which allows extended pattern matching. -Examples: -.INDENT 0.0 -.IP \(bu 2 -\fBclear: zone\fP – Clears the \fBzone\fP section. -.IP \(bu 2 -\fBclear: mod\-*\fP – Clears all module sections. -.IP \(bu 2 -\fBclear: \(dq[!z]*\(dq\fP – Clears all sections not beginning with letter \fBz\fP\&. -.IP \(bu 2 -\fBclear: !(zone)\fP – (GNU only) Clears all sections except the \fBzone\fP one. -.IP \(bu 2 -\fBclear: @(zone|template)\fP – (GNU only) Clears the \fBzone\fP and \fBtemplate\fP sections. -.UNINDENT -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP not set -.SH MODULE SECTION -.sp -Dynamic modules loading configuration. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -If configured with non\-empty \fB\-\-with\-moduledir=path\fP parameter, all -shared modules in this directory will be automatically loaded. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -module: - \- id: STR - file: STR -.ft P -.fi -.UNINDENT -.UNINDENT -.SS id -.sp -A module identifier in the form of the \fBmod\-\fP prefix and module name suffix. -.SS file -.sp -A path to a shared library file with the module implementation. -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -If the path is not absolute, the library is searched in the set of -system directories. See \fBman dlopen\fP for more details. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB${libdir}/knot/modules\-${version}\fP/module_name.so -(or \fB${path}\fP/module_name.so if configured with \fB\-\-with\-moduledir=path\fP) -.SH SERVER SECTION -.sp -General options related to the server. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -server: - identity: [STR] - version: [STR] - nsid: [STR|HEXSTR] - rundir: STR - user: STR[:STR] - pidfile: STR - udp\-workers: INT - tcp\-workers: INT - background\-workers: INT - async\-start: BOOL - tcp\-idle\-timeout: TIME - tcp\-io\-timeout: INT - tcp\-remote\-io\-timeout: INT - tcp\-max\-clients: INT - tcp\-reuseport: BOOL - tcp\-fastopen: BOOL - quic\-max\-clients: INT - quic\-outbuf\-max\-size: SIZE - quic\-idle\-close\-timeout: TIME - remote\-pool\-limit: INT - remote\-pool\-timeout: TIME - remote\-retry\-delay: INT - socket\-affinity: BOOL - udp\-max\-payload: SIZE - udp\-max\-payload\-ipv4: SIZE - udp\-max\-payload\-ipv6: SIZE - key\-file: STR - cert\-file: STR - edns\-client\-subnet: BOOL - answer\-rotation: BOOL - automatic\-acl: BOOL - proxy\-allowlist: ADDR[/INT] | ADDR\-ADDR ... - dbus\-event: none | running | zone\-updated | ksk\-submission | dnssec\-invalid ... - dbus\-init\-delay: TIME - listen: ADDR[@INT] | STR ... - listen\-quic: ADDR[@INT] ... -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBCAUTION:\fP -.INDENT 0.0 -.INDENT 3.5 -When you change configuration parameters dynamically or via configuration file -reload, some parameters in the Server section require restarting the Knot server -so that the changes take effect. See below for the details. -.UNINDENT -.UNINDENT -.SS identity -.sp -An identity of the server returned in the response to the query for TXT -record \fBid.server.\fP or \fBhostname.bind.\fP in the CHAOS class (\fI\%RFC 4892\fP). -Set to an empty value to disable. -.sp -\fIDefault:\fP FQDN hostname -.SS version -.sp -A version of the server software returned in the response to the query -for TXT record \fBversion.server.\fP or \fBversion.bind.\fP in the CHAOS -class (\fI\%RFC 4892\fP). Set to an empty value to disable. -.sp -\fIDefault:\fP server version -.SS nsid -.sp -A DNS name server identifier (\fI\%RFC 5001\fP). Set to an empty value to disable. -.sp -\fIDefault:\fP FQDN hostname at the moment of the daemon start -.SS rundir -.sp -A path for storing run\-time data (PID file, unix sockets, etc.). A non\-absolute -path is relative to the \fI\%knotd\fP startup directory. -.sp -Depending on the usage of this parameter, its change may require restart of the Knot -server to take effect. -.sp -\fIDefault:\fP \fB${localstatedir}/run/knot\fP (configured with \fB\-\-with\-rundir=path\fP) -.SS user -.sp -A system user with an optional system group (\fBuser:group\fP) under which the -server is run after starting and binding to interfaces. Linux capabilities -are employed if supported. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fBroot:root\fP -.SS pidfile -.sp -A PID file \fI\%location\fP\&. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fI\%rundir\fP\fB/knot.pid\fP -.SS udp\-workers -.sp -A number of UDP workers (threads) used to process incoming queries -over UDP. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP equal to the number of online CPUs -.SS tcp\-workers -.sp -A number of TCP workers (threads) used to process incoming queries -over TCP. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP equal to the number of online CPUs, default value is at least 10 -.SS background\-workers -.sp -A number of workers (threads) used to execute background operations (zone -loading, zone updates, etc.). -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP equal to the number of online CPUs, default value is at most 10 -.SS async\-start -.sp -If enabled, server doesn\(aqt wait for the zones to be loaded and starts -responding immediately with SERVFAIL answers until the zone loads. -.sp -\fIDefault:\fP \fBoff\fP -.SS tcp\-idle\-timeout -.sp -Maximum idle time (in seconds) between requests on an inbound TCP connection. -It means if there is no activity on an inbound TCP connection during this limit, -the connection is closed by the server. -.sp -\fIMinimum:\fP \fB1\fP -.sp -\fIDefault:\fP \fB10\fP -.SS tcp\-io\-timeout -.sp -Maximum time (in milliseconds) to receive or send one DNS message over an inbound -TCP connection. It means this limit applies to normal DNS queries and replies, -incoming DDNS, and \fBoutgoing zone transfers\fP\&. The timeout is measured since some -data is already available for processing. -Set to 0 for infinity. -.sp -\fIDefault:\fP \fB500\fP (milliseconds) -.sp -\fBCAUTION:\fP -.INDENT 0.0 -.INDENT 3.5 -In order to reduce the risk of Slow Loris attacks, it\(aqs recommended setting -this limit as low as possible on public servers. -.UNINDENT -.UNINDENT -.SS tcp\-remote\-io\-timeout -.sp -Maximum time (in milliseconds) to receive or send one DNS message over an outbound -TCP connection which has already been established to a configured remote server. -It means this limit applies to incoming zone transfers, sending NOTIFY, -DDNS forwarding, and DS check or push. This timeout includes the time needed -for a network round\-trip and for a query processing by the remote. -Set to 0 for infinity. -.sp -\fIDefault:\fP \fB5000\fP (milliseconds) -.SS tcp\-reuseport -.sp -If enabled, each TCP worker listens on its own socket and the OS kernel -socket load balancing is employed using SO_REUSEPORT (or SO_REUSEPORT_LB -on FreeBSD). Due to the lack of one shared socket, the server can offer -higher response rate processing over TCP. However, in the case of -time\-consuming requests (e.g. zone transfers of a TLD zone), enabled reuseport -may result in delayed or not being responded client requests. So it is -advisable to use this option on secondary servers. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fBoff\fP -.SS tcp\-fastopen -.sp -If enabled, use TCP Fast Open for outbound TCP communication (client side): -incoming zone transfers, sending NOTIFY, and DDNS forwarding. This mode simplifies -TCP handshake and can result in better networking performance. TCP Fast Open -for inbound TCP communication (server side) isn\(aqt affected by this -configuration as it\(aqs enabled automatically if supported by OS. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -The TCP Fast Open support must also be enabled on the OS level: -.INDENT 0.0 -.IP \(bu 2 -Linux/macOS: ensure kernel parameter \fBnet.ipv4.tcp_fastopen\fP is \fB2\fP or -\fB3\fP for server side, and \fB1\fP or \fB3\fP for client side. -.IP \(bu 2 -FreeBSD: ensure kernel parameter \fBnet.inet.tcp.fastopen.server_enable\fP -is \fB1\fP for server side, and \fBnet.inet.tcp.fastopen.client_enable\fP is -\fB1\fP for client side. -.UNINDENT -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBoff\fP -.SS quic\-max\-clients -.sp -A maximum number of QUIC clients connected in parallel. -.sp -See also \fI\%quic\fP\&. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIMinimum:\fP \fB128\fP -.sp -\fIDefault:\fP \fB10000\fP (ten thousand) -.SS quic\-outbuf\-max\-size -.sp -Maximum cumulative size of memory used for buffers of unACKed -sent messages. This limit is per one UDP worker. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Set low if little memory is available (together with \fI\%quic\-max\-clients\fP -since QUIC connections are memory\-heavy). Set to high value if outgoing zone -transfers of big zone over QUIC are expected. -.UNINDENT -.UNINDENT -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIMinimum:\fP \fB1M\fP (1 MiB) -.sp -\fIDefault:\fP \fB100M\fP (100 MiB) -.SS quic\-idle\-close\-timeout -.sp -Time in seconds, after which any idle QUIC connection is gracefully closed. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIMinimum:\fP \fB1\fP -.sp -\fIDefault:\fP \fB4\fP -.SS remote\-pool\-limit -.sp -If nonzero, the server will keep up to this number of outgoing TCP connections -open for later use. This is an optimization to avoid frequent opening of -TCP connections to the same remote. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fB0\fP -.SS remote\-pool\-timeout -.sp -The timeout in seconds after which the unused kept\-open outgoing TCP connections -to remote servers are closed. -.sp -\fIDefault:\fP \fB5\fP -.SS remote\-retry\-delay -.sp -When a connection attempt times out to some remote address, this information will be -kept for this specified time (in milliseconds) and other connections to the same address won\(aqt -be attempted. This prevents repetitive waiting for timeout on an unreachable remote. -.sp -\fIDefault:\fP \fB0\fP -.SS socket\-affinity -.sp -If enabled and if SO_REUSEPORT is available on Linux, all configured network -sockets are bound to UDP and TCP workers in order to increase the networking performance. -This mode isn\(aqt recommended for setups where the number of network card queues -is lower than the number of UDP or TCP workers. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fBoff\fP -.SS tcp\-max\-clients -.sp -A maximum number of TCP clients connected in parallel, set this below the file -descriptor limit to avoid resource exhaustion. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -It is advisable to adjust the maximum number of open files per process in your -operating system configuration. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP one half of the file descriptor limit for the server process -.SS udp\-max\-payload -.sp -Maximum EDNS0 UDP payload size default for both IPv4 and IPv6. -.sp -\fIDefault:\fP \fB1232\fP -.SS udp\-max\-payload\-ipv4 -.sp -Maximum EDNS0 UDP payload size for IPv4. -.sp -\fIDefault:\fP \fB1232\fP -.SS udp\-max\-payload\-ipv6 -.sp -Maximum EDNS0 UDP payload size for IPv6. -.sp -\fIDefault:\fP \fB1232\fP -.SS key\-file -.sp -Path to a server key PEM file which is used for DNS over QUIC communication. -A non\-absolute path of a user specified key file is relative to the -\fB@config_dir@\fP directory. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP auto\-generated key -.SS cert\-file -.sp -Path to a server certificate PEM file which is used for DNS over QUIC communication. -A non\-absolute path is relative to the \fB@config_dir@\fP directory. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP one\-time in\-memory certificate -.SS edns\-client\-subnet -.sp -Enable or disable EDNS Client Subnet support. If enabled, responses to queries -containing the EDNS Client Subnet option -always contain a valid EDNS Client Subnet option according to \fI\%RFC 7871\fP\&. -.sp -\fIDefault:\fP \fBoff\fP -.SS answer\-rotation -.sp -Enable or disable sorted\-rrset rotation in the answer section of normal replies. -The rotation shift is simply determined by a query ID. -.sp -\fIDefault:\fP \fBoff\fP -.SS automatic\-acl -.sp -If enabled, \fI\%automatic ACL\fP setting of -configured remotes is considered when evaluating authorized operations. -.sp -\fIDefault:\fP \fBoff\fP -.SS proxy\-allowlist -.sp -An ordered list of IP addresses, network subnets, or network ranges -which are allowed as a source address of proxied DNS traffic over UDP. -The supported proxy protocol is -\fI\%haproxy PROXY v2\fP\&. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -TCP is not supported. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP not set -.SS dbus\-event -.sp -Specification of server or zone states which emit a D\-Bus signal on the system -bus. The bus name is \fBcz.nic.knotd\fP, the object path is \fB/cz/nic/knotd\fP, and -the interface name is \fBcz.nic.knotd.events\fP\&. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBnone\fP – No signal is emitted. -.IP \(bu 2 -\fBrunning\fP – There are two possible signals emitted: -.INDENT 2.0 -.IP \(bu 2 -\fBstarted\fP when the server is started and all configured zones (including -catalog zones and their members) are loaded or successfully bootstrapped. -.IP \(bu 2 -\fBstopped\fP when the server shutdown sequence is initiated. -.UNINDENT -.IP \(bu 2 -\fBzone\-updated\fP – The signal \fBzone_updated\fP is emitted when a zone has been updated; -the signal parameters are \fIzone name\fP and \fIzone SOA serial\fP\&. -.IP \(bu 2 -\fBkeys\-updated\fP \- The signal \fBkeys_updated\fP is emitted when a DNSSEC key set -of this zone is updated. -.IP \(bu 2 -\fBksk\-submission\fP – The signal \fBzone_ksk_submission\fP is emitted if there is -a ready KSK present when the zone is signed; the signal parameters are -\fIzone name\fP, \fIKSK keytag\fP, and \fIKSK KASP id\fP\&. -.IP \(bu 2 -\fBdnssec\-invalid\fP – The signal \fBzone_dnssec_invalid\fP is emitted when DNSSEC -validation fails; the signal parameter is \fIzone name\fP\&. -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This function requires systemd version at least 221. -.UNINDENT -.UNINDENT -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fBnone\fP -.SS dbus\-init\-delay -.sp -Time in seconds which the server waits upon D\-Bus initialization to ensure -the D\-Bus client is ready to receive signals. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIMinimum:\fP \fB0\fP -.sp -\fIDefault:\fP \fB1\fP -.SS listen -.sp -One or more IP addresses where the server listens for incoming queries. -Optional port specification (default is 53) can be appended to each address -using \fB@\fP separator. Use \fB0.0.0.0\fP for all configured IPv4 addresses or -\fB::\fP for all configured IPv6 addresses. Filesystem path can be specified -for listening on local unix SOCK_STREAM socket. Non\-absolute path -(i.e. not starting with \fB/\fP) is relative to \fI\%rundir\fP\&. -Non\-local address binding is automatically enabled if supported by the operating system. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP not set -.SS listen\-quic -.sp -One or more IP addresses (and optionally ports) where the server listens -for incoming queries over QUIC protocol. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP not set -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Incoming \fI\%DDNS\fP over QUIC isn\(aqt supported. -The server always responds with SERVFAIL. -.UNINDENT -.UNINDENT -.SH XDP SECTION -.sp -Various options related to XDP listening, especially TCP. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -xdp: - listen: STR[@INT] | ADDR[@INT] ... - udp: BOOL - tcp: BOOL - quic: BOOL - quic\-port: INT - tcp\-max\-clients: INT - tcp\-inbuf\-max\-size: SIZE - tcp\-outbuf\-max\-size: SIZE - tcp\-idle\-close\-timeout: TIME - tcp\-idle\-reset\-timeout: TIME - tcp\-resend\-timeout: TIME - route\-check: BOOL -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBCAUTION:\fP -.INDENT 0.0 -.INDENT 3.5 -When you change configuration parameters dynamically or via configuration file -reload, some parameters in the XDP section require restarting the Knot server -so that the changes take effect. -.UNINDENT -.UNINDENT -.SS listen -.sp -One or more network device names (e.g. \fBens786f0\fP) on which the \fI\%Mode XDP\fP -is enabled. Alternatively, an IP address can be used instead of a device name, -but the server will still listen on all addresses belonging to the same interface! -Optional port specification (default is 53) can be appended to each device name -or address using \fB@\fP separator. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fBCAUTION:\fP -.INDENT 0.0 -.INDENT 3.5 -If XDP workers only process regular DNS traffic over UDP, it is strongly -recommended to also \fI\%listen\fP on the addresses which are -intended to offer the DNS service, at least to fulfil the DNS requirement for -working TCP. -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Incoming \fI\%DDNS\fP over XDP isn\(aqt supported. -The server always responds with SERVFAIL. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP not set -.SS udp -.sp -If enabled, DNS over UDP is processed with XDP workers. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fBon\fP -.SS tcp -.sp -If enabled, DNS over TCP traffic is processed with XDP workers. -.sp -The TCP stack limitations: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.IP \(bu 2 -Congestion control is not implemented. -.IP \(bu 2 -Lost packets that do not contain TCP payload may not be resend. -.IP \(bu 2 -Not optimized for transfers of non\-trivial zones. -.UNINDENT -.UNINDENT -.UNINDENT -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fBoff\fP -.SS quic -.sp -If enabled, DNS over QUIC is processed with XDP workers. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fBoff\fP -.SS quic\-port -.sp -DNS over QUIC will listen on the interfaces configured by \fI\%listen\fP, -but on different port, configured by this option. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fB853\fP -.SS tcp\-max\-clients -.sp -A maximum number of TCP clients connected in parallel. -.sp -\fIMinimum:\fP \fB1024\fP -.sp -\fIDefault:\fP \fB1000000\fP (one million) -.SS tcp\-inbuf\-max\-size -.sp -Maximum cumulative size of memory used for buffers of incompletely -received messages. -.sp -\fIMinimum:\fP \fB1M\fP (1 MiB) -.sp -\fIDefault:\fP \fB100M\fP (100 MiB) -.SS tcp\-outbuf\-max\-size -.sp -Maximum cumulative size of memory used for buffers of unACKed -sent messages. -.sp -\fIMinimum:\fP \fB1M\fP (1 MiB) -.sp -\fIDefault:\fP \fB100M\fP (100 MiB) -.SS tcp\-idle\-close\-timeout -.sp -Time in seconds, after which any idle connection is gracefully closed. -.sp -\fIMinimum:\fP \fB1\fP -.sp -\fIDefault:\fP \fB10\fP -.SS tcp\-idle\-reset\-timeout -.sp -Time in seconds, after which any idle connection is forcibly closed. -.sp -\fIMinimum:\fP \fB1\fP -.sp -\fIDefault:\fP \fB20\fP -.SS tcp\-resend\-timeout -.sp -Resend outgoing data packets (with DNS response payload) if not ACKed -before this timeout (in seconds). -.sp -\fIMinimum:\fP \fB1\fP -.sp -\fIDefault:\fP \fB5\fP -.SS route\-check -.sp -If enabled, routing information from the operating system is considered -when processing every incoming DNS packet received over the XDP interface: -.INDENT 0.0 -.IP \(bu 2 -If the outgoing interface of the corresponding DNS response differs from -the incoming one, the packet is processed normally by UDP/TCP workers -(XDP isn\(aqt used). -.IP \(bu 2 -If the destination address is blackholed, unreachable, or prohibited, -the DNS packet is dropped without any response. -.IP \(bu 2 -The destination MAC address and possible VLAN tag for the response are taken -from the routing system. -.UNINDENT -.sp -If disabled, symmetrical routing is applied. It means that the query source -MAC address is used as a response destination MAC address. Possible VLAN tag -is preserved. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This mode requires forwarding enabled on the loopback interface -(\fBsysctl \-w net.ipv4.conf.lo.forwarding=1\fP and \fBsysctl \-w net.ipv6.conf.lo.forwarding=1\fP). -If forwarding is disabled, all incoming DNS packets are dropped! -.sp -Only VLAN 802.1Q is supported. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBoff\fP -.SH CONTROL SECTION -.sp -Configuration of the server control interface. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -control: - listen: STR - backlog: INT - timeout: TIME -.ft P -.fi -.UNINDENT -.UNINDENT -.SS listen -.sp -A UNIX socket \fI\%path\fP where the server listens for -control commands. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fI\%rundir\fP\fB/knot.sock\fP -.SS backlog -.sp -The control UNIX socket listen backlog size. -.sp -Change of this parameter requires restart of the Knot server to take effect. -.sp -\fIDefault:\fP \fB5\fP -.SS timeout -.sp -Maximum time (in seconds) the control socket operations can take. -Set to 0 for infinity. -.sp -\fIDefault:\fP \fB5\fP -.SH LOG SECTION -.sp -Server can be configured to log to the standard output, standard error -output, syslog (or systemd journal if systemd is enabled) or into an arbitrary -file. -.sp -There are 6 logging severity levels: -.INDENT 0.0 -.IP \(bu 2 -\fBcritical\fP – Non\-recoverable error resulting in server shutdown. -.IP \(bu 2 -\fBerror\fP – Recoverable error, action should be taken. -.IP \(bu 2 -\fBwarning\fP – Warning that might require user action. -.IP \(bu 2 -\fBnotice\fP – Server notice or hint. -.IP \(bu 2 -\fBinfo\fP – Informational message. -.IP \(bu 2 -\fBdebug\fP – Debug or detailed message. -.UNINDENT -.sp -In the case of a missing log section, \fBwarning\fP or more serious messages -will be logged to both standard error output and syslog. The \fBinfo\fP and -\fBnotice\fP messages will be logged to standard output. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -log: - \- target: stdout | stderr | syslog | STR - server: critical | error | warning | notice | info | debug - control: critical | error | warning | notice | info | debug - zone: critical | error | warning | notice | info | debug - quic: critical | error | warning | notice | info | debug - any: critical | error | warning | notice | info | debug -.ft P -.fi -.UNINDENT -.UNINDENT -.SS target -.sp -A logging output. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBstdout\fP – Standard output. -.IP \(bu 2 -\fBstderr\fP – Standard error output. -.IP \(bu 2 -\fBsyslog\fP – Syslog or systemd journal. -.IP \(bu 2 -\fIfile_name\fP – A specific file. -.UNINDENT -.sp -With \fBsyslog\fP target, syslog service is used. However, if Knot DNS has been compiled -with systemd support and operating system has been booted with systemd, systemd journal -is used for logging instead of syslog. -.sp -A \fIfile_name\fP may be specified as an absolute path or a path relative to the -\fI\%knotd\fP startup directory. -.SS server -.sp -Minimum severity level for messages related to general operation of the server to be -logged. -.sp -\fIDefault:\fP not set -.SS control -.sp -Minimum severity level for messages related to server control to be logged. -.sp -\fIDefault:\fP not set -.SS zone -.sp -Minimum severity level for messages related to zones to be logged. -.sp -\fIDefault:\fP not set -.SS quic -.sp -Minimum severity level for messages related to QUIC to be logged. -.sp -\fIDefault:\fP not set -.SS any -.sp -Minimum severity level for all message types, except \fBquic\fP, to be logged. -.sp -\fIDefault:\fP not set -.SH STATISTICS SECTION -.sp -Periodic server statistics dumping. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -statistics: - timer: TIME - file: STR - append: BOOL -.ft P -.fi -.UNINDENT -.UNINDENT -.SS timer -.sp -A period (in seconds) after which all available statistics metrics will by written to the -\fI\%file\fP\&. -.sp -\fIDefault:\fP not set -.SS file -.sp -A file \fI\%path\fP of statistics output in the YAML format. -.sp -\fIDefault:\fP \fI\%rundir\fP\fB/stats.yaml\fP -.SS append -.sp -If enabled, the output will be appended to the \fI\%file\fP -instead of file replacement. -.sp -\fIDefault:\fP \fBoff\fP -.SH DATABASE SECTION -.sp -Configuration of databases for zone contents, DNSSEC metadata, or event timers. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -database: - storage: STR - journal\-db: STR - journal\-db\-mode: robust | asynchronous - journal\-db\-max\-size: SIZE - kasp\-db: STR - kasp\-db\-max\-size: SIZE - timer\-db: STR - timer\-db\-max\-size: SIZE - catalog\-db: str - catalog\-db\-max\-size: SIZE -.ft P -.fi -.UNINDENT -.UNINDENT -.SS storage -.sp -A data directory for storing journal, KASP, and timer databases. A non\-absolute -path is relative to the \fI\%knotd\fP startup directory. -.sp -\fIDefault:\fP \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP) -.SS journal\-db -.sp -An explicit \fI\%specification\fP of the persistent journal database -directory. -.sp -\fIDefault:\fP \fI\%storage\fP\fB/journal\fP -.SS journal\-db\-mode -.sp -Specifies journal LMDB backend configuration, which influences performance -and durability. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBrobust\fP – The journal database disk synchronization ensures database -durability but is generally slower. -.IP \(bu 2 -\fBasynchronous\fP – The journal database disk synchronization is optimized for -better performance at the expense of lower database durability in the case of -a crash. This mode is recommended on secondary servers with many zones. -.UNINDENT -.sp -\fIDefault:\fP \fBrobust\fP -.SS journal\-db\-max\-size -.sp -The hard limit for the journal database maximum size. There is no cleanup logic -in journal to recover from reaching this limit. Journal simply starts refusing -changes across all zones. Decreasing this value has no effect if it is lower -than the actual database file size. -.sp -It is recommended to limit \fI\%journal\-max\-usage\fP -per\-zone instead of \fI\%journal\-db\-max\-size\fP -in most cases. Please keep this value larger than the sum of all zones\(aq -journal usage limits. See more details regarding -\fI\%journal behaviour\fP\&. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This value also influences server\(aqs usage of virtual memory. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB20G\fP (20 GiB), or \fB512M\fP (512 MiB) for 32\-bit -.SS kasp\-db -.sp -An explicit \fI\%specification\fP of the KASP database directory. -.sp -\fIDefault:\fP \fI\%storage\fP\fB/keys\fP -.SS kasp\-db\-max\-size -.sp -The hard limit for the KASP database maximum size. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This value also influences server\(aqs usage of virtual memory. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB500M\fP (500 MiB) -.SS timer\-db -.sp -An explicit \fI\%specification\fP of the persistent timer -database directory. -.sp -\fIDefault:\fP \fI\%storage\fP\fB/timers\fP -.SS timer\-db\-max\-size -.sp -The hard limit for the timer database maximum size. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This value also influences server\(aqs usage of virtual memory. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB100M\fP (100 MiB) -.SS catalog\-db -.sp -An explicit \fI\%specification\fP of the zone catalog -database directory. Only useful if \fI\%Catalog zones\fP are enabled. -.sp -\fIDefault:\fP \fI\%storage\fP\fB/catalog\fP -.SS catalog\-db\-max\-size -.sp -The hard limit for the catalog database maximum size. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This value also influences server\(aqs usage of virtual memory. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB20G\fP (20 GiB), or \fB512M\fP (512 MiB) for 32\-bit -.SH KEYSTORE SECTION -.sp -DNSSEC keystore configuration. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -keystore: - \- id: STR - backend: pem | pkcs11 - config: STR - key\-label: BOOL -.ft P -.fi -.UNINDENT -.UNINDENT -.SS id -.sp -A keystore identifier. -.SS backend -.sp -A key storage backend type. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBpem\fP – PEM files. -.IP \(bu 2 -\fBpkcs11\fP – PKCS #11 storage. -.UNINDENT -.sp -\fIDefault:\fP \fBpem\fP -.SS config -.sp -A backend specific configuration. A directory with PEM files (the path can -be specified as a relative path to \fI\%kasp\-db\fP) or -a configuration string for PKCS #11 storage (\fI \fP). -The PKCS #11 URI Scheme is defined in \fI\%RFC 7512\fP\&. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Example configuration string for PKCS #11: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -\(dqpkcs11:token=knot;pin\-value=1234 /usr/lib64/pkcs11/libsofthsm2.so\(dq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fI\%kasp\-db\fP\fB/keys\fP -.SS key\-label -.sp -If enabled in combination with the PKCS #11 \fI\%backend\fP, generated keys -are labeled in the form \fB KSK|ZSK\fP\&. -.sp -\fIDefault:\fP \fBoff\fP -.SH KEY SECTION -.sp -Shared TSIG keys used to authenticate communication with the server. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -key: - \- id: DNAME - algorithm: hmac\-md5 | hmac\-sha1 | hmac\-sha224 | hmac\-sha256 | hmac\-sha384 | hmac\-sha512 - secret: BASE64 -.ft P -.fi -.UNINDENT -.UNINDENT -.SS id -.sp -A key name identifier. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This value MUST be exactly the same as the name of the TSIG key on the -opposite primary/secondary server(s). -.UNINDENT -.UNINDENT -.SS algorithm -.sp -A TSIG key algorithm. See -\fI\%TSIG Algorithm Numbers\fP\&. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBhmac\-md5\fP -.IP \(bu 2 -\fBhmac\-sha1\fP -.IP \(bu 2 -\fBhmac\-sha224\fP -.IP \(bu 2 -\fBhmac\-sha256\fP -.IP \(bu 2 -\fBhmac\-sha384\fP -.IP \(bu 2 -\fBhmac\-sha512\fP -.UNINDENT -.sp -\fIDefault:\fP not set -.SS secret -.sp -Shared key secret. -.sp -\fIDefault:\fP not set -.SH REMOTE SECTION -.sp -Definitions of remote servers for outgoing connections (source of a zone -transfer, target for a notification, etc.). -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -remote: - \- id: STR - address: ADDR[@INT] | STR ... - via: ADDR[@INT] ... - quic: BOOL - key: key_id - cert\-key: BASE64 ... - block\-notify\-after\-transfer: BOOL - no\-edns: BOOL - automatic\-acl: BOOL -.ft P -.fi -.UNINDENT -.UNINDENT -.SS id -.sp -A remote identifier. -.SS address -.sp -An ordered list of destination IP addresses or UNIX socket paths which are -used for communication with the remote server. Non\-absolute path -(i.e. not starting with \fB/\fP) is relative to \fI\%rundir\fP\&. -Optional destination port (default is 53 for UDP/TCP and 853 for QUIC) -can be appended to the address using \fB@\fP separator. -The addresses are tried in sequence until the -remote is reached. -.sp -\fIDefault:\fP not set -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -If the remote is contacted and it refuses to perform requested action, -no more addresses will be tried for this remote. -.UNINDENT -.UNINDENT -.SS via -.sp -An ordered list of source IP addresses which are used as source addresses -for communication with the remote. For the N\-th \fI\%remote address\fP, -the last, but at most N\-th, specified \fI\%via address\fP -of the same family is used. -This option can help if the server listens on more addresses. -Optional source port (default is random) can be appended -to the address using \fB@\fP separator. -.sp -\fIDefault:\fP not set -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -For the following configuration: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -remote: - \- id: example - address: [198.51.100.10, 2001:db8::10, 198.51.100.20, 2001:db8::20] - via: [198.51.100.1, 198.51.100.2, 2001:db8::1] -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -the (\fBvia\fP \-> \fBaddress\fP) mapping is: -.INDENT 0.0 -.IP \(bu 2 -\fB198.51.100.1\fP \-> \fB198.51.100.10\fP -.IP \(bu 2 -\fB2001:db8::1\fP \-> \fB2001:db8::10\fP -.IP \(bu 2 -\fB198.51.100.2\fP \-> \fB198.51.100.20\fP -.IP \(bu 2 -\fB2001:db8::1\fP \-> \fB2001:db8::20\fP -.UNINDENT -.UNINDENT -.UNINDENT -.SS quic -.sp -If this option is set, the QUIC protocol will be used for outgoing communication -with this remote. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -One connection per each remote is opened; \fI\%remote\-pool\-limit\fP -does not take effect for QUIC. However, fast QUIC handshakes utilizing obtained -session tickets are used for reopening connections to recently (up to 1 day) -queried remotes. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBoff\fP -.SS key -.sp -A \fI\%reference\fP to the TSIG key which is used to authenticate -the communication with the remote server. -.sp -\fIDefault:\fP not set -.SS cert\-key -.sp -An ordered list of remote certificate public key PINs. If the list is non\-empty, -communication with the remote is possible only via QUIC protocol and -a peer certificate is required. The peer certificate key must match one of the -specified PINs. -.sp -A PIN is a unique identifier that represents the public key of the peer certificate. -It\(aqs a base64\-encoded SHA\-256 hash of the public key. This identifier -remains the same on a certificate renewal. -.sp -\fIDefault:\fP not set -.SS block\-notify\-after\-transfer -.sp -When incoming AXFR/IXFR from this remote (as a primary server), suppress -sending NOTIFY messages to all configured secondary servers. -.sp -\fIDefault:\fP \fBoff\fP -.SS no\-edns -.sp -If enabled, no OPT record (EDNS) is inserted to outgoing requests to this -remote server. This mode is necessary for communication with some broken -implementations (e.g. Windows Server 2016). -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This option effectively disables \fI\%zone expire\fP timer -updates via EDNS EXPIRE option specified in \fI\%RFC 7314\fP\&. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBoff\fP -.SS automatic\-acl -.sp -If enabled, some authorized operations for the remote are automatically allowed -based on the context: -.INDENT 0.0 -.IP \(bu 2 -Incoming NOTIFY is allowed from the remote if it\(aqs configured as a -\fI\%primary server\fP for the zone. -.IP \(bu 2 -Outgoing zone transfer is allowed to the remote if it\(aqs configured as a -\fI\%NOTIFY target\fP for the zone. -.UNINDENT -.sp -Automatic ACL rules are evaluated before explicit \fI\%zone ACL\fP configuration. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This functionality requires global activation via -\fI\%automatic\-acl\fP in the server section. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBon\fP -.SH REMOTES SECTION -.sp -Definitions of groups of remote servers. Remote grouping can simplify the -configuration. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -remotes: - \- id: STR - remote: remote_id ... -.ft P -.fi -.UNINDENT -.UNINDENT -.SS id -.sp -A remote group identifier. -.SS remote -.sp -An ordered list of \fI\%references\fP to remote server definitions. -.sp -\fIDefault:\fP not set -.SH ACL SECTION -.sp -Access control list rule definitions. An ACL rule is a description of one -or more authorized actions (zone transfer request, zone change notification, -and dynamic DNS update) which are allowed to be processed or denied. Normal -DNS queries are always allowed. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -acl: - \- id: STR - address: ADDR[/INT] | ADDR\-ADDR | STR ... - key: key_id ... - cert\-key: BASE64 ... - remote: remote_id | remotes_id ... - action: query | notify | transfer | update ... - deny: BOOL - update\-type: STR ... - update\-owner: key | zone | name - update\-owner\-match: sub\-or\-equal | equal | sub | pattern - update\-owner\-name: STR ... -.ft P -.fi -.UNINDENT -.UNINDENT -.SS id -.sp -An ACL rule identifier. -.SS address -.sp -An ordered list of IP addresses, absolute UNIX socket paths, network subnets, -or network ranges. The query\(aqs -source address must match one of them. If this item is not set, address match is not -required. -.sp -\fIDefault:\fP not set -.SS key -.sp -An ordered list of \fI\%reference\fPs to TSIG keys. The query must -match one of them. If this item is not set, transaction authentication is not used. -.sp -\fIDefault:\fP not set -.SS cert\-key -.sp -An ordered list of remote certificate public key PINs. If the list is non\-empty, -communication with the remote is possible only via QUIC protocol and -a peer certificate is required. The peer certificate key must match one of the -specified PINs. -.sp -A PIN is a unique identifier that represents the public key of the peer certificate. -It\(aqs a base64\-encoded SHA\-256 hash of the public key. This identifier -remains the same on a certificate renewal. -.sp -\fIDefault:\fP not set -.SS remote -.sp -An ordered list of references \fI\%remote\fP and -\fI\%remotes\fP\&. The query must -match one of the remotes. Specifically, one of the remote\(aqs addresses and remote\(aqs -TSIG key if configured must match. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This option cannot be specified along with the \fI\%address\fP or -\fI\%key\fP option at one ACL item. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP not set -.SS action -.sp -An ordered list of allowed, or denied, actions (request types). -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBquery\fP – Allow regular DNS query. As normal queries are always allowed, -this action is only useful in combination with \fI\%TSIG key\fP\&. -.IP \(bu 2 -\fBnotify\fP – Allow incoming notify (NOTIFY). -.IP \(bu 2 -\fBtransfer\fP – Allow zone transfer (AXFR, IXFR). -.IP \(bu 2 -\fBupdate\fP – Allow zone updates (DDNS). -.UNINDENT -.sp -\fIDefault:\fP \fBquery\fP -.SS deny -.sp -If enabled, instead of allowing, deny the specified \fI\%action\fP, -\fI\%address\fP, \fI\%key\fP, or combination if these -items. If no action is specified, deny all actions. -.sp -\fIDefault:\fP \fBoff\fP -.SS update\-type -.sp -A list of allowed types of Resource Records in a zone update. Every record in an update -must match one of the specified types. -.sp -\fIDefault:\fP not set -.SS update\-owner -.sp -This option restricts possible owners of Resource Records in a zone update by comparing -them to either the \fI\%TSIG key\fP identity, the current zone name, or to a list of -domain names given by the \fI\%update\-owner\-name\fP option. -The comparison method is given by the \fI\%update\-owner\-match\fP option. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBkey\fP — The owner of each updated RR must match the identity of the TSIG key if used. -.IP \(bu 2 -\fBname\fP — The owner of each updated RR must match at least one name in the -\fI\%update\-owner\-name\fP list. -.IP \(bu 2 -\fBzone\fP — The owner of each updated RR must match the current zone name. -.UNINDENT -.sp -\fIDefault:\fP not set -.SS update\-owner\-match -.sp -This option defines how the owners of Resource Records in an update are matched to the domain name(s) -set by the \fI\%update\-owner\fP option. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBsub\-or\-equal\fP — The owner of each RR in an update must either be equal to -or be a subdomain of at least one domain name set by \fI\%update\-owner\fP\&. -.IP \(bu 2 -\fBequal\fP — The owner of each updated RR must be equal to at least one domain -name set by \fI\%update\-owner\fP\&. -.IP \(bu 2 -\fBsub\fP — The owner of each updated RR must be a subdomain of, but MUST NOT -be equal to at least one domain name set by \fI\%update\-owner\fP\&. -.IP \(bu 2 -\fBpattern\fP — The owner of each updated RR must match a pattern specified by -\fI\%update\-owner\fP\&. The pattern can be an arbitrary FQDN or non\-FQDN -domain name. If a label consists of one \fB*\fP (asterisk) character, it -matches any label. More asterisk labels can be specified. -.UNINDENT -.sp -\fIDefault:\fP \fBsub\-or\-equal\fP -.SS update\-owner\-name -.sp -A list of allowed owners of RRs in a zone update used with \fI\%update\-owner\fP -set to \fBname\fP\&. Every listed owner name which is not FQDN (i.e. it doesn\(aqt end -in a dot) is considered as if it was appended with the target zone name. -Such a relative owner name specification allows better ACL rule reusability across -multiple zones. -.sp -\fIDefault:\fP not set -.SH SUBMISSION SECTION -.sp -Parameters of KSK submission checks. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -submission: - \- id: STR - parent: remote_id | remotes_id ... - check\-interval: TIME - timeout: TIME - parent\-delay: TIME -.ft P -.fi -.UNINDENT -.UNINDENT -.SS id -.sp -A submission identifier. -.SS parent -.sp -A list of references \fI\%remote\fP and \fI\%remotes\fP -to parent\(aqs DNS servers to be checked for -presence of corresponding DS records in the case of KSK submission. All of them must -have a corresponding DS for the rollover to continue. If none is specified, the -rollover must be pushed forward manually. -.sp -\fIDefault:\fP not set -.sp -\fBTIP:\fP -.INDENT 0.0 -.INDENT 3.5 -A DNSSEC\-validating resolver can be set as a parent. -.UNINDENT -.UNINDENT -.SS check\-interval -.sp -Interval (in seconds) for periodic checks of DS presence on parent\(aqs DNS -servers, in the case of the KSK submission. -.sp -\fIDefault:\fP \fB1h\fP (1 hour) -.SS timeout -.sp -After this time period (in seconds) the KSK submission is automatically considered -successful, even if all the checks were negative or no parents are configured. -Set to 0 for infinity. -.sp -\fIDefault:\fP \fB0\fP -.SS parent\-delay -.sp -After successful parent DS check, wait for this period (in seconds) before -continuing the next key roll\-over step. This delay shall cover the propagation -delay of update in the parent zone. -.sp -\fIDefault:\fP \fB0\fP -.SH DNSKEY-SYNC SECTION -.sp -Parameters of DNSKEY dynamic\-update synchronization. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -dnskey\-sync: - \- id: STR - remote: remote_id | remotes_id ... - check\-interval: TIME -.ft P -.fi -.UNINDENT -.UNINDENT -.SS id -.sp -A dnskey\-sync identifier. -.SS remote -.sp -A list of references \fI\%remote\fP and \fI\%remotes\fP -to other signers or common master, which the DDNS updates with -DNSKEY/CDNSKEY/CDS records shall be sent to. -.sp -\fIDefault:\fP not set -.SS check\-interval -.sp -If the last DNSKEY sync failed or resulted in any change, re\-check -the consistence after this interval (in seconds) and re\-try if needed. -.sp -\fIDefault:\fP \fB60\fP (1 minute) -.SH POLICY SECTION -.sp -DNSSEC policy configuration. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -policy: - \- id: STR - keystore: keystore_id - manual: BOOL - single\-type\-signing: BOOL - algorithm: rsasha1 | rsasha1\-nsec3\-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519 | ed448 - ksk\-size: SIZE - zsk\-size: SIZE - ksk\-shared: BOOL - dnskey\-ttl: TIME - zone\-max\-ttl: TIME - keytag\-modulo: INT/INT - ksk\-lifetime: TIME - zsk\-lifetime: TIME - delete\-delay: TIME - propagation\-delay: TIME - rrsig\-lifetime: TIME - rrsig\-refresh: TIME - rrsig\-pre\-refresh: TIME - reproducible\-signing: BOOL - nsec3: BOOL - nsec3\-iterations: INT - nsec3\-opt\-out: BOOL - nsec3\-salt\-length: INT - nsec3\-salt\-lifetime: TIME - signing\-threads: INT - ksk\-submission: submission_id - ds\-push: remote_id | remotes_id ... - cds\-cdnskey\-publish: none | delete\-dnssec | rollover | always | double\-ds - cds\-digest\-type: sha256 | sha384 - dnskey\-management: full | incremental - offline\-ksk: BOOL - unsafe\-operation: none | no\-check\-keyset | no\-update\-dnskey | no\-update\-nsec | no\-update\-expired ... -.ft P -.fi -.UNINDENT -.UNINDENT -.SS id -.sp -A policy identifier. -.SS keystore -.sp -A \fI\%reference\fP to a keystore holding private key material -for zones. -.sp -\fIDefault:\fP an imaginary keystore with all default values -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -A configured keystore called \(dqdefault\(dq won\(aqt be used unless explicitly referenced. -.UNINDENT -.UNINDENT -.SS manual -.sp -If enabled, automatic key management is not used. -.sp -\fIDefault:\fP \fBoff\fP -.SS single\-type\-signing -.sp -If enabled, Single\-Type Signing Scheme is used in the automatic key management -mode. -.sp -\fIDefault:\fP \fBoff\fP (\fI\%module onlinesign\fP has default \fBon\fP) -.SS algorithm -.sp -An algorithm of signing keys and issued signatures. See -\fI\%DNSSEC Algorithm Numbers\fP\&. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBrsasha1\fP -.IP \(bu 2 -\fBrsasha1\-nsec3\-sha1\fP -.IP \(bu 2 -\fBrsasha256\fP -.IP \(bu 2 -\fBrsasha512\fP -.IP \(bu 2 -\fBecdsap256sha256\fP -.IP \(bu 2 -\fBecdsap384sha384\fP -.IP \(bu 2 -\fBed25519\fP -.IP \(bu 2 -\fBed448\fP -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Ed25519 algorithm is only available if compiled with GnuTLS 3.6.0+. -.sp -Ed448 algorithm is only available if compiled with GnuTLS 3.6.12+ and Nettle 3.6+. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBecdsap256sha256\fP -.SS ksk\-size -.sp -A length of newly generated KSK or -CSK keys. -.sp -\fIDefault:\fP \fB2048\fP (rsa*), \fB256\fP (ecdsap256), \fB384\fP (ecdsap384), \fB256\fP (ed25519), -\fB456\fP (ed448) -.SS zsk\-size -.sp -A length of newly generated ZSK keys. -.sp -\fIDefault:\fP see default for \fI\%ksk\-size\fP -.SS ksk\-shared -.sp -If enabled, all zones with this policy assigned will share one or more KSKs. -More KSKs can be shared during a KSK rollover. -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -As the shared KSK set is bound to the policy \fI\%id\fP, renaming the -policy breaks this connection and new shared KSK set is initiated when -a new KSK is needed. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBoff\fP -.SS dnskey\-ttl -.sp -A TTL value for DNSKEY records added into zone apex. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Has influence over ZSK key lifetime. -.UNINDENT -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -Ensure all DNSKEYs with updated TTL are propagated before any subsequent -DNSKEY rollover starts. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP zone SOA TTL -.SS zone\-max\-ttl -.sp -Declare (override) maximal TTL value among all the records in zone. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -It\(aqs generally recommended to override the maximal TTL computation by setting this -explicitly whenever possible. It\(aqs required for \fI\%DNSSEC Offline KSK\fP and -really reasonable when records are generated dynamically -(e.g. by a \fI\%module\fP). -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP computed after zone is loaded -.SS keytag\-modulo -.sp -Specifies that the keytags of any generated keys shall be congruent by specified modulo. -The option value must be a string in the format \fBR/M\fP, where \fBR < M <= 256\fP are -positive integers. Whenever a DNSSEC key is generated, it is ensured -that \fBkeytag % M == R\fP\&. This prevents keytag conflict in \fI\%DNSSEC Offline KSK\fP -or \fI\%DNSSEC multi\-signer\fP (and possibly other) setups. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This only applies to newly generated keys when they are generated. Keys from -before this option and keys imported from elsewhere might not fulfill the policy. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB0/1\fP -.SS ksk\-lifetime -.sp -A period (in seconds) between KSK generation and the next rollover initiation. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -KSK key lifetime is also influenced by propagation\-delay, dnskey\-ttl, -and KSK submission delay. -.sp -Zero (aka infinity) value causes no KSK rollover as a result. -.sp -This applies for CSK lifetime if single\-type\-signing is enabled. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB0\fP (infinity) -.SS zsk\-lifetime -.sp -A period (in seconds) between ZSK activation and the next rollover initiation. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -More exactly, this period is measured since a ZSK is activated, -and after this, a new ZSK is generated to replace it within -following roll\-over. -.sp -As a consequence, in normal operation, this results in the period -of ZSK generation being \fIzsk\-lifetime + propagation\-delay + dnskey_ttl\fP\&. -.sp -Zero (aka infinity) value causes no ZSK rollover as a result. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB30d\fP (30 days) -.SS delete\-delay -.sp -Once a key (KSK or ZSK) is rolled\-over and removed from the zone, -keep it in the KASP database for at least this period (in seconds) before deleting -it completely. This might be useful in some troubleshooting cases when resurrection -is needed. -.sp -\fIDefault:\fP \fB0\fP -.SS propagation\-delay -.sp -An extra delay added for each key rollover step. This value (in seconds) -should be high enough to cover propagation of data from the primary server -to all secondary servers, as well as the duration of signing routine itself -and possible outages in signing and propagation infrastructure. In other -words, this delay should ensure that within this period of time after -planned change of the key set, all public\-facing secondaries will already -serve new DNSKEY RRSet for sure. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Has influence over ZSK key lifetime. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB1h\fP (1 hour) -.SS rrsig\-lifetime -.sp -A validity period (in seconds) of newly issued signatures. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -The RRSIG\(aqs signature inception time is set to 90 minutes in the past. This -time period is not counted to the signature lifetime. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB14d\fP (14 days) -.SS rrsig\-refresh -.sp -A period (in seconds) how long at least before a signature expiration the signature -will be refreshed, in order to prevent expired RRSIGs on secondary servers or -resolvers\(aq caches. -.sp -\fIDefault:\fP 0.1 * \fI\%rrsig\-lifetime\fP + \fI\%propagation\-delay\fP + \fI\%zone\-max\-ttl\fP -.SS rrsig\-pre\-refresh -.sp -A period (in seconds) how long at most before a signature refresh time the signature -might be refreshed, in order to refresh RRSIGs in bigger batches on a frequently updated -zone (avoid re\-sign event too often). -.sp -\fIDefault:\fP \fB1h\fP (1 hour) -.SS reproducible\-signing -.sp -For ECDSA algorithms, generate RRSIG signatures deterministically (\fI\%RFC 6979\fP). -Besides better theoretical cryptographic security, this mode allows significant -speed\-up of loading signed (by the same method) zones. However, the zone signing -is a bit slower. -.sp -\fIDefault:\fP \fBoff\fP -.SS nsec3 -.sp -Specifies if NSEC3 will be used instead of NSEC. -.sp -\fIDefault:\fP \fBoff\fP -.SS nsec3\-iterations -.sp -A number of additional times the hashing is performed. -.sp -\fIDefault:\fP \fB0\fP -.SS nsec3\-opt\-out -.sp -If set, NSEC3 records won\(aqt be created for insecure delegations. -This speeds up the zone signing and reduces overall zone size. -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -NSEC3 with the Opt\-Out bit set no longer works as a proof of non\-existence -in this zone. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBoff\fP -.SS nsec3\-salt\-length -.sp -A length of a salt field in octets, which is appended to the original owner -name before hashing. -.sp -\fIDefault:\fP \fB8\fP -.SS nsec3\-salt\-lifetime -.sp -A validity period (in seconds) of newly issued salt field. -.sp -Zero value means infinity. -.sp -Special value \fI\-1\fP triggers re\-salt every time when active ZSK changes. -This optimizes the number of big changes to the zone. -.sp -\fIDefault:\fP \fB30d\fP (30 days) -.SS signing\-threads -.sp -When signing zone or update, use this number of threads for parallel signing. -.sp -Those are extra threads independent of \fI\%Background workers\fP\&. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Some steps of the DNSSEC signing operation are not parallelized. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB1\fP (no extra threads) -.SS ksk\-submission -.sp -A reference to \fI\%submission\fP section holding parameters of -KSK submission checks. -.sp -\fIDefault:\fP not set -.SS ds\-push -.sp -Optional references \fI\%remote\fP and \fI\%remotes\fP -to authoritative DNS server of the -parent\(aqs zone. The remote server must be configured to accept DS record -updates via DDNS. Whenever a CDS record in the local zone is changed, the -corresponding DS record is sent as a dynamic update (DDNS) to the parent -DNS server. All previous DS records are deleted within the DDNS message. -It\(aqs possible to manage both child and parent zones by the same Knot DNS server. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This feature requires \fI\%cds\-cdnskey\-publish\fP -not to be set to \fBnone\fP\&. -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -The mentioned change to CDS record usually means that a KSK roll\-over is running -and the new key being rolled\-in is in \(dqready\(dq state already for the period of -\fI\%propagation\-delay\fP\&. -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Module \fI\%Onlinesign\fP doesn\(aqt support DS push. -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -When turning this feature on while a KSK roll\-over is already running, it might -not take effect for the already\-running roll\-over. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP not set -.SS dnskey\-sync -.sp -A reference to \fI\%dnskey\-sync\fP section holding parameters -of DNSKEY synchronization. -.sp -\fIDefault:\fP not set -.SS cds\-cdnskey\-publish -.sp -Controls if and how shall the CDS and CDNSKEY be published in the zone. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBnone\fP – Never publish any CDS or CDNSKEY records in the zone. -.IP \(bu 2 -\fBdelete\-dnssec\fP – Publish special CDS and CDNSKEY records indicating turning off DNSSEC. -.IP \(bu 2 -\fBrollover\fP – Publish CDS and CDNSKEY records for ready and not yet active KSK (submission phase of KSK rollover). -.IP \(bu 2 -\fBalways\fP – Always publish one CDS and one CDNSKEY records for the current KSK. -.IP \(bu 2 -\fBdouble\-ds\fP – Always publish up to two CDS and two CDNSKEY records for ready and/or active KSKs. -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -If the zone keys are managed manually, the CDS and CDNSKEY rrsets may contain -more records depending on the keys available. -.UNINDENT -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -The \fBdouble\-ds\fP value does not trigger double\-DS roll\-over method. That method is -only supported when performed manually, with unset \fI\%ksk\-submission\fP\&. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBrollover\fP -.SS cds\-digest\-type -.sp -Specify digest type for published CDS records. -.sp -\fIDefault:\fP \fBsha256\fP -.SS dnskey\-management -.sp -Specify how the DNSKEY, CDNSKEY, and CDS RRSets at the zone apex are handled -when (re\-)signing the zone. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBfull\fP – Upon every zone (re\-)sign, delete all unknown DNSKEY, CDNSKEY, and CDS -records and keep just those that are related to the zone keys stored in the KASP database. -.IP \(bu 2 -\fBincremental\fP – Keep unknown DNSKEY, CDNSKEY, and CDS records in the zone, and -modify server\-managed records incrementally by employing changes in the KASP database. -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Prerequisites for \fIincremental\fP: -.INDENT 0.0 -.IP \(bu 2 -The \fI\%Offline KSK\fP isn\(aqt supported. -.IP \(bu 2 -The \fI\%delete\-delay\fP is long enough to cover possible daemon -shutdown (e.g. due to server maintenance). -.IP \(bu 2 -Avoided manual deletion of keys with \fI\%keymgr\fP\&. -.UNINDENT -.sp -Otherwise there might remain some DNSKEY records in the zone, belonging to -deleted keys. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBfull\fP -.SS offline\-ksk -.sp -Specifies if \fI\%Offline KSK\fP feature is enabled. -.sp -\fIDefault:\fP \fBoff\fP -.SS unsafe\-operation -.sp -Turn off some DNSSEC safety features. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBnone\fP – Nothing disabled. -.IP \(bu 2 -\fBno\-check\-keyset\fP – Don\(aqt check active keys in present algorithms. This may -lead to violation of \fI\%RFC 4035#section\-2.2\fP\&. -.IP \(bu 2 -\fBno\-update\-dnskey\fP – Don\(aqt maintain/update DNSKEY, CDNSKEY, and CDS records -in the zone apex according to KASP database. Juste leave them as they are in the zone. -.IP \(bu 2 -\fBno\-update\-nsec\fP – Don\(aqt maintain/update NSEC/NSEC3 chain. Leave all the records -as they are in the zone. -.IP \(bu 2 -\fBno\-update\-expired\fP – Don\(aqt update expired RRSIGs. -.UNINDENT -.sp -Multiple values may be specified. -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This mode is intended for DNSSEC experts who understand the corresponding consequences. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBnone\fP -.SH TEMPLATE SECTION -.sp -A template is shareable zone settings, which can simplify configuration by -reducing duplicates. A special default template (with the \fIdefault\fP identifier) -can be used for global zone configuration or as an implicit configuration -if a zone doesn\(aqt have another template specified. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -template: - \- id: STR - global\-module: STR/STR ... - # All zone options (excluding \(aqtemplate\(aq item) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -If an item is explicitly specified both in the referenced template and -the zone, the template item value is overridden by the zone item value. -.UNINDENT -.UNINDENT -.SS id -.sp -A template identifier. -.SS global\-module -.sp -An ordered list of references to query modules in the form of \fImodule_name\fP or -\fImodule_name/module_id\fP\&. These modules apply to all queries. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This option is only available in the \fIdefault\fP template. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP not set -.SH ZONE SECTION -.sp -Definition of zones served by the server. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -zone: - \- domain: DNAME - template: template_id - storage: STR - file: STR - master: remote_id | remotes_id ... - ddns\-master: remote_id - notify: remote_id | remotes_id ... - acl: acl_id ... - master\-pin\-tolerance: TIME - provide\-ixfr: BOOL - semantic\-checks: BOOL | soft - default\-ttl: TIME - zonefile\-sync: TIME - zonefile\-load: none | difference | difference\-no\-serial | whole - journal\-content: none | changes | all - journal\-max\-usage: SIZE - journal\-max\-depth: INT - ixfr\-benevolent: BOOL - ixfr\-by\-one: BOOL - ixfr\-from\-axfr: BOOL - zone\-max\-size : SIZE - adjust\-threads: INT - dnssec\-signing: BOOL - dnssec\-validation: BOOL - dnssec\-policy: policy_id - ds\-push: remote_id | remotes_id ... - zonemd\-verify: BOOL - zonemd\-generate: none | zonemd\-sha384 | zonemd\-sha512 | remove - serial\-policy: increment | unixtime | dateserial - serial\-modulo: INT/INT - reverse\-generate: DNAME - refresh\-min\-interval: TIME - refresh\-max\-interval: TIME - retry\-min\-interval: TIME - retry\-max\-interval: TIME - expire\-min\-interval: TIME - expire\-max\-interval: TIME - catalog\-role: none | interpret | generate | member - catalog\-template: template_id ... - catalog\-zone: DNAME - catalog\-group: STR - module: STR/STR ... -.ft P -.fi -.UNINDENT -.UNINDENT -.SS domain -.sp -A zone name identifier. -.SS template -.sp -A \fI\%reference\fP to a configuration template. -.sp -\fIDefault:\fP not set or \fBdefault\fP (if the template exists) -.SS storage -.sp -A data directory for storing zone files. A non\-absolute path is relative to -the \fI\%knotd\fP startup directory. -.sp -\fIDefault:\fP \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP) -.SS file -.sp -A \fI\%path\fP to the zone file. It is also possible to use -the following formatters: -.INDENT 0.0 -.IP \(bu 2 -\fB%c[\fP\fIN\fP\fB]\fP or \fB%c[\fP\fIN\fP\fB\-\fP\fIM\fP\fB]\fP – Means the \fIN\fPth -character or a sequence of characters beginning from the \fIN\fPth and ending -with the \fIM\fPth character of the textual zone name (see \fB%s\fP). The -indexes are counted from 0 from the left. All dots (including the terminal -one) are considered. If the character is not available, the formatter has no effect. -.IP \(bu 2 -\fB%l[\fP\fIN\fP\fB]\fP – Means the \fIN\fPth label of the textual zone name -(see \fB%s\fP). The index is counted from 0 from the right (0 ~ TLD). -If the label is not available, the formatter has no effect. -.IP \(bu 2 -\fB%s\fP – Means the current zone name in the textual representation. -The zone name doesn\(aqt include the terminating dot (the result for the root -zone is the empty string!). -.IP \(bu 2 -\fB%%\fP – Means the \fB%\fP character. -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -Beware of special characters which are escaped or encoded in the \eDDD form -where DDD is corresponding decimal ASCII code. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fI\%storage\fP\fB/%s.zone\fP -.SS master -.sp -An ordered list of references \fI\%remote\fP and -\fI\%remotes\fP to zone primary servers -(formerly known as master servers). -Empty value is allowed for template value overriding. -.sp -\fIDefault:\fP not set -.SS ddns\-master -.sp -A \fI\%reference\fP to a zone primary master where DDNS messages -should be forwarded to. If not specified, the first \fI\%master\fP -server is used. -.sp -If set to the empty value (\(dq\(dq), incoming DDNS messages aren\(aqt forwarded but are applied -to the local zone instead, no matter if it is a secondary server. This is only allowed in -combination with \fI\%dnssec\-signing\fP enabled. -.sp -\fIDefault:\fP not set -.SS notify -.sp -An ordered list of references \fI\%remote\fP and -\fI\%remotes\fP to secondary servers to which notify -message is sent if the zone changes. -Empty value is allowed for template value overriding. -.sp -\fIDefault:\fP not set -.SS acl -.sp -An ordered list of \fI\%references\fP to ACL rules which can allow -or disallow zone transfers, updates or incoming notifies. -.sp -\fIDefault:\fP not set -.SS master\-pin\-tolerance -.sp -If set to a nonzero value on a secondary, always request AXFR/IXFR from the same -primary as the last time, effectively pinning one primary. Only when another -primary is updated and the current one lags behind for the specified amount of time -(defined by this option in seconds), change to the updated primary and force AXFR. -.sp -This option is useful when multiple primaries may have different zone history -in their journals, making it unsafe to combine interchanged IXFR -from different primaries. -.sp -\fIDefault:\fP \fB0\fP (disabled) -.SS provide\-ixfr -.sp -If disabled, the server is forced to respond with AXFR to IXFR queries. -If enabled, IXFR requests are responded normally. -.sp -\fIDefault:\fP \fBon\fP -.SS semantic\-checks -.sp -Selects if extra zone semantic checks are used or impacts of the mandatory checks. -.sp -There are several mandatory checks which are always enabled and cannot be turned -off. An error in a mandatory check causes the zone not to be loaded. Most of -the mandatory checks can be weakened by setting \fBsoft\fP, which allows the zone to -be loaded even if the check fails. -.sp -If enabled, extra checks are used. These checks don\(aqt prevent the zone from loading. -.sp -The mandatory checks are applied to zone files, zone transfers, and updates via -control interface. The extra checks are applied to zone files only! -.sp -Mandatory checks: -.INDENT 0.0 -.IP \(bu 2 -Missing SOA record at the zone apex (\fI\%RFC 1034\fP) (*) -.IP \(bu 2 -An extra record exists together with a CNAME record except for RRSIG and NSEC (\fI\%RFC 1034\fP) -.IP \(bu 2 -Multiple CNAME records with the same owner exist (\fI\%RFC 1034\fP) -.IP \(bu 2 -DNAME record having a record under it (\fI\%RFC 6672\fP) -.IP \(bu 2 -Multiple DNAME records with the same owner exist (\fI\%RFC 6672\fP) -.IP \(bu 2 -NS record exists together with a DNAME record (\fI\%RFC 6672\fP) -.IP \(bu 2 -DS record exists at the zone apex (\fI\%RFC 3658\fP) -.UNINDENT -.sp -(*) The marked check can\(aqt be weakened by the soft mode. All other mandatory checks -are subject to the optional soft mode. -.sp -Extra checks: -.INDENT 0.0 -.IP \(bu 2 -Missing NS record at the zone apex -.IP \(bu 2 -Missing glue A or AAAA record -.IP \(bu 2 -Invalid DS or NSEC3PARAM record -.IP \(bu 2 -CDS or CDNSKEY inconsistency -.IP \(bu 2 -All other DNSSEC checks executed during \fI\%dnssec\-validation\fP -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -The soft mode allows the refresh event to ignore a CNAME response to a SOA -query (malformed message) and triggers a zone bootstrap instead. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBoff\fP -.SS default\-ttl -.sp -The default TTL value if none is specified in a zone file or zone insertion -using the dynamic configuration. -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -As changing this value can result in differently parsed zone file(s), -the corresponding zone SOA serial(s) should be incremented before -reloading or commiting the configuration. Alternatively, setting -\fI\%zonefile\-load\fP to \fBdifference\-no\-serial\fP ensures -the resulting zone(s) update is correct. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB3600\fP -.SS zonefile\-sync -.sp -The time in seconds after which the current zone in memory will be synced with -a zone file on the disk (see \fI\%file\fP). The server will serve the latest -zone even after a restart using zone journal, but the zone file on the disk will -only be synced after \fBzonefile\-sync\fP time has expired (or after manual zone -flush). This is applicable when the zone is updated via IXFR, DDNS or automatic -DNSSEC signing. In order to completely disable automatic zone file synchronization, -set the value to \-1. In that case, it is still possible to force a manual zone flush -using the \fB\-f\fP option. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -If you are serving large zones with frequent updates where -the immediate sync with a zone file is not desirable, increase the value. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB0\fP (immediate) -.SS zonefile\-load -.sp -Selects how the zone file contents are applied during zone load. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBnone\fP – The zone file is not used at all. -.IP \(bu 2 -\fBdifference\fP – If the zone contents are already available during server start or reload, -the difference is computed between them and the contents of the zone file. This difference -is then checked for semantic errors and applied to the current zone contents. -.IP \(bu 2 -\fBdifference\-no\-serial\fP – Same as \fBdifference\fP, but the SOA serial in the zone file is -ignored, the server takes care of incrementing the serial automatically. -.IP \(bu 2 -\fBwhole\fP – Zone contents are loaded from the zone file. -.UNINDENT -.sp -When \fBdifference\fP is configured and there are no zone contents yet (cold start -and no zone contents in the journal), it behaves the same way as \fBwhole\fP\&. -.sp -\fIDefault:\fP \fBwhole\fP -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -See \fI\%Handling zone file, journal, changes, serials\fP for guidance on -configuring these and related options to ensure reliable operation. -.UNINDENT -.UNINDENT -.SS journal\-content -.sp -Selects how the journal shall be used to store zone and its changes. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBnone\fP – The journal is not used at all. -.IP \(bu 2 -\fBchanges\fP – Zone changes history is stored in journal. -.IP \(bu 2 -\fBall\fP – Zone contents and history is stored in journal. -.UNINDENT -.sp -\fIDefault:\fP \fBchanges\fP -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -When this option is changed, the journal still contains data respective to -the previous setting. For example, changing it to \fBnone\fP does not purge -the journal. Also, changing it from \fBall\fP to \fBchanges\fP -does not cause the deletion of the zone\-in\-journal and the behaviour of the -zone loading procedure might be different than expected. It is recommended -to consider purging the journal when this option is changed. -.UNINDENT -.UNINDENT -.SS journal\-max\-usage -.sp -Policy how much space in journal DB will the zone\(aqs journal occupy. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Journal DB may grow far above the sum of journal\-max\-usage across -all zones, because of DB free space fragmentation. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB100M\fP (100 MiB) -.SS journal\-max\-depth -.sp -Maximum history length of the journal. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Zone\-in\-journal changeset isn\(aqt counted to the limit. -.UNINDENT -.UNINDENT -.sp -\fIMinimum:\fP \fB2\fP -.sp -\fIDefault:\fP \fB20\fP -.SS ixfr\-benevolent -.sp -If enabled, incoming IXFR is applied even when it contains removals of non\-existing -or additions of existing records. -.sp -\fIDefault:\fP \fBoff\fP -.SS ixfr\-by\-one -.sp -Within incoming IXFR, process only one changeset at a time, not multiple together. -This preserves the complete history in the journal and prevents the merging of -changesets when multiple changesets are IXFRed simultaneously. However, this does not -prevent the merging (or deletion) of old changesets in the journal to save space, -as described in \fI\%journal behaviour\fP\&. -.sp -This option leads to increased server load when processing IXFR, including -network traffic. -.sp -\fIDefault:\fP \fBoff\fP -.SS ixfr\-from\-axfr -.sp -If a primary sends AXFR\-style\-IXFR upon an IXFR request, compute the difference -and process it as an incremental zone update (e.g. by storing the changeset in -the journal). -.sp -\fIDefault:\fP \fBoff\fP -.SS zone\-max\-size -.sp -Maximum size of the zone. The size is measured as size of the zone records -in wire format without compression. The limit is enforced for incoming zone -transfers and dynamic updates. -.sp -For incremental transfers (IXFR), the effective limit for the total size of -the records in the transfer is twice the configured value. However the final -size of the zone must satisfy the configured value. -.sp -\fIDefault:\fP unlimited -.SS adjust\-threads -.sp -Parallelize internal zone adjusting procedures by using specified number of -threads. This is useful with huge zones with NSEC3. Speedup observable at -server startup and while processing NSEC3 re\-salt. -.sp -\fIDefault:\fP \fB1\fP (no extra threads) -.SS dnssec\-signing -.sp -If enabled, automatic DNSSEC signing for the zone is turned on. -.sp -\fIDefault:\fP \fBoff\fP -.SS dnssec\-validation -.sp -If enabled, the zone contents are validated for being correctly signed -(including NSEC/NSEC3 chain) with DNSSEC signatures every time the zone -is loaded or changed (including AXFR/IXFR). -.sp -When the validation fails, the zone being loaded or update being applied -is cancelled with an error, and either none or previous zone state is published. -.sp -List of DNSSEC checks: -.INDENT 0.0 -.IP \(bu 2 -Every zone RRSet is correctly signed by at least one present DNSKEY. -.IP \(bu 2 -For every RRSIG there are at most 3 non\-matching DNSKEYs with the same keytag. -.IP \(bu 2 -DNSKEY RRSet is signed by KSK. -.IP \(bu 2 -NSEC(3) RR exists for each name (unless opt\-out) with correct bitmap. -.IP \(bu 2 -Every NSEC(3) RR is linked to the lexicographically next one. -.UNINDENT -.sp -The validation is not affected by \fI\%dnssec\-policy\fP configuration, -except for \fI\%signing\-threads\fP option, which specifies the number -of threads for parallel validation. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Redundant or garbage NSEC3 records are ignored. -.sp -This mode is not compatible with \fI\%dnssec\-signing\fP\&. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP not set -.SS dnssec\-policy -.sp -A \fI\%reference\fP to DNSSEC signing policy. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -A configured policy called \(dqdefault\(dq won\(aqt be used unless explicitly referenced. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP an imaginary policy with all default values -.SS ds\-push -.sp -Per zone configuration of \fI\%ds\-push\fP\&. This option overrides possible -per policy option. Empty value is allowed for template value overriding. -.sp -\fIDefault:\fP not set -.SS zonemd\-verify -.sp -On each zone load/update, verify that ZONEMD is present in the zone and valid. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Zone digest calculation may take much time and CPU on large zones. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBoff\fP -.SS zonemd\-generate -.sp -On each zone update, calculate ZONEMD and put it into the zone. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBnone\fP – No action regarding ZONEMD. -.IP \(bu 2 -\fBzonemd\-sha384\fP – Generate ZONEMD using SHA384 algorithm. -.IP \(bu 2 -\fBzonemd\-sha512\fP – Generate ZONEMD using SHA512 algorithm. -.IP \(bu 2 -\fBremove\fP – Remove any ZONEMD from the zone apex. -.UNINDENT -.sp -\fIDefault:\fP \fBnone\fP -.SS serial\-policy -.sp -Specifies how the zone serial is updated after a dynamic update or -automatic DNSSEC signing. If the serial is changed by the dynamic update, -no change is made. -.sp -Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBincrement\fP – The serial is incremented according to serial number arithmetic. -.IP \(bu 2 -\fBunixtime\fP – The serial is set to the current unix time. -.IP \(bu 2 -\fBdateserial\fP – The 10\-digit serial (YYYYMMDDnn) is incremented, the first -8 digits match the current iso\-date. -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -If the resulting serial for \fBunixtime\fP or \fBdateserial\fP is lower than or -equal to the current serial (this happens e.g. when migrating from other policy or -frequent updates), the serial is incremented instead. -.sp -To avoid user confusion, use \fBdateserial\fP only if you expect at most -100 updates per day per zone and \fBunixtime\fP only if you expect at most -one update per second per zone. -.sp -Generated catalog zones use \fBunixtime\fP only. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBincrement\fP (\fBunixtime\fP for generated catalog zones) -.SS serial\-modulo -.sp -Specifies that the zone serials shall be congruent by specified modulo. -The option value must be a string in the format \fBR/M\fP, where \fBR < M <= 256\fP are -positive integers. Whenever the zone serial is incremented, it is ensured -that \fBserial % M == R\fP\&. This can be useful in the case of multiple inconsistent -primaries, where distinct zone serial sequences prevent cross\-master\-IXFR -by any secondary. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -In order to ensure the congruent policy, this option is only allowed -with \fI\%DNSSEC signing enabled\fP and -\fI\%zonefile\-load\fP to be either \fBdifference\-no\-serial\fP or \fBnone\fP\&. -.sp -Because the zone serial effectively always increments by \fBM\fP instead of -\fB1\fP, it is not recommended to use \fBdateserial\fP \fI\%serial\-policy\fP -or even \fBunixtime\fP in case of rapidly updated zone. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fB0/1\fP -.SS reverse\-generate -.sp -This option triggers the automatic generation of reverse PTR records based on -A/AAAA records in the specified zone. The entire generated zone is automatically -stored in the journal. -.sp -Current limitations: -.INDENT 0.0 -.IP \(bu 2 -Only one zone to be reversed can be specified. -.IP \(bu 2 -Is slow for large zones (even when changing a little). -.UNINDENT -.sp -\fIDefault:\fP none -.SS refresh\-min\-interval -.sp -Forced minimum zone refresh interval (in seconds) to avoid flooding primary server. -.sp -\fIMinimum:\fP \fB2\fP -.sp -\fIDefault:\fP \fB2\fP -.SS refresh\-max\-interval -.sp -Forced maximum zone refresh interval (in seconds). -.sp -\fIDefault:\fP not set -.SS retry\-min\-interval -.sp -Forced minimum zone retry interval (in seconds) to avoid flooding primary server. -.sp -\fIMinimum:\fP \fB1\fP -.sp -\fIDefault:\fP \fB1\fP -.SS retry\-max\-interval -.sp -Forced maximum zone retry interval (in seconds). -.sp -\fIDefault:\fP not set -.SS expire\-min\-interval -.sp -Forced minimum zone expire interval (in seconds) to avoid flooding primary server. -.sp -\fIMinimum:\fP \fB3\fP -.sp -\fIDefault:\fP \fB3\fP -.SS expire\-max\-interval -.sp -Forced maximum zone expire interval (in seconds). -.sp -\fIDefault:\fP not set -.SS catalog\-role -.sp -Trigger zone catalog feature. Possible values: -.INDENT 0.0 -.IP \(bu 2 -\fBnone\fP – Not a catalog zone. -.IP \(bu 2 -\fBinterpret\fP – A catalog zone which is loaded from a zone file or XFR, -and member zones shall be configured based on its contents. -.IP \(bu 2 -\fBgenerate\fP – A catalog zone whose contents are generated according to -assigned member zones. -.IP \(bu 2 -\fBmember\fP – A member zone that is assigned to one generated catalog zone. -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -If set to \fBgenerate\fP, the \fI\%zonefile\-load\fP option has no effect -since a zone file is never loaded. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP \fBnone\fP -.SS catalog\-template -.sp -For the catalog member zones, the specified configuration template will be applied. -.sp -Multiple catalog templates may be defined. The first one is used unless the member zone -has the \fIgroup\fP property defined, matching another catalog template. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This option must be set if and only if \fI\%catalog\-role\fP is \fIinterpret\fP\&. -.sp -Nested catalog zones aren\(aqt supported. Therefore catalog templates can\(aqt -contain \fI\%catalog\-role\fP set to \fBinterpret\fP or \fBgenerate\fP\&. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP not set -.SS catalog\-zone -.sp -Assign this member zone to specified generated catalog zone. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This option must be set if and only if \fI\%catalog\-role\fP is \fImember\fP\&. -.sp -The referenced catalog zone must exist and have \fI\%catalog\-role\fP set to \fIgenerate\fP\&. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP not set -.SS catalog\-group -.sp -Assign this member zone to specified catalog group (configuration template). -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This option has effect if and only if \fI\%catalog\-role\fP is \fImember\fP\&. -.UNINDENT -.UNINDENT -.sp -\fIDefault:\fP not set -.SS module -.sp -An ordered list of references to query modules in the form of \fImodule_name\fP or -\fImodule_name/module_id\fP\&. These modules apply only to the current zone queries. -.sp -\fIDefault:\fP not set -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/knotc.8 b/doc/man/knotc.8 new file mode 100644 index 0000000..5e41e97 --- /dev/null +++ b/doc/man/knotc.8 @@ -0,0 +1,447 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KNOTC" "8" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +knotc \- Knot DNS control utility +.SH SYNOPSIS +.sp +\fBknotc\fP [\fIconfig_option\fP] [\fIoptions\fP] [\fIaction\fP] +.SH DESCRIPTION +.sp +This program controls a running \fIknotd\fP process using a socket. +.sp +If an \fIaction\fP is specified, it is performed and \fIknotc\fP exits, otherwise the program +is executed in the interactive mode. +.SS Config options +.INDENT 0.0 +.TP +\fB\-c\fP, \fB\-\-config\fP \fIfile\fP +Use a textual configuration file (default is \fB/usr/local/etc/knot/knot.conf\fP). +.TP +\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP +Use a binary configuration database directory (default is \fB/usr/local/var/lib/knot/confdb\fP). +The default configuration database, if exists, has a preference to the default +configuration file. +.UNINDENT +.SS Options +.INDENT 0.0 +.TP +\fB\-m\fP, \fB\-\-max\-conf\-size\fP \fIMiB\fP +Set maximum size of the configuration database +(default is 500 MiB, maximum 10000 MiB). +.TP +\fB\-s\fP, \fB\-\-socket\fP \fIpath\fP +Use a control UNIX socket path (default is \fB/usr/local/var/run/knot/knot.sock\fP). +.TP +\fB\-t\fP, \fB\-\-timeout\fP \fIseconds\fP +Use a control timeout in seconds. Set to 0 for infinity (default is 60). +The control socket operations are also subject to the \fI\%timeout\fP +parameter set on the server side in server\(aqs Control configuration section. +.TP +\fB\-b\fP, \fB\-\-blocking\fP +Zone event trigger commands wait until the event is finished. Control timeout +is set to infinity if not forced by explicit timeout specification. +.TP +\fB\-e\fP, \fB\-\-extended\fP +Show extended output (even empty items in zone status). +.TP +\fB\-f\fP, \fB\-\-force\fP +Forced operation. Overrides some checks. +.TP +\fB\-x\fP, \fB\-\-mono\fP +Don\(aqt generate colorized output. +.TP +\fB\-X\fP, \fB\-\-color\fP +Force colorized output in extended output or to a pipe. +.TP +\fB\-v\fP, \fB\-\-verbose\fP +Enable debug output. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.SS Actions +.INDENT 0.0 +.TP +\fBstatus\fP [\fIdetail\fP] +Check if the server is running. Details are \fBversion\fP for the running +server version, \fBworkers\fP for the numbers of worker threads, +\fBconfigure\fP for the configure summary, or \fBcert\-key\fP for the +public key pin of the currently used certificate. +.TP +\fBstop\fP +Stop the server if running. +.TP +\fBreload\fP +Reload the server configuration and modified zone files, and reopen the log files +if they are configured. All open zone transactions will be aborted! +.TP +\fBstats\fP [\fImodule\fP[\fB\&.\fP\fIcounter\fP]] +Show global statistics counter(s). To print also counters with value 0, use +force option. +.TP +\fBzone\-check\fP [\fIzone\fP\&...] +Test if the server can load the zone. Semantic checks are executed if enabled +in the configuration. If invoked with the force option, an error is returned +when semantic check warning appears. (*) +.TP +\fBzone\-status\fP [\fIzone\fP\&...] [\fIfilter\fP] +Show the zone status. Filters are \fB+role\fP, \fB+serial\fP, \fB+transaction\fP, +\fB+events\fP, \fB+freeze\fP, and \fB+catalog\fP\&. Empty zone parameters are omitted, +unless the \fB\-\-extended\fP option is used. A single dash in the output represents +an unset value. Automatic colorization can be overruled using the \fB\-\-mono\fP and +\fB\-\-color\fP options. +.sp +The color code is: +\fIgreen\fP \- zone acts as a master / \fIred\fP \- zone acts as a slave, +\fIbold font (highlited)\fP \- zone is active / \fInormal\fP \- zone is empty, +\fIunderscored\fP \- zone is an interpreted catalog member. +.TP +\fBzone\-reload\fP [\fIzone\fP\&...] +Trigger a zone reload from a disk without checking its modification time. For +secondary zone, the refresh event from primary server(s) is scheduled; +for primary zone, the notify event to secondary server(s) is scheduled. An open +zone transaction will be aborted! If invoked with the force option, also zone +modules will be re\-loaded, but blocking mode might not work reliably. (#) +.TP +\fBzone\-refresh\fP [\fIzone\fP\&...] +Trigger a check for the zone serial on the zone\(aqs primary server. If +the primary server has a newer zone, a transfer is scheduled. This command is +valid for secondary zones. (#) +.TP +\fBzone\-retransfer\fP [\fIzone\fP\&...] +Trigger a zone transfer from the zone\(aqs primary server. The server +doesn\(aqt check the serial of the primary server\(aqs zone. This command is valid +for secondary zones. (#) +.TP +\fBzone\-notify\fP [\fIzone\fP\&...] +Trigger a NOTIFY message to all configured remotes. This can help in cases +when previous NOTIFY had been lost or the secondary servers have been +offline. (#) +.TP +\fBzone\-flush\fP [\fIzone\fP\&...] [\fB+outdir\fP \fIdirectory\fP] +Trigger a zone journal flush to the configured zone file. If an output +directory is specified, the current zone is immediately dumped (in the +blocking mode) to a zone file in the specified directory. See +\fI\%Notes\fP below about the directory permissions. (#) +.TP +\fBzone\-backup\fP [\fIzone\fP\&...] \fB+backupdir\fP \fIdirectory\fP [\fIfilter\fP\&...] +Trigger a zone data and metadata backup to a specified directory. +Available filters are \fB+zonefile\fP, \fB+journal\fP, \fB+timers\fP, \fB+kaspdb\fP, +\fB+keysonly\fP, \fB+catalog\fP, \fB+quic\fP, and their negative counterparts +\fB+nozonefile\fP, \fB+nojournal\fP, \fB+notimers\fP, \fB+nokaspdb\fP, \fB+nokeysonly\fP, +\fB+nocatalog\fP, and \fB+noquic\fP\&. With these filters set, zone contents, +zone\(aqs journal, zone\-related timers, zone\-related data in the KASP database +together with keys (or keys without the KASP database), zone\(aqs catalog, +and the server QUIC key and certificate, respectively, are backed up, +or omitted from the backup. By default, filters \fB+zonefile\fP, \fB+timers\fP, +\fB+kaspdb\fP, \fB+catalog\fP, \fB+quic\fP, \fB+nojournal\fP, and \fB+nokeysonly\fP +are set for backup. The same defaults are set for restore, with the only +difference being \fB+noquic\fP\&. Setting a filter for an item doesn\(aqt change the +default settings for other items. The only exception is \fB+keysonly\fP, which +disables all other filters by default, but they can still be turned on +explicitly. If zone flushing is disabled, the original zone file is backed +up instead of writing out zone contents to a file. When backing\-up a catalog +zone, it is recommended to prevent ongoing changes to it by use of +\fBzone\-freeze\fP\&. The force option allows an already existing backupdir to +be overwritten. See \fI\%Notes\fP below about the directory permissions. +(#) +.TP +\fBzone\-restore\fP [\fIzone\fP\&...] \fB+backupdir\fP \fIdirectory\fP [\fIfilter\fP\&...] +Trigger a zone data and metadata restore from a specified backup directory. +Optional filters are equivalent to the same filters of \fBzone\-backup\fP\&. +Restore from backups created by Knot DNS releases prior to 3.1 is possible +with the force option. See \fI\%Notes\fP below about the directory +permissions. (#) +.TP +\fBzone\-sign\fP [\fIzone\fP\&...] +Trigger a DNSSEC re\-sign of the zone. Existing signatures will be dropped. +This command is valid for zones with DNSSEC signing enabled. (#) +.TP +\fBzone\-validate\fP [\fIzone\fP\&...] +Trigger a DNSSEC validation of the zone. If the validation fails and the +zone is secondary, the zone expires immediately! (#) +.TP +\fBzone\-keys\-load\fP [\fIzone\fP\&...] +Trigger a load of DNSSEC keys and other signing material from KASP database +(which might have been altered manually). If suitable, re\-sign the zone +afterwards (keeping valid signatures intact). (#) +.TP +\fBzone\-key\-rollover\fP \fIzone\fP \fIkey_type\fP +Trigger immediate key rollover. Publish new key and start a key rollover, +even when the key has a lifetime to go. Key type can be \fBksk\fP (also for CSK) +or \fBzsk\fP\&. This command is valid for zones with DNSSEC signing and automatic +key management enabled. Note that complete key rollover consists of several steps +and the blocking mode relates to the initial one only! (#) +.TP +\fBzone\-ksk\-submitted\fP \fIzone\fP\&... +Use when the zone\(aqs KSK rollover is in submission phase. By calling this command +the user confirms manually that the parent zone contains DS record for the new +KSK in submission phase and the old KSK can be retired. (#) +.TP +\fBzone\-freeze\fP [\fIzone\fP\&...] +Trigger a zone freeze. All running events will be finished and all new and pending +(planned) zone\-changing events (load, refresh, update, flush, and DNSSEC signing) +will be held up until the zone is thawed. Up to 8 (this limit is hardcoded) DDNS +updates per zone will be queued, subsequent updates will be refused. (#) +.TP +\fBzone\-thaw\fP [\fIzone\fP\&...] +Trigger dismissal of zone freeze. (#) +.TP +\fBzone\-xfr\-freeze\fP [\fIzone\fP\&...] +Temporarily disable outgoing AXFR/IXFR for the zone(s). (#) +.TP +\fBzone\-xfr\-thaw\fP [\fIzone\fP\&...] +Dismiss outgoing XFR freeze. (#) +.TP +\fBzone\-read\fP \fIzone\fP [\fIowner\fP [\fItype\fP]] +Get zone data that are currently being presented. +.TP +\fBzone\-begin\fP \fIzone\fP\&... +Begin a zone transaction. +.TP +\fBzone\-commit\fP \fIzone\fP\&... +Commit the zone transaction. All changes are applied to the zone. +.TP +\fBzone\-abort\fP \fIzone\fP\&... +Abort the zone transaction. All changes are discarded. +.TP +\fBzone\-diff\fP \fIzone\fP +Get zone changes within the transaction. +.TP +\fBzone\-get\fP \fIzone\fP [\fIowner\fP [\fItype\fP]] +Get zone data within the transaction. +.TP +\fBzone\-set\fP \fIzone\fP \fIowner\fP [\fIttl\fP] \fItype\fP \fIrdata\fP +Add zone record within the transaction. The first record in a rrset +requires a ttl value specified. +.TP +\fBzone\-unset\fP \fIzone\fP \fIowner\fP [\fItype\fP [\fIrdata\fP]] +Remove zone data within the transaction. +.TP +\fBzone\-purge\fP \fIzone\fP\&... [\fB+orphan\fP] [\fIfilter\fP\&...] +Purge zone data, zone file, journal, timers, and/or KASP data of specified zones. +Available filters are \fB+expire\fP, \fB+zonefile\fP, \fB+journal\fP, \fB+timers\fP, +\fB+kaspdb\fP, and \fB+catalog\fP\&. If no filter is specified, all filters are enabled. +If the zone is no longer configured, add \fB+orphan\fP parameter (zone file cannot +be purged in this case). When purging orphans, always check the server log for +possible errors. For proper operation, it\(aqs necessary to prevent ongoing changes +to the zone and triggering of zone related events during purge; use of +\fBzone\-freeze\fP is advisable. This command always requires the force option. (#) +.TP +\fBzone\-stats\fP \fIzone\fP [\fImodule\fP[\fB\&.\fP\fIcounter\fP]] +Show zone statistics counter(s). To print also counters with value 0, use +force option. +.TP +\fBconf\-init\fP +Initialize the configuration database. If the database doesn\(aqt exist yet, +execute this command as an intended user to ensure the server is permitted +to access the database (e.g. \fIsudo \-u knot knotc conf\-init\fP). (*) +.TP +\fBconf\-check\fP +Check the server configuration. (*) +.TP +\fBconf\-import\fP \fIfilename\fP [+nopurge] +Import a configuration file into the configuration database. If the database +doesn\(aqt exist yet, execute this command as an intended user to ensure the server +is permitted to access the database (e.g. \fIsudo \-u knot knotc conf\-import ...\fP). +An optional filter \fB+nopurge\fP prevents possibly existing configuration +database from purging before the import itself. +Also ensure the server is not using the configuration database at the same time! (*) +.TP +\fBconf\-export\fP [\fIfilename\fP] [+schema] +Export the configuration database (or JSON schema) into a file or stdout. (*) +.TP +\fBconf\-list\fP [\fIitem\fP] +List the configuration database sections or section items. +.TP +\fBconf\-read\fP [\fIitem\fP] +Read the item from the active configuration database. +.TP +\fBconf\-begin\fP +Begin a writing configuration database transaction. Only one transaction +can be opened at a time. +.TP +\fBconf\-commit\fP +Commit the configuration database transaction. +.TP +\fBconf\-abort\fP +Rollback the configuration database transaction. +.TP +\fBconf\-diff\fP [\fIitem\fP] +Get the item difference in the transaction. +.TP +\fBconf\-get\fP [\fIitem\fP] +Get the item data from the transaction. +.TP +\fBconf\-set\fP \fIitem\fP [\fIdata\fP\&...] +Set the item data in the transaction. +.TP +\fBconf\-unset\fP [\fIitem\fP] [\fIdata\fP\&...] +Unset the item data in the transaction. +.UNINDENT +.SS Notes +.sp +Empty or \fB\-\-\fP \fIzone\fP parameter means all zones or all zones with a transaction. +.sp +Use \fB@\fP \fIowner\fP to denote the zone name. +.sp +Type \fIitem\fP parameter in the form of \fIsection\fP[\fB[\fP\fIid\fP\fB]\fP][\fB\&.\fP\fIname\fP]. +.sp +(*) indicates a local operation which requires a configuration. +.sp +(#) indicates an optionally blocking operation. +.sp +The \fB\-b\fP and \fB\-f\fP options can be placed right after the command name. +.sp +Responses returned by \fIknotc\fP commands depend on the mode: +.INDENT 0.0 +.IP \(bu 2 +In the blocking mode, \fIknotc\fP reports if an error occurred during processing +of the command by the server. If an error is reported, a more detailed information +about the failure can usually be found in the server log. +.IP \(bu 2 +In the non\-blocking (default) mode, \fIknotc\fP doesn\(aqt report processing errors. +The \fIOK\fP response to triggering commands means that the command has been successfully +sent to the server. To verify if the operation succeeded, it\(aqs necessary to +check the server log. +.UNINDENT +.sp +Actions \fBzone\-flush\fP, \fBzone\-backup\fP, and \fBzone\-restore\fP are carried out by +the \fIknotd\fP process. The directory specified must be accessible to the user account +that \fIknotd\fP runs under and if the directory already exists, its permissions must be +appropriate for that user account. +.SS Interactive mode +.sp +The utility provides interactive mode with basic line editing functionality, +command completion, and command history. +.sp +Interactive mode behavior can be customized in \fI~/.editrc\fP\&. Refer to +\fBeditrc(5)\fP for details. +.sp +Command history is saved in \fI~/.knotc_history\fP\&. +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH EXAMPLES +.SS Reload the whole server configuration +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc reload +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Flush the example.com and example.org zones +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc zone\-flush example.com example.org +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Get the current server configuration +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc conf\-read server +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Get the list of the current zones +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc conf\-read zone.domain +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Get the primary servers for the example.com zone +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc conf\-read \(aqzone[example.com].master\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Add example.org zone with a zonefile location +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc conf\-begin +$ knotc conf\-set \(aqzone[example.org]\(aq +$ knotc conf\-set \(aqzone[example.org].file\(aq \(aq/var/zones/example.org.zone\(aq +$ knotc conf\-commit +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Get the SOA record for each configured zone +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knotc zone\-read \-\- @ SOA +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBknotd(8)\fP, \fBknot.conf(5)\fP, \fBeditrc(5)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/knotc.8in b/doc/man/knotc.8in deleted file mode 100644 index 01bfc95..0000000 --- a/doc/man/knotc.8in +++ /dev/null @@ -1,440 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KNOTC" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -knotc \- Knot DNS control utility -.SH SYNOPSIS -.sp -\fBknotc\fP [\fIconfig_option\fP] [\fIoptions\fP] [\fIaction\fP] -.SH DESCRIPTION -.sp -This program controls a running \fIknotd\fP process using a socket. -.sp -If an \fIaction\fP is specified, it is performed and \fIknotc\fP exits, otherwise the program -is executed in the interactive mode. -.SS Config options -.INDENT 0.0 -.TP -\fB\-c\fP, \fB\-\-config\fP \fIfile\fP -Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). -.TP -\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP -Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). -The default configuration database, if exists, has a preference to the default -configuration file. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-m\fP, \fB\-\-max\-conf\-size\fP \fIMiB\fP -Set maximum size of the configuration database -(default is @conf_mapsize@ MiB, maximum 10000 MiB). -.TP -\fB\-s\fP, \fB\-\-socket\fP \fIpath\fP -Use a control UNIX socket path (default is \fB@run_dir@/knot.sock\fP). -.TP -\fB\-t\fP, \fB\-\-timeout\fP \fIseconds\fP -Use a control timeout in seconds. Set to 0 for infinity (default is 60). -The control socket operations are also subject to the \fI\%timeout\fP -parameter set on the server side in server\(aqs Control configuration section. -.TP -\fB\-b\fP, \fB\-\-blocking\fP -Zone event trigger commands wait until the event is finished. Control timeout -is set to infinity if not forced by explicit timeout specification. -.TP -\fB\-e\fP, \fB\-\-extended\fP -Show extended output (even empty items in zone status). -.TP -\fB\-f\fP, \fB\-\-force\fP -Forced operation. Overrides some checks. -.TP -\fB\-x\fP, \fB\-\-mono\fP -Don\(aqt generate colorized output. -.TP -\fB\-X\fP, \fB\-\-color\fP -Force colorized output in extended output or to a pipe. -.TP -\fB\-v\fP, \fB\-\-verbose\fP -Enable debug output. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.UNINDENT -.SS Actions -.INDENT 0.0 -.TP -\fBstatus\fP [\fIdetail\fP] -Check if the server is running. Details are \fBversion\fP for the running -server version, \fBworkers\fP for the numbers of worker threads, -\fBconfigure\fP for the configure summary, or \fBcert\-key\fP for the -public key pin of the currently used certificate. -.TP -\fBstop\fP -Stop the server if running. -.TP -\fBreload\fP -Reload the server configuration and modified zone files, and reopen the log files -if they are configured. All open zone transactions will be aborted! -.TP -\fBstats\fP [\fImodule\fP[\fB\&.\fP\fIcounter\fP]] -Show global statistics counter(s). To print also counters with value 0, use -force option. -.TP -\fBzone\-check\fP [\fIzone\fP\&...] -Test if the server can load the zone. Semantic checks are executed if enabled -in the configuration. If invoked with the force option, an error is returned -when semantic check warning appears. (*) -.TP -\fBzone\-status\fP [\fIzone\fP\&...] [\fIfilter\fP] -Show the zone status. Filters are \fB+role\fP, \fB+serial\fP, \fB+transaction\fP, -\fB+events\fP, \fB+freeze\fP, and \fB+catalog\fP\&. Empty zone parameters are omitted, -unless the \fB\-\-extended\fP option is used. A single dash in the output represents -an unset value. Automatic colorization can be overruled using the \fB\-\-mono\fP and -\fB\-\-color\fP options. -.sp -The color code is: -\fIgreen\fP \- zone acts as a master / \fIred\fP \- zone acts as a slave, -\fIbold font (highlited)\fP \- zone is active / \fInormal\fP \- zone is empty, -\fIunderscored\fP \- zone is an interpreted catalog member. -.TP -\fBzone\-reload\fP [\fIzone\fP\&...] -Trigger a zone reload from a disk without checking its modification time. For -secondary zone, the refresh event from primary server(s) is scheduled; -for primary zone, the notify event to secondary server(s) is scheduled. An open -zone transaction will be aborted! If invoked with the force option, also zone -modules will be re\-loaded, but blocking mode might not work reliably. (#) -.TP -\fBzone\-refresh\fP [\fIzone\fP\&...] -Trigger a check for the zone serial on the zone\(aqs primary server. If -the primary server has a newer zone, a transfer is scheduled. This command is -valid for secondary zones. (#) -.TP -\fBzone\-retransfer\fP [\fIzone\fP\&...] -Trigger a zone transfer from the zone\(aqs primary server. The server -doesn\(aqt check the serial of the primary server\(aqs zone. This command is valid -for secondary zones. (#) -.TP -\fBzone\-notify\fP [\fIzone\fP\&...] -Trigger a NOTIFY message to all configured remotes. This can help in cases -when previous NOTIFY had been lost or the secondary servers have been -offline. (#) -.TP -\fBzone\-flush\fP [\fIzone\fP\&...] [\fB+outdir\fP \fIdirectory\fP] -Trigger a zone journal flush to the configured zone file. If an output -directory is specified, the current zone is immediately dumped (in the -blocking mode) to a zone file in the specified directory. See -\fI\%Notes\fP below about the directory permissions. (#) -.TP -\fBzone\-backup\fP [\fIzone\fP\&...] \fB+backupdir\fP \fIdirectory\fP [\fIfilter\fP\&...] -Trigger a zone data and metadata backup to a specified directory. -Available filters are \fB+zonefile\fP, \fB+journal\fP, \fB+timers\fP, \fB+kaspdb\fP, -\fB+keysonly\fP, \fB+catalog\fP, \fB+quic\fP, and their negative counterparts -\fB+nozonefile\fP, \fB+nojournal\fP, \fB+notimers\fP, \fB+nokaspdb\fP, \fB+nokeysonly\fP, -\fB+nocatalog\fP, and \fB+noquic\fP\&. With these filters set, zone contents, -zone\(aqs journal, zone\-related timers, zone\-related data in the KASP database -together with keys (or keys without the KASP database), zone\(aqs catalog, -and the server QUIC key and certificate, respectively, are backed up, -or omitted from the backup. By default, filters \fB+zonefile\fP, \fB+timers\fP, -\fB+kaspdb\fP, \fB+catalog\fP, \fB+quic\fP, \fB+nojournal\fP, and \fB+nokeysonly\fP -are set for backup. The same defaults are set for restore, with the only -difference being \fB+noquic\fP\&. Setting a filter for an item doesn\(aqt change the -default settings for other items. The only exception is \fB+keysonly\fP, which -disables all other filters by default, but they can still be turned on -explicitly. If zone flushing is disabled, the original zone file is backed -up instead of writing out zone contents to a file. When backing\-up a catalog -zone, it is recommended to prevent ongoing changes to it by use of -\fBzone\-freeze\fP\&. -See \fI\%Notes\fP below about the directory permissions. (#) -.TP -\fBzone\-restore\fP [\fIzone\fP\&...] \fB+backupdir\fP \fIdirectory\fP [\fIfilter\fP\&...] -Trigger a zone data and metadata restore from a specified backup directory. -Optional filters are equivalent to the same filters of \fBzone\-backup\fP\&. -Restore from backups created by Knot DNS releases prior to 3.1 is possible -with the force option. See \fI\%Notes\fP below about the directory -permissions. (#) -.TP -\fBzone\-sign\fP [\fIzone\fP\&...] -Trigger a DNSSEC re\-sign of the zone. Existing signatures will be dropped. -This command is valid for zones with DNSSEC signing enabled. (#) -.TP -\fBzone\-keys\-load\fP [\fIzone\fP\&...] -Trigger a load of DNSSEC keys and other signing material from KASP database -(which might have been altered manually). If suitable, re\-sign the zone -afterwards (keeping valid signatures intact). (#) -.TP -\fBzone\-key\-rollover\fP \fIzone\fP \fIkey_type\fP -Trigger immediate key rollover. Publish new key and start a key rollover, -even when the key has a lifetime to go. Key type can be \fBksk\fP (also for CSK) -or \fBzsk\fP\&. This command is valid for zones with DNSSEC signing and automatic -key management enabled. Note that complete key rollover consists of several steps -and the blocking mode relates to the initial one only! (#) -.TP -\fBzone\-ksk\-submitted\fP \fIzone\fP\&... -Use when the zone\(aqs KSK rollover is in submission phase. By calling this command -the user confirms manually that the parent zone contains DS record for the new -KSK in submission phase and the old KSK can be retired. (#) -.TP -\fBzone\-freeze\fP [\fIzone\fP\&...] -Trigger a zone freeze. All running events will be finished and all new and pending -(planned) zone\-changing events (load, refresh, update, flush, and DNSSEC signing) -will be held up until the zone is thawed. (#) -.TP -\fBzone\-thaw\fP [\fIzone\fP\&...] -Trigger dismissal of zone freeze. (#) -.TP -\fBzone\-xfr\-freeze\fP [\fIzone\fP\&...] -Temporarily disable outgoing AXFR/IXFR for the zone(s). (#) -.TP -\fBzone\-xfr\-thaw\fP [\fIzone\fP\&...] -Dismiss outgoing XFR freeze. (#) -.TP -\fBzone\-read\fP \fIzone\fP [\fIowner\fP [\fItype\fP]] -Get zone data that are currently being presented. -.TP -\fBzone\-begin\fP \fIzone\fP\&... -Begin a zone transaction. -.TP -\fBzone\-commit\fP \fIzone\fP\&... -Commit the zone transaction. All changes are applied to the zone. -.TP -\fBzone\-abort\fP \fIzone\fP\&... -Abort the zone transaction. All changes are discarded. -.TP -\fBzone\-diff\fP \fIzone\fP -Get zone changes within the transaction. -.TP -\fBzone\-get\fP \fIzone\fP [\fIowner\fP [\fItype\fP]] -Get zone data within the transaction. -.TP -\fBzone\-set\fP \fIzone\fP \fIowner\fP [\fIttl\fP] \fItype\fP \fIrdata\fP -Add zone record within the transaction. The first record in a rrset -requires a ttl value specified. -.TP -\fBzone\-unset\fP \fIzone\fP \fIowner\fP [\fItype\fP [\fIrdata\fP]] -Remove zone data within the transaction. -.TP -\fBzone\-purge\fP \fIzone\fP\&... [\fB+orphan\fP] [\fIfilter\fP\&...] -Purge zone data, zone file, journal, timers, and/or KASP data of specified zones. -Available filters are \fB+expire\fP, \fB+zonefile\fP, \fB+journal\fP, \fB+timers\fP, -\fB+kaspdb\fP, and \fB+catalog\fP\&. If no filter is specified, all filters are enabled. -If the zone is no longer configured, add \fB+orphan\fP parameter (zone file cannot -be purged in this case). When purging orphans, always check the server log for -possible errors. For proper operation, it\(aqs necessary to prevent ongoing changes -to the zone and triggering of zone related events during purge; use of -\fBzone\-freeze\fP is advisable. This command always requires the force option. (#) -.TP -\fBzone\-stats\fP \fIzone\fP [\fImodule\fP[\fB\&.\fP\fIcounter\fP]] -Show zone statistics counter(s). To print also counters with value 0, use -force option. -.TP -\fBconf\-init\fP -Initialize the configuration database. If the database doesn\(aqt exist yet, -execute this command as an intended user to ensure the server is permitted -to access the database (e.g. \fIsudo \-u knot knotc conf\-init\fP). (*) -.TP -\fBconf\-check\fP -Check the server configuration. (*) -.TP -\fBconf\-import\fP \fIfilename\fP [+nopurge] -Import a configuration file into the configuration database. If the database -doesn\(aqt exist yet, execute this command as an intended user to ensure the server -is permitted to access the database (e.g. \fIsudo \-u knot knotc conf\-import ...\fP). -An optional filter \fB+nopurge\fP prevents possibly existing configuration -database from purging before the import itself. -Also ensure the server is not using the configuration database at the same time! (*) -.TP -\fBconf\-export\fP [\fIfilename\fP] [+schema] -Export the configuration database (or JSON schema) into a file or stdout. (*) -.TP -\fBconf\-list\fP [\fIitem\fP] -List the configuration database sections or section items. -.TP -\fBconf\-read\fP [\fIitem\fP] -Read the item from the active configuration database. -.TP -\fBconf\-begin\fP -Begin a writing configuration database transaction. Only one transaction -can be opened at a time. -.TP -\fBconf\-commit\fP -Commit the configuration database transaction. -.TP -\fBconf\-abort\fP -Rollback the configuration database transaction. -.TP -\fBconf\-diff\fP [\fIitem\fP] -Get the item difference in the transaction. -.TP -\fBconf\-get\fP [\fIitem\fP] -Get the item data from the transaction. -.TP -\fBconf\-set\fP \fIitem\fP [\fIdata\fP\&...] -Set the item data in the transaction. -.TP -\fBconf\-unset\fP [\fIitem\fP] [\fIdata\fP\&...] -Unset the item data in the transaction. -.UNINDENT -.SS Notes -.sp -Empty or \fB\-\-\fP \fIzone\fP parameter means all zones or all zones with a transaction. -.sp -Use \fB@\fP \fIowner\fP to denote the zone name. -.sp -Type \fIitem\fP parameter in the form of \fIsection\fP[\fB[\fP\fIid\fP\fB]\fP][\fB\&.\fP\fIname\fP]. -.sp -(*) indicates a local operation which requires a configuration. -.sp -(#) indicates an optionally blocking operation. -.sp -The \fB\-b\fP and \fB\-f\fP options can be placed right after the command name. -.sp -Responses returned by \fIknotc\fP commands depend on the mode: -.INDENT 0.0 -.IP \(bu 2 -In the blocking mode, \fIknotc\fP reports if an error occurred during processing -of the command by the server. If an error is reported, a more detailed information -about the failure can usually be found in the server log. -.IP \(bu 2 -In the non\-blocking (default) mode, \fIknotc\fP doesn\(aqt report processing errors. -The \fIOK\fP response to triggering commands means that the command has been successfully -sent to the server. To verify if the operation succeeded, it\(aqs necessary to -check the server log. -.UNINDENT -.sp -Actions \fBzone\-flush\fP, \fBzone\-backup\fP, and \fBzone\-restore\fP are carried out by -the \fIknotd\fP process. The directory specified must be accessible to the user account -that \fIknotd\fP runs under and if the directory already exists, its permissions must be -appropriate for that user account. -.SS Interactive mode -.sp -The utility provides interactive mode with basic line editing functionality, -command completion, and command history. -.sp -Interactive mode behavior can be customized in \fI~/.editrc\fP\&. Refer to -\fBeditrc(5)\fP for details. -.sp -Command history is saved in \fI~/.knotc_history\fP\&. -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH EXAMPLES -.SS Reload the whole server configuration -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc reload -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Flush the example.com and example.org zones -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc zone\-flush example.com example.org -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Get the current server configuration -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc conf\-read server -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Get the list of the current zones -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc conf\-read zone.domain -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Get the primary servers for the example.com zone -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc conf\-read \(aqzone[example.com].master\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Add example.org zone with a zonefile location -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc conf\-begin -$ knotc conf\-set \(aqzone[example.org]\(aq -$ knotc conf\-set \(aqzone[example.org].file\(aq \(aq/var/zones/example.org.zone\(aq -$ knotc conf\-commit -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Get the SOA record for each configured zone -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc zone\-read \-\- @ SOA -.ft P -.fi -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fBknotd(8)\fP, \fBknot.conf(5)\fP, \fBeditrc(5)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/knotd.8 b/doc/man/knotd.8 new file mode 100644 index 0000000..bbeb6a4 --- /dev/null +++ b/doc/man/knotd.8 @@ -0,0 +1,94 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KNOTD" "8" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +knotd \- Knot DNS server daemon +.SH SYNOPSIS +.sp +\fBknotd\fP [\fIconfig_option\fP] [\fIoptions\fP] +.SH DESCRIPTION +.sp +Knot DNS is a high\-performance authoritative DNS server. The \fIknotd\fP program is +the DNS server daemon. +.SS Config options +.INDENT 0.0 +.TP +\fB\-c\fP, \fB\-\-config\fP \fIfile\fP +Use a textual configuration file (default is \fB/usr/local/etc/knot/knot.conf\fP). +.TP +\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP +Use a binary configuration database directory (default is \fB/usr/local/var/lib/knot/confdb\fP). +The default configuration database, if exists, has a preference to the default +configuration file. +.UNINDENT +.SS Options +.INDENT 0.0 +.TP +\fB\-m\fP, \fB\-\-max\-conf\-size\fP \fIMiB\fP +Set maximum size of the configuration database +(default is 500 MiB, maximum 10000 MiB). +.TP +\fB\-s\fP, \fB\-\-socket\fP \fIpath\fP +Use a remote control UNIX socket path (default is \fB/usr/local/var/run/knot/knot.sock\fP). +.TP +\fB\-d\fP, \fB\-\-daemonize\fP [\fIdirectory\fP] +Run the server as a daemon. New root directory may be specified +(default is \fB/\fP). +.TP +\fB\-v\fP, \fB\-\-verbose\fP +Enable debug output. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.SS Signals +.sp +If the \fIknotd\fP process receives a SIGHUP signal, it reloads its configuration and +reopens the log files, if they are configured. When \fIknotd\fP receives a SIGUSR1 +signal, it reloads all configured zones. Upon receiving a SIGINT signal, \fIknotd\fP +exits. +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH SEE ALSO +.sp +\fBknot.conf(5)\fP, \fBknotc(8)\fP, \fBkeymgr(8)\fP, +\fBkjournalprint(8)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/knotd.8in b/doc/man/knotd.8in deleted file mode 100644 index 1d02cc8..0000000 --- a/doc/man/knotd.8in +++ /dev/null @@ -1,93 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KNOTD" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -knotd \- Knot DNS server daemon -.SH SYNOPSIS -.sp -\fBknotd\fP [\fIconfig_option\fP] [\fIoptions\fP] -.SH DESCRIPTION -.sp -Knot DNS is a high\-performance authoritative DNS server. The \fIknotd\fP program is -the DNS server daemon. -.SS Config options -.INDENT 0.0 -.TP -\fB\-c\fP, \fB\-\-config\fP \fIfile\fP -Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). -.TP -\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP -Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). -The default configuration database, if exists, has a preference to the default -configuration file. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-m\fP, \fB\-\-max\-conf\-size\fP \fIMiB\fP -Set maximum size of the configuration database -(default is @conf_mapsize@ MiB, maximum 10000 MiB). -.TP -\fB\-s\fP, \fB\-\-socket\fP \fIpath\fP -Use a remote control UNIX socket path (default is \fB@run_dir@/knot.sock\fP). -.TP -\fB\-d\fP, \fB\-\-daemonize\fP [\fIdirectory\fP] -Run the server as a daemon. New root directory may be specified -(default is \fB/\fP). -.TP -\fB\-v\fP, \fB\-\-verbose\fP -Enable debug output. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.UNINDENT -.SS Signals -.sp -If the \fIknotd\fP process receives a SIGHUP signal, it reloads its configuration and -reopens the log files, if they are configured. When \fIknotd\fP receives a SIGUSR1 -signal, it reloads all configured zones. Upon receiving a SIGINT signal, \fIknotd\fP -exits. -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH SEE ALSO -.sp -\fBknot.conf(5)\fP, \fBknotc(8)\fP, \fBkeymgr(8)\fP, -\fBkjournalprint(8)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/knsec3hash.1 b/doc/man/knsec3hash.1 new file mode 100644 index 0000000..3bb9766 --- /dev/null +++ b/doc/man/knsec3hash.1 @@ -0,0 +1,108 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KNSEC3HASH" "1" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +knsec3hash \- Simple utility to compute NSEC3 hash +.SH SYNOPSIS +.sp +\fBknsec3hash\fP \fIsalt\fP \fIalgorithm\fP \fIiterations\fP \fIname\fP +.sp +\fBknsec3hash\fP \fIalgorithm\fP \fIflags\fP \fIiterations\fP \fIsalt\fP \fIname\fP +.sp +\fBknsec3hash\fP [\fI\-h\fP] [\fI\-V\fP] +.SH DESCRIPTION +.sp +This utility generates a NSEC3 hash for a given domain name and parameters of NSEC3 hash. +.SS Parameters +.INDENT 0.0 +.TP +.B \fIsalt\fP +Specifies a binary salt encoded as a hexadecimal string. +.TP +.B \fIalgorithm\fP +Specifies a hashing algorithm by number. Currently, the only supported algorithm is SHA\-1 (number 1). +.TP +.B \fIiterations\fP +Specifies the number of additional iterations of the hashing algorithm. +.TP +.B \fIname\fP +Specifies the domain name to be hashed. +.TP +.B \fIflags\fP +Specifies NSEC3 flags as an unsigned integer. +.UNINDENT +.SS Options +.INDENT 0.0 +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knsec3hash 1 0 10 c01dcafe knot\-dns.cz +7PTVGE7QV67EM61ROS9238P5RAKR2DM7 (salt=c01dcafe, hash=1, iterations=10) +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knsec3hash \- 1 0 net +A1RT98BS5QGC9NFI51S9HCI47ULJG6JH (salt=\-, hash=1, iterations=0) +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fI\%RFC 5155\fP – DNS Security (DNSSEC) Hashed Authenticated Denial of Existence. +.sp +\fBknotc(8)\fP, \fBknotd(8)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/knsec3hash.1in b/doc/man/knsec3hash.1in deleted file mode 100644 index d9fa4a3..0000000 --- a/doc/man/knsec3hash.1in +++ /dev/null @@ -1,96 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KNSEC3HASH" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -knsec3hash \- Simple utility to compute NSEC3 hash -.SH SYNOPSIS -.sp -\fBknsec3hash\fP \fIsalt\fP \fIalgorithm\fP \fIiterations\fP \fIname\fP -.sp -\fBknsec3hash\fP \fIalgorithm\fP \fIflags\fP \fIiterations\fP \fIsalt\fP \fIname\fP -.SH DESCRIPTION -.sp -This utility generates a NSEC3 hash for a given domain name and parameters of NSEC3 hash. -.SS Parameters -.INDENT 0.0 -.TP -\fIsalt\fP -Specifies a binary salt encoded as a hexadecimal string. -.TP -\fIalgorithm\fP -Specifies a hashing algorithm by number. Currently, the only supported algorithm is SHA\-1 (number 1). -.TP -\fIiterations\fP -Specifies the number of additional iterations of the hashing algorithm. -.TP -\fIname\fP -Specifies the domain name to be hashed. -.TP -\fIflags\fP -Specifies NSEC3 flags as an unsigned integer. -.UNINDENT -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH EXAMPLES -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knsec3hash 1 0 10 c01dcafe knot\-dns.cz -7PTVGE7QV67EM61ROS9238P5RAKR2DM7 (salt=c01dcafe, hash=1, iterations=10) -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knsec3hash \- 1 0 net -A1RT98BS5QGC9NFI51S9HCI47ULJG6JH (salt=\-, hash=1, iterations=0) -.ft P -.fi -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fI\%RFC 5155\fP – DNS Security (DNSSEC) Hashed Authenticated Denial of Existence. -.sp -\fBknotc(8)\fP, \fBknotd(8)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/knsupdate.1 b/doc/man/knsupdate.1 new file mode 100644 index 0000000..58220a0 --- /dev/null +++ b/doc/man/knsupdate.1 @@ -0,0 +1,252 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KNSUPDATE" "1" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +knsupdate \- Dynamic DNS update utility +.SH SYNOPSIS +.sp +\fBknsupdate\fP [\fB\-v\fP] [\fIoptions\fP] [\fIfilename\fP] +.sp +\fBknsupdate\fP [\fB\-q\fP] [\fIquic_options\fP] [\fIoptions\fP] [\fIfilename\fP] +.SH DESCRIPTION +.sp +This utility sends Dynamic DNS update messages to a DNS server. Update content +is read from a file (if the parameter \fIfilename\fP is given) or from the standard +input. +.sp +The format of updates is textual and is made up of commands. Every command is +placed on the separate line of the input. Lines starting with a semicolon are +comments and are not processed. +.SS Parameters +.INDENT 0.0 +.TP +.B \fIfilename\fP +Path to the file with knsupdate commands. +.UNINDENT +.SS Options +.INDENT 0.0 +.TP +\fB\-T\fP, \fB\-\-tcp\fP +Use a TCP connection. (\fB\-v\fP can be used for compatibility with nsupdate). +.TP +\fB\-S\fP, \fB\-\-tls\fP +Use a TLS connection. +.TP +\fB\-Q\fP, \fB\-\-quic\fP +Use a QUIC connection. +.TP +\fB\-p\fP, \fB\-\-port\fP \fInumber\fP +Set the port to use for connections to the server (if not explicitly specified +in the update). The default is 53 for UDP/TCP or 853 for QUIC. +.TP +\fB\-r\fP, \fB\-\-retry\fP \fIcount\fP +The number of retries for UDP requests. The default is 3. +.TP +\fB\-t\fP, \fB\-\-timeout\fP \fIseconds\fP +The total timeout (for all UDP update tries) of the update request in seconds. +The default is 12. If set to zero, the timeout is infinite. +.TP +\fB\-y\fP, \fB\-\-tsig\fP [\fIalg\fP:]\fIname\fP:\fIkey\fP +Use the TSIG key with a name \fIname\fP to authenticate the request. The \fIalg\fP +part specifies the algorithm (the default is hmac\-sha256) and \fIkey\fP specifies +the shared secret encoded in Base64. +.TP +\fB\-k\fP, \fB\-\-tsigfile\fP \fIpath\fP +Use the TSIG key stored in a file \fIkeyfile\fP to authenticate the request. The +file should contain the key in the same format, which is accepted by the +\fB\-y\fP option. +.TP +\fB\-d\fP, \fB\-\-debug\fP +Enable debug messages. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.SS QUIC/TLS options +.INDENT 0.0 +.TP +\fB\-H\fP, \fB\-\-hostname\fP \fIstring\fP +Enable remote server hostname validation. +.TP +\fB\-P\fP, \fB\-\-pin\fP \fIbase64\fP +Use Out\-of\-Band key\-pinned privacy profile +(RFC 7858#section\-4.2). The PIN must be a Base64 encoded SHA\-256 hash of the +X.509 SubjectPublicKeyInfo. Can be specified multiple times. +.TP +\fB\-A\fP, \fB\-\-ca\fP [\fIpath\fP] +Enable certificate validation. Certification authority certificates +are loaded from the specified PEM file (default is system certificate storage +if no argument is provided). Can be specified multiple times. +.TP +\fB\-E\fP, \fB\-\-certfile\fP \fIpath\fP +Path to a client certificate file. +.TP +\fB\-K\fP, \fB\-\-keyfile\fP \fIpath\fP +Path to a client key file. +.TP +\fB\-s\fP, \fB\-\-sni\fP \fIstring\fP +Use specified Server Name Indication. +.UNINDENT +.SS Commands +.INDENT 0.0 +.TP +\fBserver\fP \fIname\fP [\fIport\fP] +Specifies a receiving server of the dynamic update message. The \fIname\fP parameter +can be either a host name or an IP address. If the \fIport\fP is not specified, +the default port is used. The default port value can be controlled using +the \fB\-p\fP program option. +.TP +\fBlocal\fP \fIaddress\fP [\fIport\fP] +Specifies outgoing \fIaddress\fP and \fIport\fP\&. If no local is specified, the +address and port are set by the system automatically. The default port number +is 0. +.TP +\fBzone\fP \fIname\fP +Specifies that all updates are done within a zone \fIname\fP\&. The zone name doesn\(aqt +have a default and must be set explicitly. +.TP +\fBorigin\fP \fIname\fP +Specifies fully qualified domain name suffix which is appended to non\-fqd +owners in update commands. The default is the terminal label (\fB\&.\fP). +.TP +\fBclass\fP \fIname\fP +Sets \fIname\fP as the default class for all updates. If not used, the default +class is IN. +.TP +\fBttl\fP \fIvalue\fP +Sets \fIvalue\fP as the default TTL (in seconds). If not used, the default value +is 3600. +.TP +\fBkey\fP [\fIalg\fP:]\fIname\fP \fIkey\fP +Specifies the TSIG \fIkey\fP named \fIname\fP to authenticate the request. An optional +\fIalg\fP algorithm can be specified. This command has the same effect as +the program option \fB\-y\fP\&. +.TP +[\fBprereq\fP] \fBnxdomain\fP \fIname\fP +Adds a prerequisite for a non\-existing record owned by \fIname\fP\&. +.TP +[\fBprereq\fP] \fByxdomain\fP \fIname\fP +Adds a prerequisite for an existing record owned by \fIname\fP\&. +.TP +[\fBprereq\fP] \fBnxrrset\fP \fIname\fP [\fIclass\fP] \fItype\fP +Adds a prerequisite for a non\-existing record of the \fItype\fP owned by \fIname\fP\&. +Internet \fIclass\fP is expected. +.TP +[\fBprereq\fP] \fByxrrset\fP \fIname\fP [\fIclass\fP] \fItype\fP [\fIdata\fP] +Adds a prerequisite for an existing record of the \fItype\fP owned by \fIname\fP +with optional \fIdata\fP\&. Internet \fIclass\fP is expected. +.TP +[\fBupdate\fP] \fBadd\fP \fIname\fP [\fIttl\fP] [\fIclass\fP] \fItype\fP \fIdata\fP +Adds a request to add a new resource record into the zone. +Please note that if the \fIname\fP is not fully qualified domain name, the +current origin name is appended to it. +.TP +[\fBupdate\fP] \fBdel\fP[\fBete\fP] \fIname\fP [\fIttl\fP] [\fIclass\fP] [\fItype\fP] [\fIdata\fP] +Adds a request to remove all (or matching \fIclass\fP, \fItype\fP or \fIdata\fP) +resource records from the zone. There is the same requirement for the \fIname\fP +parameter as in \fBupdate add\fP command. The \fIttl\fP item is ignored. +.TP +\fBshow\fP +Displays current content of the update message. +.TP +\fBsend\fP +Sends the current update message and cleans the list of updates. +.TP +\fBanswer\fP +Displays the last answer from the server. +.TP +\fBdebug\fP +Enable debugging. This command has the same meaning as the \fB\-d\fP program option. +.TP +\fBexit\fP +End the program. +.UNINDENT +.SH NOTES +.sp +Options \fB\-k\fP and \fB\-y\fP can not be used simultaneously. +.sp +Neither \fItsig\-keygen(8)\fP nor \fIdnssec\-keygen(1)\fP keyfile formats are supported. +Use \fBkeymgr(8)\fP to construct a string for \fB\-y\fP or the file passed to \fB\-k\fP\&. +.sp +Zone name/server guessing is not supported if the zone name/server is not specified. +.sp +An empty line doesn\(aqt send the update. +.SS Interactive mode +.sp +The utility provides interactive mode with basic line editing functionality, +command completion, and command history. +.sp +Interactive mode behavior can be customized in \fI~/.editrc\fP\&. Refer to +\fBeditrc(5)\fP for details. +.sp +Command history is saved in \fI~/.knsupdate_history\fP\&. +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH EXAMPLES +.INDENT 0.0 +.IP 1. 3 +Send one update of the zone example.com to the server 192.168.1.1. The update +contains two new records: +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ knsupdate +knsupdate> server 192.168.1.1 +knsupdate> zone example.com. +knsupdate> origin example.com. +knsupdate> ttl 3600 +knsupdate> add test1.example.com. 7200 A 192.168.2.2 +knsupdate> add test2 TXT \(dqhello\(dq +knsupdate> show +knsupdate> send +knsupdate> answer +knsupdate> exit +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBkdig(1)\fP, \fBkhost(1)\fP, \fBkeymgr(8)\fP, \fBeditrc(5)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/knsupdate.1in b/doc/man/knsupdate.1in deleted file mode 100644 index ed34dd2..0000000 --- a/doc/man/knsupdate.1in +++ /dev/null @@ -1,218 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KNSUPDATE" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -knsupdate \- Dynamic DNS update utility -.SH SYNOPSIS -.sp -\fBknsupdate\fP [\fIoptions\fP] [\fIfilename\fP] -.SH DESCRIPTION -.sp -This utility sends Dynamic DNS update messages to a DNS server. Update content -is read from a file (if the parameter \fIfilename\fP is given) or from the standard -input. -.sp -The format of updates is textual and is made up of commands. Every command is -placed on the separate line of the input. Lines starting with a semicolon are -comments and are not processed. -.SS Parameters -.INDENT 0.0 -.TP -\fIfilename\fP -Path to the file with knsupdate commands. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-d\fP -Enable debug messages. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-k\fP \fIkeyfile\fP -Use the TSIG key stored in a file \fIkeyfile\fP to authenticate the request. The -file should contain the key in the same format, which is accepted by the -\fB\-y\fP option. -.TP -\fB\-p\fP \fIport\fP -Set the port to use for connections to the server (if not explicitly specified -in the update). The default is 53. -.TP -\fB\-r\fP \fIretries\fP -The number of retries for UDP requests. The default is 3. -.TP -\fB\-t\fP \fItimeout\fP -The total timeout (for all UDP update tries) of the update request in seconds. -The default is 12. If set to zero, the timeout is infinite. -.TP -\fB\-v\fP -Use a TCP connection. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.TP -\fB\-y\fP [\fIalg\fP:]\fIname\fP:\fIkey\fP -Use the TSIG key with a name \fIname\fP to authenticate the request. The \fIalg\fP -part specifies the algorithm (the default is hmac\-sha256) and \fIkey\fP specifies -the shared secret encoded in Base64. -.UNINDENT -.SS Commands -.INDENT 0.0 -.TP -\fBserver\fP \fIname\fP [\fIport\fP] -Specifies a receiving server of the dynamic update message. The \fIname\fP parameter -can be either a host name or an IP address. If the \fIport\fP is not specified, -the default port is used. The default port value can be controlled using -the \fB\-p\fP program option. -.TP -\fBlocal\fP \fIaddress\fP [\fIport\fP] -Specifies outgoing \fIaddress\fP and \fIport\fP\&. If no local is specified, the -address and port are set by the system automatically. The default port number -is 0. -.TP -\fBzone\fP \fIname\fP -Specifies that all updates are done within a zone \fIname\fP\&. The zone name doesn\(aqt -have a default and must be set explicitly. -.TP -\fBorigin\fP \fIname\fP -Specifies fully qualified domain name suffix which is appended to non\-fqd -owners in update commands. The default is the terminal label (\fB\&.\fP). -.TP -\fBclass\fP \fIname\fP -Sets \fIname\fP as the default class for all updates. If not used, the default -class is IN. -.TP -\fBttl\fP \fIvalue\fP -Sets \fIvalue\fP as the default TTL (in seconds). If not used, the default value -is 3600. -.TP -\fBkey\fP [\fIalg\fP:]\fIname\fP \fIkey\fP -Specifies the TSIG \fIkey\fP named \fIname\fP to authenticate the request. An optional -\fIalg\fP algorithm can be specified. This command has the same effect as -the program option \fB\-y\fP\&. -.TP -[\fBprereq\fP] \fBnxdomain\fP \fIname\fP -Adds a prerequisite for a non\-existing record owned by \fIname\fP\&. -.TP -[\fBprereq\fP] \fByxdomain\fP \fIname\fP -Adds a prerequisite for an existing record owned by \fIname\fP\&. -.TP -[\fBprereq\fP] \fBnxrrset\fP \fIname\fP [\fIclass\fP] \fItype\fP -Adds a prerequisite for a non\-existing record of the \fItype\fP owned by \fIname\fP\&. -Internet \fIclass\fP is expected. -.TP -[\fBprereq\fP] \fByxrrset\fP \fIname\fP [\fIclass\fP] \fItype\fP [\fIdata\fP] -Adds a prerequisite for an existing record of the \fItype\fP owned by \fIname\fP -with optional \fIdata\fP\&. Internet \fIclass\fP is expected. -.TP -[\fBupdate\fP] \fBadd\fP \fIname\fP [\fIttl\fP] [\fIclass\fP] \fItype\fP \fIdata\fP -Adds a request to add a new resource record into the zone. -Please note that if the \fIname\fP is not fully qualified domain name, the -current origin name is appended to it. -.TP -[\fBupdate\fP] \fBdel\fP[\fBete\fP] \fIname\fP [\fIttl\fP] [\fIclass\fP] [\fItype\fP] [\fIdata\fP] -Adds a request to remove all (or matching \fIclass\fP, \fItype\fP or \fIdata\fP) -resource records from the zone. There is the same requirement for the \fIname\fP -parameter as in \fBupdate add\fP command. The \fIttl\fP item is ignored. -.TP -\fBshow\fP -Displays current content of the update message. -.TP -\fBsend\fP -Sends the current update message and cleans the list of updates. -.TP -\fBanswer\fP -Displays the last answer from the server. -.TP -\fBdebug\fP -Enable debugging. This command has the same meaning as the \fB\-d\fP program option. -.TP -\fBexit\fP -End the program. -.UNINDENT -.SH NOTES -.sp -Options \fB\-k\fP and \fB\-y\fP can not be used simultaneously. -.sp -Neither \fItsig\-keygen(8)\fP nor \fIdnssec\-keygen(1)\fP keyfile formats are supported. -Use \fBkeymgr(8)\fP to construct a string for \fB\-y\fP or the file passed to \fB\-k\fP\&. -.sp -Zone name/server guessing is not supported if the zone name/server is not specified. -.sp -An empty line doesn\(aqt send the update. -.SS Interactive mode -.sp -The utility provides interactive mode with basic line editing functionality, -command completion, and command history. -.sp -Interactive mode behavior can be customized in \fI~/.editrc\fP\&. Refer to -\fBeditrc(5)\fP for details. -.sp -Command history is saved in \fI~/.knsupdate_history\fP\&. -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH EXAMPLES -.INDENT 0.0 -.IP 1. 3 -Send one update of the zone example.com to the server 192.168.1.1. The update -contains two new records: -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knsupdate -knsupdate> server 192.168.1.1 -knsupdate> zone example.com. -knsupdate> origin example.com. -knsupdate> ttl 3600 -knsupdate> add test1.example.com. 7200 A 192.168.2.2 -knsupdate> add test2 TXT \(dqhello\(dq -knsupdate> show -knsupdate> send -knsupdate> answer -knsupdate> exit -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fBkdig(1)\fP, \fBkhost(1)\fP, \fBkeymgr(8)\fP, \fBeditrc(5)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/kxdpgun.8 b/doc/man/kxdpgun.8 new file mode 100644 index 0000000..d7892eb --- /dev/null +++ b/doc/man/kxdpgun.8 @@ -0,0 +1,299 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KXDPGUN" "8" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +kxdpgun \- XDP-powered DNS benchmarking tool +.SH SYNOPSIS +.sp +\fBkxdpgun\fP [\fIoptions\fP] \fB\-i\fP \fIfilename\fP \fItarget\fP +.SH DESCRIPTION +.sp +Powerful generator of DNS traffic, sending and receiving packets through XDP. +.sp +Queries are generated according to a textual file which is read sequentially +in a loop until a configured duration elapses. The order of queries is not +guaranteed. Responses are received (unless disabled) and counted, but not +checked against queries. +.sp +The number of parallel threads is autodetected according to the number of queues +configured for the network interface. +.SS Parameters +.INDENT 0.0 +.TP +.B \fIfilename\fP +Path to the queries file. See the description below regarding the file format. +.TP +.B \fItarget\fP +Either the domain name, IPv4 or IPv6 address of a remote target. +.UNINDENT +.SS Options +.INDENT 0.0 +.TP +\fB\-t\fP, \fB\-\-duration\fP \fIseconds\fP +Duration of traffic generation, specified as a decimal number in seconds +(default is 5.0). +.TP +\fB\-T\fP, \fB\-\-tcp\fP[\fB=\fP\fIdebug_mode\fP] +Send queries over TCP. See the list of optional debug modes below. +.TP +\fB\-U\fP, \fB\-\-quic\fP[\fB=\fP\fIdebug_mode\fP] +Send queries over QUIC. See the list of optional debug modes below. +.TP +\fB\-Q\fP, \fB\-\-qps\fP \fIqueries\fP +Number of queries\-per\-second (approximately) to be sent (default is 1000). +The program is not optimized for low speeds at which it may lose +communication packets. The recommended minimum speed is 2 packets per thread +(Rx/Tx queue). +.TP +\fB\-b\fP, \fB\-\-batch\fP \fIsize\fP +Send more queries in a batch. Improves QPS but may affect the counterpart\(aqs +packet loss (default is 10 for UDP and 1 for TCP/QUIC). +.TP +\fB\-r\fP, \fB\-\-drop\fP +Drop incoming responses. Improves QPS, but disables response statistics. +.TP +\fB\-p\fP, \fB\-\-port\fP \fInumber\fP +Remote destination port (default is 53 for UDP/TCP, 853 for QUIC). +.TP +\fB\-F\fP, \fB\-\-affinity\fP \fIcpu_spec\fP +CPU affinity for all threads specified in the format [][s], +where is the CPU ID for the first thread and is the +CPU ID increment for next thread (default is 0s1). +.TP +\fB\-i\fP, \fB\-\-infile\fP \fIfilename\fP +Path to a file with query templates. +.TP +\fB\-B\fP, \fB\-\-binary\fP +Specify that input file is in binary format. This format is similar to the +TCP DNS message format. The file contains records formated as 2\-octet length +(network order) followed by a message in DNS wire format. +.TP +\fB\-I\fP, \fB\-\-interface\fP \fIinterface\fP +Network interface for outgoing communication. This can be useful in situations +when the interfaces are in a bond for example. +.TP +\fB\-l\fP, \fB\-\-local\fP \fIlocalIP\fP[\fB/\fP\fIprefix\fP] +Override the auto\-detected source IP address. If an address range is specified +instead, various IPs from the range will be used for different queries uniformly +(address range not supported in the QUIC mode). +.TP +\fB\-L\fP, \fB\-\-mac\-local\fP +Override auto\-detected local MAC address. +.TP +\fB\-R\fP, \fB\-\-mac\-remote\fP +Override auto\-detected remote MAC address. +.TP +\fB\-v\fP, \fB\-\-vlan\fP \fIid\fP +Add VLAN 802.1Q header with the given id. VLAN offloading should be disabled. +.TP +\fB\-e\fP, \fB\-\-edns\-size\fP \fIsize\fP +EDNS UDP payload size, range 512\-4096 (default is 1232). Note that over XDP +the maximum supported MTU is 1790. +.TP +\fB\-m\fP, \fB\-\-mode\fP \fImode\fP +Set the XDP mode. Supported values are: +.INDENT 7.0 +.IP \(bu 2 +\fBauto\fP (default) – the XDP mode is selected automatically to achieve +the best performance, which means that native driver support is preferred +over the generic one, and zero\-copy is used if available. +.IP \(bu 2 +\fBcopy\fP – the XDP socket copy mode is forced even if zero\-copy +is available. This can resolve various driver issues, but at the cost +of lower performance. +.IP \(bu 2 +\fBgeneric\fP – the generic XDP implementation is forced even if native +implementation is available. This mode doesn\(aqt require support from the +driver nor hardware, but offers the worst performance. +.UNINDENT +.TP +\fB\-G\fP, \fB\-\-qlog\fP \fIpath\fP +Generate qlog files in the directory specified by \fIpath\fP\&. The directory +has to exist. +.sp +This option is ignored if not in the QUIC mode. The recommended usage is +with \fB\-\-quic=R\fP or with low QPS. Otherwise, too many files are generated. +.TP +\fB\-j\fP, \fB\-\-json\fP +Print statistics formatted as json. +.TP +\fB\-S\fP, \fB\-\-stats\-period\fP \fIperiod\fP +Report statistics automatically every \fIperiod\fP milliseconds. +.sp +These reports contain only metrics collected in the given period. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.SS Queries file format +.sp +Each line describes a query in the form: +.sp +\fIquery_name\fP \fIquery_type\fP [\fIflags\fP] +.sp +Where \fIquery_name\fP is a domain name to be queried, \fIquery_type\fP is a record type +name, and \fIflags\fP is a single character: +.sp +\fBE\fP Send query with EDNS. +.sp +\fBD\fP Request DNSSEC (EDNS + DO flag). +.SS TCP/QUIC debug modes +.INDENT 0.0 +.TP +\fB0\fP +Perform full handshake for all connections (QUIC only). +.TP +\fB1\fP +Just send SYN (Initial) and receive SYN\-ACK (Handshake). +.TP +\fB2\fP +Perform TCP/QUIC handshake and don\(aqt send anything, allow close initiated by counterpart. +.TP +\fB3\fP +Perform TCP/QUIC handshake and don\(aqt react further. +.TP +\fB5\fP +Send incomplete query (N\-1 bytes) and don\(aqt react further. +.TP +\fB7\fP +Send query and don\(aqt ACK the response or anything further. +.TP +\fB8\fP +Don\(aqt close the connection and ignore close by counterpart. +.TP +\fB9\fP +Operate normally except for not ACKing the final FIN+ACK (TCP only). +.TP +\fBR\fP +Instead of opening a connection for each query, reuse connections. +.UNINDENT +.SS Signals +.sp +Sending USR1 signal to a running process triggers current statistics dump +to the standard output. In combination with \fB\-S\fP may cause erratic printout +timing. +.SH NOTES +.sp +Linux kernel 4.18+ is required. +.sp +The utility has to be executed under root or with these capabilities: +CAP_NET_RAW, CAP_NET_ADMIN, CAP_SYS_ADMIN, CAP_IPC_LOCK, and CAP_SYS_RESOURCE +(Linux < 5.11). +.sp +The utility allocates source UDP/TCP ports from the range 2000\-65535. +.sp +Due to the multi\-threaded program structure there are slight discrepancies in +the timespan during which metrics are collected for any given thread. The +statistics printouts ignore this and are thus ever\-so\-slightly inaccurate. The +error margin decreases proportionally to the volume of data & timespan over +which they are collected. +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH EXAMPLES +.sp +Manually created queries file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +abc6.example.com. AAAA +nxdomain.example.com. A +notzone. A +a.example.com. NS E +ab.example.com. A D +abcd.example.com. DS D +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Queries file generated from a zone file (Knot DNS format): +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +cat ZONE_FILE | awk \(dq{print \e$1,\e$3}\(dq | grep \-E \(dq(NS|DS|A|AAAA|PTR|MX|SOA)$\(dq | sort \-u \-R > queries.txt +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Basic usage: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# kxdpgun \-i ~/queries.txt 2001:DB8::1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fIUsing UDP with increased batch size\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# kxdpgun \-t 20 \-Q 1000000 \-i ~/queries.txt \-b 20 \-p 8853 192.0.2.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fIUsing TCP\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# kxdpgun \-t 20 \-Q 100000 \-i ~/queries.txt \-T \-p 8853 192.0.2.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBkdig(1)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/kxdpgun.8in b/doc/man/kxdpgun.8in deleted file mode 100644 index f93872b..0000000 --- a/doc/man/kxdpgun.8in +++ /dev/null @@ -1,278 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KXDPGUN" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -kxdpgun \- XDP-powered DNS benchmarking tool -.SH SYNOPSIS -.sp -\fBkxdpgun\fP [\fIoptions\fP] \fB\-i\fP \fIfilename\fP \fItarget\fP -.SH DESCRIPTION -.sp -Powerful generator of DNS traffic, sending and receiving packets through XDP. -.sp -Queries are generated according to a textual file which is read sequentially -in a loop until a configured duration elapses. The order of queries is not -guaranteed. Responses are received (unless disabled) and counted, but not -checked against queries. -.sp -The number of parallel threads is autodetected according to the number of queues -configured for the network interface. -.SS Parameters -.INDENT 0.0 -.TP -\fIfilename\fP -Path to the queries file. See the description below regarding the file format. -.TP -\fItarget\fP -Either the domain name, IPv4 or IPv6 address of a remote target. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-t\fP, \fB\-\-duration\fP \fIseconds\fP -Duration of traffic generation, specified as a decimal number in seconds -(default is 5.0). -.TP -\fB\-T\fP, \fB\-\-tcp\fP[\fB=\fP\fIdebug_mode\fP] -Send queries over TCP. See the list of optional debug modes below. -.TP -\fB\-U\fP, \fB\-\-quic\fP[\fB=\fP\fIdebug_mode\fP] -Send queries over QUIC. See the list of optional debug modes below. -.TP -\fB\-Q\fP, \fB\-\-qps\fP \fIqueries\fP -Number of queries\-per\-second (approximately) to be sent (default is 1000). -The program is not optimized for low speeds at which it may lose -communication packets. The recommended minimum speed is 2 packets per thread -(Rx/Tx queue). -.TP -\fB\-b\fP, \fB\-\-batch\fP \fIsize\fP -Send more queries in a batch. Improves QPS but may affect the counterpart\(aqs -packet loss (default is 10 for UDP and 1 for TCP/QUIC). -.TP -\fB\-r\fP, \fB\-\-drop\fP -Drop incoming responses. Improves QPS, but disables response statistics. -.TP -\fB\-p\fP, \fB\-\-port\fP \fInumber\fP -Remote destination port (default is 53 for UDP/TCP, 853 for QUIC). -.TP -\fB\-F\fP, \fB\-\-affinity\fP \fIcpu_spec\fP -CPU affinity for all threads specified in the format [][s], -where is the CPU ID for the first thread and is the -CPU ID increment for next thread (default is 0s1). -.TP -\fB\-i\fP, \fB\-\-infile\fP \fIfilename\fP -Path to a file with query templates. -.TP -\fB\-I\fP, \fB\-\-interface\fP \fIinterface\fP -Network interface for outgoing communication. This can be useful in situations -when the interfaces are in a bond for example. -.TP -\fB\-l\fP, \fB\-\-local\fP \fIlocalIP\fP[\fB/\fP\fIprefix\fP] -Override the auto\-detected source IP address. If an address range is specified -instead, various IPs from the range will be used for different queries uniformly -(address range not supported in the QUIC mode). -.TP -\fB\-L\fP, \fB\-\-mac\-local\fP -Override auto\-detected local MAC address. -.TP -\fB\-R\fP, \fB\-\-mac\-remote\fP -Override auto\-detected remote MAC address. -.TP -\fB\-v\fP, \fB\-\-vlan\fP \fIid\fP -Add VLAN 802.1Q header with the given id. VLAN offloading should be disabled. -.TP -\fB\-e\fP, \fB\-\-edns\-size\fP \fIsize\fP -EDNS UDP payload size, range 512\-4096 (default is 1232). Note that over XDP -the maximum supported MTU is 1790. -.TP -\fB\-m\fP, \fB\-\-mode\fP \fImode\fP -Set the XDP mode. Supported values are: -.INDENT 7.0 -.IP \(bu 2 -\fBauto\fP (default) – the XDP mode is selected automatically to achieve -the best performance, which means that native driver support is preferred -over the generic one, and zero\-copy is used if available. -.IP \(bu 2 -\fBcopy\fP – the XDP socket copy mode is forced even if zero\-copy -is available. This can resolve various driver issues, but at the cost -of lower performance. -.IP \(bu 2 -\fBgeneric\fP – the generic XDP implementation is forced even if native -implementation is available. This mode doesn\(aqt require support from the -driver nor hardware, but offers the worst performance. -.UNINDENT -.TP -\fB\-G\fP, \fB\-\-qlog\fP \fIpath\fP -Generate qlog files in the directory specified by \fIpath\fP\&. The directory -has to exist. -.sp -This option is ignored if not in the QUIC mode. The recommended usage is -with \fB\-\-quic=R\fP or with low QPS. Otherwise, too many files are generated. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.UNINDENT -.SS Queries file format -.sp -Each line describes a query in the form: -.sp -\fIquery_name\fP \fIquery_type\fP [\fIflags\fP] -.sp -Where \fIquery_name\fP is a domain name to be queried, \fIquery_type\fP is a record type -name, and \fIflags\fP is a single character: -.sp -\fBE\fP Send query with EDNS. -.sp -\fBD\fP Request DNSSEC (EDNS + DO flag). -.SS TCP/QUIC debug modes -.INDENT 0.0 -.TP -\fB0\fP -Perform full handshake for all connections (QUIC only). -.TP -\fB1\fP -Just send SYN (Initial) and receive SYN\-ACK (Handshake). -.TP -\fB2\fP -Perform TCP/QUIC handshake and don\(aqt send anything, allow close initiated by counterpart. -.TP -\fB3\fP -Perform TCP/QUIC handshake and don\(aqt react further. -.TP -\fB5\fP -Send incomplete query (N\-1 bytes) and don\(aqt react further. -.TP -\fB7\fP -Send query and don\(aqt ACK the response or anything further. -.TP -\fB8\fP -Don\(aqt close the connection and ignore close by counterpart. -.TP -\fB9\fP -Operate normally except for not ACKing the final FIN+ACK (TCP only). -.TP -\fBR\fP -Instead of opening a connection for each query, reuse connections. -.UNINDENT -.SS Signals -.sp -Sending USR1 signal to a running process triggers current statistics dump -to the standard output. -.SH NOTES -.sp -Linux kernel 4.18+ is required. -.sp -The utility has to be executed under root or with these capabilities: -CAP_NET_RAW, CAP_NET_ADMIN, CAP_SYS_ADMIN, CAP_IPC_LOCK, and CAP_SYS_RESOURCE -(Linux < 5.11). -.sp -The utility allocates source UDP/TCP ports from the range 2000\-65535. -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH EXAMPLES -.sp -Manually created queries file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -abc6.example.com. AAAA -nxdomain.example.com. A -notzone. A -a.example.com. NS E -ab.example.com. A D -abcd.example.com. DS D -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Queries file generated from a zone file (Knot DNS format): -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -cat ZONE_FILE | awk \(dq{print \e$1,\e$3}\(dq | grep \-E \(dq(NS|DS|A|AAAA|PTR|MX|SOA)$\(dq | sort \-u \-R > queries.txt -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Basic usage: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# kxdpgun \-i ~/queries.txt 2001:DB8::1 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fIUsing UDP with increased batch size\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# kxdpgun \-t 20 \-Q 1000000 \-i ~/queries.txt \-b 20 \-p 8853 192.0.2.1 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fIUsing TCP\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# kxdpgun \-t 20 \-Q 100000 \-i ~/queries.txt \-T \-p 8853 192.0.2.1 -.ft P -.fi -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fBkdig(1)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/kzonecheck.1 b/doc/man/kzonecheck.1 new file mode 100644 index 0000000..22ebe47 --- /dev/null +++ b/doc/man/kzonecheck.1 @@ -0,0 +1,95 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KZONECHECK" "1" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +kzonecheck \- Knot DNS zone check tool +.SH SYNOPSIS +.sp +\fBkzonecheck\fP [\fIoptions\fP] \fIfilename\fP +.SH DESCRIPTION +.sp +The utility checks zone file syntax and runs semantic checks on the zone +content. The executed checks are the same as the checks run by the Knot +DNS server. +.sp +Please, refer to the \fBsemantic\-checks\fP configuration option in +\fBknot.conf(5)\fP for the full list of available semantic checks. +.SS Parameters +.INDENT 0.0 +.TP +.B \fIfilename\fP +Path to the zone file to be checked. For reading from \fBstdin\fP use \fB/dev/stdin\fP +or just \fB\-\fP\&. +.UNINDENT +.SS Options +.INDENT 0.0 +.TP +\fB\-o\fP, \fB\-\-origin\fP \fIorigin\fP +Zone origin. If not specified, the origin is determined from the file name +(possibly removing the \fB\&.zone\fP suffix). +.TP +\fB\-d\fP, \fB\-\-dnssec\fP \fBon\fP|\fBoff\fP +Also check DNSSEC\-related records. The default is to decide based on the +existence of a RRSIG for SOA. +.TP +\fB\-z\fP, \fB\-\-zonemd\fP +Also check the zone hash against a ZONEMD record, which is required to exist. +.TP +\fB\-t\fP, \fB\-\-time\fP \fItime\fP +Current time specification. Use UNIX timestamp, YYYYMMDDHHmmSS +format, or [+/\-]\fItime\fP[unit] format, where unit can be \fBY\fP, \fBM\fP, +\fBD\fP, \fBh\fP, \fBm\fP, or \fBs\fP\&. Default is current UNIX timestamp. +.TP +\fB\-p\fP, \fB\-\-print\fP +Print the zone on stdout. +.TP +\fB\-v\fP, \fB\-\-verbose\fP +Enable debug output. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH SEE ALSO +.sp +\fBknotd(8)\fP, \fBknot.conf(5)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/kzonecheck.1in b/doc/man/kzonecheck.1in deleted file mode 100644 index a73b66e..0000000 --- a/doc/man/kzonecheck.1in +++ /dev/null @@ -1,94 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KZONECHECK" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -kzonecheck \- Knot DNS zone check tool -.SH SYNOPSIS -.sp -\fBkzonecheck\fP [\fIoptions\fP] \fIfilename\fP -.SH DESCRIPTION -.sp -The utility checks zone file syntax and runs semantic checks on the zone -content. The executed checks are the same as the checks run by the Knot -DNS server. -.sp -Please, refer to the \fBsemantic\-checks\fP configuration option in -\fBknot.conf(5)\fP for the full list of available semantic checks. -.SS Parameters -.INDENT 0.0 -.TP -\fIfilename\fP -Path to the zone file to be checked. For reading from \fBstdin\fP use \fB/dev/stdin\fP -or just \fB\-\fP\&. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-o\fP, \fB\-\-origin\fP \fIorigin\fP -Zone origin. If not specified, the origin is determined from the file name -(possibly removing the \fB\&.zone\fP suffix). -.TP -\fB\-d\fP, \fB\-\-dnssec\fP \fBon\fP|\fBoff\fP -Also check DNSSEC\-related records. The default is to decide based on the -existence of a RRSIG for SOA. -.TP -\fB\-z\fP, \fB\-\-zonemd\fP -Also check the zone hash against a ZONEMD record, which is required to exist. -.TP -\fB\-t\fP, \fB\-\-time\fP \fItime\fP -Current time specification. Use UNIX timestamp, YYYYMMDDHHmmSS -format, or [+/\-]\fItime\fP[unit] format, where unit can be \fBY\fP, \fBM\fP, -\fBD\fP, \fBh\fP, \fBm\fP, or \fBs\fP\&. Default is current UNIX timestamp. -.TP -\fB\-p\fP, \fB\-\-print\fP -Print the zone on stdout. -.TP -\fB\-v\fP, \fB\-\-verbose\fP -Enable debug output. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.UNINDENT -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH SEE ALSO -.sp -\fBknotd(8)\fP, \fBknot.conf(5)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man/kzonesign.1 b/doc/man/kzonesign.1 new file mode 100644 index 0000000..558c95b --- /dev/null +++ b/doc/man/kzonesign.1 @@ -0,0 +1,96 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KZONESIGN" "1" "2024-09-02" "3.4.0" "Knot DNS" +.SH NAME +kzonesign \- DNSSEC signing utility +.SH SYNOPSIS +.sp +\fBkzonesign\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIzone_name\fP +.SH DESCRIPTION +.sp +This utility reads the zone\(aqs zone file, signs the zone according to given +configuration, and writes the signed zone file back. An alternative mode +is DNSSEC validation of the given zone. The signing or validation +can run in parallel if enabled in the configuration (see policy.signing\-threads +and zone.adjust\-threads). +.SS Parameters +.INDENT 0.0 +.TP +.B \fIzone_name\fP +A name of the zone to be signed. +.UNINDENT +.SS Config options +.INDENT 0.0 +.TP +\fB\-c\fP, \fB\-\-config\fP \fIfile\fP +Use a textual configuration file (default is \fB/usr/local/etc/knot/knot.conf\fP). +.TP +\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP +Use a binary configuration database directory (default is \fB/usr/local/var/lib/knot/confdb\fP). +The default configuration database, if exists, has a preference to the default +configuration file. +.UNINDENT +.SS Options +.INDENT 0.0 +.TP +\fB\-o\fP, \fB\-\-outdir\fP \fIdir_name\fP +Write the output zone file to the specified directory instead of the configured one. +.TP +\fB\-r\fP, \fB\-\-rollover\fP +Allow key roll\-overs and NSEC3 re\-salt. In order to finish possible KSK submission, +set the KSK\(aqs \fBactive\fP timestamp to now (\fB+0\fP) using \fI\%keymgr\fP\&. +.TP +\fB\-v\fP, \fB\-\-verify\fP +Instead of (re\-)signing the zone, just verify that the zone is correctly signed. +.TP +\fB\-t\fP, \fB\-\-time\fP \fItimestamp\fP +Sign/verify the zone (and roll the keys if necessary) as if it was at the time +specified by timestamp. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print the program help. +.TP +\fB\-V\fP, \fB\-\-version\fP +Print the program version. The option \fB\-VV\fP makes the program +print the compile time configuration summary. +.UNINDENT +.SH EXIT VALUES +.sp +Exit status of 0 means successful operation. Any other exit status indicates +an error. +.SH SEE ALSO +.sp +\fBknot.conf(5)\fP, \fBkeymgr(8)\fP\&. +.SH AUTHOR +CZ.NIC Labs +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/kzonesign.1in b/doc/man/kzonesign.1in deleted file mode 100644 index 147e112..0000000 --- a/doc/man/kzonesign.1in +++ /dev/null @@ -1,95 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KZONESIGN" "1" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -kzonesign \- DNSSEC signing utility -.SH SYNOPSIS -.sp -\fBkzonesign\fP [\fIconfig_option\fP] [\fIoptions\fP] \fIzone_name\fP -.SH DESCRIPTION -.sp -This utility reads the zone\(aqs zone file, signs the zone according to given -configuration, and writes the signed zone file back. An alternative mode -is DNSSEC validation of the given zone. The signing or validation -can run in parallel if enabled in the configuration (see policy.signing\-threads -and zone.adjust\-threads). -.SS Parameters -.INDENT 0.0 -.TP -\fIzone_name\fP -A name of the zone to be signed. -.UNINDENT -.SS Config options -.INDENT 0.0 -.TP -\fB\-c\fP, \fB\-\-config\fP \fIfile\fP -Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). -.TP -\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP -Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). -The default configuration database, if exists, has a preference to the default -configuration file. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-o\fP, \fB\-\-outdir\fP \fIdir_name\fP -Write the output zone file to the specified directory instead of the configured one. -.TP -\fB\-r\fP, \fB\-\-rollover\fP -Allow key roll\-overs and NSEC3 re\-salt. In order to finish possible KSK submission, -set the KSK\(aqs \fBactive\fP timestamp to now (\fB+0\fP) using \fI\%keymgr\fP\&. -.TP -\fB\-v\fP, \fB\-\-verify\fP -Instead of (re\-)signing the zone, just verify that the zone is correctly signed. -.TP -\fB\-t\fP, \fB\-\-time\fP \fItimestamp\fP -Sign/verify the zone (and roll the keys if necessary) as if it was at the time -specified by timestamp. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. -.UNINDENT -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH SEE ALSO -.sp -\fBknot.conf(5)\fP, \fBkeymgr(8)\fP\&. -.SH AUTHOR -CZ.NIC Labs -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. diff --git a/doc/man_kcatalogprint.rst b/doc/man_kcatalogprint.rst index cccc641..da2ed97 100644 --- a/doc/man_kcatalogprint.rst +++ b/doc/man_kcatalogprint.rst @@ -40,7 +40,8 @@ Options Print the program help. **-V**, **--version** - Print the program version. + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. Exit values ----------- diff --git a/doc/man_kdig.rst b/doc/man_kdig.rst index 4457b68..cda3303 100644 --- a/doc/man_kdig.rst +++ b/doc/man_kdig.rst @@ -111,7 +111,8 @@ Options An explicit *query_type* specification. See possible values above. **-V**, **--version** - Print the program version. + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. **-x** *address* Send a reverse (PTR) query for IPv4 or IPv6 *address*. The correct name, class @@ -281,7 +282,7 @@ Options Request the nameserver identifier (NSID). **+**\ [\ **no**\ ]\ **bufsize**\ =\ *B* - Set EDNS buffer size in bytes (default is 4096 bytes). + Set EDNS buffer size in bytes (default is 1232 bytes). **+**\ [\ **no**\ ]\ **padding**\[\ =\ *B*\] Use EDNS(0) padding option to pad queries, optionally to a specific @@ -298,7 +299,7 @@ Options Set EDNS(0) client subnet SUBN=addr/prefix. **+**\ [\ **no**\ ]\ **edns**\[\ =\ *N*\] - Use EDNS version (default is 0). + Use EDNS version (default is 0). EDNS(0) is enabled by default. **+**\ [\ **no**\ ]\ **timeout**\ =\ *T* Set the wait-for-reply interval in seconds (default is 5 seconds). This timeout @@ -333,7 +334,7 @@ Options **+noidn** Disable the IDN transformation to ASCII and vice versa. IDN support depends - on libidn availability during project building! If used in *common-settings*, + on libidn2 availability during project building! If used in *common-settings*, all IDN transformations are disabled. If used in the individual query *settings*, transformation from ASCII is disabled on output for the particular query. Note that IDN transformation does not preserve domain name letter case. diff --git a/doc/man_keymgr.rst b/doc/man_keymgr.rst index 136a92c..a0001fe 100644 --- a/doc/man_keymgr.rst +++ b/doc/man_keymgr.rst @@ -75,7 +75,8 @@ Options Print the program help. **-V**, **--version** - Print the program version. + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. .. NOTE:: Keymgr runs with the same user privileges as configured for :doc:`knotd`. diff --git a/doc/man_khost.rst b/doc/man_khost.rst index 1fcc0bf..9447856 100644 --- a/doc/man_khost.rst +++ b/doc/man_khost.rst @@ -57,7 +57,8 @@ Options Enable verbose output. **-V**, **--version** - Print the program version. + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. **-w** Wait forever for the reply. diff --git a/doc/man_kjournalprint.rst b/doc/man_kjournalprint.rst index f83a137..3b2d024 100644 --- a/doc/man_kjournalprint.rst +++ b/doc/man_kjournalprint.rst @@ -57,9 +57,6 @@ Options **-x**, **--mono** Don't generate colorized output. -**-n**, **--no-color** - An alias for **-x**. Use of this option is deprecated, it will be removed in the future. - **-X**, **--color** Force colorized output. @@ -67,7 +64,8 @@ Options Print the program help. **-V**, **--version** - Print the program version. + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. Exit values ----------- diff --git a/doc/man_knotc.rst b/doc/man_knotc.rst index d03bc77..4755a6a 100644 --- a/doc/man_knotc.rst +++ b/doc/man_knotc.rst @@ -65,7 +65,8 @@ Options Print the program help. **-V**, **--version** - Print the program version. + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. Actions ....... @@ -150,8 +151,9 @@ Actions explicitly. If zone flushing is disabled, the original zone file is backed up instead of writing out zone contents to a file. When backing-up a catalog zone, it is recommended to prevent ongoing changes to it by use of - **zone-freeze**. - See :ref:`Notes` below about the directory permissions. (#) + **zone-freeze**. The force option allows an already existing backupdir to + be overwritten. See :ref:`Notes` below about the directory permissions. + (#) **zone-restore** [*zone*...] **+backupdir** *directory* [*filter*...] Trigger a zone data and metadata restore from a specified backup directory. @@ -164,6 +166,10 @@ Actions Trigger a DNSSEC re-sign of the zone. Existing signatures will be dropped. This command is valid for zones with DNSSEC signing enabled. (#) +**zone-validate** [*zone*...] + Trigger a DNSSEC validation of the zone. If the validation fails and the + zone is secondary, the zone expires immediately! (#) + **zone-keys-load** [*zone*...] Trigger a load of DNSSEC keys and other signing material from KASP database (which might have been altered manually). If suitable, re-sign the zone @@ -184,7 +190,8 @@ Actions **zone-freeze** [*zone*...] Trigger a zone freeze. All running events will be finished and all new and pending (planned) zone-changing events (load, refresh, update, flush, and DNSSEC signing) - will be held up until the zone is thawed. (#) + will be held up until the zone is thawed. Up to 8 (this limit is hardcoded) DDNS + updates per zone will be queued, subsequent updates will be refused. (#) **zone-thaw** [*zone*...] Trigger dismissal of zone freeze. (#) diff --git a/doc/man_knotd.rst b/doc/man_knotd.rst index d0fe83b..9f3193f 100644 --- a/doc/man_knotd.rst +++ b/doc/man_knotd.rst @@ -46,7 +46,8 @@ Options Print the program help. **-V**, **--version** - Print the program version. + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. Signals ....... diff --git a/doc/man_knsec3hash.rst b/doc/man_knsec3hash.rst index bf0688c..b3367fe 100644 --- a/doc/man_knsec3hash.rst +++ b/doc/man_knsec3hash.rst @@ -10,6 +10,8 @@ Synopsis :program:`knsec3hash` *algorithm* *flags* *iterations* *salt* *name* +:program:`knsec3hash` [*-h*] [*-V*] + Description ----------- @@ -33,6 +35,16 @@ Parameters *flags* Specifies NSEC3 flags as an unsigned integer. +Options +....... + +**-h**, **--help** + Print the program help. + +**-V**, **--version** + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. + Exit values ----------- diff --git a/doc/man_knsupdate.rst b/doc/man_knsupdate.rst index 40a419b..e2d71f9 100644 --- a/doc/man_knsupdate.rst +++ b/doc/man_knsupdate.rst @@ -6,7 +6,9 @@ Synopsis -------- -:program:`knsupdate` [*options*] [*filename*] +:program:`knsupdate` [**-v**] [*options*] [*filename*] + +:program:`knsupdate` [**-q**] [*quic_options*] [*options*] [*filename*] Description ----------- @@ -28,39 +30,71 @@ Parameters Options ....... -**-d** - Enable debug messages. +**-T**, **--tcp** + Use a TCP connection. (**-v** can be used for compatibility with nsupdate). -**-h**, **--help** - Print the program help. +**-S**, **--tls** + Use a TLS connection. -**-k** *keyfile* - Use the TSIG key stored in a file *keyfile* to authenticate the request. The - file should contain the key in the same format, which is accepted by the - **-y** option. +**-Q**, **--quic** + Use a QUIC connection. -**-p** *port* +**-p**, **--port** *number* Set the port to use for connections to the server (if not explicitly specified - in the update). The default is 53. + in the update). The default is 53 for UDP/TCP or 853 for QUIC. -**-r** *retries* +**-r**, **--retry** *count* The number of retries for UDP requests. The default is 3. -**-t** *timeout* +**-t**, **--timeout** *seconds* The total timeout (for all UDP update tries) of the update request in seconds. The default is 12. If set to zero, the timeout is infinite. -**-v** - Use a TCP connection. - -**-V**, **--version** - Print the program version. - -**-y** [*alg*:]\ *name*:*key* +**-y**, **--tsig** [*alg*:]\ *name*:*key* Use the TSIG key with a name *name* to authenticate the request. The *alg* part specifies the algorithm (the default is hmac-sha256) and *key* specifies the shared secret encoded in Base64. +**-k**, **--tsigfile** *path* + Use the TSIG key stored in a file *keyfile* to authenticate the request. The + file should contain the key in the same format, which is accepted by the + **-y** option. + +**-d**, **--debug** + Enable debug messages. + +**-h**, **--help** + Print the program help. + +**-V**, **--version** + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. + +QUIC/TLS options +................ + +**-H**, **--hostname** *string* + Enable remote server hostname validation. + +**-P**, **--pin** *base64* + Use Out-of-Band key-pinned privacy profile + (RFC 7858#section-4.2). The PIN must be a Base64 encoded SHA-256 hash of the + X.509 SubjectPublicKeyInfo. Can be specified multiple times. + +**-A**, **--ca** [*path*] + Enable certificate validation. Certification authority certificates + are loaded from the specified PEM file (default is system certificate storage + if no argument is provided). Can be specified multiple times. + +**-E**, **--certfile** *path* + Path to a client certificate file. + +**-K**, **--keyfile** *path* + Path to a client key file. + +**-s**, **--sni** *string* + Use specified Server Name Indication. + Commands ........ diff --git a/doc/man_kxdpgun.rst b/doc/man_kxdpgun.rst index 28713ba..bc26d12 100644 --- a/doc/man_kxdpgun.rst +++ b/doc/man_kxdpgun.rst @@ -67,6 +67,11 @@ Options **-i**, **--infile** *filename* Path to a file with query templates. +**-B**, **--binary** + Specify that input file is in binary format. This format is similar to the + TCP DNS message format. The file contains records formated as 2-octet length + (network order) followed by a message in DNS wire format. + **-I**, **--interface** *interface* Network interface for outgoing communication. This can be useful in situations when the interfaces are in a bond for example. @@ -111,11 +116,20 @@ Options This option is ignored if not in the QUIC mode. The recommended usage is with **--quic=R** or with low QPS. Otherwise, too many files are generated. +**-j**, **--json** + Print statistics formatted as json. + +**-S**, **--stats-period** *period* + Report statistics automatically every *period* milliseconds. + + These reports contain only metrics collected in the given period. + **-h**, **--help** Print the program help. **-V**, **--version** - Print the program version. + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. Queries file format ................... @@ -165,7 +179,8 @@ Signals ....... Sending USR1 signal to a running process triggers current statistics dump -to the standard output. +to the standard output. In combination with **-S** may cause erratic printout +timing. Notes ----- @@ -178,6 +193,12 @@ CAP_NET_RAW, CAP_NET_ADMIN, CAP_SYS_ADMIN, CAP_IPC_LOCK, and CAP_SYS_RESOURCE The utility allocates source UDP/TCP ports from the range 2000-65535. +Due to the multi-threaded program structure there are slight discrepancies in +the timespan during which metrics are collected for any given thread. The +statistics printouts ignore this and are thus ever-so-slightly inaccurate. The +error margin decreases proportionally to the volume of data & timespan over +which they are collected. + Exit values ----------- diff --git a/doc/man_kzonecheck.rst b/doc/man_kzonecheck.rst index 3a10863..c0dae37 100644 --- a/doc/man_kzonecheck.rst +++ b/doc/man_kzonecheck.rst @@ -54,7 +54,8 @@ Options Print the program help. **-V**, **--version** - Print the program version. + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. Exit values ----------- diff --git a/doc/man_kzonesign.rst b/doc/man_kzonesign.rst index c759c57..a1981ee 100644 --- a/doc/man_kzonesign.rst +++ b/doc/man_kzonesign.rst @@ -55,7 +55,8 @@ Options Print the program help. **-V**, **--version** - Print the program version. + Print the program version. The option **-VV** makes the program + print the compile time configuration summary. Exit values ----------- diff --git a/doc/migration.rst b/doc/migration.rst index f79539c..7c4a279 100644 --- a/doc/migration.rst +++ b/doc/migration.rst @@ -249,19 +249,19 @@ Configuration changes - Ignored obsolete options (with a notice log): - - ``server.max-journal-depth`` - - ``server.max-journal-usage`` - - ``server.max-refresh-interval`` - - ``server.min-refresh-interval`` - ``server.max-ipv4-udp-payload`` - ``server.max-ipv6-udp-payload`` - ``server.max-udp-payload`` - ``server.max-tcp-clients`` - ``server.tcp-reply-timeout`` + - ``zone.max-journal-depth`` + - ``zone.max-journal-usage`` + - ``zone.max-refresh-interval`` + - ``zone.min-refresh-interval`` + - ``zone.max-zone-size`` - ``template.journal-db`` - ``template.kasp-db`` - ``template.timer-db`` - - ``template.max-zone-size`` - ``template.max-journal-db-size`` - ``template.max-timer-db-size`` - ``template.max-kasp-db-size`` @@ -393,6 +393,86 @@ Query module API change The function ``knotd_qdata_local_addr()`` only takes one parameter. +.. _Upgrade 3.3.x to 3.4.x: + +Upgrade 3.3.x to 3.4.x +====================== + +There are the following changes between Knot DNS versions 3.4.x and 3.3.x. + +DNSSEC +------ + +- DNSSEC validation fails if the remaining RRSIG validity is shorter than + the corresponding :ref:`policy_rrsig-refresh` value. +- SKR verification fails if the end of a DNSKEY RRSIG validity period doesn't + cover the next DNSKEY snapshot. +- If DNSSEC signing is enabled, the outbound request's EDNS expire value is + lowered to the earliest RRSIG expiration if it is higher. + +Semantic checks +--------------- + +- Just one SOA record is required. +- Unified DNAME and CNAME semantic checks (see :ref:`Handling CNAME and DNAME-related updates`). + +Configuration changes +--------------------- + +- The server no longer allows concurrent control zone and configuration transactions. +- The server no longer allows opening a zone transaction when a blocking command is running. +- Removed already ignored obsolete options: + + - ``server.max-ipv4-udp-payload`` + - ``server.max-ipv6-udp-payload`` + - ``server.max-udp-payload`` + - ``server.max-tcp-clients`` + - ``server.tcp-handshake-timeout`` + - ``server.tcp-reply-timeout`` + - ``server.listen-xdp`` + - ``xdp.quic-log`` + - ``zone.max-journal-depth`` + - ``zone.max-journal-usage`` + - ``zone.max-refresh-interval`` + - ``zone.min-refresh-interval`` + - ``zone.max-zone-size`` + - ``zone.disable-any`` + - ``template.journal-db`` + - ``template.kasp-db`` + - ``template.timer-db`` + - ``template.max-journal-db-size`` + - ``template.max-timer-db-size`` + - ``template.max-kasp-db-size`` + - ``template.journal-db-mode`` + +Utilities +--------- + +- Changed defaults: + + - :doc:`kdig`: enabled ``+edns`` and ``+bufsize=1232`` + +- Removed legacy parameters: + + - :doc:`keymgr`: ``--brief`` + - :doc:`kjournalprint`: ``--no-color`` + - :doc:`kjournalprint`: database specification without ``--dir`` + - :doc:`kjournalprint`: database specification without ``--dir`` + +Documentation +------------- + +- Info pages are no longer supported. + +Building notes +-------------- + +- A GCC or LLVM Clang compiler with C11 support is required. +- Minimum required *GnuTLS* version is 3.6.10. +- *Libidn* version 1 is no longer supported. +- *Liburcu* must be available via pkg-config. +- Linux distributions CentOS 7, Debian 10, and Ubuntu 18.04 are no longer supported. + .. _Knot DNS for BIND users: Knot DNS for BIND users diff --git a/doc/operation.rst b/doc/operation.rst index 5754147..5c2bdf2 100644 --- a/doc/operation.rst +++ b/doc/operation.rst @@ -632,7 +632,7 @@ continues along the lines of :rfc:`6781#section-4.1.2`:: 2024-02-14T15:20:00+0100 info: [example.com.] DNSSEC, key, tag 36185, algorithm ECDSAP256SHA256, public, active 2024-02-14T15:20:00+0100 info: [example.com.] DNSSEC, key, tag 3375, algorithm ECDSAP256SHA256, KSK, public, active+ 2024-02-14T15:20:00+0100 info: [example.com.] DNSSEC, signing started - 2024-02-14T15:20:00+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111204 + 2024-02-14T15:20:00+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111204, new RRSIGs 3 2024-02-14T15:20:00+0100 info: [example.com.] DNSSEC, next signing at 2024-02-14T15:20:12+0100 ... (propagation-delay + dnskey-ttl) ... @@ -643,7 +643,7 @@ continues along the lines of :rfc:`6781#section-4.1.2`:: 2024-02-14T15:20:12+0100 info: [example.com.] DNSSEC, key, tag 36185, algorithm ECDSAP256SHA256, public, active 2024-02-14T15:20:12+0100 info: [example.com.] DNSSEC, key, tag 3375, algorithm ECDSAP256SHA256, KSK, public, ready, active+ 2024-02-14T15:20:12+0100 info: [example.com.] DNSSEC, signing started - 2024-02-14T15:20:12+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111205 + 2024-02-14T15:20:12+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111205, new RRSIGs 6 2024-02-14T15:20:12+0100 info: [example.com.] DNSSEC, next signing at 2024-02-28T15:19:37+0100 At this point the new KSK has to be submitted to the parent zone. Knot detects the updated parent's DS @@ -660,7 +660,7 @@ operator must confirm it manually (using ``knotc zone-ksk-submitted``):: 2024-02-14T15:20:16+0100 info: [example.com.] DNSSEC, key, tag 36185, algorithm ECDSAP256SHA256, public, active 2024-02-14T15:20:16+0100 info: [example.com.] DNSSEC, key, tag 3375, algorithm ECDSAP256SHA256, KSK, public, active 2024-02-14T15:20:16+0100 info: [example.com.] DNSSEC, signing started - 2024-02-14T15:20:16+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111206 + 2024-02-14T15:20:16+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111206, new RRSIGs 2 2024-02-14T15:20:16+0100 info: [example.com.] DNSSEC, next signing at 2024-02-14T15:20:23+0100 ... (parent's DS TTL is 7 seconds) ... @@ -670,7 +670,7 @@ operator must confirm it manually (using ``knotc zone-ksk-submitted``):: 2024-02-14T15:20:23+0100 info: [example.com.] DNSSEC, key, tag 36185, algorithm ECDSAP256SHA256, public, active 2024-02-14T15:20:23+0100 info: [example.com.] DNSSEC, key, tag 3375, algorithm ECDSAP256SHA256, KSK, public, active 2024-02-14T15:20:23+0100 info: [example.com.] DNSSEC, signing started - 2024-02-14T15:20:23+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111207 + 2024-02-14T15:20:23+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111207, new RRSIGs 2 2024-02-14T15:20:23+0100 info: [example.com.] DNSSEC, next signing at 2024-02-14T15:21:54+0100 Upon the zone's ZSK lifetime expiration, a new ZSK is generated and the rollover @@ -685,7 +685,7 @@ continues along the lines of :rfc:`6781#section-4.1.1`:: 2024-02-14T15:21:54+0100 info: [example.com.] DNSSEC, key, tag 3375, algorithm ECDSAP256SHA256, KSK, public, active 2024-02-14T15:21:54+0100 info: [example.com.] DNSSEC, key, tag 38559, algorithm ECDSAP256SHA256, public 2024-02-14T15:21:54+0100 info: [example.com.] DNSSEC, signing started - 2024-02-14T15:21:54+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111208 + 2024-02-14T15:21:54+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111208, new RRSIGs 2 2024-02-14T15:21:54+0100 info: [example.com.] DNSSEC, next signing at 2024-02-14T15:22:06+0100 ... (propagation-delay + dnskey-ttl) ... @@ -696,7 +696,7 @@ continues along the lines of :rfc:`6781#section-4.1.1`:: 2024-02-14T15:22:06+0100 info: [example.com.] DNSSEC, key, tag 3375, algorithm ECDSAP256SHA256, KSK, public, active 2024-02-14T15:22:06+0100 info: [example.com.] DNSSEC, key, tag 38559, algorithm ECDSAP256SHA256, public, active 2024-02-14T15:22:06+0100 info: [example.com.] DNSSEC, signing started - 2024-02-14T15:22:06+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111209 + 2024-02-14T15:22:06+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111209, new RRSIGs 14 2024-02-14T15:22:06+0100 info: [example.com.] DNSSEC, next signing at 2024-02-14T15:22:23+0100 ... (propagation-delay + zone-max-ttl) ... @@ -706,7 +706,7 @@ continues along the lines of :rfc:`6781#section-4.1.1`:: 2024-02-14T15:22:23+0100 info: [example.com.] DNSSEC, key, tag 3375, algorithm ECDSAP256SHA256, KSK, public, active 2024-02-14T15:22:23+0100 info: [example.com.] DNSSEC, key, tag 38559, algorithm ECDSAP256SHA256, public, active 2024-02-14T15:22:23+0100 info: [example.com.] DNSSEC, signing started - 2024-02-14T15:22:23+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111210 + 2024-02-14T15:22:23+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111210, new RRSIGs 2 2024-02-14T15:22:23+0100 info: [example.com.] DNSSEC, next signing at 2024-02-14T15:24:06+0100 Further rollovers:: @@ -722,7 +722,7 @@ Further rollovers:: 2024-02-14T15:24:06+0100 info: [example.com.] DNSSEC, key, tag 38559, algorithm ECDSAP256SHA256, public, active 2024-02-14T15:24:06+0100 info: [example.com.] DNSSEC, key, tag 59825, algorithm ECDSAP256SHA256, public 2024-02-14T15:24:06+0100 info: [example.com.] DNSSEC, signing started - 2024-02-14T15:24:06+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111211 + 2024-02-14T15:24:06+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111211, new RRSIGs 2 2024-02-14T15:24:06+0100 info: [example.com.] DNSSEC, next signing at 2024-02-14T15:24:18+0100 ... @@ -736,7 +736,7 @@ Further rollovers:: 2024-02-14T15:25:00+0100 info: [example.com.] DNSSEC, key, tag 59825, algorithm ECDSAP256SHA256, public, active 2024-02-14T15:25:00+0100 info: [example.com.] DNSSEC, key, tag 50822, algorithm ECDSAP256SHA256, KSK, public, active+ 2024-02-14T15:25:00+0100 info: [example.com.] DNSSEC, signing started - 2024-02-14T15:25:00+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111214 + 2024-02-14T15:25:00+0100 info: [example.com.] DNSSEC, successfully signed, serial 2010111214, new RRSIGs 3 2024-02-14T15:25:00+0100 info: [example.com.] DNSSEC, next signing at 2024-02-14T15:25:12+0100 ... @@ -1282,12 +1282,12 @@ if the backup was created for only a subset of zones. turns off some verification checks, it shouldn't be used in other cases. .. NOTE:: - For QUIC, only the auto-generated key is restored. The ``zone-restore`` - command doesn't restore a user-defined QUIC key and certificate so as to + For QUIC/TLS, only the auto-generated key is restored. The ``zone-restore`` + command doesn't restore a user-defined QUIC/TLS key and certificate so as to avoid possible configuration management conflicts and they must be restored from the backup (its subdirectory ``quic``) manually. In all cases, restart of the Knot server after the restore is necessary for the restored - QUIC key/certificate to take effect. + QUIC/TLS key/certificate to take effect. Limitations ----------- @@ -1375,9 +1375,15 @@ Pre-requisites * A multiqueue network card, which offers enough Combined RX/TX channels, with native XDP support is highly recommended. Successfully tested cards: + * NVIDIA (Mellanox) ConnectX-6 Dx (driver `mlx5_core`), maximum number of channels + per interface is 63. Official drivers are recommended. * Intel series 700 (driver `i40e`), maximum number of channels per interface is 64. - * Intel series 500 (driver `ixgbe`), maximum number of channels per interface is 64. - The number of CPUs available has to be at most 64! + Linux kernel drivers are recommended. + + Cards with known instability issues: + + * Intel series E810 (driver `ice`). + * Intel series 500 (driver `ixgbe`). * If the `knotd` service is not directly executed in the privileged mode, some additional Linux capabilities have to be set: diff --git a/doc/reference.rst b/doc/reference.rst index 6cb42f3..1aefc57 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -20,9 +20,10 @@ the following symbols: - ``STR`` – Textual string - ``HEXSTR`` – Hexadecimal string (with ``0x`` prefix) - ``BOOL`` – Boolean value (``on``/``off`` or ``true``/``false``) -- ``TIME`` – Number of seconds, an integer with possible time multiplier suffix - (``s`` ~ 1, ``m`` ~ 60, ``h`` ~ 3600 or ``d`` ~ 24 * 3600) -- ``SIZE`` – Number of bytes, an integer with possible size multiplier suffix +- ``TIME`` – Number of seconds, an integer with a possible time multiplier suffix + (``s`` ~ 1, ``m`` ~ 60, ``h`` ~ 3600, ``d`` ~ 24 * 3600, ``w`` ~ 7 * 24 * 3600, + ``M`` ~ 30 * 24 * 3600, ``y`` ~ 365 * 24 * 3600) +- ``SIZE`` – Number of bytes, an integer with a possible size multiplier suffix (``B`` ~ 1, ``K`` ~ 1024, ``M`` ~ 1024^2 or ``G`` ~ 1024^3) - ``BASE64`` – Base64 encoded string - ``ADDR`` – IPv4 or IPv6 address @@ -217,6 +218,7 @@ General options related to the server. dbus-init-delay: TIME listen: ADDR[@INT] | STR ... listen-quic: ADDR[@INT] ... + listen-tls: ADDR[@INT] ... .. CAUTION:: When you change configuration parameters dynamically or via configuration file @@ -561,12 +563,10 @@ Maximum EDNS0 UDP payload size for IPv6. key-file -------- -Path to a server key PEM file which is used for DNS over QUIC communication. +Path to a server key PEM file which is used for DNS over QUIC/TLS communication. A non-absolute path of a user specified key file is relative to the :file:`@config_dir@` directory. -Change of this parameter requires restart of the Knot server to take effect. - *Default:* auto-generated key .. _server_cert-file: @@ -574,11 +574,9 @@ Change of this parameter requires restart of the Knot server to take effect. cert-file --------- -Path to a server certificate PEM file which is used for DNS over QUIC communication. +Path to a server certificate PEM file which is used for DNS over QUIC/TLS communication. A non-absolute path is relative to the :file:`@config_dir@` directory. -Change of this parameter requires restart of the Knot server to take effect. - *Default:* one-time in-memory certificate .. _server_edns-client-subnet: @@ -646,16 +644,17 @@ Possible values: - ``stopped`` when the server shutdown sequence is initiated. - ``zone-updated`` – The signal ``zone_updated`` is emitted when a zone has been updated; the signal parameters are `zone name` and `zone SOA serial`. -- ``keys-updated`` - The signal ``keys_updated`` is emitted when a DNSSEC key set - of this zone is updated. +- ``keys-updated`` - The signal ``keys_updated`` is emitted when a DNSSEC key set + is updated; the signal parameter is `zone name`. - ``ksk-submission`` – The signal ``zone_ksk_submission`` is emitted if there is a ready KSK present when the zone is signed; the signal parameters are `zone name`, `KSK keytag`, and `KSK KASP id`. - ``dnssec-invalid`` – The signal ``zone_dnssec_invalid`` is emitted when DNSSEC - validation fails; the signal parameter is `zone name`. + validation fails; the signal parameters are `zone name`, and `remaining seconds` + until an RRSIG expires. .. NOTE:: - This function requires systemd version at least 221. + This function requires systemd version at least 221 or libdbus. Change of this parameter requires restart of the Knot server to take effect. @@ -704,9 +703,17 @@ Change of this parameter requires restart of the Knot server to take effect. *Default:* not set -.. NOTE:: - Incoming :ref:`DDNS` over QUIC isn't supported. - The server always responds with SERVFAIL. +.. _server_listen-tls: + +listen-tls +---------- + +One or more IP addresses (and optionally ports) where the server listens +for incoming queries over TLS protocol (DoT). + +Change of this parameter requires restart of the Knot server to take effect. + +*Default:* not set .. _xdp section: @@ -730,6 +737,9 @@ Various options related to XDP listening, especially TCP. tcp-idle-reset-timeout: TIME tcp-resend-timeout: TIME route-check: BOOL + ring-size: INT + busypoll-budget: INT + busypoll-timeout: INT .. CAUTION:: When you change configuration parameters dynamically or via configuration file @@ -912,6 +922,57 @@ Change of this parameter requires restart of the Knot server to take effect. *Default:* ``off`` +.. _xdp_ring-size: + +ring-size +--------- + +Size of RX, FQ, TX, and CQ rings. + +Change of this parameter requires restart of the Knot server to take effect. + +.. NOTE:: + This value should be at least as high as the configured RX size of the + network device in the XDP mode. + +*Default:* ``2048`` + +.. _xdp_busypoll-budget: + +busypoll-budget +--------------- + +If set to a positive value, preferred busy polling is enabled with the +specified budget. + +Change of this parameter requires restart of the Knot server to take effect. + +.. NOTE:: + + Preferred busy polling also requires setting ``napi_defer_hard_irqs`` and + ``gro_flush_timeout`` for the appropriate network interface. E.g.:: + + echo 2 | sudo tee /sys/class/net//napi_defer_hard_irqs + echo 200000 | sudo tee /sys/class/net//gro_flush_timeout + +.. NOTE:: + + A recommended value is between 8 and 64. + +*Default:* ``0`` (disabled) + +.. _xdp_busypoll-timeout: + +busypoll-timeout +---------------- + +Timeout in microseconds of preferrred busy polling if enabled by +:ref:`xdp_busypoll-budget`. + +Change of this parameter requires restart of the Knot server to take effect. + +*Default:* ``20`` (20 microseconds) + .. _control section: ``control`` section @@ -1378,6 +1439,7 @@ transfer, target for a notification, etc.). address: ADDR[@INT] | STR ... via: ADDR[@INT] ... quic: BOOL + tls: BOOL key: key_id cert-key: BASE64 ... block-notify-after-transfer: BOOL @@ -1459,6 +1521,16 @@ with this remote. *Default:* ``off`` +.. _remote_tls: + +tls +--- + +If this option is set, the TLS (DoT) protocol will be used for outgoing communication +with this remote. + +*Default:* ``off`` + .. _remote_key: key @@ -1955,8 +2027,6 @@ Possible values: - ``ed448`` .. NOTE:: - Ed25519 algorithm is only available if compiled with GnuTLS 3.6.0+. - Ed448 algorithm is only available if compiled with GnuTLS 3.6.12+ and Nettle 3.6+. *Default:* ``ecdsap256sha256`` @@ -2134,6 +2204,10 @@ resolvers' caches. *Default:* 0.1 * :ref:`policy_rrsig-lifetime` + :ref:`policy_propagation-delay` + :ref:`policy_zone-max-ttl` +If :ref:`zone_dnssec-validation` is enabled: + +*Default:* ``1d`` (1 day) + .. _policy_rrsig-pre-refresh: rrsig-pre-refresh @@ -2847,7 +2921,9 @@ List of DNSSEC checks: The validation is not affected by :ref:`zone_dnssec-policy` configuration, except for :ref:`policy_signing-threads` option, which specifies the number -of threads for parallel validation. +of threads for parallel validation, and :ref:`policy_rrsig-refresh`, which +defines minimal allowed remaining RRSIG validity (otherwise a warning is +logged). .. NOTE:: diff --git a/doc/requirements.rst b/doc/requirements.rst index 584afa2..6b25fc1 100644 --- a/doc/requirements.rst +++ b/doc/requirements.rst @@ -60,9 +60,9 @@ Required libraries Knot DNS requires a few libraries to be available: +* gnutls >= 3.6.10 * libedit -* gnutls >= 3.3 -* liburcu >= 0.5.4 +* liburcu * lmdb >= 0.9.15 .. NOTE:: @@ -72,9 +72,9 @@ Knot DNS requires a few libraries to be available: Optional libraries ================== -International Domain Names support (IDNA2008 or IDNA2003) in :doc:`kdig`: +International Domain Names support (IDNA2008) in :doc:`kdig`: -* libidn2 (or libidn) +* libidn2 Systemd's startup notification mechanism and journald logging: -- cgit v1.2.3