From 3b9b6d0b8e7f798023c9d109c490449d528fde80 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:59:48 +0200 Subject: Adding upstream version 1:9.18.19. Signed-off-by: Daniel Baumann --- doc/man/Makefile.am | 214 +++++++++ doc/man/Makefile.in | 1015 +++++++++++++++++++++++++++++++++++++++ doc/man/arpaname.1in | 48 ++ doc/man/arpaname.rst | 14 + doc/man/conf.py | 211 ++++++++ doc/man/ddns-confgen.8in | 112 +++++ doc/man/ddns-confgen.rst | 14 + doc/man/delv.1in | 411 ++++++++++++++++ doc/man/delv.rst | 14 + doc/man/dig.1in | 926 +++++++++++++++++++++++++++++++++++ doc/man/dig.rst | 14 + doc/man/dnssec-cds.1in | 256 ++++++++++ doc/man/dnssec-cds.rst | 14 + doc/man/dnssec-dsfromkey.1in | 177 +++++++ doc/man/dnssec-dsfromkey.rst | 14 + doc/man/dnssec-importkey.1in | 152 ++++++ doc/man/dnssec-importkey.rst | 14 + doc/man/dnssec-keyfromlabel.1in | 319 ++++++++++++ doc/man/dnssec-keyfromlabel.rst | 14 + doc/man/dnssec-keygen.1in | 389 +++++++++++++++ doc/man/dnssec-keygen.rst | 14 + doc/man/dnssec-revoke.1in | 97 ++++ doc/man/dnssec-revoke.rst | 14 + doc/man/dnssec-settime.1in | 296 ++++++++++++ doc/man/dnssec-settime.rst | 14 + doc/man/dnssec-signzone.1in | 515 ++++++++++++++++++++ doc/man/dnssec-signzone.rst | 14 + doc/man/dnssec-verify.1in | 128 +++++ doc/man/dnssec-verify.rst | 14 + doc/man/dnstap-read.1in | 73 +++ doc/man/dnstap-read.rst | 14 + doc/man/filter-a.8in | 106 ++++ doc/man/filter-a.rst | 14 + doc/man/filter-aaaa.8in | 110 +++++ doc/man/filter-aaaa.rst | 14 + doc/man/host.1in | 220 +++++++++ doc/man/host.rst | 14 + doc/man/index.rst | 10 + doc/man/mdig.1in | 436 +++++++++++++++++ doc/man/mdig.rst | 14 + doc/man/named-checkconf.1in | 128 +++++ doc/man/named-checkconf.rst | 14 + doc/man/named-checkzone.1in | 256 ++++++++++ doc/man/named-checkzone.rst | 14 + doc/man/named-compilezone.1in | 258 ++++++++++ doc/man/named-compilezone.rst | 14 + doc/man/named-journalprint.1in | 79 +++ doc/man/named-journalprint.rst | 14 + doc/man/named-nzd2nzf.1in | 57 +++ doc/man/named-nzd2nzf.rst | 14 + doc/man/named-rrchecker.1in | 78 +++ doc/man/named-rrchecker.rst | 14 + doc/man/named.8in | 299 ++++++++++++ doc/man/named.conf.5in | 1012 ++++++++++++++++++++++++++++++++++++++ doc/man/named.conf.rst | 14 + doc/man/named.rst | 14 + doc/man/nsec3hash.1in | 86 ++++ doc/man/nsec3hash.rst | 14 + doc/man/nslookup.1in | 225 +++++++++ doc/man/nslookup.rst | 14 + doc/man/nsupdate.1in | 437 +++++++++++++++++ doc/man/nsupdate.rst | 14 + doc/man/rndc-confgen.8in | 141 ++++++ doc/man/rndc-confgen.rst | 14 + doc/man/rndc.8in | 727 ++++++++++++++++++++++++++++ doc/man/rndc.conf.5in | 196 ++++++++ doc/man/rndc.conf.rst | 14 + doc/man/rndc.rst | 14 + doc/man/tsig-keygen.8in | 66 +++ doc/man/tsig-keygen.rst | 14 + 70 files changed, 10728 insertions(+) create mode 100644 doc/man/Makefile.am create mode 100644 doc/man/Makefile.in create mode 100644 doc/man/arpaname.1in create mode 100644 doc/man/arpaname.rst create mode 100644 doc/man/conf.py create mode 100644 doc/man/ddns-confgen.8in create mode 100644 doc/man/ddns-confgen.rst create mode 100644 doc/man/delv.1in create mode 100644 doc/man/delv.rst create mode 100644 doc/man/dig.1in create mode 100644 doc/man/dig.rst create mode 100644 doc/man/dnssec-cds.1in create mode 100644 doc/man/dnssec-cds.rst create mode 100644 doc/man/dnssec-dsfromkey.1in create mode 100644 doc/man/dnssec-dsfromkey.rst create mode 100644 doc/man/dnssec-importkey.1in create mode 100644 doc/man/dnssec-importkey.rst create mode 100644 doc/man/dnssec-keyfromlabel.1in create mode 100644 doc/man/dnssec-keyfromlabel.rst create mode 100644 doc/man/dnssec-keygen.1in create mode 100644 doc/man/dnssec-keygen.rst create mode 100644 doc/man/dnssec-revoke.1in create mode 100644 doc/man/dnssec-revoke.rst create mode 100644 doc/man/dnssec-settime.1in create mode 100644 doc/man/dnssec-settime.rst create mode 100644 doc/man/dnssec-signzone.1in create mode 100644 doc/man/dnssec-signzone.rst create mode 100644 doc/man/dnssec-verify.1in create mode 100644 doc/man/dnssec-verify.rst create mode 100644 doc/man/dnstap-read.1in create mode 100644 doc/man/dnstap-read.rst create mode 100644 doc/man/filter-a.8in create mode 100644 doc/man/filter-a.rst create mode 100644 doc/man/filter-aaaa.8in create mode 100644 doc/man/filter-aaaa.rst create mode 100644 doc/man/host.1in create mode 100644 doc/man/host.rst create mode 100644 doc/man/index.rst create mode 100644 doc/man/mdig.1in create mode 100644 doc/man/mdig.rst create mode 100644 doc/man/named-checkconf.1in create mode 100644 doc/man/named-checkconf.rst create mode 100644 doc/man/named-checkzone.1in create mode 100644 doc/man/named-checkzone.rst create mode 100644 doc/man/named-compilezone.1in create mode 100644 doc/man/named-compilezone.rst create mode 100644 doc/man/named-journalprint.1in create mode 100644 doc/man/named-journalprint.rst create mode 100644 doc/man/named-nzd2nzf.1in create mode 100644 doc/man/named-nzd2nzf.rst create mode 100644 doc/man/named-rrchecker.1in create mode 100644 doc/man/named-rrchecker.rst create mode 100644 doc/man/named.8in create mode 100644 doc/man/named.conf.5in create mode 100644 doc/man/named.conf.rst create mode 100644 doc/man/named.rst create mode 100644 doc/man/nsec3hash.1in create mode 100644 doc/man/nsec3hash.rst create mode 100644 doc/man/nslookup.1in create mode 100644 doc/man/nslookup.rst create mode 100644 doc/man/nsupdate.1in create mode 100644 doc/man/nsupdate.rst create mode 100644 doc/man/rndc-confgen.8in create mode 100644 doc/man/rndc-confgen.rst create mode 100644 doc/man/rndc.8in create mode 100644 doc/man/rndc.conf.5in create mode 100644 doc/man/rndc.conf.rst create mode 100644 doc/man/rndc.rst create mode 100644 doc/man/tsig-keygen.8in create mode 100644 doc/man/tsig-keygen.rst (limited to 'doc/man') diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am new file mode 100644 index 0000000..d814b02 --- /dev/null +++ b/doc/man/Makefile.am @@ -0,0 +1,214 @@ +include $(top_srcdir)/Makefile.top +include $(top_srcdir)/Makefile.docs + +MANPAGES_RST = \ + arpaname.rst \ + delv.rst \ + dig.rst \ + ddns-confgen.rst \ + dnssec-cds.rst \ + dnssec-dsfromkey.rst \ + dnssec-importkey.rst \ + dnssec-keyfromlabel.rst \ + dnssec-keygen.rst \ + dnssec-revoke.rst \ + dnssec-settime.rst \ + dnssec-signzone.rst \ + dnssec-verify.rst \ + dnstap-read.rst \ + filter-aaaa.rst \ + filter-a.rst \ + host.rst \ + index.rst \ + mdig.rst \ + named-checkconf.rst \ + named-checkzone.rst \ + named-compilezone.rst \ + named-journalprint.rst \ + named-nzd2nzf.rst \ + named-rrchecker.rst \ + named.conf.rst \ + named.rst \ + nsec3hash.rst \ + nslookup.rst \ + nsupdate.rst \ + rndc-confgen.rst \ + rndc.conf.rst \ + rndc.rst \ + tsig-keygen.rst \ + ../../bin/check/named-checkconf.rst \ + ../../bin/check/named-checkzone.rst \ + ../../bin/check/named-compilezone.rst \ + ../../bin/confgen/ddns-confgen.rst \ + ../../bin/confgen/rndc-confgen.rst \ + ../../bin/confgen/tsig-keygen.rst \ + ../../bin/delv/delv.rst \ + ../../bin/dig/dig.rst \ + ../../bin/dig/host.rst \ + ../../bin/dig/nslookup.rst \ + ../../bin/dnssec/dnssec-cds.rst \ + ../../bin/dnssec/dnssec-dsfromkey.rst \ + ../../bin/dnssec/dnssec-importkey.rst \ + ../../bin/dnssec/dnssec-keyfromlabel.rst \ + ../../bin/dnssec/dnssec-keygen.rst \ + ../../bin/dnssec/dnssec-revoke.rst \ + ../../bin/dnssec/dnssec-settime.rst \ + ../../bin/dnssec/dnssec-signzone.rst \ + ../../bin/dnssec/dnssec-verify.rst \ + ../../bin/named/named.conf.rst \ + ../../bin/named/named.rst \ + ../../bin/nsupdate/nsupdate.rst \ + ../../bin/plugins/filter-aaaa.rst \ + ../../bin/plugins/filter-a.rst \ + ../../bin/rndc/rndc.conf.rst \ + ../../bin/rndc/rndc.rst \ + ../../bin/tools/arpaname.rst \ + ../../bin/tools/dnstap-read.rst \ + ../../bin/tools/mdig.rst \ + ../../bin/tools/named-journalprint.rst \ + ../../bin/tools/named-nzd2nzf.rst \ + ../../bin/tools/named-rrchecker.rst \ + ../../bin/tools/nsec3hash.rst + +man_MANS = \ + arpaname.1 \ + ddns-confgen.8 \ + delv.1 \ + dig.1 \ + host.1 \ + mdig.1 \ + named-rrchecker.1 \ + nslookup.1 \ + nsupdate.1 \ + named.conf.5 \ + rndc.conf.5 \ + dnssec-cds.1 \ + dnssec-dsfromkey.1 \ + dnssec-importkey.1 \ + dnssec-keyfromlabel.1 \ + dnssec-keygen.1 \ + dnssec-revoke.1 \ + dnssec-settime.1 \ + dnssec-signzone.1 \ + dnssec-verify.1 \ + filter-aaaa.8 \ + filter-a.8 \ + named-checkconf.1 \ + named-checkzone.1 \ + named-compilezone.1 \ + named-journalprint.1 \ + named.8 \ + nsec3hash.1 \ + rndc-confgen.8 \ + rndc.8 \ + tsig-keygen.8 + +if HAVE_DNSTAP +man_MANS += \ + dnstap-read.1 +endif HAVE_DNSTAP + +if HAVE_LMDB +man_MANS += \ + named-nzd2nzf.1 +endif HAVE_LMDB + +MANPAGES_IN = \ + $(man_MANS:=in) \ + dnstap-read.1in \ + named-nzd2nzf.1in + +EXTRA_DIST = \ + conf.py \ + $(MANPAGES_RST) \ + $(MANPAGES_IN) + +CLEANFILES = \ + $(man_MANS) + +# +# Build rules for pre-generated manpages +# + +man_SUBST = \ + $(AM_V_SED)$(SED) \ + -e 's,[@]PACKAGE_VERSION@,$(PACKAGE_VERSION),' \ + -e 's,[@]RELEASE_DATE@,$(RELEASE_DATE),' \ + -e 's,[@]libdir[@],$(libdir),g' \ + -e 's,[@]runstatedir[@],$(runstatedir),g' \ + -e 's,[@]sysconfdir[@],$(sysconfdir),g' \ + $(srcdir)/$@in >$@ + +.1in.1: + $(man_SUBST) + +.5in.5: + $(man_SUBST) + +.8in.8: + $(man_SUBST) + +.NOTPARALLEL: man +man: Makefile $(man_MANS) + +doc-local: man + +clean-local:: + -rm -rf $(SPHINXBUILDDIR) + + +CLEANFILES += \ + manpages.stamp + +if MAINTAINER_MODE + +MAINTAINERCLEANFILES = \ + $(MANPAGES_IN) + +endif MAINTAINER_MODE + +# +# Build rules for generating pre-generated manpages +# + +if HAVE_SPHINX_BUILD +# +# See https://www.gnu.org/software/automake/manual/html_node/Multiple-Outputs.html +# +manpages.stamp: $(MANPAGES_RST) + @rm -f manpages.tmp + @touch manpages.tmp + echo "${man_RST_EPILOG}" + $(AM_V_SPHINX)$(SPHINX_BUILD) -b man -d $(SPHINXBUILDDIR)/.doctrees/man $(man_SPHINXOPTS) $(SPHINXBUILDDIR)/man + for f in $(SPHINXBUILDDIR)/man/*; do \ + cp -a "$$f" "$(srcdir)/$$(basename $$f)in"; \ + done + @mv -f manpages.tmp $@ + +$(MANPAGES_IN): manpages.stamp +## Recover from the removal of $@ + @dry=; for f in x $$MAKEFLAGS; do \ + case $$f in \ + *=*|--*);; \ + *n*) dry=:;; \ + esac; \ + done; \ + if test -f $@; then :; else \ + $$dry trap 'rm -rf manpages.lock manpages.stamp' 1 2 13 15; \ + if $$dry mkdir manpages.lock 2>/dev/null; then \ +## This code is being executed by the first process. + $$dry rm -f manpages.stamp; \ + $(MAKE) $(AM_MAKEFLAGS) manpages.stamp; \ + $$dry rmdir manpages.lock; \ + else \ +## This code is being executed by the follower processes. +## Wait until the first process is done. + while test -d manpages.lock && test -z "$$dry"; do \ + sleep 1; \ + done; \ +## Succeed if and only if the first process succeeded. + $$dry test -f manpages.stamp; exit $$?; \ + fi; \ + fi + +endif HAVE_SPHINX_BUILD diff --git a/doc/man/Makefile.in b/doc/man/Makefile.in new file mode 100644 index 0000000..a853924 --- /dev/null +++ b/doc/man/Makefile.in @@ -0,0 +1,1015 @@ +# Makefile.in generated by automake 1.16.5 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2021 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# Hey Emacs, this is -*- makefile-automake -*- file! +# vim: filetype=automake +VPATH = @srcdir@ +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +target_triplet = @target@ +@HOST_MACOS_TRUE@am__append_1 = \ +@HOST_MACOS_TRUE@ -Wl,-flat_namespace + +@HAVE_DNSTAP_TRUE@am__append_2 = \ +@HAVE_DNSTAP_TRUE@ dnstap-read.1 + +@HAVE_LMDB_TRUE@am__append_3 = \ +@HAVE_LMDB_TRUE@ named-nzd2nzf.1 + +subdir = doc/man +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/ax_check_compile_flag.m4 \ + $(top_srcdir)/m4/ax_check_link_flag.m4 \ + $(top_srcdir)/m4/ax_check_openssl.m4 \ + $(top_srcdir)/m4/ax_gcc_func_attribute.m4 \ + $(top_srcdir)/m4/ax_jemalloc.m4 \ + $(top_srcdir)/m4/ax_lib_lmdb.m4 \ + $(top_srcdir)/m4/ax_perl_module.m4 \ + $(top_srcdir)/m4/ax_posix_shell.m4 \ + $(top_srcdir)/m4/ax_prog_cc_for_build.m4 \ + $(top_srcdir)/m4/ax_pthread.m4 \ + $(top_srcdir)/m4/ax_python_module.m4 \ + $(top_srcdir)/m4/ax_restore_flags.m4 \ + $(top_srcdir)/m4/ax_save_flags.m4 $(top_srcdir)/m4/ax_tls.m4 \ + $(top_srcdir)/m4/libtool.m4 $(top_srcdir)/m4/ltoptions.m4 \ + $(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \ + $(top_srcdir)/m4/lt~obsolete.m4 $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } +man1dir = $(mandir)/man1 +am__installdirs = "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man5dir)" \ + "$(DESTDIR)$(man8dir)" +man5dir = $(mandir)/man5 +man8dir = $(mandir)/man8 +NROFF = nroff +MANS = $(man_MANS) +am__extra_recursive_targets = test-recursive unit-recursive \ + doc-recursive +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(srcdir)/Makefile.in $(top_srcdir)/Makefile.docs \ + $(top_srcdir)/Makefile.top +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BUILD_EXEEXT = @BUILD_EXEEXT@ +BUILD_OBJEXT = @BUILD_OBJEXT@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CC_FOR_BUILD = @CC_FOR_BUILD@ +CFLAGS = @CFLAGS@ +CFLAGS_FOR_BUILD = @CFLAGS_FOR_BUILD@ +CMOCKA_CFLAGS = @CMOCKA_CFLAGS@ +CMOCKA_LIBS = @CMOCKA_LIBS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CPPFLAGS_FOR_BUILD = @CPPFLAGS_FOR_BUILD@ +CPP_FOR_BUILD = @CPP_FOR_BUILD@ +CSCOPE = @CSCOPE@ +CTAGS = @CTAGS@ +CURL = @CURL@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DEVELOPER_MODE = @DEVELOPER_MODE@ +DLLTOOL = @DLLTOOL@ +DNSTAP_CFLAGS = @DNSTAP_CFLAGS@ +DNSTAP_LIBS = @DNSTAP_LIBS@ +DOXYGEN = @DOXYGEN@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +ETAGS = @ETAGS@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +FILECMD = @FILECMD@ +FSTRM_CAPTURE = @FSTRM_CAPTURE@ +FUZZ_LDFLAGS = @FUZZ_LDFLAGS@ +FUZZ_LOG_COMPILER = @FUZZ_LOG_COMPILER@ +GREP = @GREP@ +GSSAPI_CFLAGS = @GSSAPI_CFLAGS@ +GSSAPI_LIBS = @GSSAPI_LIBS@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +JEMALLOC_CFLAGS = @JEMALLOC_CFLAGS@ +JEMALLOC_LIBS = @JEMALLOC_LIBS@ +JSON_C_CFLAGS = @JSON_C_CFLAGS@ +JSON_C_LIBS = @JSON_C_LIBS@ +KRB5_CFLAGS = @KRB5_CFLAGS@ +KRB5_CONFIG = @KRB5_CONFIG@ +KRB5_LIBS = @KRB5_LIBS@ +LATEXMK = @LATEXMK@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LDFLAGS_FOR_BUILD = @LDFLAGS_FOR_BUILD@ +LIBCAP_LIBS = @LIBCAP_LIBS@ +LIBIDN2_CFLAGS = @LIBIDN2_CFLAGS@ +LIBIDN2_LIBS = @LIBIDN2_LIBS@ +LIBNGHTTP2_CFLAGS = @LIBNGHTTP2_CFLAGS@ +LIBNGHTTP2_LIBS = @LIBNGHTTP2_LIBS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIBUV_CFLAGS = @LIBUV_CFLAGS@ +LIBUV_LIBS = @LIBUV_LIBS@ +LIBXML2_CFLAGS = @LIBXML2_CFLAGS@ +LIBXML2_LIBS = @LIBXML2_LIBS@ +LIPO = @LIPO@ +LMDB_CFLAGS = @LMDB_CFLAGS@ +LMDB_LIBS = @LMDB_LIBS@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MAXMINDDB_CFLAGS = @MAXMINDDB_CFLAGS@ +MAXMINDDB_LIBS = @MAXMINDDB_LIBS@ +MAXMINDDB_PREFIX = @MAXMINDDB_PREFIX@ +MKDIR_P = @MKDIR_P@ +NC = @NC@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OPENSSL_CFLAGS = @OPENSSL_CFLAGS@ +OPENSSL_LDFLAGS = @OPENSSL_LDFLAGS@ +OPENSSL_LIBS = @OPENSSL_LIBS@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PKG_CONFIG = @PKG_CONFIG@ +PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ +PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ +PROTOC_C = @PROTOC_C@ +PTHREAD_CC = @PTHREAD_CC@ +PTHREAD_CFLAGS = @PTHREAD_CFLAGS@ +PTHREAD_CXX = @PTHREAD_CXX@ +PTHREAD_LIBS = @PTHREAD_LIBS@ +PYTEST = @PYTEST@ +PYTHON = @PYTHON@ +PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_PLATFORM = @PYTHON_PLATFORM@ +PYTHON_PREFIX = @PYTHON_PREFIX@ +PYTHON_VERSION = @PYTHON_VERSION@ +RANLIB = @RANLIB@ +READLINE_CFLAGS = @READLINE_CFLAGS@ +READLINE_LIBS = @READLINE_LIBS@ +RELEASE_DATE = @RELEASE_DATE@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SPHINX_BUILD = @SPHINX_BUILD@ +STD_CFLAGS = @STD_CFLAGS@ +STD_CPPFLAGS = @STD_CPPFLAGS@ +STD_LDFLAGS = @STD_LDFLAGS@ +STRIP = @STRIP@ +TEST_CFLAGS = @TEST_CFLAGS@ +VERSION = @VERSION@ +XELATEX = @XELATEX@ +XSLTPROC = @XSLTPROC@ +ZLIB_CFLAGS = @ZLIB_CFLAGS@ +ZLIB_LIBS = @ZLIB_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CC_FOR_BUILD = @ac_ct_CC_FOR_BUILD@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +ax_pthread_config = @ax_pthread_config@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +pkgpyexecdir = @pkgpyexecdir@ +pkgpythondir = @pkgpythondir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +pyexecdir = @pyexecdir@ +pythondir = @pythondir@ +runstatedir = @runstatedir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target = @target@ +target_alias = @target_alias@ +target_cpu = @target_cpu@ +target_os = @target_os@ +target_vendor = @target_vendor@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +ACLOCAL_AMFLAGS = -I $(top_srcdir)/m4 +AM_CFLAGS = \ + $(STD_CFLAGS) + +AM_CPPFLAGS = \ + $(STD_CPPFLAGS) \ + -include $(top_builddir)/config.h \ + -I$(srcdir)/include + +AM_LDFLAGS = $(STD_LDFLAGS) $(am__append_1) +LDADD = +LIBISC_CFLAGS = \ + -I$(top_srcdir)/include \ + -I$(top_srcdir)/lib/isc/include \ + -I$(top_builddir)/lib/isc/include + +LIBISC_LIBS = $(top_builddir)/lib/isc/libisc.la +LIBDNS_CFLAGS = \ + -I$(top_srcdir)/lib/dns/include \ + -I$(top_builddir)/lib/dns/include + +LIBDNS_LIBS = \ + $(top_builddir)/lib/dns/libdns.la + +LIBNS_CFLAGS = \ + -I$(top_srcdir)/lib/ns/include + +LIBNS_LIBS = \ + $(top_builddir)/lib/ns/libns.la + +LIBIRS_CFLAGS = \ + -I$(top_srcdir)/lib/irs/include + +LIBIRS_LIBS = \ + $(top_builddir)/lib/irs/libirs.la + +LIBISCCFG_CFLAGS = \ + -I$(top_srcdir)/lib/isccfg/include + +LIBISCCFG_LIBS = \ + $(top_builddir)/lib/isccfg/libisccfg.la + +LIBISCCC_CFLAGS = \ + -I$(top_srcdir)/lib/isccc/include/ + +LIBISCCC_LIBS = \ + $(top_builddir)/lib/isccc/libisccc.la + +LIBBIND9_CFLAGS = \ + -I$(top_srcdir)/lib/bind9/include + +LIBBIND9_LIBS = \ + $(top_builddir)/lib/bind9/libbind9.la + +SPHINX_V = $(SPHINX_V_@AM_V@) +SPHINX_V_ = $(SPHINX_V_@AM_DEFAULT_V@) +SPHINX_V_0 = -q +SPHINX_V_1 = -n +SPHINX_W = -W +AM_V_SPHINX = $(AM_V_SPHINX_@AM_V@) +AM_V_SPHINX_ = $(AM_V_SPHINX_@AM_DEFAULT_V@) +AM_V_SPHINX_0 = @echo " SPHINX $@"; +SPHINXBUILDDIR = $(builddir)/_build +LF = \n +RNDC_CONF = .. |rndc_conf| replace:: ``$(sysconfdir)/rndc.conf`` +RNDC_KEY = .. |rndc_key| replace:: ``$(sysconfdir)/rndc.key`` +NAMED_CONF = .. |named_conf| replace:: ``$(sysconfdir)/named.conf`` +BIND_KEYS = .. |bind_keys| replace:: ``$(sysconfdir)/bind.keys`` +NAMED_PID = .. |named_pid| replace:: ``$(runstatedir)/named.pid`` +SESSION_KEY = .. |session_key| replace:: ``$(runstatedir)/session.key`` +common_SPHINXOPTS = \ + $(SPHINX_W) \ + -c $(srcdir) \ + -a \ + $(SPHINX_V) + + +# The "today" variable set below is not directly used in the ARM, but its value +# is implicitly inserted on the title page of the PDF file produced by Sphinx. +ALLSPHINXOPTS = \ + $(common_SPHINXOPTS) \ + -D today="$(RELEASE_DATE)" \ + -D rst_epilog="$$(printf "$${RST_EPILOG}")" \ + $(SPHINXOPTS) \ + $(srcdir) + +_ = @ +man_RNDC_CONF = .. |rndc_conf| replace:: ``$(_)sysconfdir$(_)/rndc.conf`` +man_RNDC_KEY = .. |rndc_key| replace:: ``$(_)sysconfdir$(_)/rndc.key`` +man_NAMED_CONF = .. |named_conf| replace:: ``$(_)sysconfdir$(_)/named.conf`` +man_BIND_KEYS = .. |bind_keys| replace:: ``$(_)sysconfdir$(_)/bind.keys`` +man_NAMED_PID = .. |named_pid| replace:: ``$(_)runstatedir$(_)/named.pid`` +man_SESSION_KEY = .. |session_key| replace:: ``$(_)runstatedir$(_)/session.key`` +man_SPHINXOPTS = \ + $(common_SPHINXOPTS) \ + -D version="@""PACKAGE_VERSION@" \ + -D today="@""RELEASE_DATE@" \ + -D release="@""PACKAGE_VERSION@" \ + -D rst_epilog="$$(printf "$${man_RST_EPILOG}")" \ + $(SPHINXOPTS) \ + $(srcdir) + +AM_V_SED = $(AM_V_SED_@AM_V@) +AM_V_SED_ = $(AM_V_SED_@AM_DEFAULT_V@) +AM_V_SED_0 = @echo " SED $@"; +AM_V_CFG_TEST = $(AM_V_CFG_TEST_@AM_V@) +AM_V_CFG_TEST_ = $(AM_V_CFG_TEST_@AM_DEFAULT_V@) +AM_V_CFG_TEST_0 = @echo " CFG_GEN $@"; +MANPAGES_RST = \ + arpaname.rst \ + delv.rst \ + dig.rst \ + ddns-confgen.rst \ + dnssec-cds.rst \ + dnssec-dsfromkey.rst \ + dnssec-importkey.rst \ + dnssec-keyfromlabel.rst \ + dnssec-keygen.rst \ + dnssec-revoke.rst \ + dnssec-settime.rst \ + dnssec-signzone.rst \ + dnssec-verify.rst \ + dnstap-read.rst \ + filter-aaaa.rst \ + filter-a.rst \ + host.rst \ + index.rst \ + mdig.rst \ + named-checkconf.rst \ + named-checkzone.rst \ + named-compilezone.rst \ + named-journalprint.rst \ + named-nzd2nzf.rst \ + named-rrchecker.rst \ + named.conf.rst \ + named.rst \ + nsec3hash.rst \ + nslookup.rst \ + nsupdate.rst \ + rndc-confgen.rst \ + rndc.conf.rst \ + rndc.rst \ + tsig-keygen.rst \ + ../../bin/check/named-checkconf.rst \ + ../../bin/check/named-checkzone.rst \ + ../../bin/check/named-compilezone.rst \ + ../../bin/confgen/ddns-confgen.rst \ + ../../bin/confgen/rndc-confgen.rst \ + ../../bin/confgen/tsig-keygen.rst \ + ../../bin/delv/delv.rst \ + ../../bin/dig/dig.rst \ + ../../bin/dig/host.rst \ + ../../bin/dig/nslookup.rst \ + ../../bin/dnssec/dnssec-cds.rst \ + ../../bin/dnssec/dnssec-dsfromkey.rst \ + ../../bin/dnssec/dnssec-importkey.rst \ + ../../bin/dnssec/dnssec-keyfromlabel.rst \ + ../../bin/dnssec/dnssec-keygen.rst \ + ../../bin/dnssec/dnssec-revoke.rst \ + ../../bin/dnssec/dnssec-settime.rst \ + ../../bin/dnssec/dnssec-signzone.rst \ + ../../bin/dnssec/dnssec-verify.rst \ + ../../bin/named/named.conf.rst \ + ../../bin/named/named.rst \ + ../../bin/nsupdate/nsupdate.rst \ + ../../bin/plugins/filter-aaaa.rst \ + ../../bin/plugins/filter-a.rst \ + ../../bin/rndc/rndc.conf.rst \ + ../../bin/rndc/rndc.rst \ + ../../bin/tools/arpaname.rst \ + ../../bin/tools/dnstap-read.rst \ + ../../bin/tools/mdig.rst \ + ../../bin/tools/named-journalprint.rst \ + ../../bin/tools/named-nzd2nzf.rst \ + ../../bin/tools/named-rrchecker.rst \ + ../../bin/tools/nsec3hash.rst + +man_MANS = arpaname.1 ddns-confgen.8 delv.1 dig.1 host.1 mdig.1 \ + named-rrchecker.1 nslookup.1 nsupdate.1 named.conf.5 \ + rndc.conf.5 dnssec-cds.1 dnssec-dsfromkey.1 dnssec-importkey.1 \ + dnssec-keyfromlabel.1 dnssec-keygen.1 dnssec-revoke.1 \ + dnssec-settime.1 dnssec-signzone.1 dnssec-verify.1 \ + filter-aaaa.8 filter-a.8 named-checkconf.1 named-checkzone.1 \ + named-compilezone.1 named-journalprint.1 named.8 nsec3hash.1 \ + rndc-confgen.8 rndc.8 tsig-keygen.8 $(am__append_2) \ + $(am__append_3) +MANPAGES_IN = \ + $(man_MANS:=in) \ + dnstap-read.1in \ + named-nzd2nzf.1in + +EXTRA_DIST = \ + conf.py \ + $(MANPAGES_RST) \ + $(MANPAGES_IN) + +CLEANFILES = $(man_MANS) manpages.stamp + +# +# Build rules for pre-generated manpages +# +man_SUBST = \ + $(AM_V_SED)$(SED) \ + -e 's,[@]PACKAGE_VERSION@,$(PACKAGE_VERSION),' \ + -e 's,[@]RELEASE_DATE@,$(RELEASE_DATE),' \ + -e 's,[@]libdir[@],$(libdir),g' \ + -e 's,[@]runstatedir[@],$(runstatedir),g' \ + -e 's,[@]sysconfdir[@],$(sysconfdir),g' \ + $(srcdir)/$@in >$@ + +@MAINTAINER_MODE_TRUE@MAINTAINERCLEANFILES = \ +@MAINTAINER_MODE_TRUE@ $(MANPAGES_IN) + +@HAVE_SPHINX_BUILD_TRUE@@dry = ; for f in x $$MAKEFLAGS; do \ +@HAVE_SPHINX_BUILD_TRUE@ case $$f in \ +@HAVE_SPHINX_BUILD_TRUE@ *=*|--*);; \ +@HAVE_SPHINX_BUILD_TRUE@ *n*) dry=:;; \ +@HAVE_SPHINX_BUILD_TRUE@ esac; \ +@HAVE_SPHINX_BUILD_TRUE@ done; \ +@HAVE_SPHINX_BUILD_TRUE@ if test -f $@; then :; else \ +@HAVE_SPHINX_BUILD_TRUE@ $$dry trap 'rm -rf manpages.lock manpages.stamp' 1 2 13 15; \ +@HAVE_SPHINX_BUILD_TRUE@ if $$dry mkdir manpages.lock 2>/dev/null; then \ +@HAVE_SPHINX_BUILD_TRUE@ $$dry rm -f manpages.stamp; \ +@HAVE_SPHINX_BUILD_TRUE@ $(MAKE) $(AM_MAKEFLAGS) manpages.stamp; \ +@HAVE_SPHINX_BUILD_TRUE@ $$dry rmdir manpages.lock; \ +@HAVE_SPHINX_BUILD_TRUE@ else \ +@HAVE_SPHINX_BUILD_TRUE@ while test -d manpages.lock && test -z "$$dry"; do \ +@HAVE_SPHINX_BUILD_TRUE@ sleep 1; \ +@HAVE_SPHINX_BUILD_TRUE@ done; \ +@HAVE_SPHINX_BUILD_TRUE@ $$dry test -f manpages.stamp; exit $$?; \ +@HAVE_SPHINX_BUILD_TRUE@ fi; \ +@HAVE_SPHINX_BUILD_TRUE@ fi + +all: all-am + +.SUFFIXES: +.SUFFIXES: .1 .1in .5 .5in .8 .8in +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/Makefile.top $(top_srcdir)/Makefile.docs $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/man/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign doc/man/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \ + esac; +$(top_srcdir)/Makefile.top $(top_srcdir)/Makefile.docs $(am__empty): + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-man1: $(man_MANS) + @$(NORMAL_INSTALL) + @list1=''; \ + list2='$(man_MANS)'; \ + test -n "$(man1dir)" \ + && test -n "`echo $$list1$$list2`" \ + || exit 0; \ + echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \ + { for i in $$list1; do echo "$$i"; done; \ + if test -n "$$list2"; then \ + for i in $$list2; do echo "$$i"; done \ + | sed -n '/\.1[a-z]*$$/p'; \ + fi; \ + } | while read p; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; echo "$$p"; \ + done | \ + sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \ + sed 'N;N;s,\n, ,g' | { \ + list=; while read file base inst; do \ + if test "$$base" = "$$inst"; then list="$$list $$file"; else \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \ + fi; \ + done; \ + for i in $$list; do echo "$$i"; done | $(am__base_list) | \ + while read files; do \ + test -z "$$files" || { \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \ + done; } + +uninstall-man1: + @$(NORMAL_UNINSTALL) + @list=''; test -n "$(man1dir)" || exit 0; \ + files=`{ for i in $$list; do echo "$$i"; done; \ + l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.1[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir) +install-man5: $(man_MANS) + @$(NORMAL_INSTALL) + @list1=''; \ + list2='$(man_MANS)'; \ + test -n "$(man5dir)" \ + && test -n "`echo $$list1$$list2`" \ + || exit 0; \ + echo " $(MKDIR_P) '$(DESTDIR)$(man5dir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(man5dir)" || exit 1; \ + { for i in $$list1; do echo "$$i"; done; \ + if test -n "$$list2"; then \ + for i in $$list2; do echo "$$i"; done \ + | sed -n '/\.5[a-z]*$$/p'; \ + fi; \ + } | while read p; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; echo "$$p"; \ + done | \ + sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^5][0-9a-z]*$$,5,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \ + sed 'N;N;s,\n, ,g' | { \ + list=; while read file base inst; do \ + if test "$$base" = "$$inst"; then list="$$list $$file"; else \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man5dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man5dir)/$$inst" || exit $$?; \ + fi; \ + done; \ + for i in $$list; do echo "$$i"; done | $(am__base_list) | \ + while read files; do \ + test -z "$$files" || { \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man5dir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(man5dir)" || exit $$?; }; \ + done; } + +uninstall-man5: + @$(NORMAL_UNINSTALL) + @list=''; test -n "$(man5dir)" || exit 0; \ + files=`{ for i in $$list; do echo "$$i"; done; \ + l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.5[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^5][0-9a-z]*$$,5,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + dir='$(DESTDIR)$(man5dir)'; $(am__uninstall_files_from_dir) +install-man8: $(man_MANS) + @$(NORMAL_INSTALL) + @list1=''; \ + list2='$(man_MANS)'; \ + test -n "$(man8dir)" \ + && test -n "`echo $$list1$$list2`" \ + || exit 0; \ + echo " $(MKDIR_P) '$(DESTDIR)$(man8dir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(man8dir)" || exit 1; \ + { for i in $$list1; do echo "$$i"; done; \ + if test -n "$$list2"; then \ + for i in $$list2; do echo "$$i"; done \ + | sed -n '/\.8[a-z]*$$/p'; \ + fi; \ + } | while read p; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; echo "$$p"; \ + done | \ + sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^8][0-9a-z]*$$,8,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \ + sed 'N;N;s,\n, ,g' | { \ + list=; while read file base inst; do \ + if test "$$base" = "$$inst"; then list="$$list $$file"; else \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man8dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man8dir)/$$inst" || exit $$?; \ + fi; \ + done; \ + for i in $$list; do echo "$$i"; done | $(am__base_list) | \ + while read files; do \ + test -z "$$files" || { \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man8dir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(man8dir)" || exit $$?; }; \ + done; } + +uninstall-man8: + @$(NORMAL_UNINSTALL) + @list=''; test -n "$(man8dir)" || exit 0; \ + files=`{ for i in $$list; do echo "$$i"; done; \ + l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.8[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^8][0-9a-z]*$$,8,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + dir='$(DESTDIR)$(man8dir)'; $(am__uninstall_files_from_dir) +test-local: +unit-local: +doc-local: +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + +distdir: $(BUILT_SOURCES) + $(MAKE) $(AM_MAKEFLAGS) distdir-am + +distdir-am: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(MANS) +installdirs: + for dir in "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man5dir)" "$(DESTDIR)$(man8dir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." + -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES) +clean: clean-am + +clean-am: clean-generic clean-libtool clean-local mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +doc: doc-am + +doc-am: doc-local + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: install-man + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: install-man1 install-man5 install-man8 + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +test: test-am + +test-am: test-local + +uninstall-am: uninstall-man + +uninstall-man: uninstall-man1 uninstall-man5 uninstall-man8 + +unit: unit-am + +unit-am: unit-local + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + clean-local cscopelist-am ctags-am distclean distclean-generic \ + distclean-libtool distdir doc-am doc-local dvi dvi-am html \ + html-am 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-info \ + install-info-am install-man install-man1 install-man5 \ + install-man8 install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs maintainer-clean maintainer-clean-generic \ + mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \ + ps ps-am tags-am test-am test-local uninstall uninstall-am \ + uninstall-man uninstall-man1 uninstall-man5 uninstall-man8 \ + unit-am unit-local + +.PRECIOUS: Makefile + + +export RST_EPILOG = $(RNDC_CONF)$(LF)$(RNDC_KEY)$(LF)$(NAMED_CONF)$(LF)$(BIND_KEYS)$(LF)$(NAMED_PID)$(LF)$(SESSION_KEY) + +export man_RST_EPILOG = $(man_RNDC_CONF)$(LF)$(man_RNDC_KEY)$(LF)$(man_NAMED_CONF)$(LF)$(man_BIND_KEYS)$(LF)$(man_NAMED_PID)$(LF)$(man_SESSION_KEY) + +.1in.1: + $(man_SUBST) + +.5in.5: + $(man_SUBST) + +.8in.8: + $(man_SUBST) + +.NOTPARALLEL: man +man: Makefile $(man_MANS) + +doc-local: man + +clean-local:: + -rm -rf $(SPHINXBUILDDIR) + +# +# Build rules for generating pre-generated manpages +# + +# +# See https://www.gnu.org/software/automake/manual/html_node/Multiple-Outputs.html +# +@HAVE_SPHINX_BUILD_TRUE@manpages.stamp: $(MANPAGES_RST) +@HAVE_SPHINX_BUILD_TRUE@ @rm -f manpages.tmp +@HAVE_SPHINX_BUILD_TRUE@ @touch manpages.tmp +@HAVE_SPHINX_BUILD_TRUE@ echo "${man_RST_EPILOG}" +@HAVE_SPHINX_BUILD_TRUE@ $(AM_V_SPHINX)$(SPHINX_BUILD) -b man -d $(SPHINXBUILDDIR)/.doctrees/man $(man_SPHINXOPTS) $(SPHINXBUILDDIR)/man +@HAVE_SPHINX_BUILD_TRUE@ for f in $(SPHINXBUILDDIR)/man/*; do \ +@HAVE_SPHINX_BUILD_TRUE@ cp -a "$$f" "$(srcdir)/$$(basename $$f)in"; \ +@HAVE_SPHINX_BUILD_TRUE@ done +@HAVE_SPHINX_BUILD_TRUE@ @mv -f manpages.tmp $@ + +@HAVE_SPHINX_BUILD_TRUE@$(MANPAGES_IN): manpages.stamp + +# 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. +.NOEXPORT: diff --git a/doc/man/arpaname.1in b/doc/man/arpaname.1in new file mode 100644 index 0000000..e9b6515 --- /dev/null +++ b/doc/man/arpaname.1in @@ -0,0 +1,48 @@ +.\" 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 "ARPANAME" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +arpaname \- translate IP addresses to the corresponding ARPA names +.SH SYNOPSIS +.sp +\fBarpaname\fP {\fIipaddress\fP ...} +.SH DESCRIPTION +.sp +\fBarpaname\fP translates IP addresses (IPv4 and IPv6) to the +corresponding IN\-ADDR.ARPA or IP6.ARPA names. +.SH SEE ALSO +.sp +BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/arpaname.rst b/doc/man/arpaname.rst new file mode 100644 index 0000000..52d69b6 --- /dev/null +++ b/doc/man/arpaname.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/tools/arpaname.rst diff --git a/doc/man/conf.py b/doc/man/conf.py new file mode 100644 index 0000000..0f4ba58 --- /dev/null +++ b/doc/man/conf.py @@ -0,0 +1,211 @@ +############################################################################ +# Copyright (C) Internet Systems Consortium, Inc. ("ISC") +# +# SPDX-License-Identifier: MPL-2.0 +# +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, you can obtain one at https://mozilla.org/MPL/2.0/. +# +# See the COPYRIGHT file distributed with this work for additional +# information regarding copyright ownership. +############################################################################ + +# +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +# -- Project information ----------------------------------------------------- + +project = "BIND 9" +# pylint: disable=wrong-import-position +import datetime + +year = datetime.datetime.now().year +# pylint: disable=redefined-builtin +copyright = "%d, Internet Systems Consortium" % year +author = "Internet Systems Consortium" + +# -- General configuration --------------------------------------------------- + +# Build man pages directly in _build/man/, not in _build/man/
/. +# This is what the shell code in Makefile.am expects. +man_make_section_directory = False + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["../arm/_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", +] + +# The master toctree document. +master_doc = "index" + +# pylint: disable=line-too-long +man_pages = [ + ( + "arpaname", + "arpaname", + "translate IP addresses to the corresponding ARPA names", + author, + 1, + ), + ("ddns-confgen", "ddns-confgen", "ddns key generation tool", author, 8), + ("delv", "delv", "DNS lookup and validation utility", author, 1), + ("dig", "dig", "DNS lookup utility", author, 1), + ( + "dnssec-cds", + "dnssec-cds", + "change DS records for a child zone based on CDS/CDNSKEY", + author, + 1, + ), + ("dnssec-dsfromkey", "dnssec-dsfromkey", "DNSSEC DS RR generation tool", author, 1), + ( + "dnssec-importkey", + "dnssec-importkey", + "import DNSKEY records from external systems so they can be managed", + author, + 1, + ), + ( + "dnssec-keyfromlabel", + "dnssec-keyfromlabel", + "DNSSEC key generation tool", + author, + 1, + ), + ("dnssec-keygen", "dnssec-keygen", "DNSSEC key generation tool", author, 1), + ( + "dnssec-revoke", + "dnssec-revoke", + "set the REVOKED bit on a DNSSEC key", + author, + 1, + ), + ( + "dnssec-settime", + "dnssec-settime", + "set the key timing metadata for a DNSSEC key", + author, + 1, + ), + ("dnssec-signzone", "dnssec-signzone", "DNSSEC zone signing tool", author, 1), + ("dnssec-verify", "dnssec-verify", "DNSSEC zone verification tool", author, 1), + ( + "dnstap-read", + "dnstap-read", + "print dnstap data in human-readable form", + author, + 1, + ), + ( + "filter-aaaa", + "filter-aaaa", + "filter AAAA in DNS responses when A is present", + author, + 8, + ), + ( + "filter-a", + "filter-a", + "filter A in DNS responses when AAAA is present", + author, + 8, + ), + ("host", "host", "DNS lookup utility", author, 1), + ("mdig", "mdig", "DNS pipelined lookup utility", author, 1), + ( + "named-checkconf", + "named-checkconf", + "named configuration file syntax checking tool", + author, + 1, + ), + ( + "named-checkzone", + "named-checkzone", + "zone file validity checking or converting tool", + author, + 1, + ), + ( + "named-compilezone", + "named-compilezone", + "zone file validity checking or converting tool", + author, + 1, + ), + ( + "named-journalprint", + "named-journalprint", + "print zone journal in human-readable form", + author, + 1, + ), + ( + "named-nzd2nzf", + "named-nzd2nzf", + "convert an NZD database to NZF text format", + author, + 1, + ), + ( + "named-rrchecker", + "named-rrchecker", + "syntax checker for individual DNS resource records", + author, + 1, + ), + ("named.conf", "named.conf", "configuration file for **named**", author, 5), + ("named", "named", "Internet domain name server", author, 8), + ("nsec3hash", "nsec3hash", "generate NSEC3 hash", author, 1), + ("nslookup", "nslookup", "query Internet name servers interactively", author, 1), + ("nsupdate", "nsupdate", "dynamic DNS update utility", author, 1), + ("rndc-confgen", "rndc-confgen", "rndc key generation tool", author, 8), + ("rndc.conf", "rndc.conf", "rndc configuration file", author, 5), + ("rndc", "rndc", "name server control utility", author, 8), + ("tsig-keygen", "tsig-keygen", "TSIG key generation tool", author, 8), +] + +# +# The rst_epilog will be completely overwritten from the Makefile, +# the definition here is provided purely for situations when +# sphinx-build is run by hand. +# +rst_epilog = """ +.. |rndc_conf| replace:: ``@sysconfdir@/rndc.conf`` +.. |rndc_key| replace:: ``@sysconfdir@/rndc.key`` +.. |named_conf| replace:: ``@sysconfdir@/named.conf`` +.. |bind_keys| replace:: ``@sysconfdir@/bind.keys`` +.. |named_pid| replace:: ``@runstatedir@/named.pid`` +.. |session_key| replace:: ``@runstatedir@/session.key`` +""" + + +def setup(app): + app.add_crossref_type("iscman", "iscman", "pair: %s; manual page") diff --git a/doc/man/ddns-confgen.8in b/doc/man/ddns-confgen.8in new file mode 100644 index 0000000..e2a963d --- /dev/null +++ b/doc/man/ddns-confgen.8in @@ -0,0 +1,112 @@ +.\" 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 "DDNS-CONFGEN" "8" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +ddns-confgen \- ddns key generation tool +.SH SYNOPSIS +.sp +\fBddns\-confgen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [\fB\-k\fP keyname] [\fB\-q\fP] [\fB\-s\fP name] [\fB\-z\fP zone] +.SH DESCRIPTION +.sp +\fBddns\-confgen\fP is an utility that generates keys for use in TSIG signing. +The resulting keys can be used, for example, to secure dynamic DNS updates +to a zone, or for the \fI\%rndc\fP command channel. +.sp +The key name can specified using \fI\%\-k\fP parameter and defaults to \fBddns\-key\fP\&. +The generated key is accompanied by configuration text and instructions that +can be used with \fI\%nsupdate\fP and \fI\%named\fP when setting up dynamic DNS, +including an example \fBupdate\-policy\fP statement. +(This usage is similar to the \fI\%rndc\-confgen\fP command for setting up +command\-channel security.) +.sp +Note that \fI\%named\fP itself can configure a local DDNS key for use with +\fI\%nsupdate \-l\fP; it does this when a zone is configured with +\fBupdate\-policy local;\fP\&. \fBddns\-confgen\fP is only needed when a more +elaborate configuration is required: for instance, if \fI\%nsupdate\fP is to +be used from a remote system. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-a algorithm +This option specifies the algorithm to use for the TSIG key. Available +choices are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, +and hmac\-sha512. The default is hmac\-sha256. Options are +case\-insensitive, and the \(dqhmac\-\(dq prefix may be omitted. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option prints a short summary of options and arguments. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k keyname +This option specifies the key name of the DDNS authentication key. The +default is \fBddns\-key\fP when neither the \fI\%\-s\fP nor \fI\%\-z\fP option is +specified; otherwise, the default is \fBddns\-key\fP as a separate label +followed by the argument of the option, e.g., \fBddns\-key.example.com.\fP +The key name must have the format of a valid domain name, consisting of +letters, digits, hyphens, and periods. +.UNINDENT +.INDENT 0.0 +.TP +.B \-q +This option enables quiet mode, which prints only the key, with no +explanatory text or usage examples. This is essentially identical to +\fI\%tsig\-keygen\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s name +This option generates a configuration example to allow dynamic updates +of a single hostname. The example \fI\%named.conf\fP text shows how to set +an update policy for the specified name using the \(dqname\(dq nametype. The +default key name is \fBddns\-key.name\fP\&. Note that the \(dqself\(dq nametype +cannot be used, since the name to be updated may differ from the key +name. This option cannot be used with the \fI\%\-z\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-z zone +This option generates a configuration example to allow +dynamic updates of a zone. The example \fI\%named.conf\fP text shows how +to set an update policy for the specified zone using the \(dqzonesub\(dq +nametype, allowing updates to all subdomain names within that zone. +This option cannot be used with the \fI\%\-s\fP option. +.UNINDENT +.SH SEE ALSO +.sp +\fI\%nsupdate(1)\fP, \fI\%named.conf(5)\fP, \fI\%named(8)\fP, BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/ddns-confgen.rst b/doc/man/ddns-confgen.rst new file mode 100644 index 0000000..891102f --- /dev/null +++ b/doc/man/ddns-confgen.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/confgen/ddns-confgen.rst diff --git a/doc/man/delv.1in b/doc/man/delv.1in new file mode 100644 index 0000000..05d626c --- /dev/null +++ b/doc/man/delv.1in @@ -0,0 +1,411 @@ +.\" 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 "DELV" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +delv \- DNS lookup and validation utility +.SH SYNOPSIS +.sp +\fBdelv\fP [@server] [ [\fB\-4\fP] | [\fB\-6\fP] ] [\fB\-a\fP anchor\-file] [\fB\-b\fP address] [\fB\-c\fP class] [\fB\-d\fP level] [\fB\-i\fP] [\fB\-m\fP] [\fB\-p\fP port#] [\fB\-q\fP name] [\fB\-t\fP type] [\fB\-x\fP addr] [name] [type] [class] [queryopt...] +.sp +\fBdelv\fP [\fB\-h\fP] +.sp +\fBdelv\fP [\fB\-v\fP] +.sp +\fBdelv\fP [queryopt...] [query...] +.SH DESCRIPTION +.sp +\fBdelv\fP is a tool for sending DNS queries and validating the results, +using the same internal resolver and validator logic as \fI\%named\fP\&. +.sp +\fBdelv\fP sends to a specified name server all queries needed to +fetch and validate the requested data; this includes the original +requested query, subsequent queries to follow CNAME or DNAME chains, +queries for DNSKEY, and DS records to establish a chain of trust for +DNSSEC validation. It does not perform iterative resolution, but +simulates the behavior of a name server configured for DNSSEC validating +and forwarding. +.sp +By default, responses are validated using the built\-in DNSSEC trust anchor +for the root zone (\(dq.\(dq). Records returned by \fBdelv\fP are either fully +validated or were not signed. If validation fails, an explanation of the +failure is included in the output; the validation process can be traced +in detail. Because \fBdelv\fP does not rely on an external server to carry +out validation, it can be used to check the validity of DNS responses in +environments where local name servers may not be trustworthy. +.sp +Unless it is told to query a specific name server, \fBdelv\fP tries +each of the servers listed in \fB/etc/resolv.conf\fP\&. If no usable server +addresses are found, \fBdelv\fP sends queries to the localhost +addresses (127.0.0.1 for IPv4, ::1 for IPv6). +.sp +When no command\-line arguments or options are given, \fBdelv\fP +performs an NS query for \(dq.\(dq (the root zone). +.SH SIMPLE USAGE +.sp +A typical invocation of \fBdelv\fP looks like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +delv @server name type +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +where: +.INDENT 0.0 +.TP +.B server +is the name or IP address of the name server to query. This can be an +IPv4 address in dotted\-decimal notation or an IPv6 address in +colon\-delimited notation. When the supplied \fBserver\fP argument is a +hostname, \fBdelv\fP resolves that name before querying that name +server (note, however, that this initial lookup is \fInot\fP validated by +DNSSEC). +.sp +If no \fBserver\fP argument is provided, \fBdelv\fP consults +\fB/etc/resolv.conf\fP; if an address is found there, it queries the +name server at that address. If either of the \fI\%\-4\fP or \fI\%\-6\fP +options is in use, then only addresses for the corresponding +transport are tried. If no usable addresses are found, \fBdelv\fP +sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1 +for IPv6). +.UNINDENT +.INDENT 0.0 +.TP +.B name +is the domain name to be looked up. +.UNINDENT +.INDENT 0.0 +.TP +.B type +indicates what type of query is required \- ANY, A, MX, etc. +\fBtype\fP can be any valid query type. If no \fBtype\fP argument is +supplied, \fBdelv\fP performs a lookup for an A record. +.UNINDENT +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-a anchor\-file +This option specifies a file from which to read DNSSEC trust anchors. The default +is \fB@sysconfdir@/bind.keys\fP, which is included with BIND 9 and contains one +or more trust anchors for the root zone (\(dq.\(dq). +.sp +Keys that do not match the root zone name are ignored. An alternate +key name can be specified using the \fI\%+root\fP option. +.sp +Note: When reading the trust anchor file, \fBdelv\fP treats \fBtrust\-anchors\fP, +\fBinitial\-key\fP, and \fBstatic\-key\fP identically. That is, for a managed key, +it is the \fIinitial\fP key that is trusted; \fI\%RFC 5011\fP key management is not +supported. \fBdelv\fP does not consult the managed\-keys database maintained by +\fI\%named\fP, which means that if either of the keys in \fB@sysconfdir@/bind.keys\fP is +revoked and rolled over, \fB@sysconfdir@/bind.keys\fP must be updated to +use DNSSEC validation in \fBdelv\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-b address +This option sets the source IP address of the query to \fBaddress\fP\&. This must be +a valid address on one of the host\(aqs network interfaces, or \fB0.0.0.0\fP, +or \fB::\fP\&. An optional source port may be specified by appending +\fB#\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-c class +This option sets the query class for the requested data. Currently, only class +\(dqIN\(dq is supported in \fBdelv\fP and any other value is ignored. +.UNINDENT +.INDENT 0.0 +.TP +.B \-d level +This option sets the systemwide debug level to \fBlevel\fP\&. The allowed range is +from 0 to 99. The default is 0 (no debugging). Debugging traces from +\fBdelv\fP become more verbose as the debug level increases. See the +\fI\%+mtrace\fP, \fI\%+rtrace\fP, and \fI\%+vtrace\fP options below for +additional debugging details. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option displays the \fBdelv\fP help usage output and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i +This option sets insecure mode, which disables internal DNSSEC validation. (Note, +however, that this does not set the CD bit on upstream queries. If the +server being queried is performing DNSSEC validation, then it does +not return invalid data; this can cause \fBdelv\fP to time out. When it +is necessary to examine invalid data to debug a DNSSEC problem, use +\fI\%dig +cd\fP\&.) +.UNINDENT +.INDENT 0.0 +.TP +.B \-m +This option enables memory usage debugging. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p port# +This option specifies a destination port to use for queries, instead of the +standard DNS port number 53. This option is used with a name +server that has been configured to listen for queries on a +non\-standard port number. +.UNINDENT +.INDENT 0.0 +.TP +.B \-q name +This option sets the query name to \fBname\fP\&. While the query name can be +specified without using the \fI\%\-q\fP option, it is sometimes necessary to +disambiguate names from types or classes (for example, when looking +up the name \(dqns\(dq, which could be misinterpreted as the type NS, or +\(dqch\(dq, which could be misinterpreted as class CH). +.UNINDENT +.INDENT 0.0 +.TP +.B \-t type +This option sets the query type to \fBtype\fP, which can be any valid query type +supported in BIND 9 except for zone transfer types AXFR and IXFR. As +with \fI\%\-q\fP, this is useful to distinguish query\-name types or classes +when they are ambiguous. It is sometimes necessary to disambiguate +names from types. +.sp +The default query type is \(dqA\(dq, unless the \fI\%\-x\fP option is supplied +to indicate a reverse lookup, in which case it is \(dqPTR\(dq. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v +This option prints the \fBdelv\fP version and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-x addr +This option performs a reverse lookup, mapping an address to a name. \fBaddr\fP +is an IPv4 address in dotted\-decimal notation, or a colon\-delimited +IPv6 address. When \fI\%\-x\fP is used, there is no need to provide the +\fBname\fP or \fBtype\fP arguments; \fBdelv\fP automatically performs a +lookup for a name like \fB11.12.13.10.in\-addr.arpa\fP and sets the +query type to PTR. IPv6 addresses are looked up using nibble format +under the IP6.ARPA domain. +.UNINDENT +.INDENT 0.0 +.TP +.B \-4 +This option forces \fBdelv\fP to only use IPv4. +.UNINDENT +.INDENT 0.0 +.TP +.B \-6 +This option forces \fBdelv\fP to only use IPv6. +.UNINDENT +.SH QUERY OPTIONS +.sp +\fBdelv\fP provides a number of query options which affect the way results +are displayed, and in some cases the way lookups are performed. +.sp +Each query option is identified by a keyword preceded by a plus sign +(\fB+\fP). Some keywords set or reset an option. These may be preceded by +the string \fBno\fP to negate the meaning of that keyword. Other keywords +assign values to options like the timeout interval. They have the form +\fB+keyword=value\fP\&. The query options are: +.INDENT 0.0 +.TP +.B +cdflag, +nocdflag +This option controls whether to set the CD (checking disabled) bit in queries +sent by \fBdelv\fP\&. This may be useful when troubleshooting DNSSEC +problems from behind a validating resolver. A validating resolver +blocks invalid responses, making it difficult to retrieve them +for analysis. Setting the CD flag on queries causes the resolver +to return invalid responses, which \fBdelv\fP can then validate +internally and report the errors in detail. +.UNINDENT +.INDENT 0.0 +.TP +.B +class, +noclass +This option controls whether to display the CLASS when printing a record. The +default is to display the CLASS. +.UNINDENT +.INDENT 0.0 +.TP +.B +ttl, +nottl +This option controls whether to display the TTL when printing a record. The +default is to display the TTL. +.UNINDENT +.INDENT 0.0 +.TP +.B +rtrace, +nortrace +This option toggles resolver fetch logging. This reports the name and type of each +query sent by \fBdelv\fP in the process of carrying out the resolution +and validation process, including the original query +and all subsequent queries to follow CNAMEs and to establish a chain +of trust for DNSSEC validation. +.sp +This is equivalent to setting the debug level to 1 in the \(dqresolver\(dq +logging category. Setting the systemwide debug level to 1 using the +\fI\%\-d\fP option produces the same output, but affects other +logging categories as well. +.UNINDENT +.INDENT 0.0 +.TP +.B +mtrace, +nomtrace +This option toggles message logging. This produces a detailed dump of the +responses received by \fBdelv\fP in the process of carrying out the +resolution and validation process. +.sp +This is equivalent to setting the debug level to 10 for the \(dqpackets\(dq +module of the \(dqresolver\(dq logging category. Setting the systemwide +debug level to 10 using the \fI\%\-d\fP option produces the same +output, but affects other logging categories as well. +.UNINDENT +.INDENT 0.0 +.TP +.B +vtrace, +novtrace +This option toggles validation logging. This shows the internal process of the +validator as it determines whether an answer is validly signed, +unsigned, or invalid. +.sp +This is equivalent to setting the debug level to 3 for the +\(dqvalidator\(dq module of the \(dqdnssec\(dq logging category. Setting the +systemwide debug level to 3 using the \fI\%\-d\fP option produces the +same output, but affects other logging categories as well. +.UNINDENT +.INDENT 0.0 +.TP +.B +short, +noshort +This option toggles between verbose and terse answers. The default is to print the answer in a +verbose form. +.UNINDENT +.INDENT 0.0 +.TP +.B +comments, +nocomments +This option toggles the display of comment lines in the output. The default is to +print comments. +.UNINDENT +.INDENT 0.0 +.TP +.B +rrcomments, +norrcomments +This option toggles the display of per\-record comments in the output (for example, +human\-readable key information about DNSKEY records). The default is +to print per\-record comments. +.UNINDENT +.INDENT 0.0 +.TP +.B +crypto, +nocrypto +This option toggles the display of cryptographic fields in DNSSEC records. The +contents of these fields are unnecessary to debug most DNSSEC +validation failures and removing them makes it easier to see the +common failures. The default is to display the fields. When omitted, +they are replaced by the string \fB[omitted]\fP or, in the DNSKEY case, the +key ID is displayed as the replacement, e.g. \fB[ key id = value ]\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +trust, +notrust +This option controls whether to display the trust level when printing a record. +The default is to display the trust level. +.UNINDENT +.INDENT 0.0 +.TP +.B +split[=W], +nosplit +This option splits long hex\- or base64\-formatted fields in resource records into +chunks of \fBW\fP characters (where \fBW\fP is rounded up to the nearest +multiple of 4). \fB+nosplit\fP or \fB+split=0\fP causes fields not to be +split at all. The default is 56 characters, or 44 characters when +multiline mode is active. +.UNINDENT +.INDENT 0.0 +.TP +.B +all, +noall +This option sets or clears the display options \fI\%+comments\fP, +\fI\%+rrcomments\fP, and \fI\%+trust\fP as a group. +.UNINDENT +.INDENT 0.0 +.TP +.B +multiline, +nomultiline +This option prints long records (such as RRSIG, DNSKEY, and SOA records) in a +verbose multi\-line format with human\-readable comments. The default +is to print each record on a single line, to facilitate machine +parsing of the \fBdelv\fP output. +.UNINDENT +.INDENT 0.0 +.TP +.B +dnssec, +nodnssec +This option indicates whether to display RRSIG records in the \fBdelv\fP output. +The default is to do so. Note that (unlike in \fI\%dig\fP) this does +\fInot\fP control whether to request DNSSEC records or to +validate them. DNSSEC records are always requested, and validation +always occurs unless suppressed by the use of \fI\%\-i\fP or +\fI\%+noroot\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +root[=ROOT], +noroot +This option indicates whether to perform conventional DNSSEC validation, and if so, +specifies the name of a trust anchor. The default is to validate using a +trust anchor of \(dq.\(dq (the root zone), for which there is a built\-in key. If +specifying a different trust anchor, then \fI\%\-a\fP must be used to specify a +file containing the key. +.UNINDENT +.INDENT 0.0 +.TP +.B +tcp, +notcp +This option controls whether to use TCP when sending queries. The default is to +use UDP unless a truncated response has been received. +.UNINDENT +.INDENT 0.0 +.TP +.B +unknownformat, +nounknownformat +This option prints all RDATA in unknown RR\-type presentation format (\fI\%RFC 3597\fP). +The default is to print RDATA for known types in the type\(aqs +presentation format. +.UNINDENT +.INDENT 0.0 +.TP +.B +yaml, +noyaml +This option prints response data in YAML format. +.UNINDENT +.SH FILES +.sp +\fB@sysconfdir@/bind.keys\fP +.sp +\fB/etc/resolv.conf\fP +.SH SEE ALSO +.sp +\fI\%dig(1)\fP, \fI\%named(8)\fP, \fI\%RFC 4034\fP, \fI\%RFC 4035\fP, \fI\%RFC 4431\fP, \fI\%RFC 5074\fP, \fI\%RFC 5155\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/delv.rst b/doc/man/delv.rst new file mode 100644 index 0000000..8f3b548 --- /dev/null +++ b/doc/man/delv.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/delv/delv.rst diff --git a/doc/man/dig.1in b/doc/man/dig.1in new file mode 100644 index 0000000..62154ab --- /dev/null +++ b/doc/man/dig.1in @@ -0,0 +1,926 @@ +.\" 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 "DIG" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dig \- DNS lookup utility +.SH SYNOPSIS +.sp +\fBdig\fP [@server] [\fB\-b\fP address] [\fB\-c\fP class] [\fB\-f\fP filename] [\fB\-k\fP filename] [\fB\-m\fP] [\fB\-p\fP port#] [\fB\-q\fP name] [\fB\-t\fP type] [\fB\-v\fP] [\fB\-x\fP addr] [\fB\-y\fP [hmac:]name:key] [ [\fB\-4\fP] | [\fB\-6\fP] ] [name] [type] [class] [queryopt...] +.sp +\fBdig\fP [\fB\-h\fP] +.sp +\fBdig\fP [global\-queryopt...] [query...] +.SH DESCRIPTION +.sp +\fBdig\fP is a flexible tool for interrogating DNS name servers. It +performs DNS lookups and displays the answers that are returned from the +name server(s) that were queried. Most DNS administrators use \fBdig\fP to +troubleshoot DNS problems because of its flexibility, ease of use, and +clarity of output. Other lookup tools tend to have less functionality +than \fBdig\fP\&. +.sp +Although \fBdig\fP is normally used with command\-line arguments, it also +has a batch mode of operation for reading lookup requests from a file. A +brief summary of its command\-line arguments and options is printed when +the \fI\%\-h\fP option is given. The BIND 9 +implementation of \fBdig\fP allows multiple lookups to be issued from the +command line. +.sp +Unless it is told to query a specific name server, \fBdig\fP tries each +of the servers listed in \fB/etc/resolv.conf\fP\&. If no usable server +addresses are found, \fBdig\fP sends the query to the local host. +.sp +When no command\-line arguments or options are given, \fBdig\fP +performs an NS query for \(dq.\(dq (the root). +.sp +It is possible to set per\-user defaults for \fBdig\fP via +\fB${HOME}/.digrc\fP\&. This file is read and any options in it are applied +before the command\-line arguments. The \fI\%\-r\fP option disables this +feature, for scripts that need predictable behavior. +.sp +The IN and CH class names overlap with the IN and CH top\-level domain +names. Either use the \fI\%\-t\fP and \fI\%\-c\fP options to specify the type and +class, use the \fI\%\-q\fP to specify the domain name, or use \(dqIN.\(dq and +\(dqCH.\(dq when looking up these top\-level domains. +.SH SIMPLE USAGE +.sp +A typical invocation of \fBdig\fP looks like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +dig @server name type +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +where: +.INDENT 0.0 +.TP +.B server +is the name or IP address of the name server to query. This can be an +IPv4 address in dotted\-decimal notation or an IPv6 address in +colon\-delimited notation. When the supplied \fBserver\fP argument is a +hostname, \fBdig\fP resolves that name before querying that name +server. +.sp +If no \fBserver\fP argument is provided, \fBdig\fP consults +\fB/etc/resolv.conf\fP; if an address is found there, it queries the +name server at that address. If either of the \fI\%\-4\fP or \fI\%\-6\fP +options are in use, then only addresses for the corresponding +transport are tried. If no usable addresses are found, \fBdig\fP +sends the query to the local host. The reply from the name server +that responds is displayed. +.UNINDENT +.INDENT 0.0 +.TP +.B name +is the name of the resource record that is to be looked up. +.UNINDENT +.INDENT 0.0 +.TP +.B type +indicates what type of query is required \- ANY, A, MX, SIG, etc. +\fBtype\fP can be any valid query type. If no \fBtype\fP argument is +supplied, \fBdig\fP performs a lookup for an A record. +.UNINDENT +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-4 +This option indicates that only IPv4 should be used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-6 +This option indicates that only IPv6 should be used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-b address[#port] +This option sets the source IP address of the query. The \fBaddress\fP must be a +valid address on one of the host\(aqs network interfaces, or \(dq0.0.0.0\(dq +or \(dq::\(dq. An optional port may be specified by appending \fB#port\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c class +This option sets the query class. The default \fBclass\fP is IN; other classes are +HS for Hesiod records or CH for Chaosnet records. +.UNINDENT +.INDENT 0.0 +.TP +.B \-f file +This option sets batch mode, in which \fBdig\fP reads a list of lookup requests to process from +the given \fBfile\fP\&. Each line in the file should be organized in the +same way it would be presented as a query to \fBdig\fP using the +command\-line interface. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +Print a usage summary. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k keyfile +This option tells \fBdig\fP to sign queries using TSIG or +SIG(0) using a key read from the given file. Key files can be +generated using \fI\%tsig\-keygen\fP\&. When using TSIG authentication +with \fBdig\fP, the name server that is queried needs to +know the key and algorithm that is being used. In BIND, this is +done by providing appropriate \fBkey\fP and \fBserver\fP statements +in \fI\%named.conf\fP for TSIG and by looking up the KEY record +in zone data for SIG(0). +.UNINDENT +.INDENT 0.0 +.TP +.B \-m +This option enables memory usage debugging. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p port +This option sends the query to a non\-standard port on the server, instead of the +default port 53. This option is used to test a name server that +has been configured to listen for queries on a non\-standard port +number. +.UNINDENT +.INDENT 0.0 +.TP +.B \-q name +This option specifies the domain name to query. This is useful to distinguish the \fBname\fP +from other arguments. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r +This option indicates that options from \fB${HOME}/.digrc\fP should not be read. This is useful for +scripts that need predictable behavior. +.UNINDENT +.INDENT 0.0 +.TP +.B \-t type +This option indicates the resource record type to query, which can be any valid query type. If +it is a resource record type supported in BIND 9, it can be given by +the type mnemonic (such as \fBNS\fP or \fBAAAA\fP). The default query type is +\fBA\fP, unless the \fI\%\-x\fP option is supplied to indicate a reverse +lookup. A zone transfer can be requested by specifying a type of +AXFR. When an incremental zone transfer (IXFR) is required, set the +\fBtype\fP to \fBixfr=N\fP\&. The incremental zone transfer contains +all changes made to the zone since the serial number in the zone\(aqs +SOA record was \fBN\fP\&. +.sp +All resource record types can be expressed as \fBTYPEnn\fP, where \fBnn\fP is +the number of the type. If the resource record type is not supported +in BIND 9, the result is displayed as described in \fI\%RFC 3597\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-u +This option indicates that print query times should be provided in microseconds instead of milliseconds. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v +This option prints the version number and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-x addr +This option sets simplified reverse lookups, for mapping addresses to names. The +\fBaddr\fP is an IPv4 address in dotted\-decimal notation, or a +colon\-delimited IPv6 address. When the \fI\%\-x\fP option is used, there is no +need to provide the \fBname\fP, \fBclass\fP, and \fBtype\fP arguments. +\fBdig\fP automatically performs a lookup for a name like +\fB94.2.0.192.in\-addr.arpa\fP and sets the query type and class to PTR +and IN respectively. IPv6 addresses are looked up using nibble format +under the IP6.ARPA domain. +.UNINDENT +.INDENT 0.0 +.TP +.B \-y [hmac:]keyname:secret +This option signs queries using TSIG with the given authentication key. +\fBkeyname\fP is the name of the key, and \fBsecret\fP is the +base64\-encoded shared secret. \fBhmac\fP is the name of the key algorithm; +valid choices are \fBhmac\-md5\fP, \fBhmac\-sha1\fP, \fBhmac\-sha224\fP, +\fBhmac\-sha256\fP, \fBhmac\-sha384\fP, or \fBhmac\-sha512\fP\&. If \fBhmac\fP is +not specified, the default is \fBhmac\-md5\fP; if MD5 was disabled, the default is +\fBhmac\-sha256\fP\&. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Only the \fI\%\-k\fP option should be used, rather than the \fI\%\-y\fP option, +because with \fI\%\-y\fP the shared secret is supplied as a command\-line +argument in clear text. This may be visible in the output from \fBps1\fP or +in a history file maintained by the user\(aqs shell. +.UNINDENT +.UNINDENT +.SH QUERY OPTIONS +.sp +\fBdig\fP provides a number of query options which affect the way in which +lookups are made and the results displayed. Some of these set or reset +flag bits in the query header, some determine which sections of the +answer get printed, and others determine the timeout and retry +strategies. +.sp +Each query option is identified by a keyword preceded by a plus sign +(\fB+\fP). Some keywords set or reset an option; these may be preceded by +the string \fBno\fP to negate the meaning of that keyword. Other keywords +assign values to options, like the timeout interval. They have the form +\fB+keyword=value\fP\&. Keywords may be abbreviated, provided the +abbreviation is unambiguous; for example, \fI\%+cd\fP is equivalent to +\fI\%+cdflag\fP\&. The query options are: +.INDENT 0.0 +.TP +.B +aaflag, +noaaflag +This option is a synonym for \fI\%+aaonly\fP, \fI\%+noaaonly\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +aaonly, +noaaonly +This option sets the \fBaa\fP flag in the query. +.UNINDENT +.INDENT 0.0 +.TP +.B +additional, +noadditional +This option displays [or does not display] the additional section of a reply. The +default is to display it. +.UNINDENT +.INDENT 0.0 +.TP +.B +adflag, +noadflag +This option sets [or does not set] the AD (authentic data) bit in the query. This +requests the server to return whether all of the answer and authority +sections have been validated as secure, according to the security +policy of the server. \fBAD=1\fP indicates that all records have been +validated as secure and the answer is not from a OPT\-OUT range. \fBAD=0\fP +indicates that some part of the answer was insecure or not validated. +This bit is set by default. +.UNINDENT +.INDENT 0.0 +.TP +.B +all, +noall +This option sets or clears all display flags. +.UNINDENT +.INDENT 0.0 +.TP +.B +answer, +noanswer +This option displays [or does not display] the answer section of a reply. The default +is to display it. +.UNINDENT +.INDENT 0.0 +.TP +.B +authority, +noauthority +This option displays [or does not display] the authority section of a reply. The +default is to display it. +.UNINDENT +.INDENT 0.0 +.TP +.B +badcookie, +nobadcookie +This option retries the lookup with a new server cookie if a BADCOOKIE response is +received. +.UNINDENT +.INDENT 0.0 +.TP +.B +besteffort, +nobesteffort +This option attempts to display the contents of messages which are malformed. The +default is to not display malformed answers. +.UNINDENT +.INDENT 0.0 +.TP +.B +bufsize[=B] +This option sets the UDP message buffer size advertised using EDNS0 to +\fBB\fP bytes. The maximum and minimum sizes of this buffer are 65535 and +0, respectively. \fB+bufsize\fP restores the default buffer size. +.UNINDENT +.INDENT 0.0 +.TP +.B +cd, +cdflag, +nocdflag +This option sets [or does not set] the CD (checking disabled) bit in the query. This +requests the server to not perform DNSSEC validation of responses. +.UNINDENT +.INDENT 0.0 +.TP +.B +class, +noclass +This option displays [or does not display] the CLASS when printing the record. +.UNINDENT +.INDENT 0.0 +.TP +.B +cmd, +nocmd +This option toggles the printing of the initial comment in the output, identifying the +version of \fBdig\fP and the query options that have been applied. This option +always has a global effect; it cannot be set globally and then overridden on a +per\-lookup basis. The default is to print this comment. +.UNINDENT +.INDENT 0.0 +.TP +.B +comments, +nocomments +This option toggles the display of some comment lines in the output, with +information about the packet header and OPT pseudosection, and the names of +the response section. The default is to print these comments. +.sp +Other types of comments in the output are not affected by this option, but +can be controlled using other command\-line switches. These include +\fI\%+cmd\fP, \fI\%+question\fP, \fI\%+stats\fP, and \fI\%+rrcomments\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +cookie=####, +nocookie +This option sends [or does not send] a COOKIE EDNS option, with an optional value. Replaying a COOKIE +from a previous response allows the server to identify a previous +client. The default is \fB+cookie\fP\&. +.sp +\fB+cookie\fP is also set when \fI\%+trace\fP is set to better emulate the +default queries from a nameserver. +.UNINDENT +.INDENT 0.0 +.TP +.B +crypto, +nocrypto +This option toggles the display of cryptographic fields in DNSSEC records. The +contents of these fields are unnecessary for debugging most DNSSEC +validation failures and removing them makes it easier to see the +common failures. The default is to display the fields. When omitted, +they are replaced by the string \fB[omitted]\fP or, in the DNSKEY case, the +key ID is displayed as the replacement, e.g. \fB[ key id = value ]\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +defname, +nodefname +This option, which is deprecated, is treated as a synonym for +\fI\%+search\fP, \fI\%+nosearch\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +dns64prefix, +nodns64prefix +Lookup IPV4ONLY.ARPA AAAA and print any DNS64 prefixes found. +.UNINDENT +.INDENT 0.0 +.TP +.B +dnssec, +do, +nodnssec, +nodo +This option requests that DNSSEC records be sent by setting the DNSSEC OK (DO) bit in +the OPT record in the additional section of the query. +.UNINDENT +.INDENT 0.0 +.TP +.B +domain=somename +This option sets the search list to contain the single domain \fBsomename\fP, as if +specified in a \fBdomain\fP directive in \fB/etc/resolv.conf\fP, and +enables search list processing as if the \fI\%+search\fP option were +given. +.UNINDENT +.INDENT 0.0 +.TP +.B +dscp=value +This option formerly set the DSCP value used when sending a query. +It is now obsolete, and has no effect. +.UNINDENT +.INDENT 0.0 +.TP +.B +edns[=#], +noedns +This option specifies the EDNS version to query with. Valid values are 0 to 255. +Setting the EDNS version causes an EDNS query to be sent. +\fB+noedns\fP clears the remembered EDNS version. EDNS is set to 0 by +default. +.UNINDENT +.INDENT 0.0 +.TP +.B +ednsflags[=#], +noednsflags +This option sets the must\-be\-zero EDNS flags bits (Z bits) to the specified value. +Decimal, hex, and octal encodings are accepted. Setting a named flag +(e.g., DO) is silently ignored. By default, no Z bits are set. +.UNINDENT +.INDENT 0.0 +.TP +.B +ednsnegotiation, +noednsnegotiation +This option enables/disables EDNS version negotiation. By default, EDNS version +negotiation is enabled. +.UNINDENT +.INDENT 0.0 +.TP +.B +ednsopt[=code[:value]], +noednsopt +This option specifies the EDNS option with code point \fBcode\fP and an optional payload +of \fBvalue\fP as a hexadecimal string. \fBcode\fP can be either an EDNS +option name (for example, \fBNSID\fP or \fBECS\fP) or an arbitrary +numeric value. \fB+noednsopt\fP clears the EDNS options to be sent. +.UNINDENT +.INDENT 0.0 +.TP +.B +expire, +noexpire +This option sends an EDNS Expire option. +.UNINDENT +.INDENT 0.0 +.TP +.B +fail, +nofail +This option indicates that \fI\%named\fP should try [or not try] the next server if a SERVFAIL is received. The default is +to not try the next server, which is the reverse of normal stub +resolver behavior. +.UNINDENT +.INDENT 0.0 +.TP +.B +fuzztime[=value], +nofuzztime +This option allows the signing time to be specified when generating +signed messages. If a value is specified it is the seconds since +00:00:00 January 1, 1970 UTC ignoring leap seconds. If no value +is specified 1646972129 (Fri 11 Mar 2022 04:15:29 UTC) is used. +The default is \fB+nofuzztime\fP and the current time is used. +.UNINDENT +.INDENT 0.0 +.TP +.B +header\-only, +noheader\-only +This option sends a query with a DNS header without a question section. The +default is to add a question section. The query type and query name +are ignored when this is set. +.UNINDENT +.INDENT 0.0 +.TP +.B +https[=value], +nohttps +This option indicates whether to use DNS over HTTPS (DoH) when querying +name servers. When this option is in use, the port number defaults to 443. +The HTTP POST request mode is used when sending the query. +.sp +If \fBvalue\fP is specified, it will be used as the HTTP endpoint in the +query URI; the default is \fB/dns\-query\fP\&. So, for example, \fBdig +@example.com +https\fP will use the URI \fBhttps://example.com/dns\-query\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +https\-get[=value], +nohttps\-get +Similar to \fI\%+https\fP, except that the HTTP GET request mode is used +when sending the query. +.UNINDENT +.INDENT 0.0 +.TP +.B +https\-post[=value], +nohttps\-post +Same as \fI\%+https\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +http\-plain[=value], +nohttp\-plain +Similar to \fI\%+https\fP, except that HTTP queries will be sent over a +non\-encrypted channel. When this option is in use, the port number +defaults to 80 and the HTTP request mode is POST. +.UNINDENT +.INDENT 0.0 +.TP +.B +http\-plain\-get[=value], +nohttp\-plain\-get +Similar to \fI\%+http\-plain\fP, except that the HTTP request mode is GET. +.UNINDENT +.INDENT 0.0 +.TP +.B +http\-plain\-post[=value], +nohttp\-plain\-post +Same as \fI\%+http\-plain\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +identify, +noidentify +This option shows [or does not show] the IP address and port number that +supplied the answer, when the \fI\%+short\fP option is enabled. If short +form answers are requested, the default is not to show the source +address and port number of the server that provided the answer. +.UNINDENT +.INDENT 0.0 +.TP +.B +idnin, +noidnin +This option processes [or does not process] IDN domain names on input. This requires +\fBIDN SUPPORT\fP to have been enabled at compile time. +.sp +The default is to process IDN input when standard output is a tty. +The IDN processing on input is disabled when \fBdig\fP output is redirected +to files, pipes, and other non\-tty file descriptors. +.UNINDENT +.INDENT 0.0 +.TP +.B +idnout, +noidnout +This option converts [or does not convert] puny code on output. This requires +\fBIDN SUPPORT\fP to have been enabled at compile time. +.sp +The default is to process puny code on output when standard output is +a tty. The puny code processing on output is disabled when \fBdig\fP output +is redirected to files, pipes, and other non\-tty file descriptors. +.UNINDENT +.INDENT 0.0 +.TP +.B +ignore, +noignore +This option ignores [or does not ignore] truncation in UDP responses instead of retrying with TCP. By +default, TCP retries are performed. +.UNINDENT +.INDENT 0.0 +.TP +.B +keepalive, +nokeepalive +This option sends [or does not send] an EDNS Keepalive option. +.UNINDENT +.INDENT 0.0 +.TP +.B +keepopen, +nokeepopen +This option keeps [or does not keep] the TCP socket open between queries, and reuses it rather than +creating a new TCP socket for each lookup. The default is +\fB+nokeepopen\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +multiline, +nomultiline +This option prints [or does not print] records, like the SOA records, in a verbose multi\-line format +with human\-readable comments. The default is to print each record on +a single line to facilitate machine parsing of the \fBdig\fP output. +.UNINDENT +.INDENT 0.0 +.TP +.B +ndots=D +This option sets the number of dots (\fBD\fP) that must appear in \fBname\fP for +it to be considered absolute. The default value is that defined using +the \fBndots\fP statement in \fB/etc/resolv.conf\fP, or 1 if no \fBndots\fP +statement is present. Names with fewer dots are interpreted as +relative names, and are searched for in the domains listed in the +\fBsearch\fP or \fBdomain\fP directive in \fB/etc/resolv.conf\fP if +\fI\%+search\fP is set. +.UNINDENT +.INDENT 0.0 +.TP +.B +nsid, +nonsid +When enabled, this option includes an EDNS name server ID request when sending a query. +.UNINDENT +.INDENT 0.0 +.TP +.B +nssearch, +nonssearch +When this option is set, \fBdig\fP attempts to find the authoritative +name servers for the zone containing the name being looked up, and +display the SOA record that each name server has for the zone. +Addresses of servers that did not respond are also printed. +.UNINDENT +.INDENT 0.0 +.TP +.B +onesoa, +noonesoa +When enabled, this option prints only one (starting) SOA record when performing an AXFR. The +default is to print both the starting and ending SOA records. +.UNINDENT +.INDENT 0.0 +.TP +.B +opcode=value, +noopcode +When enabled, this option sets (restores) the DNS message opcode to the specified value. The +default value is QUERY (0). +.UNINDENT +.INDENT 0.0 +.TP +.B +padding=value +This option pads the size of the query packet using the EDNS Padding option to +blocks of \fBvalue\fP bytes. For example, \fB+padding=32\fP causes a +48\-byte query to be padded to 64 bytes. The default block size is 0, +which disables padding; the maximum is 512. Values are ordinarily +expected to be powers of two, such as 128; however, this is not +mandatory. Responses to padded queries may also be padded, but only +if the query uses TCP or DNS COOKIE. +.UNINDENT +.INDENT 0.0 +.TP +.B +qid=value +This option specifies the query ID to use when sending queries. +.UNINDENT +.INDENT 0.0 +.TP +.B +qr, +noqr +This option toggles the display of the query message as it is sent. By default, the query +is not printed. +.UNINDENT +.INDENT 0.0 +.TP +.B +question, +noquestion +This option toggles the display of the question section of a query when an answer is +returned. The default is to print the question section as a comment. +.UNINDENT +.INDENT 0.0 +.TP +.B +raflag, +noraflag +This option sets [or does not set] the RA (Recursion Available) bit in the query. The +default is \fB+noraflag\fP\&. This bit is ignored by the server for +QUERY. +.UNINDENT +.INDENT 0.0 +.TP +.B +rdflag, +nordflag +This option is a synonym for \fI\%+recurse\fP, \fI\%+norecurse\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +recurse, +norecurse +This option toggles the setting of the RD (recursion desired) bit in the query. +This bit is set by default, which means \fBdig\fP normally sends +recursive queries. Recursion is automatically disabled when the +\fI\%+nssearch\fP or \fI\%+trace\fP query option is used. +.UNINDENT +.INDENT 0.0 +.TP +.B +retry=T +This option sets the number of times to retry UDP and TCP queries to server to \fBT\fP +instead of the default, 2. Unlike \fI\%+tries\fP, this does not include +the initial query. +.UNINDENT +.INDENT 0.0 +.TP +.B +rrcomments, +norrcomments +This option toggles the display of per\-record comments in the output (for example, +human\-readable key information about DNSKEY records). The default is +not to print record comments unless multiline mode is active. +.UNINDENT +.INDENT 0.0 +.TP +.B +search, +nosearch +This option uses [or does not use] the search list defined by the searchlist or domain +directive in \fBresolv.conf\fP, if any. The search list is not used by +default. +.sp +\fBndots\fP from \fBresolv.conf\fP (default 1), which may be overridden by +\fI\%+ndots\fP, determines whether the name is treated as relative +and hence whether a search is eventually performed. +.UNINDENT +.INDENT 0.0 +.TP +.B +short, +noshort +This option toggles whether a terse answer is provided. The default is to print the answer in a verbose +form. This option always has a global effect; it cannot be set globally and +then overridden on a per\-lookup basis. +.UNINDENT +.INDENT 0.0 +.TP +.B +showbadcookie, +noshowbadcookie +This option toggles whether to show the message containing the +BADCOOKIE rcode before retrying the request or not. The default +is to not show the messages. +.UNINDENT +.INDENT 0.0 +.TP +.B +showsearch, +noshowsearch +This option performs [or does not perform] a search showing intermediate results. +.UNINDENT +.INDENT 0.0 +.TP +.B +sigchase, +nosigchase +This feature is now obsolete and has been removed; use \fI\%delv\fP +instead. +.UNINDENT +.INDENT 0.0 +.TP +.B +split=W +This option splits long hex\- or base64\-formatted fields in resource records into +chunks of \fBW\fP characters (where \fBW\fP is rounded up to the nearest +multiple of 4). \fB+nosplit\fP or \fB+split=0\fP causes fields not to be +split at all. The default is 56 characters, or 44 characters when +multiline mode is active. +.UNINDENT +.INDENT 0.0 +.TP +.B +stats, +nostats +This option toggles the printing of statistics: when the query was made, the size of the +reply, etc. The default behavior is to print the query statistics as a +comment after each lookup. +.UNINDENT +.INDENT 0.0 +.TP +.B +subnet=addr[/prefix\-length], +nosubnet +This option sends [or does not send] an EDNS CLIENT\-SUBNET option with the specified IP +address or network prefix. +.sp +\fBdig +subnet=0.0.0.0/0\fP, or simply \fBdig +subnet=0\fP for short, +sends an EDNS CLIENT\-SUBNET option with an empty address and a source +prefix\-length of zero, which signals a resolver that the client\(aqs +address information must \fInot\fP be used when resolving this query. +.UNINDENT +.INDENT 0.0 +.TP +.B +tcflag, +notcflag +This option sets [or does not set] the TC (TrunCation) bit in the query. The default is +\fB+notcflag\fP\&. This bit is ignored by the server for QUERY. +.UNINDENT +.INDENT 0.0 +.TP +.B +tcp, +notcp +This option indicates whether to use TCP when querying name +servers. The default behavior is to use UDP unless a type \fBany\fP +or \fBixfr=N\fP query is requested, in which case the default is +TCP. AXFR queries always use TCP. To prevent retry over TCP when +TC=1 is returned from a UDP query, use \fB+ignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +timeout=T +This option sets the timeout for a query to \fBT\fP seconds. The default timeout is +5 seconds. An attempt to set \fBT\fP to less than 1 is silently set to 1. +.UNINDENT +.INDENT 0.0 +.TP +.B +tls, +notls +This option indicates whether to use DNS over TLS (DoT) when querying +name servers. When this option is in use, the port number defaults +to 853. +.UNINDENT +.INDENT 0.0 +.TP +.B +tls\-ca[=file\-name], +notls\-ca +This option enables remote server TLS certificate validation for +DNS transports, relying on TLS. Certificate authorities +certificates are loaded from the specified PEM file +(\fBfile\-name\fP). If the file is not specified, the default +certificates from the global certificates store are used. +.UNINDENT +.INDENT 0.0 +.TP +.B +tls\-certfile=file\-name, +tls\-keyfile=file\-name, +notls\-certfile, +notls\-keyfile +These options set the state of certificate\-based client +authentication for DNS transports, relying on TLS. Both certificate +chain file and private key file are expected to be in PEM format. +Both options must be specified at the same time. +.UNINDENT +.INDENT 0.0 +.TP +.B +tls\-hostname=hostname, +notls\-hostname +This option makes \fBdig\fP use the provided hostname during remote +server TLS certificate verification. Otherwise, the DNS server name +is used. This option has no effect if \fI\%+tls\-ca\fP is not specified. +.UNINDENT +.INDENT 0.0 +.TP +.B +topdown, +notopdown +This feature is related to \fI\%dig +sigchase\fP, which is obsolete and +has been removed. Use \fI\%delv\fP instead. +.UNINDENT +.INDENT 0.0 +.TP +.B +trace, +notrace +This option toggles tracing of the delegation path from the root name servers for +the name being looked up. Tracing is disabled by default. When +tracing is enabled, \fBdig\fP makes iterative queries to resolve the +name being looked up. It follows referrals from the root servers, +showing the answer from each server that was used to resolve the +lookup. +.sp +If \fB@server\fP is also specified, it affects only the initial query for +the root zone name servers. +.sp +\fI\%+dnssec\fP is also set when \fI\%+trace\fP is set, to better emulate the +default queries from a name server. +.UNINDENT +.INDENT 0.0 +.TP +.B +tries=T +This option sets the number of times to try UDP and TCP queries to server to \fBT\fP +instead of the default, 3. If \fBT\fP is less than or equal to zero, +the number of tries is silently rounded up to 1. +.UNINDENT +.INDENT 0.0 +.TP +.B +trusted\-key=#### +This option formerly specified trusted keys for use with \fI\%dig +sigchase\fP\&. This +feature is now obsolete and has been removed; use \fI\%delv\fP instead. +.UNINDENT +.INDENT 0.0 +.TP +.B +ttlid, +nottlid +This option displays [or does not display] the TTL when printing the record. +.UNINDENT +.INDENT 0.0 +.TP +.B +ttlunits, +nottlunits +This option displays [or does not display] the TTL in friendly human\-readable time +units of \fBs\fP, \fBm\fP, \fBh\fP, \fBd\fP, and \fBw\fP, representing seconds, minutes, +hours, days, and weeks. This implies \fI\%+ttlid\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +unknownformat, +nounknownformat +This option prints all RDATA in unknown RR type presentation format (\fI\%RFC 3597\fP). +The default is to print RDATA for known types in the type\(aqs +presentation format. +.UNINDENT +.INDENT 0.0 +.TP +.B +vc, +novc +This option uses [or does not use] TCP when querying name servers. This alternate +syntax to \fI\%+tcp\fP is provided for backwards compatibility. The +\fBvc\fP stands for \(dqvirtual circuit.\(dq +.UNINDENT +.INDENT 0.0 +.TP +.B +yaml, +noyaml +When enabled, this option prints the responses (and, if \fI\%+qr\fP is in use, also the +outgoing queries) in a detailed YAML format. +.UNINDENT +.INDENT 0.0 +.TP +.B +zflag, +nozflag +This option sets [or does not set] the last unassigned DNS header flag in a DNS query. +This flag is off by default. +.UNINDENT +.SH MULTIPLE QUERIES +.sp +The BIND 9 implementation of \fBdig\fP supports specifying multiple +queries on the command line (in addition to supporting the \fI\%\-f\fP batch +file option). Each of those queries can be supplied with its own set of +flags, options, and query options. +.sp +In this case, each \fBquery\fP argument represents an individual query in +the command\-line syntax described above. Each consists of any of the +standard options and flags, the name to be looked up, an optional query +type and class, and any query options that should be applied to that +query. +.sp +A global set of query options, which should be applied to all queries, +can also be supplied. These global query options must precede the first +tuple of name, class, type, options, flags, and query options supplied +on the command line. Any global query options (except \fI\%+cmd\fP and +\fI\%+short\fP options) can be overridden by a query\-specific set of +query options. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +dig +qr www.isc.org any \-x 127.0.0.1 isc.org ns +noqr +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +shows how \fBdig\fP can be used from the command line to make three +lookups: an ANY query for \fBwww.isc.org\fP, a reverse lookup of 127.0.0.1, +and a query for the NS records of \fBisc.org\fP\&. A global query option of +\fI\%+qr\fP is applied, so that \fBdig\fP shows the initial query it made for +each lookup. The final query has a local query option of \fI\%+noqr\fP which +means that \fBdig\fP does not print the initial query when it looks up the +NS records for \fBisc.org\fP\&. +.SH IDN SUPPORT +.sp +If \fBdig\fP has been built with IDN (internationalized domain name) +support, it can accept and display non\-ASCII domain names. \fBdig\fP +appropriately converts character encoding of a domain name before sending +a request to a DNS server or displaying a reply from the server. +To turn off IDN support, use the parameters +\fI\%+idnin\fP and \fI\%+idnout\fP, or define the \fBIDN_DISABLE\fP environment +variable. +.SH RETURN CODES +.sp +\fBdig\fP return codes are: +.INDENT 0.0 +.TP +.B \fB0\fP +DNS response received, including NXDOMAIN status +.TP +.B \fB1\fP +Usage error +.TP +.B \fB8\fP +Couldn\(aqt open batch file +.TP +.B \fB9\fP +No reply from server +.TP +.B \fB10\fP +Internal error +.UNINDENT +.SH FILES +.sp +\fB/etc/resolv.conf\fP +.sp +\fB${HOME}/.digrc\fP +.SH SEE ALSO +.sp +\fI\%delv(1)\fP, \fI\%host(1)\fP, \fI\%named(8)\fP, \fI\%dnssec\-keygen(8)\fP, \fI\%RFC 1035\fP\&. +.SH BUGS +.sp +There are probably too many query options. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dig.rst b/doc/man/dig.rst new file mode 100644 index 0000000..578a0be --- /dev/null +++ b/doc/man/dig.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dig/dig.rst diff --git a/doc/man/dnssec-cds.1in b/doc/man/dnssec-cds.1in new file mode 100644 index 0000000..143253f --- /dev/null +++ b/doc/man/dnssec-cds.1in @@ -0,0 +1,256 @@ +.\" 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 "DNSSEC-CDS" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dnssec-cds \- change DS records for a child zone based on CDS/CDNSKEY +.SH SYNOPSIS +.sp +\fBdnssec\-cds\fP [\fB\-a\fP alg...] [\fB\-c\fP class] [\fB\-D\fP] {\fB\-d\fP dsset\-file} {\fB\-f\fP child\-file} [\fB\-i**[extension]] [\fP\-s** start\-time] [\fB\-T\fP ttl] [\fB\-u\fP] [\fB\-v\fP level] [\fB\-V\fP] {domain} +.SH DESCRIPTION +.sp +The \fBdnssec\-cds\fP command changes DS records at a delegation point +based on CDS or CDNSKEY records published in the child zone. If both CDS +and CDNSKEY records are present in the child zone, the CDS is preferred. +This enables a child zone to inform its parent of upcoming changes to +its key\-signing keys (KSKs); by polling periodically with \fBdnssec\-cds\fP, the +parent can keep the DS records up\-to\-date and enable automatic rolling +of KSKs. +.sp +Two input files are required. The \fI\%\-f child\-file\fP option specifies a +file containing the child\(aqs CDS and/or CDNSKEY records, plus RRSIG and +DNSKEY records so that they can be authenticated. The \fI\%\-d path\fP option +specifies the location of a file containing the current DS records. For +example, this could be a \fBdsset\-\fP file generated by +\fI\%dnssec\-signzone\fP, or the output of \fI\%dnssec\-dsfromkey\fP, or the +output of a previous run of \fBdnssec\-cds\fP\&. +.sp +The \fBdnssec\-cds\fP command uses special DNSSEC validation logic +specified by \fI\%RFC 7344\fP\&. It requires that the CDS and/or CDNSKEY records +be validly signed by a key represented in the existing DS records. This +is typically the pre\-existing KSK. +.sp +For protection against replay attacks, the signatures on the child +records must not be older than they were on a previous run of +\fBdnssec\-cds\fP\&. Their age is obtained from the modification time of the +\fBdsset\-\fP file, or from the \fI\%\-s\fP option. +.sp +To protect against breaking the delegation, \fBdnssec\-cds\fP ensures that +the DNSKEY RRset can be verified by every key algorithm in the new DS +RRset, and that the same set of keys are covered by every DS digest +type. +.sp +By default, replacement DS records are written to the standard output; +with the \fI\%\-i\fP option the input file is overwritten in place. The +replacement DS records are the same as the existing records, when no +change is required. The output can be empty if the CDS/CDNSKEY records +specify that the child zone wants to be insecure. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Be careful not to delete the DS records when \fBdnssec\-cds\fP fails! +.UNINDENT +.UNINDENT +.sp +Alternatively, :option\(gadnssec\-cds \-u\(ga writes an \fI\%nsupdate\fP script to the +standard output. The \fI\%\-u\fP and \fI\%\-i\fP options can be used together to +maintain a \fBdsset\-\fP file as well as emit an \fI\%nsupdate\fP script. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-a algorithm +When converting CDS records to DS records, this option specifies +the acceptable digest algorithms. This option can be repeated, so +that multiple digest types are allowed. If none of the CDS records +use an acceptable digest type, \fBdnssec\-cds\fP will try to use CDNSKEY +records instead; if there are no CDNSKEY records, it reports an error. +.sp +When converting CDNSKEY records to DS records, this option specifies the +digest algorithm to use. It can be repeated, so that multiple DS records +are created for each CDNSKEY records. +.sp +The algorithm must be one of SHA\-1, SHA\-256, or SHA\-384. These values +are case\-insensitive, and the hyphen may be omitted. If no algorithm +is specified, the default is SHA\-256 only. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c class +This option specifies the DNS class of the zones. +.UNINDENT +.INDENT 0.0 +.TP +.B \-D +This option generates DS records from CDNSKEY records if both CDS and CDNSKEY +records are present in the child zone. By default CDS records are +preferred. +.UNINDENT +.INDENT 0.0 +.TP +.B \-d path +This specifies the location of the parent DS records. The path can be the name of a file +containing the DS records; if it is a directory, \fBdnssec\-cds\fP +looks for a \fBdsset\-\fP file for the domain inside the directory. +.sp +To protect against replay attacks, child records are rejected if they +were signed earlier than the modification time of the \fBdsset\-\fP +file. This can be adjusted with the \fI\%\-s\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-f child\-file +This option specifies the file containing the child\(aqs CDS and/or CDNSKEY records, plus its +DNSKEY records and the covering RRSIG records, so that they can be +authenticated. +.sp +The examples below describe how to generate this file. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i extension +This option updates the \fBdsset\-\fP file in place, instead of writing DS records to +the standard output. +.sp +There must be no space between the \fI\%\-i\fP and the extension. If +no extension is provided, the old \fBdsset\-\fP is discarded. If an +extension is present, a backup of the old \fBdsset\-\fP file is kept +with the extension appended to its filename. +.sp +To protect against replay attacks, the modification time of the +\fBdsset\-\fP file is set to match the signature inception time of the +child records, provided that it is later than the file\(aqs current +modification time. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s start\-time +This option specifies the date and time after which RRSIG records become +acceptable. This can be either an absolute or a relative time. An +absolute start time is indicated by a number in YYYYMMDDHHMMSS +notation; 20170827133700 denotes 13:37:00 UTC on August 27th, 2017. A +time relative to the \fBdsset\-\fP file is indicated with \fB\-N\fP, which is N +seconds before the file modification time. A time relative to the +current time is indicated with \fBnow+N\fP\&. +.sp +If no start\-time is specified, the modification time of the +\fBdsset\-\fP file is used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-T ttl +This option specifies a TTL to be used for new DS records. If not specified, the +default is the TTL of the old DS records. If they had no explicit TTL, +the new DS records also have no explicit TTL. +.UNINDENT +.INDENT 0.0 +.TP +.B \-u +This option writes an \fI\%nsupdate\fP script to the standard output, instead of +printing the new DS reords. The output is empty if no change is +needed. +.sp +Note: The TTL of new records needs to be specified: it can be done in the +original \fBdsset\-\fP file, with the \fI\%\-T\fP option, or using the +\fI\%nsupdate\fP \fBttl\fP command. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints version information. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v level +This option sets the debugging level. Level 1 is intended to be usefully verbose +for general users; higher levels are intended for developers. +.UNINDENT +.INDENT 0.0 +.TP +.B \fBdomain\fP +This indicates the name of the delegation point/child zone apex. +.UNINDENT +.SH EXIT STATUS +.sp +The \fBdnssec\-cds\fP command exits 0 on success, or non\-zero if an error +occurred. +.sp +If successful, the DS records may or may not need to be +changed. +.SH EXAMPLES +.sp +Before running \fI\%dnssec\-signzone\fP, ensure that the delegations +are up\-to\-date by running \fBdnssec\-cds\fP on every \fBdsset\-\fP file. +.sp +To fetch the child records required by \fBdnssec\-cds\fP, invoke +\fI\%dig\fP as in the script below. It is acceptable if the \fI\%dig\fP fails, since +\fBdnssec\-cds\fP performs all the necessary checking. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +for f in dsset\-* +do + d=${f#dsset\-} + dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS | + dnssec\-cds \-i \-f /dev/stdin \-d $f $d +done +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +When the parent zone is automatically signed by \fI\%named\fP, +\fBdnssec\-cds\fP can be used with \fI\%nsupdate\fP to maintain a delegation as follows. +The \fBdsset\-\fP file allows the script to avoid having to fetch and +validate the parent DS records, and it maintains the replay attack +protection time. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS | +dnssec\-cds \-u \-i \-f /dev/stdin \-d $f $d | +nsupdate \-l +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fI\%dig(1)\fP, \fI\%dnssec\-settime(8)\fP, \fI\%dnssec\-signzone(8)\fP, \fI\%nsupdate(1)\fP, BIND 9 Administrator +Reference Manual, \fI\%RFC 7344\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-cds.rst b/doc/man/dnssec-cds.rst new file mode 100644 index 0000000..fadc1a1 --- /dev/null +++ b/doc/man/dnssec-cds.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dnssec/dnssec-cds.rst diff --git a/doc/man/dnssec-dsfromkey.1in b/doc/man/dnssec-dsfromkey.1in new file mode 100644 index 0000000..5a76afa --- /dev/null +++ b/doc/man/dnssec-dsfromkey.1in @@ -0,0 +1,177 @@ +.\" 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 "DNSSEC-DSFROMKEY" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dnssec-dsfromkey \- DNSSEC DS RR generation tool +.SH SYNOPSIS +.sp +\fBdnssec\-dsfromkey\fP [ \fB\-1\fP | \fB\-2\fP | \fB\-a\fP alg ] [ \fB\-C\fP ] [\fB\-T\fP TTL] [\fB\-v\fP level] [\fB\-K\fP directory] {keyfile} +.sp +\fBdnssec\-dsfromkey\fP [ \fB\-1\fP | \fB\-2\fP | \fB\-a\fP alg ] [ \fB\-C\fP ] [\fB\-T\fP TTL] [\fB\-v\fP level] [\fB\-c\fP class] [\fB\-A\fP] {\fB\-f\fP file} [dnsname] +.sp +\fBdnssec\-dsfromkey\fP [ \fB\-1\fP | \fB\-2\fP | \fB\-a\fP alg ] [ \fB\-C\fP ] [\fB\-T\fP TTL] [\fB\-v\fP level] [\fB\-c\fP class] [\fB\-K\fP directory] {\fB\-s\fP} {dnsname} +.sp +\fBdnssec\-dsfromkey\fP [ \fB\-h\fP | \fB\-V\fP ] +.SH DESCRIPTION +.sp +The \fBdnssec\-dsfromkey\fP command outputs DS (Delegation Signer) resource records +(RRs), or CDS (Child DS) RRs with the \fI\%\-C\fP option. +.sp +By default, only KSKs are converted (keys with flags = 257). The +\fI\%\-A\fP option includes ZSKs (flags = 256). Revoked keys are never +included. +.sp +The input keys can be specified in a number of ways: +.sp +By default, \fBdnssec\-dsfromkey\fP reads a key file named in the format +\fBKnnnn.+aaa+iiiii.key\fP, as generated by \fI\%dnssec\-keygen\fP\&. +.sp +With the \fI\%\-f file\fP option, \fBdnssec\-dsfromkey\fP reads keys from a zone +file or partial zone file (which can contain just the DNSKEY records). +.sp +With the \fI\%\-s\fP option, \fBdnssec\-dsfromkey\fP reads a \fBkeyset\-\fP file, +as generated by \fI\%dnssec\-keygen\fP \fI\%\-C\fP\&. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-1 +This option is an abbreviation for \fI\%\-a SHA1\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-2 +This option is an abbreviation for \fI\%\-a SHA\-256\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-a algorithm +This option specifies a digest algorithm to use when converting DNSKEY records to +DS records. This option can be repeated, so that multiple DS records +are created for each DNSKEY record. +.sp +The algorithm must be one of SHA\-1, SHA\-256, or SHA\-384. These values +are case\-insensitive, and the hyphen may be omitted. If no algorithm +is specified, the default is SHA\-256. +.UNINDENT +.INDENT 0.0 +.TP +.B \-A +This option indicates that ZSKs are to be included when generating DS records. Without this option, only +keys which have the KSK flag set are converted to DS records and +printed. This option is only useful in \fI\%\-f\fP zone file mode. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c class +This option specifies the DNS class; the default is IN. This option is only useful in \fI\%\-s\fP keyset +or \fI\%\-f\fP zone file mode. +.UNINDENT +.INDENT 0.0 +.TP +.B \-C +This option generates CDS records rather than DS records. +.UNINDENT +.INDENT 0.0 +.TP +.B \-f file +This option sets zone file mode, in which the final dnsname argument of \fBdnssec\-dsfromkey\fP is the +DNS domain name of a zone whose master file can be read from +\fBfile\fP\&. If the zone name is the same as \fBfile\fP, then it may be +omitted. +.sp +If \fBfile\fP is \fB\-\fP, then the zone data is read from the standard +input. This makes it possible to use the output of the \fI\%dig\fP +command as input, as in: +.sp +\fBdig dnskey example.com | dnssec\-dsfromkey \-f \- example.com\fP +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option prints usage information. +.UNINDENT +.INDENT 0.0 +.TP +.B \-K directory +This option tells BIND 9 to look for key files or \fBkeyset\-\fP files in \fBdirectory\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s +This option enables keyset mode, in which the final dnsname argument from \fBdnssec\-dsfromkey\fP is the DNS +domain name used to locate a \fBkeyset\-\fP file. +.UNINDENT +.INDENT 0.0 +.TP +.B \-T TTL +This option specifies the TTL of the DS records. By default the TTL is omitted. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v level +This option sets the debugging level. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints version information. +.UNINDENT +.SH EXAMPLE +.sp +To build the SHA\-256 DS RR from the \fBKexample.com.+003+26160\fP keyfile, +issue the following command: +.sp +\fBdnssec\-dsfromkey \-2 Kexample.com.+003+26160\fP +.sp +The command returns something similar to: +.sp +\fBexample.com. IN DS 26160 5 2 3A1EADA7A74B8D0BA86726B0C227AA85AB8BBD2B2004F41A868A54F0C5EA0B94\fP +.SH FILES +.sp +The keyfile can be designated by the key identification +\fBKnnnn.+aaa+iiiii\fP or the full file name \fBKnnnn.+aaa+iiiii.key\fP, as +generated by \fI\%dnssec\-keygen\fP\&. +.sp +The keyset file name is built from the \fBdirectory\fP, the string +\fBkeyset\-\fP, and the \fBdnsname\fP\&. +.SH CAVEAT +.sp +A keyfile error may return \(dqfile not found,\(dq even if the file exists. +.SH SEE ALSO +.sp +\fI\%dnssec\-keygen(8)\fP, \fI\%dnssec\-signzone(8)\fP, BIND 9 Administrator Reference Manual, +\fI\%RFC 3658\fP (DS RRs), \fI\%RFC 4509\fP (SHA\-256 for DS RRs), +\fI\%RFC 6605\fP (SHA\-384 for DS RRs), \fI\%RFC 7344\fP (CDS and CDNSKEY RRs). +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-dsfromkey.rst b/doc/man/dnssec-dsfromkey.rst new file mode 100644 index 0000000..9a016b1 --- /dev/null +++ b/doc/man/dnssec-dsfromkey.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dnssec/dnssec-dsfromkey.rst diff --git a/doc/man/dnssec-importkey.1in b/doc/man/dnssec-importkey.1in new file mode 100644 index 0000000..a15a496 --- /dev/null +++ b/doc/man/dnssec-importkey.1in @@ -0,0 +1,152 @@ +.\" 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 "DNSSEC-IMPORTKEY" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dnssec-importkey \- import DNSKEY records from external systems so they can be managed +.SH SYNOPSIS +.sp +\fBdnssec\-importkey\fP [\fB\-K\fP directory] [\fB\-L\fP ttl] [\fB\-P\fP date/offset] [\fB\-P\fP sync date/offset] [\fB\-D\fP date/offset] [\fB\-D\fP sync date/offset] [\fB\-h\fP] [\fB\-v\fP level] [\fB\-V\fP] {keyfile} +.sp +\fBdnssec\-importkey\fP {\fB\-f\fP filename} [\fB\-K\fP directory] [\fB\-L\fP ttl] [\fB\-P\fP date/offset] [\fB\-P\fP sync date/offset] [\fB\-D\fP date/offset] [\fB\-D\fP sync date/offset] [\fB\-h\fP] [\fB\-v\fP level] [\fB\-V\fP] [dnsname] +.SH DESCRIPTION +.sp +\fBdnssec\-importkey\fP reads a public DNSKEY record and generates a pair +of .key/.private files. The DNSKEY record may be read from an +existing .key file, in which case a corresponding .private file is +generated, or it may be read from any other file or from the standard +input, in which case both .key and .private files are generated. +.sp +The newly created .private file does \fInot\fP contain private key data, and +cannot be used for signing. However, having a .private file makes it +possible to set publication (\fI\%\-P\fP) and deletion (\fI\%\-D\fP) times for the +key, which means the public key can be added to and removed from the +DNSKEY RRset on schedule even if the true private key is stored offline. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-f filename +This option indicates the zone file mode. Instead of a public keyfile name, the argument is the +DNS domain name of a zone master file, which can be read from +\fBfilename\fP\&. If the domain name is the same as \fBfilename\fP, then it may be +omitted. +.sp +If \fBfilename\fP is set to \fB\(dq\-\(dq\fP, then the zone data is read from the +standard input. +.UNINDENT +.INDENT 0.0 +.TP +.B \-K directory +This option sets the directory in which the key files are to reside. +.UNINDENT +.INDENT 0.0 +.TP +.B \-L ttl +This option sets the default TTL to use for this key when it is converted into a +DNSKEY RR. This is the TTL used when the key is imported into a zone, +unless there was already a DNSKEY RRset in +place, in which case the existing TTL takes precedence. Setting the default TTL to \fB0\fP or \fBnone\fP +removes it from the key. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option emits a usage message and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v level +This option sets the debugging level. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints version information. +.UNINDENT +.SH TIMING OPTIONS +.sp +Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. +(which is the format used inside key files), +or \(aqDay Mon DD HH:MM:SS YYYY\(aq (as printed by \fBdnssec\-settime \-p\fP), +or UNIX epoch time (as printed by \fBdnssec\-settime \-up\fP), +or the literal \fBnow\fP\&. +.sp +The argument can be followed by \fB+\fP or \fB\-\fP and an offset from the +given time. The literal \fBnow\fP can be omitted before an offset. The +offset can be followed by one of the suffixes \fBy\fP, \fBmo\fP, \fBw\fP, +\fBd\fP, \fBh\fP, or \fBmi\fP, so that it is computed in years (defined as +365 24\-hour days, ignoring leap years), months (defined as 30 24\-hour +days), weeks, days, hours, or minutes, respectively. Without a suffix, +the offset is computed in seconds. +.sp +To explicitly prevent a date from being set, use \fBnone\fP, \fBnever\fP, +or \fBunset\fP\&. +.sp +All these formats are case\-insensitive. +.INDENT 0.0 +.TP +.B \-P date/offset +This option sets the date on which a key is to be published to the zone. After +that date, the key is included in the zone but is not used +to sign it. +.INDENT 7.0 +.TP +.B sync date/offset +This option sets the date on which CDS and CDNSKEY records that match this key +are to be published to the zone. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-D date/offset +This option sets the date on which the key is to be deleted. After that date, the +key is no longer included in the zone. (However, it may remain in the key +repository.) +.INDENT 7.0 +.TP +.B sync date/offset +This option sets the date on which the CDS and CDNSKEY records that match this +key are to be deleted. +.UNINDENT +.UNINDENT +.SH FILES +.sp +A keyfile can be designed by the key identification \fBKnnnn.+aaa+iiiii\fP +or the full file name \fBKnnnn.+aaa+iiiii.key\fP, as generated by +\fI\%dnssec\-keygen\fP\&. +.SH SEE ALSO +.sp +\fI\%dnssec\-keygen(8)\fP, \fI\%dnssec\-signzone(8)\fP, BIND 9 Administrator Reference Manual, +\fI\%RFC 5011\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-importkey.rst b/doc/man/dnssec-importkey.rst new file mode 100644 index 0000000..a9df508 --- /dev/null +++ b/doc/man/dnssec-importkey.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dnssec/dnssec-importkey.rst diff --git a/doc/man/dnssec-keyfromlabel.1in b/doc/man/dnssec-keyfromlabel.1in new file mode 100644 index 0000000..92c3b7d --- /dev/null +++ b/doc/man/dnssec-keyfromlabel.1in @@ -0,0 +1,319 @@ +.\" 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 "DNSSEC-KEYFROMLABEL" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dnssec-keyfromlabel \- DNSSEC key generation tool +.SH SYNOPSIS +.sp +\fBdnssec\-keyfromlabel\fP {\fB\-l\fP label} [\fB\-3\fP] [\fB\-a\fP algorithm] [\fB\-A\fP date/offset] [\fB\-c\fP class] [\fB\-D\fP date/offset] [\fB\-D\fP sync date/offset] [\fB\-E\fP engine] [\fB\-f\fP flag] [\fB\-G\fP] [\fB\-I\fP date/offset] [\fB\-i\fP interval] [\fB\-k\fP] [\fB\-K\fP directory] [\fB\-L\fP ttl] [\fB\-n\fP nametype] [\fB\-P\fP date/offset] [\fB\-P\fP sync date/offset] [\fB\-p\fP protocol] [\fB\-R\fP date/offset] [\fB\-S\fP key] [\fB\-t\fP type] [\fB\-v\fP level] [\fB\-V\fP] [\fB\-y\fP] {name} +.SH DESCRIPTION +.sp +\fBdnssec\-keyfromlabel\fP generates a pair of key files that reference a +key object stored in a cryptographic hardware service module (HSM). The +private key file can be used for DNSSEC signing of zone data as if it +were a conventional signing key created by \fI\%dnssec\-keygen\fP, but the +key material is stored within the HSM and the actual signing takes +place there. +.sp +The \fBname\fP of the key is specified on the command line. This must +match the name of the zone for which the key is being generated. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-a algorithm +This option selects the cryptographic algorithm. The value of \fBalgorithm\fP must +be one of RSASHA1, NSEC3RSASHA1, RSASHA256, RSASHA512, +ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. +.sp +These values are case\-insensitive. In some cases, abbreviations are +supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for +ECDSAP384SHA384. If RSASHA1 is specified along with the \fI\%\-3\fP +option, then NSEC3RSASHA1 is used instead. +.sp +This option is mandatory except when using the +\fI\%\-S\fP option, which copies the algorithm from the predecessory key. +.sp +Changed in version 9.12.0: The default value RSASHA1 for newly generated keys was removed. + +.UNINDENT +.INDENT 0.0 +.TP +.B \-3 +This option uses an NSEC3\-capable algorithm to generate a DNSSEC key. If this +option is used with an algorithm that has both NSEC and NSEC3 +versions, then the NSEC3 version is used; for example, +\fBdnssec\-keygen \-3a RSASHA1\fP specifies the NSEC3RSASHA1 algorithm. +.UNINDENT +.INDENT 0.0 +.TP +.B \-E engine +This option specifies the cryptographic hardware to use. +.sp +When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL +engine identifier that drives the cryptographic accelerator or +hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 +.TP +.B \-l label +This option specifies the label for a key pair in the crypto hardware. +.sp +When BIND 9 is built with OpenSSL\-based PKCS#11 support, the label is +an arbitrary string that identifies a particular key. It may be +preceded by an optional OpenSSL engine name, followed by a colon, as +in \fBpkcs11:keylabel\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-n nametype +This option specifies the owner type of the key. The value of \fBnametype\fP must +either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY +(for a key associated with a host (KEY)), USER (for a key associated +with a user (KEY)), or OTHER (DNSKEY). These values are +case\-insensitive. +.UNINDENT +.INDENT 0.0 +.TP +.B \-C +This option enables compatibility mode, which generates an old\-style key, without any metadata. +By default, \fBdnssec\-keyfromlabel\fP includes the key\(aqs creation +date in the metadata stored with the private key; other dates may +be set there as well, including publication date, activation date, etc. Keys +that include this data may be incompatible with older versions of +BIND; the \fI\%\-C\fP option suppresses them. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c class +This option indicates that the DNS record containing the key should have the +specified class. If not specified, class IN is used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-f flag +This option sets the specified flag in the \fBflag\fP field of the KEY/DNSKEY record. +The only recognized flags are KSK (Key\-Signing Key) and REVOKE. +.UNINDENT +.INDENT 0.0 +.TP +.B \-G +This option generates a key, but does not publish it or sign with it. This option is +incompatible with \fI\%\-P\fP and \fI\%\-A\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option prints a short summary of the options and arguments to +\fBdnssec\-keyfromlabel\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-K directory +This option sets the directory in which the key files are to be written. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k +This option generates KEY records rather than DNSKEY records. +.UNINDENT +.INDENT 0.0 +.TP +.B \-L ttl +This option sets the default TTL to use for this key when it is converted into a +DNSKEY RR. This is the TTL used when the key is imported into a zone, +unless there was already a DNSKEY RRset in +place, in which case the existing TTL would take precedence. Setting +the default TTL to \fB0\fP or \fBnone\fP removes it. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p protocol +This option sets the protocol value for the key. The protocol is a number between +0 and 255. The default is 3 (DNSSEC). Other possible values for this +argument are listed in \fI\%RFC 2535\fP and its successors. +.UNINDENT +.INDENT 0.0 +.TP +.B \-S key +This option generates a key as an explicit successor to an existing key. The name, +algorithm, size, and type of the key are set to match the +predecessor. The activation date of the new key is set to the +inactivation date of the existing one. The publication date is +set to the activation date minus the prepublication interval, which +defaults to 30 days. +.UNINDENT +.INDENT 0.0 +.TP +.B \-t type +This option indicates the type of the key. \fBtype\fP must be one of AUTHCONF, +NOAUTHCONF, NOAUTH, or NOCONF. The default is AUTHCONF. AUTH refers +to the ability to authenticate data, and CONF to the ability to encrypt +data. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v level +This option sets the debugging level. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints version information. +.UNINDENT +.INDENT 0.0 +.TP +.B \-y +This option allows DNSSEC key files to be generated even if the key ID would +collide with that of an existing key, in the event of either key +being revoked. (This is only safe to enable if +\fI\%RFC 5011\fP trust anchor maintenance is not used with either of the keys +involved.) +.UNINDENT +.SH TIMING OPTIONS +.sp +Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS +(which is the format used inside key files), +or \(aqDay Mon DD HH:MM:SS YYYY\(aq (as printed by \fBdnssec\-settime \-p\fP), +or UNIX epoch time (as printed by \fBdnssec\-settime \-up\fP), +or the literal \fBnow\fP\&. +.sp +The argument can be followed by \fB+\fP or \fB\-\fP and an offset from the +given time. The literal \fBnow\fP can be omitted before an offset. The +offset can be followed by one of the suffixes \fBy\fP, \fBmo\fP, \fBw\fP, +\fBd\fP, \fBh\fP, or \fBmi\fP, so that it is computed in years (defined as +365 24\-hour days, ignoring leap years), months (defined as 30 24\-hour +days), weeks, days, hours, or minutes, respectively. Without a suffix, +the offset is computed in seconds. +.sp +To explicitly prevent a date from being set, use \fBnone\fP, \fBnever\fP, +or \fBunset\fP\&. +.sp +All these formats are case\-insensitive. +.INDENT 0.0 +.TP +.B \-P date/offset +This option sets the date on which a key is to be published to the zone. After +that date, the key is included in the zone but is not used +to sign it. If not set, and if the \fI\%\-G\fP option has not been used, the +default is the current date. +.INDENT 7.0 +.TP +.B sync date/offset +This option sets the date on which CDS and CDNSKEY records that match this key +are to be published to the zone. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-A date/offset +This option sets the date on which the key is to be activated. After that date, +the key is included in the zone and used to sign it. If not set, +and if the \fI\%\-G\fP option has not been used, the default is the current date. +.UNINDENT +.INDENT 0.0 +.TP +.B \-R date/offset +This option sets the date on which the key is to be revoked. After that date, the +key is flagged as revoked. It is included in the zone and +is used to sign it. +.UNINDENT +.INDENT 0.0 +.TP +.B \-I date/offset +This option sets the date on which the key is to be retired. After that date, the +key is still included in the zone, but it is not used to +sign it. +.UNINDENT +.INDENT 0.0 +.TP +.B \-D date/offset +This option sets the date on which the key is to be deleted. After that date, the +key is no longer included in the zone. (However, it may remain in the key +repository.) +.INDENT 7.0 +.TP +.B sync date/offset +This option sets the date on which the CDS and CDNSKEY records that match this +key are to be deleted. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-i interval +This option sets the prepublication interval for a key. If set, then the +publication and activation dates must be separated by at least this +much time. If the activation date is specified but the publication +date is not, the publication date defaults to this much time +before the activation date; conversely, if the publication date is +specified but not the activation date, activation is set to +this much time after publication. +.sp +If the key is being created as an explicit successor to another key, +then the default prepublication interval is 30 days; otherwise it is +zero. +.sp +As with date offsets, if the argument is followed by one of the +suffixes \fBy\fP, \fBmo\fP, \fBw\fP, \fBd\fP, \fBh\fP, or \fBmi\fP, the interval is +measured in years, months, weeks, days, hours, or minutes, +respectively. Without a suffix, the interval is measured in seconds. +.UNINDENT +.SH GENERATED KEY FILES +.sp +When \fBdnssec\-keyfromlabel\fP completes successfully, it prints a string +of the form \fBKnnnn.+aaa+iiiii\fP to the standard output. This is an +identification string for the key files it has generated. +.INDENT 0.0 +.IP \(bu 2 +\fBnnnn\fP is the key name. +.IP \(bu 2 +\fBaaa\fP is the numeric representation of the algorithm. +.IP \(bu 2 +\fBiiiii\fP is the key identifier (or footprint). +.UNINDENT +.sp +\fBdnssec\-keyfromlabel\fP creates two files, with names based on the +printed string. \fBKnnnn.+aaa+iiiii.key\fP contains the public key, and +\fBKnnnn.+aaa+iiiii.private\fP contains the private key. +.sp +The \fB\&.key\fP file contains a DNS KEY record that can be inserted into a +zone file (directly or with an $INCLUDE statement). +.sp +The \fB\&.private\fP file contains algorithm\-specific fields. For obvious +security reasons, this file does not have general read permission. +.SH SEE ALSO +.sp +\fI\%dnssec\-keygen(8)\fP, \fI\%dnssec\-signzone(8)\fP, BIND 9 Administrator Reference Manual, +\fI\%RFC 4034\fP, \fI\%RFC 7512\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-keyfromlabel.rst b/doc/man/dnssec-keyfromlabel.rst new file mode 100644 index 0000000..ae00dc0 --- /dev/null +++ b/doc/man/dnssec-keyfromlabel.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dnssec/dnssec-keyfromlabel.rst diff --git a/doc/man/dnssec-keygen.1in b/doc/man/dnssec-keygen.1in new file mode 100644 index 0000000..e5f3034 --- /dev/null +++ b/doc/man/dnssec-keygen.1in @@ -0,0 +1,389 @@ +.\" 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 "DNSSEC-KEYGEN" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dnssec-keygen \- DNSSEC key generation tool +.SH SYNOPSIS +.sp +\fBdnssec\-keygen\fP [\fB\-3\fP] [\fB\-A\fP date/offset] [\fB\-a\fP algorithm] [\fB\-b\fP keysize] [\fB\-C\fP] [\fB\-c\fP class] [\fB\-D\fP date/offset] [\fB\-d\fP bits] [\fB\-D\fP sync date/offset] [\fB\-E\fP engine] [\fB\-f\fP flag] [\fB\-G\fP] [\fB\-g\fP generator] [\fB\-h\fP] [\fB\-I\fP date/offset] [\fB\-i\fP interval] [\fB\-K\fP directory] [\fB\-k\fP policy] [\fB\-L\fP ttl] [\fB\-l\fP file] [\fB\-n\fP nametype] [\fB\-P\fP date/offset] [\fB\-P\fP sync date/offset] [\fB\-p\fP protocol] [\fB\-q\fP] [\fB\-R\fP date/offset] [\fB\-S\fP key] [\fB\-s\fP strength] [\fB\-T\fP rrtype] [\fB\-t\fP type] [\fB\-V\fP] [\fB\-v\fP level] {name} +.SH DESCRIPTION +.sp +\fBdnssec\-keygen\fP generates keys for DNSSEC (Secure DNS), as defined in +\fI\%RFC 2535\fP and \fI\%RFC 4034\fP\&. It can also generate keys for use with TSIG +(Transaction Signatures) as defined in \fI\%RFC 2845\fP, or TKEY (Transaction +Key) as defined in \fI\%RFC 2930\fP\&. +.sp +The \fBname\fP of the key is specified on the command line. For DNSSEC +keys, this must match the name of the zone for which the key is being +generated. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-3 +This option uses an NSEC3\-capable algorithm to generate a DNSSEC key. If this +option is used with an algorithm that has both NSEC and NSEC3 +versions, then the NSEC3 version is selected; for example, +\fBdnssec\-keygen \-3 \-a RSASHA1\fP specifies the NSEC3RSASHA1 algorithm. +.UNINDENT +.INDENT 0.0 +.TP +.B \-a algorithm +This option selects the cryptographic algorithm. For DNSSEC keys, the value of +\fBalgorithm\fP must be one of RSASHA1, NSEC3RSASHA1, RSASHA256, +RSASHA512, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, or ED448. For +TKEY, the value must be DH (Diffie\-Hellman); specifying this value +automatically sets the \fI\%\-T KEY\fP option as well. +.sp +These values are case\-insensitive. In some cases, abbreviations are +supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for +ECDSAP384SHA384. If RSASHA1 is specified along with the \fI\%\-3\fP +option, NSEC3RSASHA1 is used instead. +.sp +This parameter \fImust\fP be specified except when using the \fI\%\-S\fP +option, which copies the algorithm from the predecessor key. +.sp +In prior releases, HMAC algorithms could be generated for use as TSIG +keys, but that feature was removed in BIND 9.13.0. Use +\fI\%tsig\-keygen\fP to generate TSIG keys. +.UNINDENT +.INDENT 0.0 +.TP +.B \-b keysize +This option specifies the number of bits in the key. The choice of key size +depends on the algorithm used: RSA keys must be between 1024 and 4096 +bits; Diffie\-Hellman keys must be between 128 and 4096 bits. Elliptic +curve algorithms do not need this parameter. +.sp +If the key size is not specified, some algorithms have pre\-defined +defaults. For example, RSA keys for use as DNSSEC zone\-signing keys +have a default size of 1024 bits; RSA keys for use as key\-signing +keys (KSKs, generated with \fI\%\-f KSK\fP) default to 2048 bits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-C +This option enables compatibility mode, which generates an old\-style key, without any timing +metadata. By default, \fBdnssec\-keygen\fP includes the key\(aqs +creation date in the metadata stored with the private key; other +dates may be set there as well, including publication date, activation date, +etc. Keys that include this data may be incompatible with older +versions of BIND; the \fI\%\-C\fP option suppresses them. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c class +This option indicates that the DNS record containing the key should have the +specified class. If not specified, class IN is used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-d bits +This option specifies the key size in bits. For the algorithms RSASHA1, NSEC3RSASA1, RSASHA256, and +RSASHA512 the key size must be between 1024 and 4096 bits; DH size is between 128 +and 4096 bits. This option is ignored for algorithms ECDSAP256SHA256, +ECDSAP384SHA384, ED25519, and ED448. +.UNINDENT +.INDENT 0.0 +.TP +.B \-E engine +This option specifies the cryptographic hardware to use, when applicable. +.sp +When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL +engine identifier that drives the cryptographic accelerator or +hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 +.TP +.B \-f flag +This option sets the specified flag in the flag field of the KEY/DNSKEY record. +The only recognized flags are KSK (Key\-Signing Key) and REVOKE. +.UNINDENT +.INDENT 0.0 +.TP +.B \-G +This option generates a key, but does not publish it or sign with it. This option is +incompatible with \fI\%\-P\fP and \fI\%\-A\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-g generator +This option indicates the generator to use if generating a Diffie\-Hellman key. Allowed +values are 2 and 5. If no generator is specified, a known prime from +\fI\%RFC 2539\fP is used if possible; otherwise the default is 2. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option prints a short summary of the options and arguments to +\fBdnssec\-keygen\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-K directory +This option sets the directory in which the key files are to be written. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k policy +This option creates keys for a specific \fBdnssec\-policy\fP\&. If a policy uses multiple keys, +\fBdnssec\-keygen\fP generates multiple keys. This also +creates a \(dq.state\(dq file to keep track of the key state. +.sp +This option creates keys according to the \fBdnssec\-policy\fP configuration, hence +it cannot be used at the same time as many of the other options that +\fBdnssec\-keygen\fP provides. +.UNINDENT +.INDENT 0.0 +.TP +.B \-L ttl +This option sets the default TTL to use for this key when it is converted into a +DNSKEY RR. This is the TTL used when the key is imported into a zone, +unless there was already a DNSKEY RRset in +place, in which case the existing TTL takes precedence. If this +value is not set and there is no existing DNSKEY RRset, the TTL +defaults to the SOA TTL. Setting the default TTL to \fB0\fP or \fBnone\fP +is the same as leaving it unset. +.UNINDENT +.INDENT 0.0 +.TP +.B \-l file +This option provides a configuration file that contains a \fBdnssec\-policy\fP statement +(matching the policy set with \fI\%\-k\fP). +.UNINDENT +.INDENT 0.0 +.TP +.B \-n nametype +This option specifies the owner type of the key. The value of \fBnametype\fP must +either be ZONE (for a DNSSEC zone key (KEY/DNSKEY)), HOST or ENTITY +(for a key associated with a host (KEY)), USER (for a key associated +with a user (KEY)), or OTHER (DNSKEY). These values are +case\-insensitive. The default is ZONE for DNSKEY generation. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p protocol +This option sets the protocol value for the generated key, for use with +\fI\%\-T KEY\fP\&. The protocol is a number between 0 and 255. The default +is 3 (DNSSEC). Other possible values for this argument are listed in +\fI\%RFC 2535\fP and its successors. +.UNINDENT +.INDENT 0.0 +.TP +.B \-q +This option sets quiet mode, which suppresses unnecessary output, including progress +indication. Without this option, when \fBdnssec\-keygen\fP is run +interactively to generate an RSA or DSA key pair, it prints a +string of symbols to \fBstderr\fP indicating the progress of the key +generation. A \fB\&.\fP indicates that a random number has been found which +passed an initial sieve test; \fB+\fP means a number has passed a single +round of the Miller\-Rabin primality test; and a space ( ) means that the +number has passed all the tests and is a satisfactory key. +.UNINDENT +.INDENT 0.0 +.TP +.B \-S key +This option creates a new key which is an explicit successor to an existing key. +The name, algorithm, size, and type of the key are set to match +the existing key. The activation date of the new key is set to +the inactivation date of the existing one. The publication date is +set to the activation date minus the prepublication interval, +which defaults to 30 days. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s strength +This option specifies the strength value of the key. The strength is a number +between 0 and 15, and currently has no defined purpose in DNSSEC. +.UNINDENT +.INDENT 0.0 +.TP +.B \-T rrtype +This option specifies the resource record type to use for the key. \fBrrtype\fP +must be either DNSKEY or KEY. The default is DNSKEY when using a +DNSSEC algorithm, but it can be overridden to KEY for use with +SIG(0). +.UNINDENT +.INDENT 0.0 +.TP +.B \-t type +This option indicates the type of the key for use with \fI\%\-T KEY\fP\&. \fBtype\fP +must be one of AUTHCONF, NOAUTHCONF, NOAUTH, or NOCONF. The default +is AUTHCONF. AUTH refers to the ability to authenticate data, and +CONF to the ability to encrypt data. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints version information. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v level +This option sets the debugging level. +.UNINDENT +.SH TIMING OPTIONS +.sp +Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS +(which is the format used inside key files), +or \(aqDay Mon DD HH:MM:SS YYYY\(aq (as printed by \fBdnssec\-settime \-p\fP), +or UNIX epoch time (as printed by \fBdnssec\-settime \-up\fP), +or the literal \fBnow\fP\&. +.sp +The argument can be followed by \fB+\fP or \fB\-\fP and an offset from the +given time. The literal \fBnow\fP can be omitted before an offset. The +offset can be followed by one of the suffixes \fBy\fP, \fBmo\fP, \fBw\fP, +\fBd\fP, \fBh\fP, or \fBmi\fP, so that it is computed in years (defined as +365 24\-hour days, ignoring leap years), months (defined as 30 24\-hour +days), weeks, days, hours, or minutes, respectively. Without a suffix, +the offset is computed in seconds. +.sp +To unset a date, use \fBnone\fP, \fBnever\fP, or \fBunset\fP\&. +.INDENT 0.0 +.TP +.B \-P date/offset +This option sets the date on which a key is to be published to the zone. After +that date, the key is included in the zone but is not used +to sign it. If not set, and if the \fI\%\-G\fP option has not been used, the +default is the current date. +.INDENT 7.0 +.TP +.B sync date/offset +This option sets the date on which CDS and CDNSKEY records that match this key +are to be published to the zone. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-A date/offset +This option sets the date on which the key is to be activated. After that date, +the key is included in the zone and used to sign it. If not set, +and if the \fI\%\-G\fP option has not been used, the default is the current date. If set, +and \fI\%\-P\fP is not set, the publication date is set to the +activation date minus the prepublication interval. +.UNINDENT +.INDENT 0.0 +.TP +.B \-R date/offset +This option sets the date on which the key is to be revoked. After that date, the +key is flagged as revoked. It is included in the zone and +is used to sign it. +.UNINDENT +.INDENT 0.0 +.TP +.B \-I date/offset +This option sets the date on which the key is to be retired. After that date, the +key is still included in the zone, but it is not used to +sign it. +.UNINDENT +.INDENT 0.0 +.TP +.B \-D date/offset +This option sets the date on which the key is to be deleted. After that date, the +key is no longer included in the zone. (However, it may remain in the key +repository.) +.INDENT 7.0 +.TP +.B sync date/offset +This option sets the date on which the CDS and CDNSKEY records that match this +key are to be deleted. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-i interval +This option sets the prepublication interval for a key. If set, then the +publication and activation dates must be separated by at least this +much time. If the activation date is specified but the publication +date is not, the publication date defaults to this much time +before the activation date; conversely, if the publication date is +specified but not the activation date, activation is set to +this much time after publication. +.sp +If the key is being created as an explicit successor to another key, +then the default prepublication interval is 30 days; otherwise it is +zero. +.sp +As with date offsets, if the argument is followed by one of the +suffixes \fBy\fP, \fBmo\fP, \fBw\fP, \fBd\fP, \fBh\fP, or \fBmi\fP, the interval is +measured in years, months, weeks, days, hours, or minutes, +respectively. Without a suffix, the interval is measured in seconds. +.UNINDENT +.SH GENERATED KEYS +.sp +When \fBdnssec\-keygen\fP completes successfully, it prints a string of the +form \fBKnnnn.+aaa+iiiii\fP to the standard output. This is an +identification string for the key it has generated. +.INDENT 0.0 +.IP \(bu 2 +\fBnnnn\fP is the key name. +.IP \(bu 2 +\fBaaa\fP is the numeric representation of the algorithm. +.IP \(bu 2 +\fBiiiii\fP is the key identifier (or footprint). +.UNINDENT +.sp +\fBdnssec\-keygen\fP creates two files, with names based on the printed +string. \fBKnnnn.+aaa+iiiii.key\fP contains the public key, and +\fBKnnnn.+aaa+iiiii.private\fP contains the private key. +.sp +The \fB\&.key\fP file contains a DNSKEY or KEY record. When a zone is being +signed by \fI\%named\fP or \fI\%dnssec\-signzone \-S\fP, DNSKEY records are +included automatically. In other cases, the \fB\&.key\fP file can be +inserted into a zone file manually or with an \fB$INCLUDE\fP statement. +.sp +The \fB\&.private\fP file contains algorithm\-specific fields. For obvious +security reasons, this file does not have general read permission. +.SH EXAMPLE +.sp +To generate an ECDSAP256SHA256 zone\-signing key for the zone +\fBexample.com\fP, issue the command: +.sp +\fBdnssec\-keygen \-a ECDSAP256SHA256 example.com\fP +.sp +The command prints a string of the form: +.sp +\fBKexample.com.+013+26160\fP +.sp +In this example, \fBdnssec\-keygen\fP creates the files +\fBKexample.com.+013+26160.key\fP and \fBKexample.com.+013+26160.private\fP\&. +.sp +To generate a matching key\-signing key, issue the command: +.sp +\fBdnssec\-keygen \-a ECDSAP256SHA256 \-f KSK example.com\fP +.SH SEE ALSO +.sp +\fI\%dnssec\-signzone(8)\fP, BIND 9 Administrator Reference Manual, \fI\%RFC 2539\fP, +\fI\%RFC 2845\fP, \fI\%RFC 4034\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-keygen.rst b/doc/man/dnssec-keygen.rst new file mode 100644 index 0000000..70e0c54 --- /dev/null +++ b/doc/man/dnssec-keygen.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dnssec/dnssec-keygen.rst diff --git a/doc/man/dnssec-revoke.1in b/doc/man/dnssec-revoke.1in new file mode 100644 index 0000000..edb0c5f --- /dev/null +++ b/doc/man/dnssec-revoke.1in @@ -0,0 +1,97 @@ +.\" 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 "DNSSEC-REVOKE" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dnssec-revoke \- set the REVOKED bit on a DNSSEC key +.SH SYNOPSIS +.sp +\fBdnssec\-revoke\fP [\fB\-hr\fP] [\fB\-v\fP level] [\fB\-V\fP] [\fB\-K\fP directory] [\fB\-E\fP engine] [\fB\-f\fP] [\fB\-R\fP] {keyfile} +.SH DESCRIPTION +.sp +\fBdnssec\-revoke\fP reads a DNSSEC key file, sets the REVOKED bit on the +key as defined in \fI\%RFC 5011\fP, and creates a new pair of key files +containing the now\-revoked key. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-h +This option emits a usage message and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-K directory +This option sets the directory in which the key files are to reside. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r +This option indicates to remove the original keyset files after writing the new keyset files. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v level +This option sets the debugging level. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints version information. +.UNINDENT +.INDENT 0.0 +.TP +.B \-E engine +This option specifies the cryptographic hardware to use, when applicable. +.sp +When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL +engine identifier that drives the cryptographic accelerator or +hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 +.TP +.B \-f +This option indicates a forced overwrite and causes \fBdnssec\-revoke\fP to write the new key pair, +even if a file already exists matching the algorithm and key ID of +the revoked key. +.UNINDENT +.INDENT 0.0 +.TP +.B \-R +This option prints the key tag of the key with the REVOKE bit set, but does not +revoke the key. +.UNINDENT +.SH SEE ALSO +.sp +\fI\%dnssec\-keygen(8)\fP, BIND 9 Administrator Reference Manual, \fI\%RFC 5011\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-revoke.rst b/doc/man/dnssec-revoke.rst new file mode 100644 index 0000000..a5a71ab --- /dev/null +++ b/doc/man/dnssec-revoke.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dnssec/dnssec-revoke.rst diff --git a/doc/man/dnssec-settime.1in b/doc/man/dnssec-settime.1in new file mode 100644 index 0000000..b0862d9 --- /dev/null +++ b/doc/man/dnssec-settime.1in @@ -0,0 +1,296 @@ +.\" 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 "DNSSEC-SETTIME" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dnssec-settime \- set the key timing metadata for a DNSSEC key +.SH SYNOPSIS +.sp +\fBdnssec\-settime\fP [\fB\-f\fP] [\fB\-K\fP directory] [\fB\-L\fP ttl] [\fB\-P\fP date/offset] [\fB\-P\fP ds date/offset] [\fB\-P\fP sync date/offset] [\fB\-A\fP date/offset] [\fB\-R\fP date/offset] [\fB\-I\fP date/offset] [\fB\-D\fP date/offset] [\fB\-D\fP ds date/offset] [\fB\-D\fP sync date/offset] [\fB\-S\fP key] [\fB\-i\fP interval] [\fB\-h\fP] [\fB\-V\fP] [\fB\-v\fP level] [\fB\-E\fP engine] {keyfile} [\fB\-s\fP] [\fB\-g\fP state] [\fB\-d\fP state date/offset] [\fB\-k\fP state date/offset] [\fB\-r\fP state date/offset] [\fB\-z\fP state date/offset] +.SH DESCRIPTION +.sp +\fBdnssec\-settime\fP reads a DNSSEC private key file and sets the key +timing metadata as specified by the \fI\%\-P\fP, \fI\%\-A\fP, \fI\%\-R\fP, +\fI\%\-I\fP, and \fI\%\-D\fP options. The metadata can then be used by +\fI\%dnssec\-signzone\fP or other signing software to determine when a key is +to be published, whether it should be used for signing a zone, etc. +.sp +If none of these options is set on the command line, +\fBdnssec\-settime\fP simply prints the key timing metadata already stored +in the key. +.sp +When key metadata fields are changed, both files of a key pair +(\fBKnnnn.+aaa+iiiii.key\fP and \fBKnnnn.+aaa+iiiii.private\fP) are +regenerated. +.sp +Metadata fields are stored in the private file. A +human\-readable description of the metadata is also placed in comments in +the key file. The private file\(aqs permissions are always set to be +inaccessible to anyone other than the owner (mode 0600). +.sp +When working with state files, it is possible to update the timing metadata in +those files as well with \fI\%\-s\fP\&. With this option, it is also possible +to update key states with \fI\%\-d\fP (DS), \fI\%\-k\fP (DNSKEY), \fI\%\-r\fP +(RRSIG of KSK), or \fI\%\-z\fP (RRSIG of ZSK). Allowed states are HIDDEN, +RUMOURED, OMNIPRESENT, and UNRETENTIVE. +.sp +The goal state of the key can also be set with \fI\%\-g\fP\&. This should be either +HIDDEN or OMNIPRESENT, representing whether the key should be removed from the +zone or published. +.sp +It is NOT RECOMMENDED to manipulate state files manually, except for testing +purposes. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-f +This option forces an update of an old\-format key with no metadata fields. Without +this option, \fBdnssec\-settime\fP fails when attempting to update a +legacy key. With this option, the key is recreated in the new +format, but with the original key data retained. The key\(aqs creation +date is set to the present time. If no other values are +specified, then the key\(aqs publication and activation dates are also +set to the present time. +.UNINDENT +.INDENT 0.0 +.TP +.B \-K directory +This option sets the directory in which the key files are to reside. +.UNINDENT +.INDENT 0.0 +.TP +.B \-L ttl +This option sets the default TTL to use for this key when it is converted into a +DNSKEY RR. This is the TTL used when the key is imported into a zone, +unless there was already a DNSKEY RRset in +place, in which case the existing TTL takes precedence. If this +value is not set and there is no existing DNSKEY RRset, the TTL +defaults to the SOA TTL. Setting the default TTL to \fB0\fP or \fBnone\fP +removes it from the key. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option emits a usage message and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints version information. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v level +This option sets the debugging level. +.UNINDENT +.INDENT 0.0 +.TP +.B \-E engine +This option specifies the cryptographic hardware to use, when applicable. +.sp +When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL +engine identifier that drives the cryptographic accelerator or +hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.SH TIMING OPTIONS +.sp +Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS +(which is the format used inside key files), +or \(aqDay Mon DD HH:MM:SS YYYY\(aq (as printed by \fBdnssec\-settime \-p\fP), +or UNIX epoch time (as printed by \fBdnssec\-settime \-up\fP), +or the literal \fBnow\fP\&. +.sp +The argument can be followed by \fB+\fP or \fB\-\fP and an offset from the +given time. The literal \fBnow\fP can be omitted before an offset. The +offset can be followed by one of the suffixes \fBy\fP, \fBmo\fP, \fBw\fP, +\fBd\fP, \fBh\fP, or \fBmi\fP, so that it is computed in years (defined as +365 24\-hour days, ignoring leap years), months (defined as 30 24\-hour +days), weeks, days, hours, or minutes, respectively. Without a suffix, +the offset is computed in seconds. +.sp +To unset a date, use \fBnone\fP, \fBnever\fP, or \fBunset\fP\&. +.sp +All these formats are case\-insensitive. +.INDENT 0.0 +.TP +.B \-P date/offset +This option sets the date on which a key is to be published to the zone. After +that date, the key is included in the zone but is not used +to sign it. +.INDENT 7.0 +.TP +.B ds date/offset +This option sets the date on which DS records that match this key have been +seen in the parent zone. +.UNINDENT +.INDENT 7.0 +.TP +.B sync date/offset +This option sets the date on which CDS and CDNSKEY records that match this key +are to be published to the zone. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-A date/offset +This option sets the date on which the key is to be activated. After that date, +the key is included in the zone and used to sign it. +.UNINDENT +.INDENT 0.0 +.TP +.B \-R date/offset +This option sets the date on which the key is to be revoked. After that date, the +key is flagged as revoked. It is included in the zone and +is used to sign it. +.UNINDENT +.INDENT 0.0 +.TP +.B \-I date/offset +This option sets the date on which the key is to be retired. After that date, the +key is still included in the zone, but it is not used to +sign it. +.UNINDENT +.INDENT 0.0 +.TP +.B \-D date/offset +This option sets the date on which the key is to be deleted. After that date, the +key is no longer included in the zone. (However, it may remain in the key +repository.) +.INDENT 7.0 +.TP +.B ds date/offset +This option sets the date on which the DS records that match this key have +been seen removed from the parent zone. +.UNINDENT +.INDENT 7.0 +.TP +.B sync date/offset +This option sets the date on which the CDS and CDNSKEY records that match this +key are to be deleted. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-S predecessor key +This option selects a key for which the key being modified is an explicit +successor. The name, algorithm, size, and type of the predecessor key +must exactly match those of the key being modified. The activation +date of the successor key is set to the inactivation date of the +predecessor. The publication date is set to the activation date +minus the prepublication interval, which defaults to 30 days. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i interval +This option sets the prepublication interval for a key. If set, then the +publication and activation dates must be separated by at least this +much time. If the activation date is specified but the publication +date is not, the publication date defaults to this much time +before the activation date; conversely, if the publication date is +specified but not the activation date, activation is set to +this much time after publication. +.sp +If the key is being created as an explicit successor to another key, +then the default prepublication interval is 30 days; otherwise it is +zero. +.sp +As with date offsets, if the argument is followed by one of the +suffixes \fBy\fP, \fBmo\fP, \fBw\fP, \fBd\fP, \fBh\fP, or \fBmi\fP, the interval is +measured in years, months, weeks, days, hours, or minutes, +respectively. Without a suffix, the interval is measured in seconds. +.UNINDENT +.SH KEY STATE OPTIONS +.sp +To test dnssec\-policy it may be necessary to construct keys with artificial +state information; these options are used by the testing framework for that +purpose, but should never be used in production. +.sp +Known key states are HIDDEN, RUMOURED, OMNIPRESENT, and UNRETENTIVE. +.INDENT 0.0 +.TP +.B \-s +This option indicates that when setting key timing data, the state file should also be updated. +.UNINDENT +.INDENT 0.0 +.TP +.B \-g state +This option sets the goal state for this key. Must be HIDDEN or OMNIPRESENT. +.UNINDENT +.INDENT 0.0 +.TP +.B \-d state date/offset +This option sets the DS state for this key as of the specified date, offset from the current date. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k state date/offset +This option sets the DNSKEY state for this key as of the specified date, offset from the current date. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r state date/offset +This option sets the RRSIG (KSK) state for this key as of the specified date, offset from the current date. +.UNINDENT +.INDENT 0.0 +.TP +.B \-z state date/offset +This option sets the RRSIG (ZSK) state for this key as of the specified date, offset from the current date. +.UNINDENT +.SH PRINTING OPTIONS +.sp +\fBdnssec\-settime\fP can also be used to print the timing metadata +associated with a key. +.INDENT 0.0 +.TP +.B \-u +This option indicates that times should be printed in Unix epoch format. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all +This option prints a specific metadata value or set of metadata values. +The \fI\%\-p\fP option may be followed by one or more of the following letters or +strings to indicate which value or values to print: \fBC\fP for the +creation date, \fBP\fP for the publication date, \fBPds\(ga for the DS publication +date, \(ga\(gaPsync\fP for the CDS and CDNSKEY publication date, \fBA\fP for the +activation date, \fBR\fP for the revocation date, \fBI\fP for the inactivation +date, \fBD\fP for the deletion date, \fBDds\fP for the DS deletion date, +and \fBDsync\fP for the CDS and CDNSKEY deletion date. To print all of the +metadata, use \fBall\fP\&. +.UNINDENT +.SH SEE ALSO +.sp +\fI\%dnssec\-keygen(8)\fP, \fI\%dnssec\-signzone(8)\fP, BIND 9 Administrator Reference Manual, +\fI\%RFC 5011\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-settime.rst b/doc/man/dnssec-settime.rst new file mode 100644 index 0000000..c1bb692 --- /dev/null +++ b/doc/man/dnssec-settime.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dnssec/dnssec-settime.rst diff --git a/doc/man/dnssec-signzone.1in b/doc/man/dnssec-signzone.1in new file mode 100644 index 0000000..c60431b --- /dev/null +++ b/doc/man/dnssec-signzone.1in @@ -0,0 +1,515 @@ +.\" 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 "DNSSEC-SIGNZONE" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dnssec-signzone \- DNSSEC zone signing tool +.SH SYNOPSIS +.sp +\fBdnssec\-signzone\fP [\fB\-a\fP] [\fB\-c\fP class] [\fB\-d\fP directory] [\fB\-D\fP] [\fB\-E\fP engine] [\fB\-e\fP end\-time] [\fB\-f\fP output\-file] [\fB\-g\fP] [\fB\-h\fP] [\fB\-i\fP interval] [\fB\-I\fP input\-format] [\fB\-j\fP jitter] [\fB\-K\fP directory] [\fB\-k\fP key] [\fB\-L\fP serial] [\fB\-M\fP maxttl] [\fB\-N\fP soa\-serial\-format] [\fB\-o\fP origin] [\fB\-O\fP output\-format] [\fB\-P\fP] [\fB\-Q\fP] [\fB\-q\fP] [\fB\-R\fP] [\fB\-S\fP] [\fB\-s\fP start\-time] [\fB\-T\fP ttl] [\fB\-t\fP] [\fB\-u\fP] [\fB\-v\fP level] [\fB\-V\fP] [\fB\-X\fP extended end\-time] [\fB\-x\fP] [\fB\-z\fP] [\fB\-3\fP salt] [\fB\-H\fP iterations] [\fB\-A\fP] {zonefile} [key...] +.SH DESCRIPTION +.sp +\fBdnssec\-signzone\fP signs a zone; it generates NSEC and RRSIG records +and produces a signed version of the zone. The security status of +delegations from the signed zone (that is, whether the child zones are +secure) is determined by the presence or absence of a \fBkeyset\fP +file for each child zone. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-a +This option verifies all generated signatures. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c class +This option specifies the DNS class of the zone. +.UNINDENT +.INDENT 0.0 +.TP +.B \-C +This option sets compatibility mode, in which a \fBkeyset\-zonename\fP file is generated in addition +to \fBdsset\-zonename\fP when signing a zone, for use by older versions +of \fBdnssec\-signzone\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-d directory +This option indicates the directory where BIND 9 should look for \fBdsset\-\fP or \fBkeyset\-\fP files. +.UNINDENT +.INDENT 0.0 +.TP +.B \-D +This option indicates that only those record types automatically managed by +\fBdnssec\-signzone\fP, i.e., RRSIG, NSEC, NSEC3 and NSEC3PARAM records, should be included in the output. +If smart signing (\fI\%\-S\fP) is used, DNSKEY records are also included. +The resulting file can be included in the original zone file with +\fB$INCLUDE\fP\&. This option cannot be combined with \fI\%\-O raw\fP +or serial\-number updating. +.UNINDENT +.INDENT 0.0 +.TP +.B \-E engine +This option specifies the hardware to use for cryptographic +operations, such as a secure key store used for signing, when applicable. +.sp +When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL +engine identifier that drives the cryptographic accelerator or +hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 +.TP +.B \-g +This option indicates that DS records for child zones should be generated from a \fBdsset\-\fP or \fBkeyset\-\fP +file. Existing DS records are removed. +.UNINDENT +.INDENT 0.0 +.TP +.B \-K directory +This option specifies the directory to search for DNSSEC keys. If not +specified, it defaults to the current directory. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k key +This option tells BIND 9 to treat the specified key as a key\-signing key, ignoring any key flags. This +option may be specified multiple times. +.UNINDENT +.INDENT 0.0 +.TP +.B \-M maxttl +This option sets the maximum TTL for the signed zone. Any TTL higher than \fBmaxttl\fP +in the input zone is reduced to \fBmaxttl\fP in the output. This +provides certainty as to the largest possible TTL in the signed zone, +which is useful to know when rolling keys. The maxttl is the longest +possible time before signatures that have been retrieved by resolvers +expire from resolver caches. Zones that are signed with this +option should be configured to use a matching \fBmax\-zone\-ttl\fP in +\fI\%named.conf\fP\&. (Note: This option is incompatible with \fI\%\-D\fP, +because it modifies non\-DNSSEC data in the output zone.) +.UNINDENT +.INDENT 0.0 +.TP +.B \-s start\-time +This option specifies the date and time when the generated RRSIG records become +valid. This can be either an absolute or relative time. An absolute +start time is indicated by a number in YYYYMMDDHHMMSS notation; +20000530144500 denotes 14:45:00 UTC on May 30th, 2000. A relative +start time is indicated by \fB+N\fP, which is N seconds from the current +time. If no \fBstart\-time\fP is specified, the current time minus 1 +hour (to allow for clock skew) is used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-e end\-time +This option specifies the date and time when the generated RRSIG records expire. As +with \fBstart\-time\fP, an absolute time is indicated in YYYYMMDDHHMMSS +notation. A time relative to the start time is indicated with \fB+N\fP, +which is N seconds from the start time. A time relative to the +current time is indicated with \fBnow+N\fP\&. If no \fBend\-time\fP is +specified, 30 days from the start time is the default. +\fBend\-time\fP must be later than \fBstart\-time\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-X extended end\-time +This option specifies the date and time when the generated RRSIG records for the +DNSKEY RRset expire. This is to be used in cases when the DNSKEY +signatures need to persist longer than signatures on other records; +e.g., when the private component of the KSK is kept offline and the +KSK signature is to be refreshed manually. +.sp +As with \fBend\-time\fP, an absolute time is indicated in +YYYYMMDDHHMMSS notation. A time relative to the start time is +indicated with \fB+N\fP, which is N seconds from the start time. A time +relative to the current time is indicated with \fBnow+N\fP\&. If no +\fBextended end\-time\fP is specified, the value of \fBend\-time\fP is used +as the default. (\fBend\-time\fP, in turn, defaults to 30 days from the +start time.) \fBextended end\-time\fP must be later than \fBstart\-time\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-f output\-file +This option indicates the name of the output file containing the signed zone. The default +is to append \fB\&.signed\fP to the input filename. If \fBoutput\-file\fP is +set to \fB\-\fP, then the signed zone is written to the standard +output, with a default output format of \fBfull\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option prints a short summary of the options and arguments to +\fBdnssec\-signzone\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints version information. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i interval +This option indicates that, when a previously signed zone is passed as input, records may be +re\-signed. The \fBinterval\fP option specifies the cycle interval as an +offset from the current time, in seconds. If a RRSIG record expires +after the cycle interval, it is retained; otherwise, it is considered +to be expiring soon and it is replaced. +.sp +The default cycle interval is one quarter of the difference between +the signature end and start times. So if neither \fBend\-time\fP nor +\fBstart\-time\fP is specified, \fBdnssec\-signzone\fP generates +signatures that are valid for 30 days, with a cycle interval of 7.5 +days. Therefore, if any existing RRSIG records are due to expire in +less than 7.5 days, they are replaced. +.UNINDENT +.INDENT 0.0 +.TP +.B \-I input\-format +This option sets the format of the input zone file. Possible formats are +\fBtext\fP (the default), and \fBraw\fP\&. This option is primarily +intended to be used for dynamic signed zones, so that the dumped zone +file in a non\-text format containing updates can be signed directly. +This option is not useful for non\-dynamic zones. +.UNINDENT +.INDENT 0.0 +.TP +.B \-j jitter +When signing a zone with a fixed signature lifetime, all RRSIG +records issued at the time of signing expire simultaneously. If the +zone is incrementally signed, i.e., a previously signed zone is passed +as input to the signer, all expired signatures must be regenerated +at approximately the same time. The \fBjitter\fP option specifies a jitter +window that is used to randomize the signature expire time, thus +spreading incremental signature regeneration over time. +.sp +Signature lifetime jitter also, to some extent, benefits validators and +servers by spreading out cache expiration, i.e., if large numbers of +RRSIGs do not expire at the same time from all caches, there is +less congestion than if all validators need to refetch at around the +same time. +.UNINDENT +.INDENT 0.0 +.TP +.B \-L serial +When writing a signed zone to \(dqraw\(dq format, this option sets the \(dqsource +serial\(dq value in the header to the specified \fBserial\fP number. (This is +expected to be used primarily for testing purposes.) +.UNINDENT +.INDENT 0.0 +.TP +.B \-n ncpus +This option specifies the number of threads to use. By default, one thread is +started for each detected CPU. +.UNINDENT +.INDENT 0.0 +.TP +.B \-N soa\-serial\-format +This option sets the SOA serial number format of the signed zone. Possible formats are +\fBkeep\fP (the default), \fBincrement\fP, \fBunixtime\fP, and +\fBdate\fP\&. +.INDENT 7.0 +.TP +\fBkeep\fP +This format indicates that the SOA serial number should not be modified. +.TP +\fBincrement\fP +This format increments the SOA serial number using \fI\%RFC 1982\fP arithmetic. +.TP +\fBunixtime\fP +This format sets the SOA serial number to the number of seconds +since the beginning of the Unix epoch, unless the serial +number is already greater than or equal to that value, in +which case it is simply incremented by one. +.TP +\fBdate\fP +This format sets the SOA serial number to today\(aqs date, in +YYYYMMDDNN format, unless the serial number is already greater +than or equal to that value, in which case it is simply +incremented by one. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-o origin +This option sets the zone origin. If not specified, the name of the zone file is +assumed to be the origin. +.UNINDENT +.INDENT 0.0 +.TP +.B \-O output\-format +This option sets the format of the output file containing the signed +zone. Possible formats are \fBtext\fP (the default), which is the standard +textual representation of the zone; \fBfull\fP, which is text output in a +format suitable for processing by external scripts; and \fBraw\fP and +\fBraw=N\fP, which store the zone in binary formats for rapid loading by +\fI\%named\fP\&. \fBraw=N\fP specifies the format version of the raw zone file: +if N is 0, the raw file can be read by any version of \fI\%named\fP; if N is +1, the file can be read by release 9.9.0 or higher. The default is 1. +.UNINDENT +.INDENT 0.0 +.TP +.B \-P +This option disables post\-sign verification tests. +.sp +The post\-sign verification tests ensure that for each algorithm in +use there is at least one non\-revoked self\-signed KSK key, that all +revoked KSK keys are self\-signed, and that all records in the zone +are signed by the algorithm. This option skips these tests. +.UNINDENT +.INDENT 0.0 +.TP +.B \-Q +This option removes signatures from keys that are no longer active. +.sp +Normally, when a previously signed zone is passed as input to the +signer, and a DNSKEY record has been removed and replaced with a new +one, signatures from the old key that are still within their validity +period are retained. This allows the zone to continue to validate +with cached copies of the old DNSKEY RRset. The \fI\%\-Q\fP option forces +\fBdnssec\-signzone\fP to remove signatures from keys that are no longer +active. This enables ZSK rollover using the procedure described in +\fI\%RFC 4641#4.2.1.1\fP (\(dqPre\-Publish Key Rollover\(dq). +.UNINDENT +.INDENT 0.0 +.TP +.B \-q +This option enables quiet mode, which suppresses unnecessary output. Without this option, when +\fBdnssec\-signzone\fP is run it prints three pieces of information to standard output: the number of +keys in use; the algorithms used to verify the zone was signed correctly and +other status information; and the filename containing the signed +zone. With the option that output is suppressed, leaving only the filename. +.UNINDENT +.INDENT 0.0 +.TP +.B \-R +This option removes signatures from keys that are no longer published. +.sp +This option is similar to \fI\%\-Q\fP, except it forces +\fBdnssec\-signzone\fP to remove signatures from keys that are no longer +published. This enables ZSK rollover using the procedure described in +\fI\%RFC 4641#4.2.1.2\fP (\(dqDouble Signature Zone Signing Key +Rollover\(dq). +.UNINDENT +.INDENT 0.0 +.TP +.B \-S +This option enables smart signing, which instructs \fBdnssec\-signzone\fP to search the key +repository for keys that match the zone being signed, and to include +them in the zone if appropriate. +.sp +When a key is found, its timing metadata is examined to determine how +it should be used, according to the following rules. Each successive +rule takes priority over the prior ones: +.INDENT 7.0 +.INDENT 3.5 +If no timing metadata has been set for the key, the key is +published in the zone and used to sign the zone. +.sp +If the key\(aqs publication date is set and is in the past, the key +is published in the zone. +.sp +If the key\(aqs activation date is set and is in the past, the key is +published (regardless of publication date) and used to sign the +zone. +.sp +If the key\(aqs revocation date is set and is in the past, and the key +is published, then the key is revoked, and the revoked key is used +to sign the zone. +.sp +If either the key\(aqs unpublication or deletion date is set and +in the past, the key is NOT published or used to sign the zone, +regardless of any other metadata. +.sp +If the key\(aqs sync publication date is set and is in the past, +synchronization records (type CDS and/or CDNSKEY) are created. +.sp +If the key\(aqs sync deletion date is set and is in the past, +synchronization records (type CDS and/or CDNSKEY) are removed. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-T ttl +This option specifies a TTL to be used for new DNSKEY records imported into the +zone from the key repository. If not specified, the default is the +TTL value from the zone\(aqs SOA record. This option is ignored when +signing without \fI\%\-S\fP, since DNSKEY records are not imported from +the key repository in that case. It is also ignored if there are any +pre\-existing DNSKEY records at the zone apex, in which case new +records\(aq TTL values are set to match them, or if any of the +imported DNSKEY records had a default TTL value. In the event of a +conflict between TTL values in imported keys, the shortest one is +used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-t +This option prints statistics at completion. +.UNINDENT +.INDENT 0.0 +.TP +.B \-u +This option updates the NSEC/NSEC3 chain when re\-signing a previously signed zone. +With this option, a zone signed with NSEC can be switched to NSEC3, +or a zone signed with NSEC3 can be switched to NSEC or to NSEC3 with +different parameters. Without this option, \fBdnssec\-signzone\fP +retains the existing chain when re\-signing. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v level +This option sets the debugging level. +.UNINDENT +.INDENT 0.0 +.TP +.B \-x +This option indicates that BIND 9 should only sign the DNSKEY, CDNSKEY, and CDS RRsets with key\-signing keys, +and should omit signatures from zone\-signing keys. (This is similar to the +\fBdnssec\-dnskey\-kskonly yes;\fP zone option in \fI\%named\fP\&.) +.UNINDENT +.INDENT 0.0 +.TP +.B \-z +This option indicates that BIND 9 should ignore the KSK flag on keys when determining what to sign. This causes +KSK\-flagged keys to sign all records, not just the DNSKEY RRset. +(This is similar to the \fBupdate\-check\-ksk no;\fP zone option in +\fI\%named\fP\&.) +.UNINDENT +.INDENT 0.0 +.TP +.B \-3 salt +This option generates an NSEC3 chain with the given hex\-encoded salt. A dash +(\-) can be used to indicate that no salt is to be used when +generating the NSEC3 chain. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fB\-3 \-\fP is the recommended configuration. Adding salt provides no practical benefits. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-H iterations +This option indicates that, when generating an NSEC3 chain, BIND 9 should use this many iterations. The default +is 0. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Values greater than 0 cause interoperability issues and also increase the risk of CPU\-exhausting DoS attacks. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-A +This option indicates that, when generating an NSEC3 chain, BIND 9 should set the OPTOUT flag on all NSEC3 +records and should not generate NSEC3 records for insecure delegations. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Do not use this option unless all its implications are fully understood. This option is intended only for extremely large zones (comparable to \fBcom.\fP) with sparse secure delegations. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-AA +This option turns the OPTOUT flag off for +all records. This is useful when using the \fI\%\-u\fP option to modify an +NSEC3 chain which previously had OPTOUT set. +.UNINDENT +.INDENT 0.0 +.TP +.B zonefile +This option sets the file containing the zone to be signed. +.UNINDENT +.INDENT 0.0 +.TP +.B key +This option specifies which keys should be used to sign the zone. If no keys are +specified, the zone is examined for DNSKEY records at the +zone apex. If these records are found and there are matching private keys in +the current directory, they are used for signing. +.UNINDENT +.SH EXAMPLE +.sp +The following command signs the \fBexample.com\fP zone with the +ECDSAP256SHA256 key generated by \fI\%dnssec\-keygen\fP +(Kexample.com.+013+17247). Because the \fI\%\-S\fP option is not being used, +the zone\(aqs keys must be in the master file (\fBdb.example.com\fP). This +invocation looks for \fBdsset\fP files in the current directory, so that +DS records can be imported from them (\fI\%\-g\fP). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +% dnssec\-signzone \-g \-o example.com db.example.com \e +Kexample.com.+013+17247 +db.example.com.signed +% +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In the above example, \fBdnssec\-signzone\fP creates the file +\fBdb.example.com.signed\fP\&. This file should be referenced in a zone +statement in the \fI\%named.conf\fP file. +.sp +This example re\-signs a previously signed zone with default parameters. +The private keys are assumed to be in the current directory. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +% cp db.example.com.signed db.example.com +% dnssec\-signzone \-o example.com db.example.com +db.example.com.signed +% +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fI\%dnssec\-keygen(8)\fP, BIND 9 Administrator Reference Manual, \fI\%RFC 4033\fP, +\fI\%RFC 4641\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-signzone.rst b/doc/man/dnssec-signzone.rst new file mode 100644 index 0000000..b95e04a --- /dev/null +++ b/doc/man/dnssec-signzone.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dnssec/dnssec-signzone.rst diff --git a/doc/man/dnssec-verify.1in b/doc/man/dnssec-verify.1in new file mode 100644 index 0000000..baccdf2 --- /dev/null +++ b/doc/man/dnssec-verify.1in @@ -0,0 +1,128 @@ +.\" 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 "DNSSEC-VERIFY" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dnssec-verify \- DNSSEC zone verification tool +.SH SYNOPSIS +.sp +\fBdnssec\-verify\fP [\fB\-c\fP class] [\fB\-E\fP engine] [\fB\-I\fP input\-format] [\fB\-o\fP origin] [\fB\-q\fP] [\fB\-v\fP level] [\fB\-V\fP] [\fB\-x\fP] [\fB\-z\fP] {zonefile} +.SH DESCRIPTION +.sp +\fBdnssec\-verify\fP verifies that a zone is fully signed for each +algorithm found in the DNSKEY RRset for the zone, and that the +NSEC/NSEC3 chains are complete. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-c class +This option specifies the DNS class of the zone. +.UNINDENT +.INDENT 0.0 +.TP +.B \-E engine +This option specifies the cryptographic hardware to use, when applicable. +.sp +When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL +engine identifier that drives the cryptographic accelerator or +hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 +.TP +.B \-I input\-format +This option sets the format of the input zone file. Possible formats are \fBtext\fP +(the default) and \fBraw\fP\&. This option is primarily intended to be used +for dynamic signed zones, so that the dumped zone file in a non\-text +format containing updates can be verified independently. +This option is not useful for non\-dynamic zones. +.UNINDENT +.INDENT 0.0 +.TP +.B \-o origin +This option indicates the zone origin. If not specified, the name of the zone file is +assumed to be the origin. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v level +This option sets the debugging level. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints version information. +.UNINDENT +.INDENT 0.0 +.TP +.B \-q +This option sets quiet mode, which suppresses output. Without this option, when \fBdnssec\-verify\fP +is run it prints to standard output the number of keys in use, the +algorithms used to verify the zone was signed correctly, and other status +information. With this option, all non\-error output is suppressed, and only the exit +code indicates success. +.UNINDENT +.INDENT 0.0 +.TP +.B \-x +This option verifies only that the DNSKEY RRset is signed with key\-signing keys. +Without this flag, it is assumed that the DNSKEY RRset is signed +by all active keys. When this flag is set, it is not an error if +the DNSKEY RRset is not signed by zone\-signing keys. This corresponds +to the \fI\%\-x option in dnssec\-signzone\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-z +This option indicates that the KSK flag on the keys should be ignored when determining whether the zone is +correctly signed. Without this flag, it is assumed that there is +a non\-revoked, self\-signed DNSKEY with the KSK flag set for each +algorithm, and that RRsets other than DNSKEY RRset are signed with +a different DNSKEY without the KSK flag set. +.sp +With this flag set, BIND 9 only requires that for each algorithm, there +be at least one non\-revoked, self\-signed DNSKEY, regardless of +the KSK flag state, and that other RRsets be signed by a +non\-revoked key for the same algorithm that includes the self\-signed +key; the same key may be used for both purposes. This corresponds to +the \fI\%\-z option in dnssec\-signzone\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B zonefile +This option indicates the file containing the zone to be signed. +.UNINDENT +.SH SEE ALSO +.sp +\fI\%dnssec\-signzone(8)\fP, BIND 9 Administrator Reference Manual, \fI\%RFC 4033\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-verify.rst b/doc/man/dnssec-verify.rst new file mode 100644 index 0000000..c565fed --- /dev/null +++ b/doc/man/dnssec-verify.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dnssec/dnssec-verify.rst diff --git a/doc/man/dnstap-read.1in b/doc/man/dnstap-read.1in new file mode 100644 index 0000000..e122c34 --- /dev/null +++ b/doc/man/dnstap-read.1in @@ -0,0 +1,73 @@ +.\" 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 "DNSTAP-READ" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +dnstap-read \- print dnstap data in human-readable form +.SH SYNOPSIS +.sp +\fBdnstap\-read\fP [\fB\-m\fP] [\fB\-p\fP] [\fB\-x\fP] [\fB\-y\fP] {file} +.SH DESCRIPTION +.sp +\fBdnstap\-read\fP reads \fBdnstap\fP data from a specified file and prints +it in a human\-readable format. By default, \fBdnstap\fP data is printed in +a short summary format, but if the \fI\%\-y\fP option is specified, a +longer and more detailed YAML format is used. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-m +This option indicates trace memory allocations, and is used for debugging memory leaks. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p +This option prints the text form of the DNS +message that was encapsulated in the \fBdnstap\fP frame, after printing the \fBdnstap\fP data. +.UNINDENT +.INDENT 0.0 +.TP +.B \-x +This option prints a hex dump of the wire form +of the DNS message that was encapsulated in the \fBdnstap\fP frame, after printing the \fBdnstap\fP data. +.UNINDENT +.INDENT 0.0 +.TP +.B \-y +This option prints \fBdnstap\fP data in a detailed YAML format. +.UNINDENT +.SH SEE ALSO +.sp +\fI\%named(8)\fP, \fI\%rndc(8)\fP, BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnstap-read.rst b/doc/man/dnstap-read.rst new file mode 100644 index 0000000..9b60739 --- /dev/null +++ b/doc/man/dnstap-read.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/tools/dnstap-read.rst diff --git a/doc/man/filter-a.8in b/doc/man/filter-a.8in new file mode 100644 index 0000000..c67ae70 --- /dev/null +++ b/doc/man/filter-a.8in @@ -0,0 +1,106 @@ +.\" 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 "FILTER-A" "8" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +filter-a \- filter A in DNS responses when AAAA is present +.SH SYNOPSIS +.sp +\fBplugin query\fP \(dqfilter\-a.so\(dq [{ parameters }]; +.SH DESCRIPTION +.sp +\fBfilter\-a.so\fP is a query plugin module for \fI\%named\fP, enabling +\fI\%named\fP to omit some IPv4 addresses when responding to clients. +.sp +For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +plugin query \(dqfilter\-a.so\(dq { + filter\-a\-on\-v6 yes; + filter\-a\-on\-v4 yes; + filter\-a { 192.0.2.1; 2001:db8:2::1; }; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This module is intended to aid transition from IPv4 to IPv6 by +withholding IPv4 addresses from DNS clients which are not connected to +the IPv4 Internet, when the name being looked up has an IPv6 address +available. Use of this module is not recommended unless absolutely +necessary. +.sp +Note: This mechanism can erroneously cause other servers not to give +A records to their clients. If a recursing server with both IPv6 and +IPv4 network connections queries an authoritative server using this +mechanism via IPv6, it is denied A records even if its client is +using IPv4. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fBfilter\-a\fP +This option specifies a list of client addresses for which A filtering is to +be applied. The default is \fBany\fP\&. +.TP +.B \fBfilter\-a\-on\-v6\fP +If set to \fByes\fP, this option indicates that the DNS client is at an IPv6 address, in +\fBfilter\-a\fP\&. If the response does not include DNSSEC +signatures, then all A records are deleted from the response. This +filtering applies to all responses, not only authoritative +ones. +.sp +If set to \fBbreak\-dnssec\fP, then A records are deleted even when +DNSSEC is enabled. As suggested by the name, this causes the response +to fail to verify, because the DNSSEC protocol is designed to detect +deletions. +.sp +This mechanism can erroneously cause other servers not to give A +records to their clients. If a recursing server with both IPv6 and IPv4 +network connections queries an authoritative server using this +mechanism via IPv6, it is denied A records even if its client is +using IPv4. +.TP +.B \fBfilter\-a\-on\-v4\fP +This option is identical to \fBfilter\-a\-on\-v6\fP, except that it filters A responses +to queries from IPv4 clients instead of IPv6 clients. To filter all +responses, set both options to \fByes\fP\&. +.UNINDENT +.SH SEE ALSO +.sp +BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/filter-a.rst b/doc/man/filter-a.rst new file mode 100644 index 0000000..a5c4d40 --- /dev/null +++ b/doc/man/filter-a.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/plugins/filter-a.rst diff --git a/doc/man/filter-aaaa.8in b/doc/man/filter-aaaa.8in new file mode 100644 index 0000000..ad6269a --- /dev/null +++ b/doc/man/filter-aaaa.8in @@ -0,0 +1,110 @@ +.\" 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 "FILTER-AAAA" "8" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +filter-aaaa \- filter AAAA in DNS responses when A is present +.SH SYNOPSIS +.sp +\fBplugin query\fP \(dqfilter\-aaaa.so\(dq [{ parameters }]; +.SH DESCRIPTION +.sp +\fBfilter\-aaaa.so\fP is a query plugin module for \fI\%named\fP, enabling +\fI\%named\fP to omit some IPv6 addresses when responding to clients. +.sp +Until BIND 9.12, this feature was implemented natively in \fI\%named\fP and +enabled with the \fBfilter\-aaaa\fP ACL and the \fBfilter\-aaaa\-on\-v4\fP and +\fBfilter\-aaaa\-on\-v6\fP options. These options are now deprecated in +\fI\%named.conf\fP but can be passed as parameters to the +\fBfilter\-aaaa.so\fP plugin, for example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +plugin query \(dqfilter\-aaaa.so\(dq { + filter\-aaaa\-on\-v4 yes; + filter\-aaaa\-on\-v6 yes; + filter\-aaaa { 192.0.2.1; 2001:db8:2::1; }; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This module is intended to aid transition from IPv4 to IPv6 by +withholding IPv6 addresses from DNS clients which are not connected to +the IPv6 Internet, when the name being looked up has an IPv4 address +available. Use of this module is not recommended unless absolutely +necessary. +.sp +Note: This mechanism can erroneously cause other servers not to give +AAAA records to their clients. If a recursing server with both IPv6 and +IPv4 network connections queries an authoritative server using this +mechanism via IPv4, it is denied AAAA records even if its client is +using IPv6. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fBfilter\-aaaa\fP +This option specifies a list of client addresses for which AAAA filtering is to +be applied. The default is \fBany\fP\&. +.TP +.B \fBfilter\-aaaa\-on\-v4\fP +If set to \fByes\fP, this option indicates that the DNS client is at an IPv4 address, in +\fBfilter\-aaaa\fP\&. If the response does not include DNSSEC +signatures, then all AAAA records are deleted from the response. This +filtering applies to all responses, not only authoritative +ones. +.sp +If set to \fBbreak\-dnssec\fP, then AAAA records are deleted even when +DNSSEC is enabled. As suggested by the name, this causes the response +to fail to verify, because the DNSSEC protocol is designed to detect +deletions. +.sp +This mechanism can erroneously cause other servers not to give AAAA +records to their clients. If a recursing server with both IPv6 and IPv4 +network connections queries an authoritative server using this +mechanism via IPv4, it is denied AAAA records even if its client is +using IPv6. +.TP +.B \fBfilter\-aaaa\-on\-v6\fP +This option is identical to \fBfilter\-aaaa\-on\-v4\fP, except that it filters AAAA responses +to queries from IPv6 clients instead of IPv4 clients. To filter all +responses, set both options to \fByes\fP\&. +.UNINDENT +.SH SEE ALSO +.sp +BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/filter-aaaa.rst b/doc/man/filter-aaaa.rst new file mode 100644 index 0000000..2ad0521 --- /dev/null +++ b/doc/man/filter-aaaa.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/plugins/filter-aaaa.rst diff --git a/doc/man/host.1in b/doc/man/host.1in new file mode 100644 index 0000000..c261da2 --- /dev/null +++ b/doc/man/host.1in @@ -0,0 +1,220 @@ +.\" 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 "HOST" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +host \- DNS lookup utility +.SH SYNOPSIS +.sp +\fBhost\fP [\fB\-aACdlnrsTUwv\fP] [\fB\-c\fP class] [\fB\-N\fP ndots] [\fB\-p\fP port] [\fB\-R\fP number] [\fB\-t\fP type] [\fB\-W\fP wait] [\fB\-m\fP flag] [ [\fB\-4\fP] | [\fB\-6\fP] ] [\fB\-v\fP] [\fB\-V\fP] {name} [server] +.SH DESCRIPTION +.sp +\fBhost\fP is a simple utility for performing DNS lookups. It is normally +used to convert names to IP addresses and vice versa. When no arguments +or options are given, \fBhost\fP prints a short summary of its +command\-line arguments and options. +.sp +\fBname\fP is the domain name that is to be looked up. It can also be a +dotted\-decimal IPv4 address or a colon\-delimited IPv6 address, in which +case \fBhost\fP by default performs a reverse lookup for that address. +\fBserver\fP is an optional argument which is either the name or IP +address of the name server that \fBhost\fP should query instead of the +server or servers listed in \fB/etc/resolv.conf\fP\&. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-4 +This option specifies that only IPv4 should be used for query transport. See also the \fI\%\-6\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-6 +This option specifies that only IPv6 should be used for query transport. See also the \fI\%\-4\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-a +The \fI\%\-a\fP (\(dqall\(dq) option is normally equivalent to \fI\%\-v\fP \fI\%\-t ANY\fP\&. It +also affects the behavior of the \fI\%\-l\fP list zone option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-A +The \fI\%\-A\fP (\(dqalmost all\(dq) option is equivalent to \fI\%\-a\fP, except that RRSIG, +NSEC, and NSEC3 records are omitted from the output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c class +This option specifies the query class, which can be used to lookup HS (Hesiod) or CH (Chaosnet) +class resource records. The default class is IN (Internet). +.UNINDENT +.INDENT 0.0 +.TP +.B \-C +This option indicates that \fI\%named\fP should check consistency, meaning that \fBhost\fP queries the SOA records for zone +\fBname\fP from all the listed authoritative name servers for that +zone. The list of name servers is defined by the NS records that are +found for the zone. +.UNINDENT +.INDENT 0.0 +.TP +.B \-d +This option prints debugging traces, and is equivalent to the \fI\%\-v\fP verbose option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-l +This option tells \fI\%named\fP to list the zone, meaning the \fBhost\fP command performs a zone transfer of zone +\fBname\fP and prints out the NS, PTR, and address records (A/AAAA). +.sp +Together, the \fI\%\-l\fP \fI\%\-a\fP options print all records in the zone. +.UNINDENT +.INDENT 0.0 +.TP +.B \-N ndots +This option specifies the number of dots (\fBndots\fP) that have to be in \fBname\fP for it to be +considered absolute. The default value is that defined using the +\fBndots\fP statement in \fB/etc/resolv.conf\fP, or 1 if no \fBndots\fP statement +is present. Names with fewer dots are interpreted as relative names, +and are searched for in the domains listed in the \fBsearch\fP or +\fBdomain\fP directive in \fB/etc/resolv.conf\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p port +This option specifies the port to query on the server. The default is 53. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r +This option specifies a non\-recursive query; setting this option clears the RD (recursion +desired) bit in the query. This means that the name server +receiving the query does not attempt to resolve \fBname\fP\&. The \fI\%\-r\fP +option enables \fBhost\fP to mimic the behavior of a name server by +making non\-recursive queries, and expecting to receive answers to +those queries that can be referrals to other name servers. +.UNINDENT +.INDENT 0.0 +.TP +.B \-R number +This option specifies the number of retries for UDP queries. If \fBnumber\fP is negative or zero, +the number of retries is silently set to 1. The default value is 1, or +the value of the \fBattempts\fP option in \fB/etc/resolv.conf\fP, if set. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s +This option tells \fI\%named\fP \fInot\fP to send the query to the next nameserver if any server responds +with a SERVFAIL response, which is the reverse of normal stub +resolver behavior. +.UNINDENT +.INDENT 0.0 +.TP +.B \-t type +This option specifies the query type. The \fBtype\fP argument can be any recognized query type: +CNAME, NS, SOA, TXT, DNSKEY, AXFR, etc. +.sp +When no query type is specified, \fBhost\fP automatically selects an +appropriate query type. By default, it looks for A, AAAA, and MX +records. If the \fI\%\-C\fP option is given, queries are made for SOA +records. If \fBname\fP is a dotted\-decimal IPv4 address or +colon\-delimited IPv6 address, \fBhost\fP queries for PTR records. +.sp +If a query type of IXFR is chosen, the starting serial number can be +specified by appending an equals sign (=), followed by the starting serial +number, e.g., \fI\%\-t IXFR=12345678\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-T, \-U +This option specifies TCP or UDP. By default, \fBhost\fP uses UDP when making queries; the +\fI\%\-T\fP option makes it use a TCP connection when querying the name +server. TCP is automatically selected for queries that require +it, such as zone transfer (AXFR) requests. Type \fBANY\fP queries default +to TCP, but can be forced to use UDP initially via \fI\%\-U\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-m flag +This option sets memory usage debugging: the flag can be \fBrecord\fP, \fBusage\fP, or +\fBtrace\fP\&. The \fI\%\-m\fP option can be specified more than once to set +multiple flags. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v +This option sets verbose output, and is equivalent to the \fI\%\-d\fP debug option. Verbose output +can also be enabled by setting the \fBdebug\fP option in +\fB/etc/resolv.conf\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints the version number and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-w +This option sets \(dqwait forever\(dq: the query timeout is set to the maximum possible. See +also the \fI\%\-W\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-W wait +This options sets the length of the wait timeout, indicating that \fI\%named\fP should wait for up to \fBwait\fP seconds for a reply. If \fBwait\fP is +less than 1, the wait interval is set to 1 second. +.sp +By default, \fBhost\fP waits for 5 seconds for UDP responses and 10 +seconds for TCP connections. These defaults can be overridden by the +\fBtimeout\fP option in \fB/etc/resolv.conf\fP\&. +.sp +See also the \fI\%\-w\fP option. +.UNINDENT +.SH IDN SUPPORT +.sp +If \fBhost\fP has been built with IDN (internationalized domain name) +support, it can accept and display non\-ASCII domain names. \fBhost\fP +appropriately converts character encoding of a domain name before sending +a request to a DNS server or displaying a reply from the server. +To turn off IDN support, define the \fBIDN_DISABLE\fP +environment variable. IDN support is disabled if the variable is set +when \fBhost\fP runs. +.SH FILES +.sp +\fB/etc/resolv.conf\fP +.SH SEE ALSO +.sp +\fI\%dig(1)\fP, \fI\%named(8)\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/host.rst b/doc/man/host.rst new file mode 100644 index 0000000..690243d --- /dev/null +++ b/doc/man/host.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dig/host.rst diff --git a/doc/man/index.rst b/doc/man/index.rst new file mode 100644 index 0000000..35fd8d3 --- /dev/null +++ b/doc/man/index.rst @@ -0,0 +1,10 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. diff --git a/doc/man/mdig.1in b/doc/man/mdig.1in new file mode 100644 index 0000000..c3b6a3f --- /dev/null +++ b/doc/man/mdig.1in @@ -0,0 +1,436 @@ +.\" 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 "MDIG" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +mdig \- DNS pipelined lookup utility +.SH SYNOPSIS +.sp +\fBmdig\fP \fI\%{@server\fP} [\fB\-f\fP filename] [\fB\-h\fP] [\fB\-v\fP] [ [\fB\-4\fP] | [\fB\-6\fP] ] [\fB\-m\fP] [\fB\-b\fP address] [\fB\-p\fP port#] [\fB\-c\fP class] [\fB\-t\fP type] [\fB\-i\fP] [\fB\-x\fP addr] [plusopt...] +.sp +\fBmdig\fP {\fB\-h\fP} +.sp +\fBmdig\fP [@server] {global\-opt...} { {local\-opt...} {query} ...} +.SH DESCRIPTION +.sp +\fBmdig\fP is a multiple/pipelined query version of \fI\%dig\fP: instead of +waiting for a response after sending each query, it begins by sending +all queries. Responses are displayed in the order in which they are +received, not in the order the corresponding queries were sent. +.sp +\fBmdig\fP options are a subset of the \fI\%dig\fP options, and are divided +into \(dqanywhere options,\(dq which can occur anywhere, \(dqglobal options,\(dq which +must occur before the query name (or they are ignored with a warning), +and \(dqlocal options,\(dq which apply to the next query on the command line. +.sp +The \fB@server\fP option is a mandatory global option. It is the name or IP +address of the name server to query. (Unlike \fI\%dig\fP, this value is not +retrieved from \fB/etc/resolv.conf\fP\&.) It can be an IPv4 address in +dotted\-decimal notation, an IPv6 address in colon\-delimited notation, or +a hostname. When the supplied \fBserver\fP argument is a hostname, +\fBmdig\fP resolves that name before querying the name server. +.sp +\fBmdig\fP provides a number of query options which affect the way in +which lookups are made and the results displayed. Some of these set or +reset flag bits in the query header, some determine which sections of +the answer get printed, and others determine the timeout and retry +strategies. +.sp +Each query option is identified by a keyword preceded by a plus sign +(\fB+\fP). Some keywords set or reset an option. These may be preceded by +the string \fBno\fP to negate the meaning of that keyword. Other keywords +assign values to options like the timeout interval. They have the form +\fB+keyword=value\fP\&. +.SH ANYWHERE OPTIONS +.INDENT 0.0 +.TP +.B \-f +This option makes \fBmdig\fP operate in batch mode by reading a list +of lookup requests to process from the file \fBfilename\fP\&. The file +contains a number of queries, one per line. Each entry in the file +should be organized in the same way they would be presented as queries +to \fBmdig\fP using the command\-line interface. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option causes \fBmdig\fP to print detailed help information, with the full list +of options, and exit. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v +This option causes \fBmdig\fP to print the version number and exit. +.UNINDENT +.SH GLOBAL OPTIONS +.INDENT 0.0 +.TP +.B \-4 +This option forces \fBmdig\fP to only use IPv4 query transport. +.UNINDENT +.INDENT 0.0 +.TP +.B \-6 +This option forces \fBmdig\fP to only use IPv6 query transport. +.UNINDENT +.INDENT 0.0 +.TP +.B \-b address +This option sets the source IP address of the query to +\fBaddress\fP\&. This must be a valid address on one of the host\(aqs network +interfaces or \(dq0.0.0.0\(dq or \(dq::\(dq. An optional port may be specified by +appending \(dq#\(dq +.UNINDENT +.INDENT 0.0 +.TP +.B \-m +This option enables memory usage debugging. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p port# +This option is used when a non\-standard port number is to be +queried. \fBport#\fP is the port number that \fBmdig\fP sends its +queries to, instead of the standard DNS port number 53. This option is +used to test a name server that has been configured to listen for +queries on a non\-standard port number. +.UNINDENT +.sp +The global query options are: +.INDENT 0.0 +.TP +.B +additional, +noadditional +This option displays [or does not display] the additional section of a reply. The +default is to display it. +.UNINDENT +.INDENT 0.0 +.TP +.B +all, +noall +This option sets or clears all display flags. +.UNINDENT +.INDENT 0.0 +.TP +.B +answer, +noanswer +This option displays [or does not display] the answer section of a reply. The default +is to display it. +.UNINDENT +.INDENT 0.0 +.TP +.B +authority, +noauthority +This option displays [or does not display] the authority section of a reply. The +default is to display it. +.UNINDENT +.INDENT 0.0 +.TP +.B +besteffort, +nobesteffort +This option attempts to display [or does not display] the contents of messages which are malformed. The +default is to not display malformed answers. +.UNINDENT +.INDENT 0.0 +.TP +.B +burst +This option delays queries until the start of the next second. +.UNINDENT +.INDENT 0.0 +.TP +.B +cl, +nocl +This option displays [or does not display] the CLASS when printing the record. +.UNINDENT +.INDENT 0.0 +.TP +.B +comments, +nocomments +This option toggles the display of comment lines in the output. The default is to +print comments. +.UNINDENT +.INDENT 0.0 +.TP +.B +continue, +nocontinue +This option toggles continuation on errors (e.g. timeouts). +.UNINDENT +.INDENT 0.0 +.TP +.B +crypto, +nocrypto +This option toggles the display of cryptographic fields in DNSSEC records. The +contents of these fields are unnecessary to debug most DNSSEC +validation failures and removing them makes it easier to see the +common failures. The default is to display the fields. When omitted, +they are replaced by the string \(dq[omitted]\(dq; in the DNSKEY case, the +key ID is displayed as the replacement, e.g., \fB[ key id = value ]\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +dscp=value +This option formerly set the DSCP value used when sending a query. +It is now obsolete, and has no effect. +.UNINDENT +.INDENT 0.0 +.TP +.B +multiline, +nomultiline +This option toggles printing of records, like the SOA records, in a verbose multi\-line format +with human\-readable comments. The default is to print each record on +a single line, to facilitate machine parsing of the \fBmdig\fP output. +.UNINDENT +.INDENT 0.0 +.TP +.B +question, +noquestion +This option prints [or does not print] the question section of a query when an answer +is returned. The default is to print the question section as a +comment. +.UNINDENT +.INDENT 0.0 +.TP +.B +rrcomments, +norrcomments +This option toggles the display of per\-record comments in the output (for example, +human\-readable key information about DNSKEY records). The default is +not to print record comments unless multiline mode is active. +.UNINDENT +.INDENT 0.0 +.TP +.B +short, +noshort +This option provides [or does not provide] a terse answer. The default is to print the answer in a +verbose form. +.UNINDENT +.INDENT 0.0 +.TP +.B +split=W +This option splits long hex\- or base64\-formatted fields in resource records into +chunks of \fBW\fP characters (where \fBW\fP is rounded up to the nearest +multiple of 4). \fB+nosplit\fP or \fB+split=0\fP causes fields not to be +split. The default is 56 characters, or 44 characters when +multiline mode is active. +.UNINDENT +.INDENT 0.0 +.TP +.B +tcp, +notcp +This option uses [or does not use] TCP when querying name servers. The default behavior +is to use UDP. +.UNINDENT +.INDENT 0.0 +.TP +.B +ttlid, +nottlid +This option displays [or does not display] the TTL when printing the record. +.UNINDENT +.INDENT 0.0 +.TP +.B +ttlunits, +nottlunits +This option displays [or does not display] the TTL in friendly human\-readable time +units of \(dqs\(dq, \(dqm\(dq, \(dqh\(dq, \(dqd\(dq, and \(dqw\(dq, representing seconds, minutes, +hours, days, and weeks. This implies +ttlid. +.UNINDENT +.INDENT 0.0 +.TP +.B +vc, +novc +This option uses [or does not use] TCP when querying name servers. This alternate +syntax to \fI\%+tcp\fP is provided for backwards compatibility. The +\fBvc\fP stands for \(dqvirtual circuit\(dq. +.UNINDENT +.SH LOCAL OPTIONS +.INDENT 0.0 +.TP +.B \-c class +This option sets the query class to \fBclass\fP\&. It can be any valid +query class which is supported in BIND 9. The default query class is +\(dqIN\(dq. +.UNINDENT +.INDENT 0.0 +.TP +.B \-t type +This option sets the query type to \fBtype\fP\&. It can be any valid +query type which is supported in BIND 9. The default query type is \(dqA\(dq, +unless the \fI\%\-x\fP option is supplied to indicate a reverse lookup with +the \(dqPTR\(dq query type. +.UNINDENT +.INDENT 0.0 +.TP +.B \-x addr +Reverse lookups \- mapping addresses to names \- are simplified by +this option. \fBaddr\fP is an IPv4 address in dotted\-decimal +notation, or a colon\-delimited IPv6 address. \fBmdig\fP automatically +performs a lookup for a query name like \fB11.12.13.10.in\-addr.arpa\fP and +sets the query type and class to PTR and IN respectively. By default, +IPv6 addresses are looked up using nibble format under the IP6.ARPA +domain. +.UNINDENT +.sp +The local query options are: +.INDENT 0.0 +.TP +.B +aaflag, +noaaflag +This is a synonym for \fI\%+aaonly\fP, \fI\%+noaaonly\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +aaonly, +noaaonly +This sets the \fBaa\fP flag in the query. +.UNINDENT +.INDENT 0.0 +.TP +.B +adflag, +noadflag +This sets [or does not set] the AD (authentic data) bit in the query. This +requests the server to return whether all of the answer and authority +sections have all been validated as secure, according to the security +policy of the server. AD=1 indicates that all records have been +validated as secure and the answer is not from a OPT\-OUT range. AD=0 +indicates that some part of the answer was insecure or not validated. +This bit is set by default. +.UNINDENT +.INDENT 0.0 +.TP +.B +bufsize=B +This sets the UDP message buffer size advertised using EDNS0 to \fBB\fP +bytes. The maximum and minimum sizes of this buffer are 65535 and 0 +respectively. Values outside this range are rounded up or down +appropriately. Values other than zero cause a EDNS query to be +sent. +.UNINDENT +.INDENT 0.0 +.TP +.B +cdflag, +nocdflag +This sets [or does not set] the CD (checking disabled) bit in the query. This +requests the server to not perform DNSSEC validation of responses. +.UNINDENT +.INDENT 0.0 +.TP +.B +cookie=####, +nocookie +This sends [or does not send] a COOKIE EDNS option, with an optional value. Replaying a COOKIE +from a previous response allows the server to identify a previous +client. The default is \fB+nocookie\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +dnssec, +nodnssec +This requests that DNSSEC records be sent by setting the DNSSEC OK (DO) bit in +the OPT record in the additional section of the query. +.UNINDENT +.INDENT 0.0 +.TP +.B +edns[=#], +noedns +This specifies [or does not specify] the EDNS version to query with. Valid values are 0 to 255. +Setting the EDNS version causes an EDNS query to be sent. +\fB+noedns\fP clears the remembered EDNS version. EDNS is set to 0 by +default. +.UNINDENT +.INDENT 0.0 +.TP +.B +ednsflags[=#], +noednsflags +This sets the must\-be\-zero EDNS flag bits (Z bits) to the specified value. +Decimal, hex, and octal encodings are accepted. Setting a named flag +(e.g. DO) is silently ignored. By default, no Z bits are set. +.UNINDENT +.INDENT 0.0 +.TP +.B +ednsopt[=code[:value]], +noednsopt +This specifies [or does not specify] an EDNS option with code point \fBcode\fP and an optional payload +of \fBvalue\fP as a hexadecimal string. \fB+noednsopt\fP clears the EDNS +options to be sent. +.UNINDENT +.INDENT 0.0 +.TP +.B +expire, +noexpire +This toggles sending of an EDNS Expire option. +.UNINDENT +.INDENT 0.0 +.TP +.B +nsid, +nonsid +This toggles inclusion of an EDNS name server ID request when sending a query. +.UNINDENT +.INDENT 0.0 +.TP +.B +recurse, +norecurse +This toggles the setting of the RD (recursion desired) bit in the query. +This bit is set by default, which means \fBmdig\fP normally sends +recursive queries. +.UNINDENT +.INDENT 0.0 +.TP +.B +retry=T +This sets the number of times to retry UDP queries to server to \fBT\fP +instead of the default, 2. Unlike \fI\%+tries\fP, this does not include +the initial query. +.UNINDENT +.INDENT 0.0 +.TP +.B +subnet=addr[/prefix\-length], +nosubnet +This sends [or does not send] an EDNS Client Subnet option with the specified IP +address or network prefix. +.UNINDENT +.INDENT 0.0 +.TP +.B \fBmdig +subnet=0.0.0.0/0\fP, or simply \fBmdig +subnet=0\fP +This sends an EDNS client\-subnet option with an empty address and a source +prefix\-length of zero, which signals a resolver that the client\(aqs +address information must \fInot\fP be used when resolving this query. +.UNINDENT +.INDENT 0.0 +.TP +.B +timeout=T +This sets the timeout for a query to \fBT\fP seconds. The default timeout is +5 seconds for UDP transport and 10 for TCP. An attempt to set \fBT\fP +to less than 1 results in a query timeout of 1 second being +applied. +.UNINDENT +.INDENT 0.0 +.TP +.B +tries=T +This sets the number of times to try UDP queries to server to \fBT\fP +instead of the default, 3. If \fBT\fP is less than or equal to zero, +the number of tries is silently rounded up to 1. +.UNINDENT +.INDENT 0.0 +.TP +.B +udptimeout=T +This sets the timeout between UDP query retries to \fBT\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B +unknownformat, +nounknownformat +This prints [or does not print] all RDATA in unknown RR\-type presentation format (see \fI\%RFC 3597\fP). +The default is to print RDATA for known types in the type\(aqs +presentation format. +.UNINDENT +.INDENT 0.0 +.TP +.B +yaml, +noyaml +This toggles printing of the responses in a detailed YAML format. +.UNINDENT +.INDENT 0.0 +.TP +.B +zflag, +nozflag +This sets [or does not set] the last unassigned DNS header flag in a DNS query. +This flag is off by default. +.UNINDENT +.SH SEE ALSO +.sp +\fI\%dig(1)\fP, \fI\%RFC 1035\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/mdig.rst b/doc/man/mdig.rst new file mode 100644 index 0000000..351d17f --- /dev/null +++ b/doc/man/mdig.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/tools/mdig.rst diff --git a/doc/man/named-checkconf.1in b/doc/man/named-checkconf.1in new file mode 100644 index 0000000..9c7e1e5 --- /dev/null +++ b/doc/man/named-checkconf.1in @@ -0,0 +1,128 @@ +.\" 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 "NAMED-CHECKCONF" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +named-checkconf \- named configuration file syntax checking tool +.SH SYNOPSIS +.sp +\fBnamed\-checkconf\fP [\fB\-chjlvz\fP] [\fB\-p\fP [\fB\-x\fP ]] [\fB\-t\fP directory] {filename} +.SH DESCRIPTION +.sp +\fBnamed\-checkconf\fP checks the syntax, but not the semantics, of a +\fI\%named\fP configuration file. The file, along with all files included by it, is parsed and checked for syntax +errors. If no file is specified, +\fB@sysconfdir@/named.conf\fP is read by default. +.sp +Note: files that \fI\%named\fP reads in separate parser contexts, such as +\fBrndc.key\fP and \fBbind.keys\fP, are not automatically read by +\fBnamed\-checkconf\fP\&. Configuration errors in these files may cause +\fI\%named\fP to fail to run, even if \fBnamed\-checkconf\fP was successful. +However, \fBnamed\-checkconf\fP can be run on these files explicitly. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-h +This option prints the usage summary and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-j +When loading a zonefile, this option instructs \fI\%named\fP to read the journal if it exists. +.UNINDENT +.INDENT 0.0 +.TP +.B \-l +This option lists all the configured zones. Each line of output contains the zone +name, class (e.g. IN), view, and type (e.g. primary or secondary). +.UNINDENT +.INDENT 0.0 +.TP +.B \-c +This option specifies that only the \(dqcore\(dq configuration should be checked. This suppresses the loading of +plugin modules, and causes all parameters to \fBplugin\fP statements to +be ignored. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i +This option ignores warnings on deprecated options. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p +This option prints out the \fI\%named.conf\fP and included files in canonical form if +no errors were detected. See also the \fI\%\-x\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-t directory +This option instructs \fI\%named\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the +configuration file are processed as if run by a similarly chrooted +\fI\%named\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v +This option prints the version of the \fBnamed\-checkconf\fP program and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-x +When printing the configuration files in canonical form, this option obscures +shared secrets by replacing them with strings of question marks +(\fB?\fP). This allows the contents of \fI\%named.conf\fP and related files +to be shared \- for example, when submitting bug reports \- +without compromising private data. This option cannot be used without +\fI\%\-p\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-z +This option performs a test load of all zones of type \fBprimary\fP found in \fI\%named.conf\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B filename +This indicates the name of the configuration file to be checked. If not specified, +it defaults to \fB@sysconfdir@/named.conf\fP\&. +.UNINDENT +.SH RETURN VALUES +.sp +\fBnamed\-checkconf\fP returns an exit status of 1 if errors were detected +and 0 otherwise. +.SH SEE ALSO +.sp +\fI\%named(8)\fP, \fI\%named\-checkzone(8)\fP, BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/named-checkconf.rst b/doc/man/named-checkconf.rst new file mode 100644 index 0000000..a120b43 --- /dev/null +++ b/doc/man/named-checkconf.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/check/named-checkconf.rst diff --git a/doc/man/named-checkzone.1in b/doc/man/named-checkzone.1in new file mode 100644 index 0000000..b2f50d1 --- /dev/null +++ b/doc/man/named-checkzone.1in @@ -0,0 +1,256 @@ +.\" 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 "NAMED-CHECKZONE" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +named-checkzone \- zone file validity checking or converting tool +.SH SYNOPSIS +.sp +\fBnamed\-checkzone\fP [\fB\-d\fP] [\fB\-h\fP] [\fB\-j\fP] [\fB\-q\fP] [\fB\-v\fP] [\fB\-c\fP class] [\fB\-f\fP format] [\fB\-F\fP format] [\fB\-J\fP filename] [\fB\-i\fP mode] [\fB\-k\fP mode] [\fB\-m\fP mode] [\fB\-M\fP mode] [\fB\-n\fP mode] [\fB\-l\fP ttl] [\fB\-L\fP serial] [\fB\-o\fP filename] [\fB\-r\fP mode] [\fB\-s\fP style] [\fB\-S\fP mode] [\fB\-t\fP directory] [\fB\-T\fP mode] [\fB\-w\fP directory] [\fB\-D\fP] [\fB\-W\fP mode] {zonename} {filename} +.SH DESCRIPTION +.sp +\fBnamed\-checkzone\fP checks the syntax and integrity of a zone file. It +performs the same checks as \fI\%named\fP does when loading a zone. This +makes \fBnamed\-checkzone\fP useful for checking zone files before +configuring them into a name server. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-d +This option enables debugging. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option prints the usage summary and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-q +This option sets quiet mode, which only sets an exit code to indicate +successful or failed completion. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v +This option prints the version of the \fBnamed\-checkzone\fP program and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-j +When loading a zone file, this option tells \fI\%named\fP to read the journal if it exists. The journal +file name is assumed to be the zone file name with the +string \fB\&.jnl\fP appended. +.UNINDENT +.INDENT 0.0 +.TP +.B \-J filename +When loading the zone file, this option tells \fI\%named\fP to read the journal from the given file, if +it exists. This implies \fI\%\-j\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c class +This option specifies the class of the zone. If not specified, \fBIN\fP is assumed. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i mode +This option performs post\-load zone integrity checks. Possible modes are +\fBfull\fP (the default), \fBfull\-sibling\fP, \fBlocal\fP, +\fBlocal\-sibling\fP, and \fBnone\fP\&. +.sp +Mode \fBfull\fP checks that MX records refer to A or AAAA records +(both in\-zone and out\-of\-zone hostnames). Mode \fBlocal\fP only +checks MX records which refer to in\-zone hostnames. +.sp +Mode \fBfull\fP checks that SRV records refer to A or AAAA records +(both in\-zone and out\-of\-zone hostnames). Mode \fBlocal\fP only +checks SRV records which refer to in\-zone hostnames. +.sp +Mode \fBfull\fP checks that delegation NS records refer to A or AAAA +records (both in\-zone and out\-of\-zone hostnames). It also checks that +glue address records in the zone match those advertised by the child. +Mode \fBlocal\fP only checks NS records which refer to in\-zone +hostnames or verifies that some required glue exists, i.e., when the +name server is in a child zone. +.sp +Modes \fBfull\-sibling\fP and \fBlocal\-sibling\fP disable sibling glue +checks, but are otherwise the same as \fBfull\fP and \fBlocal\fP, +respectively. +.sp +Mode \fBnone\fP disables the checks. +.UNINDENT +.INDENT 0.0 +.TP +.B \-f format +This option specifies the format of the zone file. Possible formats are +\fBtext\fP (the default), and \fBraw\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-F format +This option specifies the format of the output file specified. For +\fBnamed\-checkzone\fP, this does not have any effect unless it dumps +the zone contents. +.sp +Possible formats are \fBtext\fP (the default), which is the standard +textual representation of the zone, and \fBraw\fP and \fBraw=N\fP, which +store the zone in a binary format for rapid loading by \fI\%named\fP\&. +\fBraw=N\fP specifies the format version of the raw zone file: if \fBN\fP is +0, the raw file can be read by any version of \fI\%named\fP; if N is 1, the +file can only be read by release 9.9.0 or higher. The default is 1. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k mode +This option performs \fBcheck\-names\fP checks with the specified failure mode. +Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-l ttl +This option sets a maximum permissible TTL for the input file. Any record with a +TTL higher than this value causes the zone to be rejected. This +is similar to using the \fBmax\-zone\-ttl\fP option in \fI\%named.conf\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-L serial +When compiling a zone to \fBraw\fP format, this option sets the \(dqsource +serial\(dq value in the header to the specified serial number. This is +expected to be used primarily for testing purposes. +.UNINDENT +.INDENT 0.0 +.TP +.B \-m mode +This option specifies whether MX records should be checked to see if they are +addresses. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and +\fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-M mode +This option checks whether a MX record refers to a CNAME. Possible modes are +\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-n mode +This option specifies whether NS records should be checked to see if they are +addresses. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-o filename +This option writes the zone output to \fBfilename\fP\&. If \fBfilename\fP is \fB\-\fP, then +the zone output is written to standard output. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r mode +This option checks for records that are treated as different by DNSSEC but are +semantically equal in plain DNS. Possible modes are \fBfail\fP, +\fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s style +This option specifies the style of the dumped zone file. Possible styles are +\fBfull\fP (the default) and \fBrelative\fP\&. The \fBfull\fP format is most +suitable for processing automatically by a separate script. +The relative format is more human\-readable and is thus +suitable for editing by hand. This does not have any effect unless it dumps +the zone contents. It also does not have any meaning if the output format +is not text. +.UNINDENT +.INDENT 0.0 +.TP +.B \-S mode +This option checks whether an SRV record refers to a CNAME. Possible modes are +\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-t directory +This option tells \fI\%named\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the +configuration file are processed as if run by a similarly chrooted +\fI\%named\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-T mode +This option checks whether Sender Policy Framework (SPF) records exist and issues a +warning if an SPF\-formatted TXT record is not also present. Possible +modes are \fBwarn\fP (the default) and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-w directory +This option instructs \fI\%named\fP to chdir to \fBdirectory\fP, so that relative filenames in master file +\fB$INCLUDE\fP directives work. This is similar to the directory clause in +\fI\%named.conf\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-D +This option dumps the zone file in canonical format. +.UNINDENT +.INDENT 0.0 +.TP +.B \-W mode +This option specifies whether to check for non\-terminal wildcards. Non\-terminal +wildcards are almost always the result of a failure to understand the +wildcard matching algorithm (\fI\%RFC 4592\fP). Possible modes are \fBwarn\fP +(the default) and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B zonename +This indicates the domain name of the zone being checked. +.UNINDENT +.INDENT 0.0 +.TP +.B filename +This is the name of the zone file. +.UNINDENT +.SH RETURN VALUES +.sp +\fBnamed\-checkzone\fP returns an exit status of 1 if errors were detected +and 0 otherwise. +.SH SEE ALSO +.sp +\fI\%named(8)\fP, \fI\%named\-checkconf(8)\fP, \fI\%named\-compilezone(8)\fP, \fI\%RFC 1035\fP, BIND 9 Administrator Reference +Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/named-checkzone.rst b/doc/man/named-checkzone.rst new file mode 100644 index 0000000..53d2a00 --- /dev/null +++ b/doc/man/named-checkzone.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/check/named-checkzone.rst diff --git a/doc/man/named-compilezone.1in b/doc/man/named-compilezone.1in new file mode 100644 index 0000000..47842ae --- /dev/null +++ b/doc/man/named-compilezone.1in @@ -0,0 +1,258 @@ +.\" 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 "NAMED-COMPILEZONE" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +named-compilezone \- zone file validity checking or converting tool +.SH SYNOPSIS +.sp +\fBnamed\-compilezone\fP [\fB\-d\fP] [\fB\-h\fP] [\fB\-j\fP] [\fB\-q\fP] [\fB\-v\fP] [\fB\-c\fP class] [\fB\-f\fP format] [\fB\-F\fP format] [\fB\-J\fP filename] [\fB\-i\fP mode] [\fB\-k\fP mode] [\fB\-m\fP mode] [\fB\-M\fP mode] [\fB\-n\fP mode] [\fB\-l\fP ttl] [\fB\-L\fP serial] [\fB\-r\fP mode] [\fB\-s\fP style] [\fB\-S\fP mode] [\fB\-t\fP directory] [\fB\-T\fP mode] [\fB\-w\fP directory] [\fB\-D\fP] [\fB\-W\fP mode] {\fB\-o\fP filename} {zonename} {filename} +.SH DESCRIPTION +.sp +\fBnamed\-compilezone\fP checks the syntax and integrity of a zone file, +and dumps the zone contents to a specified file in a specified format. +It applies strict check levels by default, since the +dump output is used as an actual zone file loaded by \fI\%named\fP\&. +When manually specified otherwise, the check levels must at least be as +strict as those specified in the \fI\%named\fP configuration file. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-d +This option enables debugging. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option prints the usage summary and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-q +This option sets quiet mode, which only sets an exit code to indicate +successful or failed completion. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v +This option prints the version of the \fI\%named\-checkzone\fP program and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-j +When loading a zone file, this option tells \fI\%named\fP to read the journal if it exists. The journal +file name is assumed to be the zone file name with the +string \fB\&.jnl\fP appended. +.UNINDENT +.INDENT 0.0 +.TP +.B \-J filename +When loading the zone file, this option tells \fI\%named\fP to read the journal from the given file, if +it exists. This implies \fI\%\-j\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c class +This option specifies the class of the zone. If not specified, \fBIN\fP is assumed. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i mode +This option performs post\-load zone integrity checks. Possible modes are +\fBfull\fP (the default), \fBfull\-sibling\fP, \fBlocal\fP, +\fBlocal\-sibling\fP, and \fBnone\fP\&. +.sp +Mode \fBfull\fP checks that MX records refer to A or AAAA records +(both in\-zone and out\-of\-zone hostnames). Mode \fBlocal\fP only +checks MX records which refer to in\-zone hostnames. +.sp +Mode \fBfull\fP checks that SRV records refer to A or AAAA records +(both in\-zone and out\-of\-zone hostnames). Mode \fBlocal\fP only +checks SRV records which refer to in\-zone hostnames. +.sp +Mode \fBfull\fP checks that delegation NS records refer to A or AAAA +records (both in\-zone and out\-of\-zone hostnames). It also checks that +glue address records in the zone match those advertised by the child. +Mode \fBlocal\fP only checks NS records which refer to in\-zone +hostnames or verifies that some required glue exists, i.e., when the +name server is in a child zone. +.sp +Modes \fBfull\-sibling\fP and \fBlocal\-sibling\fP disable sibling glue +checks, but are otherwise the same as \fBfull\fP and \fBlocal\fP, +respectively. +.sp +Mode \fBnone\fP disables the checks. +.UNINDENT +.INDENT 0.0 +.TP +.B \-f format +This option specifies the format of the zone file. Possible formats are +\fBtext\fP (the default), and \fBraw\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-F format +This option specifies the format of the output file specified. For +\fI\%named\-checkzone\fP, this does not have any effect unless it dumps +the zone contents. +.sp +Possible formats are \fBtext\fP (the default), which is the standard +textual representation of the zone, and \fBraw\fP and \fBraw=N\fP, which +store the zone in a binary format for rapid loading by \fI\%named\fP\&. +\fBraw=N\fP specifies the format version of the raw zone file: if \fBN\fP is +0, the raw file can be read by any version of \fI\%named\fP; if N is 1, the +file can only be read by release 9.9.0 or higher. The default is 1. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k mode +This option performs \fBcheck\-names\fP checks with the specified failure mode. +Possible modes are \fBfail\fP (the default), \fBwarn\fP, and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-l ttl +This option sets a maximum permissible TTL for the input file. Any record with a +TTL higher than this value causes the zone to be rejected. This +is similar to using the \fBmax\-zone\-ttl\fP option in \fI\%named.conf\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-L serial +When compiling a zone to \fBraw\fP format, this option sets the \(dqsource +serial\(dq value in the header to the specified serial number. This is +expected to be used primarily for testing purposes. +.UNINDENT +.INDENT 0.0 +.TP +.B \-m mode +This option specifies whether MX records should be checked to see if they are +addresses. Possible modes are \fBfail\fP, \fBwarn\fP (the default), and +\fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-M mode +This option checks whether a MX record refers to a CNAME. Possible modes are +\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-n mode +This option specifies whether NS records should be checked to see if they are +addresses. Possible modes are \fBfail\fP (the default), \fBwarn\fP, and +\fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-o filename +This option writes the zone output to \fBfilename\fP\&. If \fBfilename\fP is \fB\-\fP, then +the zone output is written to standard output. This is mandatory for \fBnamed\-compilezone\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r mode +This option checks for records that are treated as different by DNSSEC but are +semantically equal in plain DNS. Possible modes are \fBfail\fP, +\fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s style +This option specifies the style of the dumped zone file. Possible styles are +\fBfull\fP (the default) and \fBrelative\fP\&. The \fBfull\fP format is most +suitable for processing automatically by a separate script. +The relative format is more human\-readable and is thus +suitable for editing by hand. +.UNINDENT +.INDENT 0.0 +.TP +.B \-S mode +This option checks whether an SRV record refers to a CNAME. Possible modes are +\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-t directory +This option tells \fI\%named\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the +configuration file are processed as if run by a similarly chrooted +\fI\%named\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-T mode +This option checks whether Sender Policy Framework (SPF) records exist and issues a +warning if an SPF\-formatted TXT record is not also present. Possible +modes are \fBwarn\fP (the default) and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-w directory +This option instructs \fI\%named\fP to chdir to \fBdirectory\fP, so that relative filenames in master file +\fB$INCLUDE\fP directives work. This is similar to the directory clause in +\fI\%named.conf\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-D +This option dumps the zone file in canonical format. This is always enabled for +\fBnamed\-compilezone\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-W mode +This option specifies whether to check for non\-terminal wildcards. Non\-terminal +wildcards are almost always the result of a failure to understand the +wildcard matching algorithm (\fI\%RFC 4592\fP). Possible modes are \fBwarn\fP +(the default) and \fBignore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B zonename +This indicates the domain name of the zone being checked. +.UNINDENT +.INDENT 0.0 +.TP +.B filename +This is the name of the zone file. +.UNINDENT +.SH RETURN VALUES +.sp +\fBnamed\-compilezone\fP returns an exit status of 1 if errors were detected +and 0 otherwise. +.SH SEE ALSO +.sp +\fI\%named(8)\fP, \fI\%named\-checkconf(8)\fP, \fI\%named\-checkzone(8)\fP, \fI\%RFC 1035\fP, +BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/named-compilezone.rst b/doc/man/named-compilezone.rst new file mode 100644 index 0000000..9d3cae6 --- /dev/null +++ b/doc/man/named-compilezone.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/check/named-compilezone.rst diff --git a/doc/man/named-journalprint.1in b/doc/man/named-journalprint.1in new file mode 100644 index 0000000..14b9e6f --- /dev/null +++ b/doc/man/named-journalprint.1in @@ -0,0 +1,79 @@ +.\" 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 "NAMED-JOURNALPRINT" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +named-journalprint \- print zone journal in human-readable form +.SH SYNOPSIS +.sp +\fBnamed\-journalprint\fP [\-c serial] [\fB\-dux\fP] {journal} +.SH DESCRIPTION +.sp +\fBnamed\-journalprint\fP scans the contents of a zone journal file, +printing it in a human\-readable form, or, optionally, converting it +to a different journal file format. +.sp +Journal files are automatically created by \fI\%named\fP when changes are +made to dynamic zones (e.g., by \fI\%nsupdate\fP). They record each addition +or deletion of a resource record, in binary format, allowing the changes +to be re\-applied to the zone when the server is restarted after a +shutdown or crash. By default, the name of the journal file is formed by +appending the extension \fB\&.jnl\fP to the name of the corresponding zone +file. +.sp +\fBnamed\-journalprint\fP converts the contents of a given journal file +into a human\-readable text format. Each line begins with \fBadd\fP or \fBdel\fP, +to indicate whether the record was added or deleted, and continues with +the resource record in master\-file format. +.sp +The \fB\-c\fP (compact) option provides a mechanism to reduce the size of +a journal by removing (most/all) transactions prior to the specified +serial number. Note: this option \fImust not\fP be used while \fI\%named\fP is +running, and can cause data loss if the zone file has not been updated +to contain the data being removed from the journal. Use with extreme caution. +.sp +The \fB\-x\fP option causes additional data about the journal file to be +printed at the beginning of the output and before each group of changes. +.sp +The \fB\-u\fP (upgrade) and \fB\-d\fP (downgrade) options recreate the journal +file with a modified format version. The existing journal file is +replaced. \fB\-d\fP writes out the journal in the format used by +versions of BIND up to 9.16.11; \fB\-u\fP writes it out in the format used +by versions since 9.16.13. (9.16.12 is omitted due to a journal\-formatting +bug in that release.) Note that these options \fImust not\fP be used while +\fI\%named\fP is running. +.SH SEE ALSO +.sp +\fI\%named(8)\fP, \fI\%nsupdate(1)\fP, BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/named-journalprint.rst b/doc/man/named-journalprint.rst new file mode 100644 index 0000000..9317f7b --- /dev/null +++ b/doc/man/named-journalprint.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/tools/named-journalprint.rst diff --git a/doc/man/named-nzd2nzf.1in b/doc/man/named-nzd2nzf.1in new file mode 100644 index 0000000..b39acb4 --- /dev/null +++ b/doc/man/named-nzd2nzf.1in @@ -0,0 +1,57 @@ +.\" 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 "NAMED-NZD2NZF" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +named-nzd2nzf \- convert an NZD database to NZF text format +.SH SYNOPSIS +.sp +\fBnamed\-nzd2nzf\fP {filename} +.SH DESCRIPTION +.sp +\fBnamed\-nzd2nzf\fP converts an NZD database to NZF format and prints it +to standard output. This can be used to review the configuration of +zones that were added to \fI\%named\fP via \fI\%rndc addzone\fP\&. It can also be +used to restore the old file format when rolling back from a newer +version of BIND to an older version. +.SH ARGUMENTS +.INDENT 0.0 +.TP +.B filename +This is the name of the \fB\&.nzd\fP file whose contents should be printed. +.UNINDENT +.SH SEE ALSO +.sp +BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/named-nzd2nzf.rst b/doc/man/named-nzd2nzf.rst new file mode 100644 index 0000000..10d59e9 --- /dev/null +++ b/doc/man/named-nzd2nzf.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/tools/named-nzd2nzf.rst diff --git a/doc/man/named-rrchecker.1in b/doc/man/named-rrchecker.1in new file mode 100644 index 0000000..39196e0 --- /dev/null +++ b/doc/man/named-rrchecker.1in @@ -0,0 +1,78 @@ +.\" 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 "NAMED-RRCHECKER" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +named-rrchecker \- syntax checker for individual DNS resource records +.SH SYNOPSIS +.sp +\fBnamed\-rrchecker\fP [\fB\-h\fP] [\fB\-o\fP origin] [\fB\-p\fP] [\fB\-u\fP] [\fB\-C\fP] [\fB\-T\fP] [\fB\-P\fP] +.SH DESCRIPTION +.sp +\fBnamed\-rrchecker\fP reads a individual DNS resource record from standard +input and checks whether it is syntactically correct. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-h +This option prints out the help menu. +.UNINDENT +.INDENT 0.0 +.TP +.B \-o origin +This option specifies the origin to be used when interpreting +the record. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p +This option prints out the resulting record in canonical form. If there +is no canonical form defined, the record is printed in unknown +record format. +.UNINDENT +.INDENT 0.0 +.TP +.B \-u +This option prints out the resulting record in unknown record form. +.UNINDENT +.INDENT 0.0 +.TP +.B \-C, \-T, \-P +These options print out the known class, standard type, +and private type mnemonics, respectively. +.UNINDENT +.SH SEE ALSO +.sp +\fI\%RFC 1034\fP, \fI\%RFC 1035\fP, \fI\%named(8)\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/named-rrchecker.rst b/doc/man/named-rrchecker.rst new file mode 100644 index 0000000..fff9f82 --- /dev/null +++ b/doc/man/named-rrchecker.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/tools/named-rrchecker.rst diff --git a/doc/man/named.8in b/doc/man/named.8in new file mode 100644 index 0000000..b33c7db --- /dev/null +++ b/doc/man/named.8in @@ -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 "NAMED" "8" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +named \- Internet domain name server +.SH SYNOPSIS +.sp +\fBnamed\fP [ [\fB\-4\fP] | [\fB\-6\fP] ] [\fB\-c\fP config\-file] [\fB\-C\fP] [\fB\-d\fP debug\-level] [\fB\-D\fP string] [\fB\-E\fP engine\-name] [\fB\-f\fP] [\fB\-g\fP] [\fB\-L\fP logfile] [\fB\-M\fP option] [\fB\-m\fP flag] [\fB\-n\fP #cpus] [\fB\-p\fP port] [\fB\-s\fP] [\fB\-t\fP directory] [\fB\-U\fP #listeners] [\fB\-u\fP user] [\fB\-v\fP] [\fB\-V\fP] [\fB\-X\fP lock\-file] +.SH DESCRIPTION +.sp +\fBnamed\fP is a Domain Name System (DNS) server, part of the BIND 9 +distribution from ISC. For more information on the DNS, see \fI\%RFC 1033\fP, +\fI\%RFC 1034\fP, and \fI\%RFC 1035\fP\&. +.sp +When invoked without arguments, \fBnamed\fP reads the default +configuration file \fB@sysconfdir@/named.conf\fP, reads any initial data, and +listens for queries. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-4 +This option tells \fBnamed\fP to use only IPv4, even if the host machine is capable of IPv6. \fI\%\-4\fP and +\fI\%\-6\fP are mutually exclusive. +.UNINDENT +.INDENT 0.0 +.TP +.B \-6 +This option tells \fBnamed\fP to use only IPv6, even if the host machine is capable of IPv4. \fI\%\-4\fP and +\fI\%\-6\fP are mutually exclusive. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c config\-file +This option tells \fBnamed\fP to use \fBconfig\-file\fP as its configuration file instead of the default, +\fB@sysconfdir@/named.conf\fP\&. To ensure that the configuration file +can be reloaded after the server has changed its working directory +due to to a possible \fBdirectory\fP option in the configuration file, +\fBconfig\-file\fP should be an absolute pathname. +.UNINDENT +.INDENT 0.0 +.TP +.B \-C +This option prints out the default built\-in configuration and exits. +.sp +NOTE: This is for debugging purposes only and is not an +accurate representation of the actual configuration used by \fI\%named\fP +at runtime. +.UNINDENT +.INDENT 0.0 +.TP +.B \-d debug\-level +This option sets the daemon\(aqs debug level to \fBdebug\-level\fP\&. Debugging traces from +\fBnamed\fP become more verbose as the debug level increases. +.UNINDENT +.INDENT 0.0 +.TP +.B \-D string +This option specifies a string that is used to identify a instance of \fBnamed\fP +in a process listing. The contents of \fBstring\fP are not examined. +.UNINDENT +.INDENT 0.0 +.TP +.B \-E engine\-name +When applicable, this option specifies the hardware to use for cryptographic +operations, such as a secure key store used for signing. +.sp +When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL +engine identifier that drives the cryptographic accelerator or +hardware service module (usually \fBpkcs11\fP). +.UNINDENT +.INDENT 0.0 +.TP +.B \-f +This option runs the server in the foreground (i.e., do not daemonize). +.UNINDENT +.INDENT 0.0 +.TP +.B \-g +This option runs the server in the foreground and forces all logging to \fBstderr\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-L logfile +This option sets the log to the file \fBlogfile\fP by default, instead of the system log. +.UNINDENT +.INDENT 0.0 +.TP +.B \-M option +This option sets the default (comma\-separated) memory context +options. The possible flags are: +.INDENT 7.0 +.IP \(bu 2 +\fBfill\fP: fill blocks of memory with tag values when they are +allocated or freed, to assist debugging of memory problems; this is +the implicit default if \fBnamed\fP has been compiled with +\fB\-\-enable\-developer\fP\&. +.IP \(bu 2 +\fBnofill\fP: disable the behavior enabled by \fBfill\fP; this is the +implicit default unless \fBnamed\fP has been compiled with +\fB\-\-enable\-developer\fP\&. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-m flag +This option turns on memory usage debugging flags. Possible flags are \fBusage\fP, +\fBtrace\fP, \fBrecord\fP, \fBsize\fP, and \fBmctx\fP\&. These correspond to the +\fBISC_MEM_DEBUGXXXX\fP flags described in \fB\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-n #cpus +This option creates \fB#cpus\fP worker threads to take advantage of multiple CPUs. If +not specified, \fBnamed\fP tries to determine the number of CPUs +present and creates one thread per CPU. If it is unable to determine +the number of CPUs, a single worker thread is created. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p value +This option specifies the port(s) on which the server will listen +for queries. If \fBvalue\fP is of the form \fB\fP or +\fBdns=\fP, the server will listen for DNS queries on +\fBportnum\fP; if not not specified, the default is port 53. If +\fBvalue\fP is of the form \fBtls=\fP, the server will +listen for TLS queries on \fBportnum\fP; the default is 853. +If \fBvalue\fP is of the form \fBhttps=\fP, the server will +listen for HTTPS queries on \fBportnum\fP; the default is 443. +If \fBvalue\fP is of the form \fBhttp=\fP, the server will +listen for HTTP queries on \fBportnum\fP; the default is 80. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s +This option writes memory usage statistics to \fBstdout\fP on exit. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is mainly of interest to BIND 9 developers and may be +removed or changed in a future release. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-S #max\-socks +This option is deprecated and no longer has any function. +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This option should be unnecessary for the vast majority of users. +The use of this option could even be harmful, because the specified +value may exceed the limitation of the underlying system API. It +is therefore set only when the default configuration causes +exhaustion of file descriptors and the operational environment is +known to support the specified number of sockets. Note also that +the actual maximum number is normally slightly fewer than the +specified value, because \fBnamed\fP reserves some file descriptors +for its internal use. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-t directory +This option tells \fBnamed\fP to chroot to \fBdirectory\fP after processing the command\-line arguments, but +before reading the configuration file. +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This option should be used in conjunction with the \fI\%\-u\fP option, +as chrooting a process running as root doesn\(aqt enhance security on +most systems; the way \fBchroot\fP is defined allows a process +with root privileges to escape a chroot jail. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-U #listeners +This option tells \fBnamed\fP the number of \fB#listeners\fP worker threads to listen on, for incoming UDP packets on +each address. If not specified, \fBnamed\fP calculates a default +value based on the number of detected CPUs: 1 for 1 CPU, and the +number of detected CPUs minus one for machines with more than 1 CPU. +This cannot be increased to a value higher than the number of CPUs. +If \fI\%\-n\fP has been set to a higher value than the number of detected +CPUs, then \fI\%\-U\fP may be increased as high as that value, but no +higher. +.UNINDENT +.INDENT 0.0 +.TP +.B \-u user +This option sets the setuid to \fBuser\fP after completing privileged operations, such as +creating sockets that listen on privileged ports. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +On Linux, \fBnamed\fP uses the kernel\(aqs capability mechanism to drop +all root privileges except the ability to \fBbind\fP to a +privileged port and set process resource limits. Unfortunately, +this means that the \fI\%\-u\fP option only works when \fBnamed\fP is run +on kernel 2.2.18 or later, or kernel 2.3.99\-pre3 or later, since +previous kernels did not allow privileges to be retained after +\fBsetuid\fP\&. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-v +This option reports the version number and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option reports the version number, build options, supported +cryptographics algorithms, and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-X lock\-file +This option acquires a lock on the specified file at runtime; this helps to +prevent duplicate \fBnamed\fP instances from running simultaneously. +Use of this option overrides the \fBlock\-file\fP option in +\fI\%named.conf\fP\&. If set to \fBnone\fP, the lock file check is disabled. +.UNINDENT +.SH SIGNALS +.sp +In routine operation, signals should not be used to control the +nameserver; \fI\%rndc\fP should be used instead. +.INDENT 0.0 +.TP +.B SIGHUP +This signal forces a reload of the server. +.TP +.B SIGINT, SIGTERM +These signals shut down the server. +.UNINDENT +.sp +The result of sending any other signals to the server is undefined. +.SH CONFIGURATION +.sp +The \fBnamed\fP configuration file is too complex to describe in detail +here. A complete description is provided in the BIND 9 Administrator +Reference Manual. +.sp +\fBnamed\fP inherits the \fBumask\fP (file creation mode mask) from the +parent process. If files created by \fBnamed\fP, such as journal files, +need to have custom permissions, the \fBumask\fP should be set explicitly +in the script used to start the \fBnamed\fP process. +.SH FILES +.INDENT 0.0 +.TP +.B \fB@sysconfdir@/named.conf\fP +The default configuration file. +.TP +.B \fB@runstatedir@/named.pid\fP +The default process\-id file. +.UNINDENT +.SH SEE ALSO +.sp +\fI\%RFC 1033\fP, \fI\%RFC 1034\fP, \fI\%RFC 1035\fP, \fI\%named\-checkconf(8)\fP, \fI\%named\-checkzone(8)\fP, \fI\%rndc(8)\fP, \fI\%named.conf(5)\fP, BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/named.conf.5in b/doc/man/named.conf.5in new file mode 100644 index 0000000..c5619dc --- /dev/null +++ b/doc/man/named.conf.5in @@ -0,0 +1,1012 @@ +.\" 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 "NAMED.CONF" "5" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +named.conf \- configuration file for **named** +.SH SYNOPSIS +.sp +\fBnamed.conf\fP +.SH DESCRIPTION +.sp +\fBnamed.conf\fP is the configuration file for \fI\%named\fP\&. +.sp +For complete documentation about the configuration statements, please refer to +the Configuration Reference section in the BIND 9 Administrator Reference +Manual. +.sp +Statements are enclosed in braces and terminated with a semi\-colon. +Clauses in the statements are also semi\-colon terminated. The usual +comment styles are supported: +.sp +C style: /* */ +.sp +C++ style: // to end of line +.sp +Unix style: # to end of line +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +acl { ; ... }; // may occur multiple times + +controls { + inet ( | | * ) [ port ( | * ) ] allow { ; ... } [ keys { ; ... } ] [ read\-only ]; // may occur multiple times + unix perm owner group [ keys { ; ... } ] [ read\-only ]; // may occur multiple times +}; // may occur multiple times + +dlz { + database ; + search ; +}; // may occur multiple times + +dnssec\-policy { + dnskey\-ttl ; + keys { ( csk | ksk | zsk ) [ ( key\-directory ) ] lifetime algorithm [ ]; ... }; + max\-zone\-ttl ; + nsec3param [ iterations ] [ optout ] [ salt\-length ]; + parent\-ds\-ttl ; + parent\-propagation\-delay ; + parent\-registration\-delay ; // obsolete + publish\-safety ; + purge\-keys ; + retire\-safety ; + signatures\-refresh ; + signatures\-validity ; + signatures\-validity\-dnskey ; + zone\-propagation\-delay ; +}; // may occur multiple times + +dyndb { }; // may occur multiple times + +http { + endpoints { ; ... }; + listener\-clients ; + streams\-per\-connection ; +}; // may occur multiple times + +key { + algorithm ; + secret ; +}; // may occur multiple times + +logging { + category { ; ... }; // may occur multiple times + channel { + buffered ; + file [ versions ( unlimited | ) ] [ size ] [ suffix ( increment | timestamp ) ]; + null; + print\-category ; + print\-severity ; + print\-time ( iso8601 | iso8601\-utc | local | ); + severity ; + stderr; + syslog [ ]; + }; // may occur multiple times +}; + +managed\-keys { ( static\-key | initial\-key | static\-ds | initial\-ds ) ; ... }; // may occur multiple times, deprecated + +options { + allow\-new\-zones ; + allow\-notify { ; ... }; + allow\-query { ; ... }; + allow\-query\-cache { ; ... }; + allow\-query\-cache\-on { ; ... }; + allow\-query\-on { ; ... }; + allow\-recursion { ; ... }; + allow\-recursion\-on { ; ... }; + allow\-transfer [ port ] [ transport ] { ; ... }; + allow\-update { ; ... }; + allow\-update\-forwarding { ; ... }; + also\-notify [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + alt\-transfer\-source ( | * ) ; // deprecated + alt\-transfer\-source\-v6 ( | * ) ; // deprecated + answer\-cookie ; + attach\-cache ; + auth\-nxdomain ; + auto\-dnssec ( allow | maintain | off ); // deprecated + automatic\-interface\-scan ; + avoid\-v4\-udp\-ports { ; ... }; // deprecated + avoid\-v6\-udp\-ports { ; ... }; // deprecated + bindkeys\-file ; + blackhole { ; ... }; + catalog\-zones { zone [ default\-primaries [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... } ] [ zone\-directory ] [ in\-memory ] [ min\-update\-interval ]; ... }; + check\-dup\-records ( fail | warn | ignore ); + check\-integrity ; + check\-mx ( fail | warn | ignore ); + check\-mx\-cname ( fail | warn | ignore ); + check\-names ( primary | master | secondary | slave | response ) ( fail | warn | ignore ); // may occur multiple times + check\-sibling ; + check\-spf ( warn | ignore ); + check\-srv\-cname ( fail | warn | ignore ); + check\-wildcard ; + clients\-per\-query ; + cookie\-algorithm ( aes | siphash24 ); + cookie\-secret ; // may occur multiple times + coresize ( default | unlimited | ); // deprecated + datasize ( default | unlimited | ); // deprecated + deny\-answer\-addresses { ; ... } [ except\-from { ; ... } ]; + deny\-answer\-aliases { ; ... } [ except\-from { ; ... } ]; + dialup ( notify | notify\-passive | passive | refresh | ); // deprecated + directory ; + disable\-algorithms { ; ... }; // may occur multiple times + disable\-ds\-digests { ; ... }; // may occur multiple times + disable\-empty\-zone ; // may occur multiple times + dns64 { + break\-dnssec ; + clients { ; ... }; + exclude { ; ... }; + mapped { ; ... }; + recursive\-only ; + suffix ; + }; // may occur multiple times + dns64\-contact ; + dns64\-server ; + dnskey\-sig\-validity ; + dnsrps\-enable ; // not configured + dnsrps\-options { }; // not configured + dnssec\-accept\-expired ; + dnssec\-dnskey\-kskonly ; + dnssec\-loadkeys\-interval ; + dnssec\-must\-be\-secure ; // may occur multiple times, deprecated + dnssec\-policy ; + dnssec\-secure\-to\-insecure ; + dnssec\-update\-mode ( maintain | no\-resign ); + dnssec\-validation ( yes | no | auto ); + dnstap { ( all | auth | client | forwarder | resolver | update ) [ ( query | response ) ]; ... }; // not configured + dnstap\-identity ( | none | hostname ); // not configured + dnstap\-output ( file | unix ) [ size ( unlimited | ) ] [ versions ( unlimited | ) ] [ suffix ( increment | timestamp ) ]; // not configured + dnstap\-version ( | none ); // not configured + dscp ; // obsolete + dual\-stack\-servers [ port ] { ( [ port ] | [ port ] | [ port ] ); ... }; + dump\-file ; + edns\-udp\-size ; + empty\-contact ; + empty\-server ; + empty\-zones\-enable ; + fetch\-quota\-params ; + fetches\-per\-server [ ( drop | fail ) ]; + fetches\-per\-zone [ ( drop | fail ) ]; + files ( default | unlimited | ); // deprecated + flush\-zones\-on\-shutdown ; + forward ( first | only ); + forwarders [ port ] { ( | ) [ port ]; ... }; + fstrm\-set\-buffer\-hint ; // not configured + fstrm\-set\-flush\-timeout ; // not configured + fstrm\-set\-input\-queue\-size ; // not configured + fstrm\-set\-output\-notify\-threshold ; // not configured + fstrm\-set\-output\-queue\-model ( mpsc | spsc ); // not configured + fstrm\-set\-output\-queue\-size ; // not configured + fstrm\-set\-reopen\-interval ; // not configured + geoip\-directory ( | none ); + glue\-cache ; // deprecated + heartbeat\-interval ; // deprecated + hostname ( | none ); + http\-listener\-clients ; + http\-port ; + http\-streams\-per\-connection ; + https\-port ; + interface\-interval ; + ipv4only\-contact ; + ipv4only\-enable ; + ipv4only\-server ; + ixfr\-from\-differences ( primary | master | secondary | slave | ); + keep\-response\-order { ; ... }; + key\-directory ; + lame\-ttl ; + listen\-on [ port ] [ tls ] [ http ] { ; ... }; // may occur multiple times + listen\-on\-v6 [ port ] [ tls ] [ http ] { ; ... }; // may occur multiple times + lmdb\-mapsize ; + lock\-file ( | none ); + managed\-keys\-directory ; + masterfile\-format ( raw | text ); + masterfile\-style ( full | relative ); + match\-mapped\-addresses ; + max\-cache\-size ( default | unlimited | | ); + max\-cache\-ttl ; + max\-clients\-per\-query ; + max\-ixfr\-ratio ( unlimited | ); + max\-journal\-size ( default | unlimited | ); + max\-ncache\-ttl ; + max\-records ; + max\-recursion\-depth ; + max\-recursion\-queries ; + max\-refresh\-time ; + max\-retry\-time ; + max\-rsa\-exponent\-size ; + max\-stale\-ttl ; + max\-transfer\-idle\-in ; + max\-transfer\-idle\-out ; + max\-transfer\-time\-in ; + max\-transfer\-time\-out ; + max\-udp\-size ; + max\-zone\-ttl ( unlimited | ); + memstatistics ; + memstatistics\-file ; + message\-compression ; + min\-cache\-ttl ; + min\-ncache\-ttl ; + min\-refresh\-time ; + min\-retry\-time ; + minimal\-any ; + minimal\-responses ( no\-auth | no\-auth\-recursive | ); + multi\-master ; + new\-zones\-directory ; + no\-case\-compress { ; ... }; + nocookie\-udp\-size ; + notify ( explicit | master\-only | primary\-only | ); + notify\-delay ; + notify\-rate ; + notify\-source ( | * ) ; + notify\-source\-v6 ( | * ) ; + notify\-to\-soa ; + nsec3\-test\-zone ; // test only + nta\-lifetime ; + nta\-recheck ; + nxdomain\-redirect ; + parental\-source ( | * ) ; + parental\-source\-v6 ( | * ) ; + pid\-file ( | none ); + port ; + preferred\-glue ; + prefetch [ ]; + provide\-ixfr ; + qname\-minimization ( strict | relaxed | disabled | off ); + query\-source [ address ] ( | * ); + query\-source\-v6 [ address ] ( | * ); + querylog ; + random\-device ( | none ); // obsolete + rate\-limit { + all\-per\-second ; + errors\-per\-second ; + exempt\-clients { ; ... }; + ipv4\-prefix\-length ; + ipv6\-prefix\-length ; + log\-only ; + max\-table\-size ; + min\-table\-size ; + nodata\-per\-second ; + nxdomains\-per\-second ; + qps\-scale ; + referrals\-per\-second ; + responses\-per\-second ; + slip ; + window ; + }; + recursing\-file ; + recursion ; + recursive\-clients ; + request\-expire ; + request\-ixfr ; + request\-nsid ; + require\-server\-cookie ; + reserved\-sockets ; // deprecated + resolver\-nonbackoff\-tries ; + resolver\-query\-timeout ; + resolver\-retry\-interval ; + response\-padding { ; ... } block\-size ; + response\-policy { zone [ add\-soa ] [ log ] [ max\-policy\-ttl ] [ min\-update\-interval ] [ policy ( cname | disabled | drop | given | no\-op | nodata | nxdomain | passthru | tcp\-only ) ] [ recursive\-only ] [ nsip\-enable ] [ nsdname\-enable ]; ... } [ add\-soa ] [ break\-dnssec ] [ max\-policy\-ttl ] [ min\-update\-interval ] [ min\-ns\-dots ] [ nsip\-wait\-recurse ] [ nsdname\-wait\-recurse ] [ qname\-wait\-recurse ] [ recursive\-only ] [ nsip\-enable ] [ nsdname\-enable ] [ dnsrps\-enable ] [ dnsrps\-options { } ]; + reuseport ; + root\-delegation\-only [ exclude { ; ... } ]; // deprecated + root\-key\-sentinel ; + rrset\-order { [ class ] [ type ] [ name ] ; ... }; + secroots\-file ; + send\-cookie ; + serial\-query\-rate ; + serial\-update\-method ( date | increment | unixtime ); + server\-id ( | none | hostname ); + servfail\-ttl ; + session\-keyalg ; + session\-keyfile ( | none ); + session\-keyname ; + sig\-signing\-nodes ; + sig\-signing\-signatures ; + sig\-signing\-type ; + sig\-validity\-interval [ ]; + sortlist { ; ... }; + stacksize ( default | unlimited | ); // deprecated + stale\-answer\-client\-timeout ( disabled | off | ); + stale\-answer\-enable ; + stale\-answer\-ttl ; + stale\-cache\-enable ; + stale\-refresh\-time ; + startup\-notify\-rate ; + statistics\-file ; + suppress\-initial\-notify ; // obsolete + synth\-from\-dnssec ; + tcp\-advertised\-timeout ; + tcp\-clients ; + tcp\-idle\-timeout ; + tcp\-initial\-timeout ; + tcp\-keepalive\-timeout ; + tcp\-listen\-queue ; + tcp\-receive\-buffer ; + tcp\-send\-buffer ; + tkey\-dhkey ; // deprecated + tkey\-domain ; + tkey\-gssapi\-credential ; + tkey\-gssapi\-keytab ; + tls\-port ; + transfer\-format ( many\-answers | one\-answer ); + transfer\-message\-size ; + transfer\-source ( | * ) ; + transfer\-source\-v6 ( | * ) ; + transfers\-in ; + transfers\-out ; + transfers\-per\-ns ; + trust\-anchor\-telemetry ; // experimental + try\-tcp\-refresh ; + udp\-receive\-buffer ; + udp\-send\-buffer ; + update\-check\-ksk ; + update\-quota ; + use\-alt\-transfer\-source ; // deprecated + use\-v4\-udp\-ports { ; ... }; // deprecated + use\-v6\-udp\-ports { ; ... }; // deprecated + v6\-bias ; + validate\-except { ; ... }; + version ( | none ); + zero\-no\-soa\-ttl ; + zero\-no\-soa\-ttl\-cache ; + zone\-statistics ( full | terse | none | ); +}; + +parental\-agents [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; // may occur multiple times + +plugin ( query ) [ { } ]; // may occur multiple times + +primaries [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; // may occur multiple times + +server { + bogus ; + edns ; + edns\-udp\-size ; + edns\-version ; + keys ; + max\-udp\-size ; + notify\-source ( | * ) ; + notify\-source\-v6 ( | * ) ; + padding ; + provide\-ixfr ; + query\-source [ address ] ( | * ); + query\-source\-v6 [ address ] ( | * ); + request\-expire ; + request\-ixfr ; + request\-nsid ; + send\-cookie ; + tcp\-keepalive ; + tcp\-only ; + transfer\-format ( many\-answers | one\-answer ); + transfer\-source ( | * ) ; + transfer\-source\-v6 ( | * ) ; + transfers ; +}; // may occur multiple times + +statistics\-channels { + inet ( | | * ) [ port ( | * ) ] [ allow { ; ... } ]; // may occur multiple times +}; // may occur multiple times + +tls { + ca\-file ; + cert\-file ; + ciphers ; + dhparam\-file ; + key\-file ; + prefer\-server\-ciphers ; + protocols { ; ... }; + remote\-hostname ; + session\-tickets ; +}; // may occur multiple times + +trust\-anchors { ( static\-key | initial\-key | static\-ds | initial\-ds ) ; ... }; // may occur multiple times + +trusted\-keys { ; ... }; // may occur multiple times, deprecated + +view [ ] { + allow\-new\-zones ; + allow\-notify { ; ... }; + allow\-query { ; ... }; + allow\-query\-cache { ; ... }; + allow\-query\-cache\-on { ; ... }; + allow\-query\-on { ; ... }; + allow\-recursion { ; ... }; + allow\-recursion\-on { ; ... }; + allow\-transfer [ port ] [ transport ] { ; ... }; + allow\-update { ; ... }; + allow\-update\-forwarding { ; ... }; + also\-notify [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + alt\-transfer\-source ( | * ) ; // deprecated + alt\-transfer\-source\-v6 ( | * ) ; // deprecated + attach\-cache ; + auth\-nxdomain ; + auto\-dnssec ( allow | maintain | off ); // deprecated + catalog\-zones { zone [ default\-primaries [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... } ] [ zone\-directory ] [ in\-memory ] [ min\-update\-interval ]; ... }; + check\-dup\-records ( fail | warn | ignore ); + check\-integrity ; + check\-mx ( fail | warn | ignore ); + check\-mx\-cname ( fail | warn | ignore ); + check\-names ( primary | master | secondary | slave | response ) ( fail | warn | ignore ); // may occur multiple times + check\-sibling ; + check\-spf ( warn | ignore ); + check\-srv\-cname ( fail | warn | ignore ); + check\-wildcard ; + clients\-per\-query ; + deny\-answer\-addresses { ; ... } [ except\-from { ; ... } ]; + deny\-answer\-aliases { ; ... } [ except\-from { ; ... } ]; + dialup ( notify | notify\-passive | passive | refresh | ); // deprecated + disable\-algorithms { ; ... }; // may occur multiple times + disable\-ds\-digests { ; ... }; // may occur multiple times + disable\-empty\-zone ; // may occur multiple times + dlz { + database ; + search ; + }; // may occur multiple times + dns64 { + break\-dnssec ; + clients { ; ... }; + exclude { ; ... }; + mapped { ; ... }; + recursive\-only ; + suffix ; + }; // may occur multiple times + dns64\-contact ; + dns64\-server ; + dnskey\-sig\-validity ; + dnsrps\-enable ; // not configured + dnsrps\-options { }; // not configured + dnssec\-accept\-expired ; + dnssec\-dnskey\-kskonly ; + dnssec\-loadkeys\-interval ; + dnssec\-must\-be\-secure ; // may occur multiple times, deprecated + dnssec\-policy ; + dnssec\-secure\-to\-insecure ; + dnssec\-update\-mode ( maintain | no\-resign ); + dnssec\-validation ( yes | no | auto ); + dnstap { ( all | auth | client | forwarder | resolver | update ) [ ( query | response ) ]; ... }; // not configured + dual\-stack\-servers [ port ] { ( [ port ] | [ port ] | [ port ] ); ... }; + dyndb { }; // may occur multiple times + edns\-udp\-size ; + empty\-contact ; + empty\-server ; + empty\-zones\-enable ; + fetch\-quota\-params ; + fetches\-per\-server [ ( drop | fail ) ]; + fetches\-per\-zone [ ( drop | fail ) ]; + forward ( first | only ); + forwarders [ port ] { ( | ) [ port ]; ... }; + glue\-cache ; // deprecated + ipv4only\-contact ; + ipv4only\-enable ; + ipv4only\-server ; + ixfr\-from\-differences ( primary | master | secondary | slave | ); + key { + algorithm ; + secret ; + }; // may occur multiple times + key\-directory ; + lame\-ttl ; + lmdb\-mapsize ; + managed\-keys { ( static\-key | initial\-key | static\-ds | initial\-ds ) ; ... }; // may occur multiple times, deprecated + masterfile\-format ( raw | text ); + masterfile\-style ( full | relative ); + match\-clients { ; ... }; + match\-destinations { ; ... }; + match\-recursive\-only ; + max\-cache\-size ( default | unlimited | | ); + max\-cache\-ttl ; + max\-clients\-per\-query ; + max\-ixfr\-ratio ( unlimited | ); + max\-journal\-size ( default | unlimited | ); + max\-ncache\-ttl ; + max\-records ; + max\-recursion\-depth ; + max\-recursion\-queries ; + max\-refresh\-time ; + max\-retry\-time ; + max\-stale\-ttl ; + max\-transfer\-idle\-in ; + max\-transfer\-idle\-out ; + max\-transfer\-time\-in ; + max\-transfer\-time\-out ; + max\-udp\-size ; + max\-zone\-ttl ( unlimited | ); + message\-compression ; + min\-cache\-ttl ; + min\-ncache\-ttl ; + min\-refresh\-time ; + min\-retry\-time ; + minimal\-any ; + minimal\-responses ( no\-auth | no\-auth\-recursive | ); + multi\-master ; + new\-zones\-directory ; + no\-case\-compress { ; ... }; + nocookie\-udp\-size ; + notify ( explicit | master\-only | primary\-only | ); + notify\-delay ; + notify\-source ( | * ) ; + notify\-source\-v6 ( | * ) ; + notify\-to\-soa ; + nsec3\-test\-zone ; // test only + nta\-lifetime ; + nta\-recheck ; + nxdomain\-redirect ; + parental\-source ( | * ) ; + parental\-source\-v6 ( | * ) ; + plugin ( query ) [ { } ]; // may occur multiple times + preferred\-glue ; + prefetch [ ]; + provide\-ixfr ; + qname\-minimization ( strict | relaxed | disabled | off ); + query\-source [ address ] ( | * ); + query\-source\-v6 [ address ] ( | * ); + rate\-limit { + all\-per\-second ; + errors\-per\-second ; + exempt\-clients { ; ... }; + ipv4\-prefix\-length ; + ipv6\-prefix\-length ; + log\-only ; + max\-table\-size ; + min\-table\-size ; + nodata\-per\-second ; + nxdomains\-per\-second ; + qps\-scale ; + referrals\-per\-second ; + responses\-per\-second ; + slip ; + window ; + }; + recursion ; + request\-expire ; + request\-ixfr ; + request\-nsid ; + require\-server\-cookie ; + resolver\-nonbackoff\-tries ; + resolver\-query\-timeout ; + resolver\-retry\-interval ; + response\-padding { ; ... } block\-size ; + response\-policy { zone [ add\-soa ] [ log ] [ max\-policy\-ttl ] [ min\-update\-interval ] [ policy ( cname | disabled | drop | given | no\-op | nodata | nxdomain | passthru | tcp\-only ) ] [ recursive\-only ] [ nsip\-enable ] [ nsdname\-enable ]; ... } [ add\-soa ] [ break\-dnssec ] [ max\-policy\-ttl ] [ min\-update\-interval ] [ min\-ns\-dots ] [ nsip\-wait\-recurse ] [ nsdname\-wait\-recurse ] [ qname\-wait\-recurse ] [ recursive\-only ] [ nsip\-enable ] [ nsdname\-enable ] [ dnsrps\-enable ] [ dnsrps\-options { } ]; + root\-delegation\-only [ exclude { ; ... } ]; // deprecated + root\-key\-sentinel ; + rrset\-order { [ class ] [ type ] [ name ] ; ... }; + send\-cookie ; + serial\-update\-method ( date | increment | unixtime ); + server { + bogus ; + edns ; + edns\-udp\-size ; + edns\-version ; + keys ; + max\-udp\-size ; + notify\-source ( | * ) ; + notify\-source\-v6 ( | * ) ; + padding ; + provide\-ixfr ; + query\-source [ address ] ( | * ); + query\-source\-v6 [ address ] ( | * ); + request\-expire ; + request\-ixfr ; + request\-nsid ; + send\-cookie ; + tcp\-keepalive ; + tcp\-only ; + transfer\-format ( many\-answers | one\-answer ); + transfer\-source ( | * ) ; + transfer\-source\-v6 ( | * ) ; + transfers ; + }; // may occur multiple times + servfail\-ttl ; + sig\-signing\-nodes ; + sig\-signing\-signatures ; + sig\-signing\-type ; + sig\-validity\-interval [ ]; + sortlist { ; ... }; + stale\-answer\-client\-timeout ( disabled | off | ); + stale\-answer\-enable ; + stale\-answer\-ttl ; + stale\-cache\-enable ; + stale\-refresh\-time ; + suppress\-initial\-notify ; // obsolete + synth\-from\-dnssec ; + transfer\-format ( many\-answers | one\-answer ); + transfer\-source ( | * ) ; + transfer\-source\-v6 ( | * ) ; + trust\-anchor\-telemetry ; // experimental + trust\-anchors { ( static\-key | initial\-key | static\-ds | initial\-ds ) ; ... }; // may occur multiple times + trusted\-keys { ; ... }; // may occur multiple times, deprecated + try\-tcp\-refresh ; + update\-check\-ksk ; + use\-alt\-transfer\-source ; // deprecated + v6\-bias ; + validate\-except { ; ... }; + zero\-no\-soa\-ttl ; + zero\-no\-soa\-ttl\-cache ; + zone\-statistics ( full | terse | none | ); +}; // may occur multiple times + + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Any of these zone statements can also be set inside the view statement. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone [ ] { + type primary; + allow\-query { ; ... }; + allow\-query\-on { ; ... }; + allow\-transfer [ port ] [ transport ] { ; ... }; + allow\-update { ; ... }; + also\-notify [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + alt\-transfer\-source ( | * ) ; // deprecated + alt\-transfer\-source\-v6 ( | * ) ; // deprecated + auto\-dnssec ( allow | maintain | off ); // deprecated + check\-dup\-records ( fail | warn | ignore ); + check\-integrity ; + check\-mx ( fail | warn | ignore ); + check\-mx\-cname ( fail | warn | ignore ); + check\-names ( fail | warn | ignore ); + check\-sibling ; + check\-spf ( warn | ignore ); + check\-srv\-cname ( fail | warn | ignore ); + check\-wildcard ; + database ; + dialup ( notify | notify\-passive | passive | refresh | ); // deprecated + dlz ; + dnskey\-sig\-validity ; + dnssec\-dnskey\-kskonly ; + dnssec\-loadkeys\-interval ; + dnssec\-policy ; + dnssec\-secure\-to\-insecure ; + dnssec\-update\-mode ( maintain | no\-resign ); + file ; + forward ( first | only ); + forwarders [ port ] { ( | ) [ port ]; ... }; + inline\-signing ; + ixfr\-from\-differences ; + journal ; + key\-directory ; + masterfile\-format ( raw | text ); + masterfile\-style ( full | relative ); + max\-ixfr\-ratio ( unlimited | ); + max\-journal\-size ( default | unlimited | ); + max\-records ; + max\-transfer\-idle\-out ; + max\-transfer\-time\-out ; + max\-zone\-ttl ( unlimited | ); + notify ( explicit | master\-only | primary\-only | ); + notify\-delay ; + notify\-source ( | * ) ; + notify\-source\-v6 ( | * ) ; + notify\-to\-soa ; + nsec3\-test\-zone ; // test only + parental\-agents [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + parental\-source ( | * ) ; + parental\-source\-v6 ( | * ) ; + serial\-update\-method ( date | increment | unixtime ); + sig\-signing\-nodes ; + sig\-signing\-signatures ; + sig\-signing\-type ; + sig\-validity\-interval [ ]; + update\-check\-ksk ; + update\-policy ( local | { ( deny | grant ) ( 6to4\-self | external | krb5\-self | krb5\-selfsub | krb5\-subdomain | krb5\-subdomain\-self\-rhs | ms\-self | ms\-selfsub | ms\-subdomain | ms\-subdomain\-self\-rhs | name | self | selfsub | selfwild | subdomain | tcp\-self | wildcard | zonesub ) [ ] ; ... } ); + zero\-no\-soa\-ttl ; + zone\-statistics ( full | terse | none | ); +}; + +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone [ ] { + type secondary; + allow\-notify { ; ... }; + allow\-query { ; ... }; + allow\-query\-on { ; ... }; + allow\-transfer [ port ] [ transport ] { ; ... }; + allow\-update\-forwarding { ; ... }; + also\-notify [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + alt\-transfer\-source ( | * ) ; // deprecated + alt\-transfer\-source\-v6 ( | * ) ; // deprecated + auto\-dnssec ( allow | maintain | off ); // deprecated + check\-names ( fail | warn | ignore ); + database ; + dialup ( notify | notify\-passive | passive | refresh | ); // deprecated + dlz ; + dnskey\-sig\-validity ; + dnssec\-dnskey\-kskonly ; + dnssec\-loadkeys\-interval ; + dnssec\-policy ; + dnssec\-update\-mode ( maintain | no\-resign ); + file ; + forward ( first | only ); + forwarders [ port ] { ( | ) [ port ]; ... }; + inline\-signing ; + ixfr\-from\-differences ; + journal ; + key\-directory ; + masterfile\-format ( raw | text ); + masterfile\-style ( full | relative ); + max\-ixfr\-ratio ( unlimited | ); + max\-journal\-size ( default | unlimited | ); + max\-records ; + max\-refresh\-time ; + max\-retry\-time ; + max\-transfer\-idle\-in ; + max\-transfer\-idle\-out ; + max\-transfer\-time\-in ; + max\-transfer\-time\-out ; + min\-refresh\-time ; + min\-retry\-time ; + multi\-master ; + notify ( explicit | master\-only | primary\-only | ); + notify\-delay ; + notify\-source ( | * ) ; + notify\-source\-v6 ( | * ) ; + notify\-to\-soa ; + nsec3\-test\-zone ; // test only + parental\-agents [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + parental\-source ( | * ) ; + parental\-source\-v6 ( | * ) ; + primaries [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + request\-expire ; + request\-ixfr ; + sig\-signing\-nodes ; + sig\-signing\-signatures ; + sig\-signing\-type ; + sig\-validity\-interval [ ]; + transfer\-source ( | * ) ; + transfer\-source\-v6 ( | * ) ; + try\-tcp\-refresh ; + update\-check\-ksk ; + use\-alt\-transfer\-source ; // deprecated + zero\-no\-soa\-ttl ; + zone\-statistics ( full | terse | none | ); +}; + +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone [ ] { + type mirror; + allow\-notify { ; ... }; + allow\-query { ; ... }; + allow\-query\-on { ; ... }; + allow\-transfer [ port ] [ transport ] { ; ... }; + allow\-update\-forwarding { ; ... }; + also\-notify [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + alt\-transfer\-source ( | * ) ; // deprecated + alt\-transfer\-source\-v6 ( | * ) ; // deprecated + check\-names ( fail | warn | ignore ); + database ; + file ; + ixfr\-from\-differences ; + journal ; + masterfile\-format ( raw | text ); + masterfile\-style ( full | relative ); + max\-ixfr\-ratio ( unlimited | ); + max\-journal\-size ( default | unlimited | ); + max\-records ; + max\-refresh\-time ; + max\-retry\-time ; + max\-transfer\-idle\-in ; + max\-transfer\-idle\-out ; + max\-transfer\-time\-in ; + max\-transfer\-time\-out ; + min\-refresh\-time ; + min\-retry\-time ; + multi\-master ; + notify ( explicit | master\-only | primary\-only | ); + notify\-delay ; + notify\-source ( | * ) ; + notify\-source\-v6 ( | * ) ; + primaries [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + request\-expire ; + request\-ixfr ; + transfer\-source ( | * ) ; + transfer\-source\-v6 ( | * ) ; + try\-tcp\-refresh ; + use\-alt\-transfer\-source ; // deprecated + zero\-no\-soa\-ttl ; + zone\-statistics ( full | terse | none | ); +}; + +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone [ ] { + type forward; + delegation\-only ; // deprecated + forward ( first | only ); + forwarders [ port ] { ( | ) [ port ]; ... }; +}; + +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone [ ] { + type hint; + check\-names ( fail | warn | ignore ); + delegation\-only ; // deprecated + file ; +}; + +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone [ ] { + type redirect; + allow\-query { ; ... }; + allow\-query\-on { ; ... }; + dlz ; + file ; + masterfile\-format ( raw | text ); + masterfile\-style ( full | relative ); + max\-records ; + max\-zone\-ttl ( unlimited | ); + primaries [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + zone\-statistics ( full | terse | none | ); +}; + +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone [ ] { + type static\-stub; + allow\-query { ; ... }; + allow\-query\-on { ; ... }; + forward ( first | only ); + forwarders [ port ] { ( | ) [ port ]; ... }; + max\-records ; + server\-addresses { ( | ); ... }; + server\-names { ; ... }; + zone\-statistics ( full | terse | none | ); +}; + +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone [ ] { + type stub; + allow\-query { ; ... }; + allow\-query\-on { ; ... }; + check\-names ( fail | warn | ignore ); + database ; + delegation\-only ; // deprecated + dialup ( notify | notify\-passive | passive | refresh | ); // deprecated + file ; + forward ( first | only ); + forwarders [ port ] { ( | ) [ port ]; ... }; + masterfile\-format ( raw | text ); + masterfile\-style ( full | relative ); + max\-records ; + max\-refresh\-time ; + max\-retry\-time ; + max\-transfer\-idle\-in ; + max\-transfer\-time\-in ; + min\-refresh\-time ; + min\-retry\-time ; + multi\-master ; + primaries [ port ] { ( | [ port ] | [ port ] ) [ key ] [ tls ]; ... }; + transfer\-source ( | * ) ; + transfer\-source\-v6 ( | * ) ; + use\-alt\-transfer\-source ; // deprecated + zone\-statistics ( full | terse | none | ); +}; + +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone [ ] { + type delegation\-only; +}; + +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone [ ] { + in\-view ; +}; + +.ft P +.fi +.UNINDENT +.UNINDENT +.SH FILES +.sp +\fB@sysconfdir@/named.conf\fP +.SH SEE ALSO +.sp +\fI\%named(8)\fP, \fI\%named\-checkconf(8)\fP, \fI\%rndc(8)\fP, \fI\%rndc\-confgen(8)\fP, \fI\%tsig\-keygen(8)\fP, BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/named.conf.rst b/doc/man/named.conf.rst new file mode 100644 index 0000000..6fbdda6 --- /dev/null +++ b/doc/man/named.conf.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/named/named.conf.rst diff --git a/doc/man/named.rst b/doc/man/named.rst new file mode 100644 index 0000000..63c0f4b --- /dev/null +++ b/doc/man/named.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/named/named.rst diff --git a/doc/man/nsec3hash.1in b/doc/man/nsec3hash.1in new file mode 100644 index 0000000..4d1bc42 --- /dev/null +++ b/doc/man/nsec3hash.1in @@ -0,0 +1,86 @@ +.\" 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 "NSEC3HASH" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +nsec3hash \- generate NSEC3 hash +.SH SYNOPSIS +.sp +\fBnsec3hash\fP {salt} {algorithm} {iterations} {domain} +.sp +\fBnsec3hash\fP \fB\-r\fP {algorithm} {flags} {iterations} {salt} {domain} +.SH DESCRIPTION +.sp +\fBnsec3hash\fP generates an NSEC3 hash based on a set of NSEC3 +parameters. This can be used to check the validity of NSEC3 records in a +signed zone. +.sp +If this command is invoked as \fBnsec3hash \-r\fP, it takes arguments in +order, matching the first four fields of an NSEC3 record followed by the +domain name: \fBalgorithm\fP, \fBflags\fP, \fBiterations\fP, \fBsalt\fP, \fBdomain\fP\&. This makes it +convenient to copy and paste a portion of an NSEC3 or NSEC3PARAM record +into a command line to confirm the correctness of an NSEC3 hash. +.SH ARGUMENTS +.INDENT 0.0 +.TP +.B salt +This is the salt provided to the hash algorithm. +.UNINDENT +.INDENT 0.0 +.TP +.B algorithm +This is a number indicating the hash algorithm. Currently the only supported +hash algorithm for NSEC3 is SHA\-1, which is indicated by the number +1; consequently \(dq1\(dq is the only useful value for this argument. +.UNINDENT +.INDENT 0.0 +.TP +.B flags +This is provided for compatibility with NSEC3 record presentation format, but +is ignored since the flags do not affect the hash. +.UNINDENT +.INDENT 0.0 +.TP +.B iterations +This is the number of additional times the hash should be performed. +.UNINDENT +.INDENT 0.0 +.TP +.B domain +This is the domain name to be hashed. +.UNINDENT +.SH SEE ALSO +.sp +BIND 9 Administrator Reference Manual, \fI\%RFC 5155\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/nsec3hash.rst b/doc/man/nsec3hash.rst new file mode 100644 index 0000000..ba81f0d --- /dev/null +++ b/doc/man/nsec3hash.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/tools/nsec3hash.rst diff --git a/doc/man/nslookup.1in b/doc/man/nslookup.1in new file mode 100644 index 0000000..25bd5dd --- /dev/null +++ b/doc/man/nslookup.1in @@ -0,0 +1,225 @@ +.\" 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 "NSLOOKUP" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +nslookup \- query Internet name servers interactively +.SH SYNOPSIS +.sp +\fBnslookup\fP [\-option] [name | \-] [server] +.SH DESCRIPTION +.sp +\fBnslookup\fP is a program to query Internet domain name servers. +\fBnslookup\fP has two modes: interactive and non\-interactive. Interactive +mode allows the user to query name servers for information about various +hosts and domains or to print a list of hosts in a domain. +Non\-interactive mode prints just the name and requested +information for a host or domain. +.SH ARGUMENTS +.sp +Interactive mode is entered in the following cases: +.INDENT 0.0 +.IP a. 3 +when no arguments are given (the default name server is used); +.IP b. 3 +when the first argument is a hyphen (\-) and the second argument is +the host name or Internet address of a name server. +.UNINDENT +.sp +Non\-interactive mode is used when the name or Internet address of the +host to be looked up is given as the first argument. The optional second +argument specifies the host name or address of a name server. +.sp +Options can also be specified on the command line if they precede the +arguments and are prefixed with a hyphen. For example, to change the +default query type to host information, with an initial timeout of 10 +seconds, type: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +nslookup \-query=hinfo \-timeout=10 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fB\-version\fP option causes \fBnslookup\fP to print the version number +and immediately exit. +.SH INTERACTIVE COMMANDS +.INDENT 0.0 +.TP +.B \fBhost [server]\fP +This command looks up information for \fI\%host\fP using the current default server or +using \fBserver\fP, if specified. If \fI\%host\fP is an Internet address and the +query type is A or PTR, the name of the host is returned. If \fI\%host\fP is +a name and does not have a trailing period (\fB\&.\fP), the search list is used +to qualify the name. +.sp +To look up a host not in the current domain, append a period to the +name. +.TP +.B \fBserver domain\fP | \fBlserver domain\fP +These commands change the default server to \fBdomain\fP; \fBlserver\fP uses the initial +server to look up information about \fBdomain\fP, while \fBserver\fP uses the +current default server. If an authoritative answer cannot be found, +the names of servers that might have the answer are returned. +.TP +.B \fBroot\fP +This command is not implemented. +.TP +.B \fBfinger\fP +This command is not implemented. +.TP +.B \fBls\fP +This command is not implemented. +.TP +.B \fBview\fP +This command is not implemented. +.TP +.B \fBhelp\fP +This command is not implemented. +.TP +.B \fB?\fP +This command is not implemented. +.TP +.B \fBexit\fP +This command exits the program. +.TP +.B \fBset keyword[=value]\fP +This command is used to change state information that affects the +lookups. Valid keywords are: +.INDENT 7.0 +.TP +.B \fBall\fP +This keyword prints the current values of the frequently used options to +\fBset\fP\&. Information about the current default server and host is +also printed. +.TP +.B \fBclass=value\fP +This keyword changes the query class to one of: +.INDENT 7.0 +.TP +.B \fBIN\fP +the Internet class +.TP +.B \fBCH\fP +the Chaos class +.TP +.B \fBHS\fP +the Hesiod class +.TP +.B \fBANY\fP +wildcard +.UNINDENT +.sp +The class specifies the protocol group of the information. The default +is \fBIN\fP; the abbreviation for this keyword is \fBcl\fP\&. +.TP +.B \fBnodebug\fP +This keyword turns on or off the display of the full response packet, and any +intermediate response packets, when searching. The default for this keyword is +\fBnodebug\fP; the abbreviation for this keyword is \fB[no]deb\fP\&. +.TP +.B \fBnod2\fP +This keyword turns debugging mode on or off. This displays more about what +nslookup is doing. The default is \fBnod2\fP\&. +.TP +.B \fBdomain=name\fP +This keyword sets the search list to \fBname\fP\&. +.TP +.B \fBnosearch\fP +If the lookup request contains at least one period, but does not end +with a trailing period, this keyword appends the domain names in the domain +search list to the request until an answer is received. The default is \fBsearch\fP\&. +.TP +.B \fBport=value\fP +This keyword changes the default TCP/UDP name server port to \fBvalue\fP from +its default, port 53. The abbreviation for this keyword is \fBpo\fP\&. +.TP +.B \fBquerytype=value\fP | \fBtype=value\fP +This keyword changes the type of the information query to \fBvalue\fP\&. The +defaults are A and then AAAA; the abbreviations for these keywords are +\fBq\fP and \fBty\fP\&. +.sp +Please note that it is only possible to specify one query type. Only the default +behavior looks up both when an alternative is not specified. +.TP +.B \fBnorecurse\fP +This keyword tells the name server to query other servers if it does not have +the information. The default is \fBrecurse\fP; the abbreviation for this +keyword is \fB[no]rec\fP\&. +.TP +.B \fBndots=number\fP +This keyword sets the number of dots (label separators) in a domain that +disables searching. Absolute names always stop searching. +.TP +.B \fBretry=number\fP +This keyword sets the number of retries to \fBnumber\fP\&. +.TP +.B \fBtimeout=number\fP +This keyword changes the initial timeout interval to wait for a reply to +\fBnumber\fP, in seconds. +.TP +.B \fBnovc\fP +This keyword indicates that a virtual circuit should always be used when sending requests to the server. +\fBnovc\fP is the default. +.TP +.B \fBnofail\fP +This keyword tries the next nameserver if a nameserver responds with SERVFAIL or +a referral (nofail), or terminates the query (fail) on such a response. The +default is \fBnofail\fP\&. +.UNINDENT +.UNINDENT +.SH RETURN VALUES +.sp +\fBnslookup\fP returns with an exit status of 1 if any query failed, and 0 +otherwise. +.SH IDN SUPPORT +.sp +If \fBnslookup\fP has been built with IDN (internationalized domain name) +support, it can accept and display non\-ASCII domain names. \fBnslookup\fP +appropriately converts character encoding of a domain name before sending +a request to a DNS server or displaying a reply from the server. +To turn off IDN support, define the \fBIDN_DISABLE\fP +environment variable. IDN support is disabled if the variable is set +when \fBnslookup\fP runs, or when the standard output is not a tty. +.SH FILES +.sp +\fB/etc/resolv.conf\fP +.SH SEE ALSO +.sp +\fI\%dig(1)\fP, \fI\%host(1)\fP, \fI\%named(8)\fP\&. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/nslookup.rst b/doc/man/nslookup.rst new file mode 100644 index 0000000..015740d --- /dev/null +++ b/doc/man/nslookup.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/dig/nslookup.rst diff --git a/doc/man/nsupdate.1in b/doc/man/nsupdate.1in new file mode 100644 index 0000000..b80f329 --- /dev/null +++ b/doc/man/nsupdate.1in @@ -0,0 +1,437 @@ +.\" 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 "NSUPDATE" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +nsupdate \- dynamic DNS update utility +.SH SYNOPSIS +.sp +\fBnsupdate\fP [\fB\-d\fP] [\fB\-D\fP] [\fB\-i\fP] [\fB\-L\fP level] [ [\fB\-g\fP] | [\fB\-o\fP] | [\fB\-l\fP] | [\fB\-y\fP [hmac:]keyname:secret] | [\fB\-k\fP keyfile] ] [\fB\-t\fP timeout] [\fB\-u\fP udptimeout] [\fB\-r\fP udpretries] [\fB\-v\fP] [\fB\-T\fP] [\fB\-P\fP] [\fB\-V\fP] [ [\fB\-4\fP] | [\fB\-6\fP] ] [filename] +.SH DESCRIPTION +.sp +\fBnsupdate\fP is used to submit Dynamic DNS Update requests, as defined in +\fI\%RFC 2136\fP, to a name server. This allows resource records to be added or +removed from a zone without manually editing the zone file. A single +update request can contain requests to add or remove more than one +resource record. +.sp +Zones that are under dynamic control via \fBnsupdate\fP or a DHCP server +should not be edited by hand. Manual edits could conflict with dynamic +updates and cause data to be lost. +.sp +The resource records that are dynamically added or removed with +\fBnsupdate\fP must be in the same zone. Requests are sent to the +zone\(aqs primary server, which is identified by the MNAME field of the +zone\(aqs SOA record. +.sp +Transaction signatures can be used to authenticate the Dynamic DNS +updates. These use the TSIG resource record type described in \fI\%RFC 2845\fP, +the SIG(0) record described in \fI\%RFC 2535\fP and \fI\%RFC 2931\fP, or GSS\-TSIG as +described in \fI\%RFC 3645\fP\&. +.sp +TSIG relies on a shared secret that should only be known to \fBnsupdate\fP +and the name server. For instance, suitable \fBkey\fP and \fBserver\fP +statements are added to \fB@sysconfdir@/named.conf\fP so that the name server +can associate the appropriate secret key and algorithm with the IP +address of the client application that is using TSIG +authentication. \fI\%ddns\-confgen\fP can generate suitable +configuration fragments. \fBnsupdate\fP uses the \fI\%\-y\fP or \fI\%\-k\fP options +to provide the TSIG shared secret; these options are mutually exclusive. +.sp +SIG(0) uses public key cryptography. To use a SIG(0) key, the public key +must be stored in a KEY record in a zone served by the name server. +.sp +GSS\-TSIG uses Kerberos credentials. Standard GSS\-TSIG mode is switched +on with the \fI\%\-g\fP flag. A non\-standards\-compliant variant of GSS\-TSIG +used by Windows 2000 can be switched on with the \fI\%\-o\fP flag. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-4 +This option sets use of IPv4 only. +.UNINDENT +.INDENT 0.0 +.TP +.B \-6 +This option sets use of IPv6 only. +.UNINDENT +.INDENT 0.0 +.TP +.B \-C +Overrides the default \fIresolv.conf\fP file. This is only intended for testing. +.UNINDENT +.INDENT 0.0 +.TP +.B \-d +This option sets debug mode, which provides tracing information about the update +requests that are made and the replies received from the name server. +.UNINDENT +.INDENT 0.0 +.TP +.B \-D +This option sets extra debug mode. +.UNINDENT +.INDENT 0.0 +.TP +.B \-g +This option enables standard GSS\-TSIG mode. +.UNINDENT +.INDENT 0.0 +.TP +.B \-i +This option forces interactive mode, even when standard input is not a terminal. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k keyfile +This option indicates the file containing the TSIG authentication key. Keyfiles may be in +two formats: a single file containing a \fI\%named.conf\fP\-format \fBkey\fP +statement, which may be generated automatically by \fI\%ddns\-confgen\fP; +or a pair of files whose names are of the format +\fBK{name}.+157.+{random}.key\fP and +\fBK{name}.+157.+{random}.private\fP, which can be generated by +\fI\%dnssec\-keygen\fP\&. The \fI\%\-k\fP option can also be used to specify a SIG(0) +key used to authenticate Dynamic DNS update requests. In this case, +the key specified is not an HMAC\-MD5 key. +.UNINDENT +.INDENT 0.0 +.TP +.B \-l +This option sets local\-host only mode, which sets the server address to localhost +(disabling the \fBserver\fP so that the server address cannot be +overridden). Connections to the local server use a TSIG key +found in \fB@runstatedir@/session.key\fP, which is automatically +generated by \fI\%named\fP if any local \fBprimary\fP zone has set +\fBupdate\-policy\fP to \fBlocal\fP\&. The location of this key file can be +overridden with the \fI\%\-k\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-L level +This option sets the logging debug level. If zero, logging is disabled. +.UNINDENT +.INDENT 0.0 +.TP +.B \-o +This option enables a non\-standards\-compliant variant of GSS\-TSIG +used by Windows 2000. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p port +This option sets the port to use for connections to a name server. The default is +53. +.UNINDENT +.INDENT 0.0 +.TP +.B \-P +This option prints the list of private BIND\-specific resource record types whose +format is understood by \fBnsupdate\fP\&. See also the \fI\%\-T\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r udpretries +This option sets the number of UDP retries. The default is 3. If zero, only one update +request is made. +.UNINDENT +.INDENT 0.0 +.TP +.B \-t timeout +This option sets the maximum time an update request can take before it is aborted. The +default is 300 seconds. If zero, the timeout is disabled for TCP mode. For UDP mode, +the option \fI\%\-u\fP takes precedence over this option, unless the option \fI\%\-u\fP +is set to zero, in which case the interval is computed from the \fI\%\-t\fP timeout interval +and the number of UDP retries. For UDP mode, the timeout can not be disabled, and will +be rounded up to 1 second in case if both \fI\%\-t\fP and \fI\%\-u\fP are set to zero. +.UNINDENT +.INDENT 0.0 +.TP +.B \-T +This option prints the list of IANA standard resource record types whose format is +understood by \fBnsupdate\fP\&. \fBnsupdate\fP exits after the lists +are printed. The \fI\%\-T\fP option can be combined with the \fI\%\-P\fP +option. +.sp +Other types can be entered using \fBTYPEXXXXX\fP where \fBXXXXX\fP is the +decimal value of the type with no leading zeros. The rdata, if +present, is parsed using the UNKNOWN rdata format, ( + ). +.UNINDENT +.INDENT 0.0 +.TP +.B \-u udptimeout +This option sets the UDP retry interval. The default is 3 seconds. If zero, the +interval is computed from the timeout interval and number of UDP +retries. +.UNINDENT +.INDENT 0.0 +.TP +.B \-v +This option specifies that TCP should be used even for small update requests. By default, \fBnsupdate\fP uses +UDP to send update requests to the name server unless they are too +large to fit in a UDP request, in which case TCP is used. TCP may +be preferable when a batch of update requests is made. +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option prints the version number and exits. +.UNINDENT +.INDENT 0.0 +.TP +.B \-y [hmac:]keyname:secret +This option sets the literal TSIG authentication key. \fBkeyname\fP is the name of the key, +and \fBsecret\fP is the base64 encoded shared secret. \fBhmac\fP is the +name of the key algorithm; valid choices are \fBhmac\-md5\fP, +\fBhmac\-sha1\fP, \fBhmac\-sha224\fP, \fBhmac\-sha256\fP, \fBhmac\-sha384\fP, or +\fBhmac\-sha512\fP\&. If \fBhmac\fP is not specified, the default is +\fBhmac\-md5\fP, or if MD5 was disabled, \fBhmac\-sha256\fP\&. +.sp +NOTE: Use of the \fI\%\-y\fP option is discouraged because the shared +secret is supplied as a command\-line argument in clear text. This may +be visible in the output from ps1 or in a history file maintained by +the user\(aqs shell. +.UNINDENT +.SH INPUT FORMAT +.sp +\fBnsupdate\fP reads input from \fBfilename\fP or standard input. Each +command is supplied on exactly one line of input. Some commands are for +administrative purposes; others are either update instructions or +prerequisite checks on the contents of the zone. These checks set +conditions that some name or set of resource records (RRset) either +exists or is absent from the zone. These conditions must be met if the +entire update request is to succeed. Updates are rejected if the +tests for the prerequisite conditions fail. +.sp +Every update request consists of zero or more prerequisites and zero or +more updates. This allows a suitably authenticated update request to +proceed if some specified resource records are either present or missing from +the zone. A blank input line (or the \fBsend\fP command) causes the +accumulated commands to be sent as one Dynamic DNS update request to the +name server. +.sp +The command formats and their meanings are as follows: +.INDENT 0.0 +.TP +.B \fBserver servername port\fP +This command sends all dynamic update requests to the name server \fBservername\fP\&. +When no server statement is provided, \fBnsupdate\fP sends updates +to the primary server of the correct zone. The MNAME field of that +zone\(aqs SOA record identify the primary server for that zone. +\fBport\fP is the port number on \fBservername\fP where the dynamic +update requests are sent. If no port number is specified, the default +DNS port number of 53 is used. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This command has no effect when GSS\-TSIG is in use. +.UNINDENT +.UNINDENT +.TP +.B \fBlocal address port\fP +This command sends all dynamic update requests using the local \fBaddress\fP\&. When +no local statement is provided, \fBnsupdate\fP sends updates using +an address and port chosen by the system. \fBport\fP can also +be used to force requests to come from a specific port. If no port number +is specified, the system assigns one. +.TP +.B \fBzone zonename\fP +This command specifies that all updates are to be made to the zone \fBzonename\fP\&. +If no \fBzone\fP statement is provided, \fBnsupdate\fP attempts to +determine the correct zone to update based on the rest of the input. +.TP +.B \fBclass classname\fP +This command specifies the default class. If no \fBclass\fP is specified, the default +class is \fBIN\fP\&. +.TP +.B \fBttl seconds\fP +This command specifies the default time\-to\-live, in seconds, for records to be added. The value +\fBnone\fP clears the default TTL. +.TP +.B \fBkey hmac:keyname secret\fP +This command specifies that all updates are to be TSIG\-signed using the +\fBkeyname\fP\-\fBsecret\fP pair. If \fBhmac\fP is specified, it sets +the signing algorithm in use. The default is \fBhmac\-md5\fP; if MD5 +was disabled, the default is \fBhmac\-sha256\fP\&. The \fBkey\fP command overrides any key +specified on the command line via \fI\%\-y\fP or \fI\%\-k\fP\&. +.TP +.B \fBgsstsig\fP +This command uses GSS\-TSIG to sign the updates. This is equivalent to specifying +\fI\%\-g\fP on the command line. +.TP +.B \fBoldgsstsig\fP +This command uses the Windows 2000 version of GSS\-TSIG to sign the updates. This is +equivalent to specifying \fI\%\-o\fP on the command line. +.TP +.B \fBrealm [realm_name]\fP +When using GSS\-TSIG, this command specifies the use of \fBrealm_name\fP rather than the default realm +in \fBkrb5.conf\fP\&. If no realm is specified, the saved realm is +cleared. +.TP +.B \fBcheck\-names [boolean]\fP +This command turns on or off check\-names processing on records to be added. +Check\-names has no effect on prerequisites or records to be deleted. +By default check\-names processing is on. If check\-names processing +fails, the record is not added to the UPDATE message. +.TP +.B \fBprereq nxdomain domain\-name\fP +This command requires that no resource record of any type exist with the name +\fBdomain\-name\fP\&. +.TP +.B \fBprereq yxdomain domain\-name\fP +This command requires that \fBdomain\-name\fP exist (as at least one resource +record, of any type). +.TP +.B \fBprereq nxrrset domain\-name class type\fP +This command requires that no resource record exist of the specified \fBtype\fP, +\fBclass\fP, and \fBdomain\-name\fP\&. If \fBclass\fP is omitted, IN (Internet) +is assumed. +.TP +.B \fBprereq yxrrset domain\-name class type\fP +This command requires that a resource record of the specified \fBtype\fP, +\fBclass\fP and \fBdomain\-name\fP exist. If \fBclass\fP is omitted, IN +(internet) is assumed. +.TP +.B \fBprereq yxrrset domain\-name class type data\fP +With this command, the \fBdata\fP from each set of prerequisites of this form sharing a +common \fBtype\fP, \fBclass\fP, and \fBdomain\-name\fP are combined to form +a set of RRs. This set of RRs must exactly match the set of RRs +existing in the zone at the given \fBtype\fP, \fBclass\fP, and +\fBdomain\-name\fP\&. The \fBdata\fP are written in the standard text +representation of the resource record\(aqs RDATA. +.TP +.B \fBupdate delete domain\-name ttl class type data\fP +This command deletes any resource records named \fBdomain\-name\fP\&. If \fBtype\fP and +\fBdata\fP are provided, only matching resource records are removed. +The Internet class is assumed if \fBclass\fP is not supplied. The +\fBttl\fP is ignored, and is only allowed for compatibility. +.TP +.B \fBupdate add domain\-name ttl class type data\fP +This command adds a new resource record with the specified \fBttl\fP, \fBclass\fP, and +\fBdata\fP\&. +.TP +.B \fBshow\fP +This command displays the current message, containing all of the prerequisites and +updates specified since the last send. +.TP +.B \fBsend\fP +This command sends the current message. This is equivalent to entering a blank +line. +.TP +.B \fBanswer\fP +This command displays the answer. +.TP +.B \fBdebug\fP +This command turns on debugging. +.TP +.B \fBversion\fP +This command prints the version number. +.TP +.B \fBhelp\fP +This command prints a list of commands. +.UNINDENT +.sp +Lines beginning with a semicolon (;) are comments and are ignored. +.SH EXAMPLES +.sp +The examples below show how \fBnsupdate\fP can be used to insert and +delete resource records from the \fBexample.com\fP zone. Notice that the +input in each example contains a trailing blank line, so that a group of +commands is sent as one dynamic update request to the primary name +server for \fBexample.com\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# nsupdate +> update delete oldhost.example.com A +> update add newhost.example.com 86400 A 172.16.1.1 +> send +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Any A records for \fBoldhost.example.com\fP are deleted, and an A record +for \fBnewhost.example.com\fP with IP address 172.16.1.1 is added. The +newly added record has a TTL of 1 day (86400 seconds). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# nsupdate +> prereq nxdomain nickname.example.com +> update add nickname.example.com 86400 CNAME somehost.example.com +> send +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The prerequisite condition tells the name server to verify that there are +no resource records of any type for \fBnickname.example.com\fP\&. If there +are, the update request fails. If this name does not exist, a CNAME for +it is added. This ensures that when the CNAME is added, it cannot +conflict with the long\-standing rule in \fI\%RFC 1034\fP that a name must not +exist as any other record type if it exists as a CNAME. (The rule has +been updated for DNSSEC in \fI\%RFC 2535\fP to allow CNAMEs to have RRSIG, +DNSKEY, and NSEC records.) +.SH FILES +.INDENT 0.0 +.TP +.B \fB/etc/resolv.conf\fP +Used to identify the default name server +.TP +.B \fB@runstatedir@/session.key\fP +Sets the default TSIG key for use in local\-only mode +.TP +.B \fBK{name}.+157.+{random}.key\fP +Base\-64 encoding of the HMAC\-MD5 key created by \fI\%dnssec\-keygen\fP\&. +.TP +.B \fBK{name}.+157.+{random}.private\fP +Base\-64 encoding of the HMAC\-MD5 key created by \fI\%dnssec\-keygen\fP\&. +.UNINDENT +.SH SEE ALSO +.sp +\fI\%RFC 2136\fP, \fI\%RFC 3007\fP, \fI\%RFC 2104\fP, \fI\%RFC 2845\fP, \fI\%RFC 1034\fP, \fI\%RFC 2535\fP, \fI\%RFC 2931\fP, +\fI\%named(8)\fP, \fI\%dnssec\-keygen(8)\fP, \fI\%tsig\-keygen(8)\fP\&. +.SH BUGS +.sp +The TSIG key is redundantly stored in two separate files. This is a +consequence of \fBnsupdate\fP using the DST library for its cryptographic +operations, and may change in future releases. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/nsupdate.rst b/doc/man/nsupdate.rst new file mode 100644 index 0000000..bced04e --- /dev/null +++ b/doc/man/nsupdate.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/nsupdate/nsupdate.rst diff --git a/doc/man/rndc-confgen.8in b/doc/man/rndc-confgen.8in new file mode 100644 index 0000000..fa20381 --- /dev/null +++ b/doc/man/rndc-confgen.8in @@ -0,0 +1,141 @@ +.\" 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 "RNDC-CONFGEN" "8" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +rndc-confgen \- rndc key generation tool +.SH SYNOPSIS +.sp +\fBrndc\-confgen\fP [\fB\-a\fP] [\fB\-A\fP algorithm] [\fB\-b\fP keysize] [\fB\-c\fP keyfile] [\fB\-h\fP] [\fB\-k\fP keyname] [\fB\-p\fP port] [\fB\-s\fP address] [\fB\-t\fP chrootdir] [\fB\-u\fP user] +.SH DESCRIPTION +.sp +\fBrndc\-confgen\fP generates configuration files for \fI\%rndc\fP\&. It can be +used as a convenient alternative to writing the \fI\%rndc.conf\fP file and +the corresponding \fBcontrols\fP and \fBkey\fP statements in \fI\%named.conf\fP +by hand. Alternatively, it can be run with the \fI\%\-a\fP option to set up a +\fBrndc.key\fP file and avoid the need for a \fI\%rndc.conf\fP file and a +\fBcontrols\fP statement altogether. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-a +This option sets automatic \fI\%rndc\fP configuration, which creates a file +\fB@sysconfdir@/rndc.key\fP that is read by both \fI\%rndc\fP and \fI\%named\fP on startup. +The \fBrndc.key\fP file defines a default command channel and +authentication key allowing \fI\%rndc\fP to communicate with \fI\%named\fP on +the local host with no further configuration. +.sp +If a more elaborate configuration than that generated by +\fI\%rndc\-confgen \-a\fP is required, for example if rndc is to be used +remotely, run \fBrndc\-confgen\fP without the \fI\%\-a\fP option +and set up \fI\%rndc.conf\fP and \fI\%named.conf\fP as directed. +.UNINDENT +.INDENT 0.0 +.TP +.B \-A algorithm +This option specifies the algorithm to use for the TSIG key. Available choices +are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, and +hmac\-sha512. The default is hmac\-sha256. +.UNINDENT +.INDENT 0.0 +.TP +.B \-b keysize +This option specifies the size of the authentication key in bits. The size must be between +1 and 512 bits; the default is the hash size. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c keyfile +This option is used with the \fI\%\-a\fP option to specify an alternate location for +\fBrndc.key\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option prints a short summary of the options and arguments to +\fBrndc\-confgen\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k keyname +This option specifies the key name of the \fI\%rndc\fP authentication key. This must be a +valid domain name. The default is \fBrndc\-key\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p port +This option specifies the command channel port where \fI\%named\fP listens for +connections from \fI\%rndc\fP\&. The default is 953. +.UNINDENT +.INDENT 0.0 +.TP +.B \-q +This option prevets printing the written path in automatic configuration mode. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s address +This option specifies the IP address where \fI\%named\fP listens for command\-channel +connections from \fI\%rndc\fP\&. The default is the loopback address +127.0.0.1. +.UNINDENT +.INDENT 0.0 +.TP +.B \-t chrootdir +This option is used with the \fI\%\-a\fP option to specify a directory where \fI\%named\fP +runs chrooted. An additional copy of the \fBrndc.key\fP is +written relative to this directory, so that it is found by the +chrooted \fI\%named\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-u user +This option is used with the \fI\%\-a\fP option to set the owner of the generated \fBrndc.key\fP file. +If \fI\%\-t\fP is also specified, only the file in the chroot +area has its owner changed. +.UNINDENT +.SH EXAMPLES +.sp +To allow \fI\%rndc\fP to be used with no manual configuration, run: +.sp +\fBrndc\-confgen \-a\fP +.sp +To print a sample \fI\%rndc.conf\fP file and the corresponding \fBcontrols\fP and +\fBkey\fP statements to be manually inserted into \fI\%named.conf\fP, run: +.sp +\fBrndc\-confgen\fP +.SH SEE ALSO +.sp +\fI\%rndc(8)\fP, \fI\%rndc.conf(5)\fP, \fI\%named(8)\fP, BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/rndc-confgen.rst b/doc/man/rndc-confgen.rst new file mode 100644 index 0000000..dac57ba --- /dev/null +++ b/doc/man/rndc-confgen.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/confgen/rndc-confgen.rst diff --git a/doc/man/rndc.8in b/doc/man/rndc.8in new file mode 100644 index 0000000..7361778 --- /dev/null +++ b/doc/man/rndc.8in @@ -0,0 +1,727 @@ +.\" 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 "RNDC" "8" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +rndc \- name server control utility +.SH SYNOPSIS +.sp +\fBrndc\fP [\fB\-b\fP source\-address] [\fB\-c\fP config\-file] [\fB\-k\fP key\-file] [\fB\-s\fP server] [\fB\-p\fP port] [\fB\-q\fP] [\fB\-r\fP] [\fB\-V\fP] [\fB\-y\fP server_key] [[\fB\-4\fP] | [\fB\-6\fP]] {command} +.SH DESCRIPTION +.sp +\fBrndc\fP controls the operation of a name server. If \fBrndc\fP is +invoked with no command line options or arguments, it prints a short +summary of the supported commands and the available options and their +arguments. +.sp +\fBrndc\fP communicates with the name server over a TCP connection, +sending commands authenticated with digital signatures. In the current +versions of \fBrndc\fP and \fI\%named\fP, the only supported authentication +algorithms are HMAC\-MD5 (for compatibility), HMAC\-SHA1, HMAC\-SHA224, +HMAC\-SHA256 (default), HMAC\-SHA384, and HMAC\-SHA512. They use a shared +secret on each end of the connection, which provides TSIG\-style +authentication for the command request and the name server\(aqs response. +All commands sent over the channel must be signed by a server_key known to +the server. +.sp +\fBrndc\fP reads a configuration file to determine how to contact the name +server and decide what algorithm and key it should use. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-4 +This option indicates use of IPv4 only. +.UNINDENT +.INDENT 0.0 +.TP +.B \-6 +This option indicates use of IPv6 only. +.UNINDENT +.INDENT 0.0 +.TP +.B \-b source\-address +This option indicates \fBsource\-address\fP as the source address for the connection to the +server. Multiple instances are permitted, to allow setting of both the +IPv4 and IPv6 source addresses. +.UNINDENT +.INDENT 0.0 +.TP +.B \-c config\-file +This option indicates \fBconfig\-file\fP as the configuration file instead of the default, +\fB@sysconfdir@/rndc.conf\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-k key\-file +This option indicates \fBkey\-file\fP as the key file instead of the default, +\fB@sysconfdir@/rndc.key\fP\&. The key in \fB@sysconfdir@/rndc.key\fP is used to +authenticate commands sent to the server if the config\-file does not +exist. +.UNINDENT +.INDENT 0.0 +.TP +.B \-s server +\fBserver\fP is the name or address of the server which matches a server +statement in the configuration file for \fBrndc\fP\&. If no server is +supplied on the command line, the host named by the default\-server +clause in the options statement of the \fBrndc\fP configuration file +is used. +.UNINDENT +.INDENT 0.0 +.TP +.B \-p port +This option instructs BIND 9 to send commands to TCP port \fBport\fP instead of its default control +channel port, 953. +.UNINDENT +.INDENT 0.0 +.TP +.B \-q +This option sets quiet mode, where message text returned by the server is not printed +unless there is an error. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r +This option instructs \fBrndc\fP to print the result code returned by \fI\%named\fP +after executing the requested command (e.g., ISC_R_SUCCESS, +ISC_R_FAILURE, etc.). +.UNINDENT +.INDENT 0.0 +.TP +.B \-V +This option enables verbose logging. +.UNINDENT +.INDENT 0.0 +.TP +.B \-y server_key +This option indicates use of the key \fBserver_key\fP from the configuration file. For control message validation to succeed, \fBserver_key\fP must be known +by \fI\%named\fP with the same algorithm and secret string. If no \fBserver_key\fP is specified, +\fBrndc\fP first looks for a key clause in the server statement of +the server being used, or if no server statement is present for that +host, then in the default\-key clause of the options statement. Note that +the configuration file contains shared secrets which are used to send +authenticated control commands to name servers, and should therefore +not have general read or write access. +.UNINDENT +.SH COMMANDS +.sp +A list of commands supported by \fBrndc\fP can be seen by running \fBrndc\fP +without arguments. +.sp +Currently supported commands are: +.INDENT 0.0 +.TP +.B addzone zone [class [view]] configuration +This command adds a zone while the server is running. This command requires the +\fBallow\-new\-zones\fP option to be set to \fByes\fP\&. The configuration +string specified on the command line is the zone configuration text +that would ordinarily be placed in \fI\%named.conf\fP\&. +.sp +The configuration is saved in a file called \fBviewname.nzf\fP (or, if +\fI\%named\fP is compiled with liblmdb, an LMDB database file called +\fBviewname.nzd\fP). \fBviewname\fP is the name of the view, unless the view +name contains characters that are incompatible with use as a file +name, in which case a cryptographic hash of the view name is used +instead. When \fI\%named\fP is restarted, the file is loaded into +the view configuration so that zones that were added can persist +after a restart. +.sp +This sample \fBaddzone\fP command adds the zone \fBexample.com\fP to +the default view: +.sp +\fBrndc addzone example.com \(aq{ type primary; file \(dqexample.com.db\(dq; };\(aq\fP +.sp +(Note the brackets around and semi\-colon after the zone configuration +text.) +.sp +See also \fI\%rndc delzone\fP and \fI\%rndc modzone\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B delzone [\-clean] zone [class [view]] +This command deletes a zone while the server is running. +.sp +If the \fB\-clean\fP argument is specified, the zone\(aqs master file (and +journal file, if any) are deleted along with the zone. Without +the \fB\-clean\fP option, zone files must be deleted manually. (If the +zone is of type \fBsecondary\fP or \fBstub\fP, the files needing to be removed +are reported in the output of the \fBrndc delzone\fP command.) +.sp +If the zone was originally added via \fBrndc addzone\fP, then it is +removed permanently. However, if it was originally configured in +\fI\%named.conf\fP, then that original configuration remains in place; +when the server is restarted or reconfigured, the zone is +recreated. To remove it permanently, it must also be removed from +\fI\%named.conf\fP\&. +.sp +See also \fI\%rndc addzone\fP and \fI\%rndc modzone\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B dnssec (\-status | \-rollover \-key id [\-alg algorithm] [\-when time] | \-checkds [\-key id [\-alg algorithm]] [\-when time] published | withdrawn)) zone [class [view]] +This command allows you to interact with the \(dqdnssec\-policy\(dq of a given +zone. +.sp +\fBrndc dnssec \-status\fP show the DNSSEC signing state for the specified +zone. +.sp +\fBrndc dnssec \-rollover\fP allows you to schedule key rollover for a +specific key (overriding the original key lifetime). +.sp +\fBrndc dnssec \-checkds\fP informs \fI\%named\fP that the DS for +a specified zone\(aqs key\-signing key has been confirmed to be published +in, or withdrawn from, the parent zone. This is required in order to +complete a KSK rollover. The \fB\-key id\fP and \fB\-alg algorithm\fP arguments +can be used to specify a particular KSK, if necessary; if there is only +one key acting as a KSK for the zone, these arguments can be omitted. +The time of publication or withdrawal for the DS is set to the current +time by default, but can be overridden to a specific time with the +argument \fB\-when time\fP, where \fBtime\fP is expressed in YYYYMMDDHHMMSS +notation. +.UNINDENT +.INDENT 0.0 +.TP +.B dnstap (\-reopen | \-roll [number]) +This command closes and re\-opens DNSTAP output files. +.sp +\fBrndc dnstap \-reopen\fP allows +the output file to be renamed externally, so that \fI\%named\fP can +truncate and re\-open it. +.sp +\fBrndc dnstap \-roll\fP causes the output file +to be rolled automatically, similar to log files. The most recent +output file has \(dq.0\(dq appended to its name; the previous most recent +output file is moved to \(dq.1\(dq, and so on. If \fBnumber\fP is specified, then +the number of backup log files is limited to that number. +.UNINDENT +.INDENT 0.0 +.TP +.B dumpdb [\-all | \-cache | \-zones | \-adb | \-bad | \-expired | \-fail] [view ...] +This command dumps the server\(aqs caches (default) and/or zones to the dump file for +the specified views. If no view is specified, all views are dumped. +(See the \fBdump\-file\fP option in the BIND 9 Administrator Reference +Manual.) +.UNINDENT +.INDENT 0.0 +.TP +.B flush +This command flushes the server\(aqs cache. +.UNINDENT +.INDENT 0.0 +.TP +.B flushname name [view] +This command flushes the given name from the view\(aqs DNS cache and, if applicable, +from the view\(aqs nameserver address database, bad server cache, and +SERVFAIL cache. +.UNINDENT +.INDENT 0.0 +.TP +.B flushtree name [view] +This command flushes the given name, and all of its subdomains, from the view\(aqs +DNS cache, address database, bad server cache, and SERVFAIL cache. +.UNINDENT +.INDENT 0.0 +.TP +.B freeze [zone [class [view]]] +This command suspends updates to a dynamic zone. If no zone is specified, then all +zones are suspended. This allows manual edits to be made to a zone +normally updated by dynamic update, and causes changes in the +journal file to be synced into the master file. All dynamic update +attempts are refused while the zone is frozen. +.sp +See also \fI\%rndc thaw\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B halt [\-p] +This command stops the server immediately. Recent changes made through dynamic +update or IXFR are not saved to the master files, but are rolled +forward from the journal files when the server is restarted. If +\fB\-p\fP is specified, \fI\%named\fP\(aqs process ID is returned. This allows +an external process to determine when \fI\%named\fP has completed +halting. +.sp +See also \fI\%rndc stop\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B loadkeys [zone [class [view]]] +This command fetches all DNSSEC keys for the given zone from the key directory. If +they are within their publication period, they are merged into the +zone\(aqs DNSKEY RRset. Unlike \fI\%rndc sign\fP, however, the zone is not +immediately re\-signed by the new keys, but is allowed to +incrementally re\-sign over time. +.sp +This command requires that the zone be configured with a \fBdnssec\-policy\fP, or +that the \fBauto\-dnssec\fP zone option be set to \fBmaintain\fP, and also requires the +zone to be configured to allow dynamic DNS. (See \(dqDynamic Update Policies\(dq in +the Administrator Reference Manual for more details.) +.UNINDENT +.INDENT 0.0 +.TP +.B managed\-keys (status | refresh | sync | destroy) [class [view]] +This command inspects and controls the \(dqmanaged\-keys\(dq database which handles +\fI\%RFC 5011\fP DNSSEC trust anchor maintenance. If a view is specified, these +commands are applied to that view; otherwise, they are applied to all +views. +.INDENT 7.0 +.IP \(bu 2 +When run with the \fBstatus\fP keyword, this prints the current status of +the managed\-keys database. +.IP \(bu 2 +When run with the \fBrefresh\fP keyword, this forces an immediate refresh +query to be sent for all the managed keys, updating the +managed\-keys database if any new keys are found, without waiting +the normal refresh interval. +.IP \(bu 2 +When run with the \fBsync\fP keyword, this forces an immediate dump of +the managed\-keys database to disk (in the file +\fBmanaged\-keys.bind\fP or (\fBviewname.mkeys\fP). This synchronizes +the database with its journal file, so that the database\(aqs current +contents can be inspected visually. +.IP \(bu 2 +When run with the \fBdestroy\fP keyword, the managed\-keys database +is shut down and deleted, and all key maintenance is terminated. +This command should be used only with extreme caution. +.sp +Existing keys that are already trusted are not deleted from +memory; DNSSEC validation can continue after this command is used. +However, key maintenance operations cease until \fI\%named\fP is +restarted or reconfigured, and all existing key maintenance states +are deleted. +.sp +Running \fI\%rndc reconfig\fP or restarting \fI\%named\fP immediately +after this command causes key maintenance to be reinitialized +from scratch, just as if the server were being started for the +first time. This is primarily intended for testing, but it may +also be used, for example, to jumpstart the acquisition of new +keys in the event of a trust anchor rollover, or as a brute\-force +repair for key maintenance problems. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B modzone zone [class [view]] configuration +This command modifies the configuration of a zone while the server is running. This +command requires the \fBallow\-new\-zones\fP option to be set to \fByes\fP\&. +As with \fBaddzone\fP, the configuration string specified on the +command line is the zone configuration text that would ordinarily be +placed in \fI\%named.conf\fP\&. +.sp +If the zone was originally added via \fI\%rndc addzone\fP, the +configuration changes are recorded permanently and are still +in effect after the server is restarted or reconfigured. However, if +it was originally configured in \fI\%named.conf\fP, then that original +configuration remains in place; when the server is restarted or +reconfigured, the zone reverts to its original configuration. To +make the changes permanent, it must also be modified in +\fI\%named.conf\fP\&. +.sp +See also \fI\%rndc addzone\fP and \fI\%rndc delzone\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B notify zone [class [view]] +This command resends NOTIFY messages for the zone. +.UNINDENT +.INDENT 0.0 +.TP +.B notrace +This command sets the server\(aqs debugging level to 0. +.sp +See also \fI\%rndc trace\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B nta [(\-class class | \-dump | \-force | \-remove | \-lifetime duration)] domain [view] +This command sets a DNSSEC negative trust anchor (NTA) for \fBdomain\fP, with a +lifetime of \fBduration\fP\&. The default lifetime is configured in +\fI\%named.conf\fP via the \fBnta\-lifetime\fP option, and defaults to one +hour. The lifetime cannot exceed one week. +.sp +A negative trust anchor selectively disables DNSSEC validation for +zones that are known to be failing because of misconfiguration rather +than an attack. When data to be validated is at or below an active +NTA (and above any other configured trust anchors), \fI\%named\fP +aborts the DNSSEC validation process and treats the data as insecure +rather than bogus. This continues until the NTA\(aqs lifetime has +elapsed. +.sp +NTAs persist across restarts of the \fI\%named\fP server. The NTAs for a +view are saved in a file called \fBname.nta\fP, where \fBname\fP is the name +of the view; if it contains characters that are incompatible with +use as a file name, a cryptographic hash is generated from the name of +the view. +.sp +An existing NTA can be removed by using the \fB\-remove\fP option. +.sp +An NTA\(aqs lifetime can be specified with the \fB\-lifetime\fP option. +TTL\-style suffixes can be used to specify the lifetime in seconds, +minutes, or hours. If the specified NTA already exists, its lifetime +is updated to the new value. Setting \fBlifetime\fP to zero is +equivalent to \fB\-remove\fP\&. +.sp +If \fB\-dump\fP is used, any other arguments are ignored and a list +of existing NTAs is printed. Note that this may include NTAs that are +expired but have not yet been cleaned up. +.sp +Normally, \fI\%named\fP periodically tests to see whether data below +an NTA can now be validated (see the \fBnta\-recheck\fP option in the +Administrator Reference Manual for details). If data can be +validated, then the NTA is regarded as no longer necessary and is +allowed to expire early. The \fB\-force\fP parameter overrides this behavior +and forces an NTA to persist for its entire lifetime, regardless of +whether data could be validated if the NTA were not present. +.sp +The view class can be specified with \fB\-class\fP\&. The default is class +\fBIN\fP, which is the only class for which DNSSEC is currently +supported. +.sp +All of these options can be shortened, i.e., to \fB\-l\fP, \fB\-r\fP, +\fB\-d\fP, \fB\-f\fP, and \fB\-c\fP\&. +.sp +Unrecognized options are treated as errors. To refer to a domain or +view name that begins with a hyphen, use a double\-hyphen (\-\-) on the +command line to indicate the end of options. +.UNINDENT +.INDENT 0.0 +.TP +.B querylog [(on | off)] +This command enables or disables query logging. For backward compatibility, this +command can also be used without an argument to toggle query logging +on and off. +.sp +Query logging can also be enabled by explicitly directing the +\fBqueries\fP \fBcategory\fP to a \fBchannel\fP in the \fBlogging\fP section +of \fI\%named.conf\fP, or by specifying \fBquerylog yes;\fP in the +\fBoptions\fP section of \fI\%named.conf\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B reconfig +This command reloads the configuration file and loads new zones, but does not reload +existing zone files even if they have changed. This is faster than a +full \fI\%rndc reload\fP when there is a large number of zones, because it +avoids the need to examine the modification times of the zone files. +.UNINDENT +.INDENT 0.0 +.TP +.B recursing +This command dumps the list of queries \fI\%named\fP is currently +recursing on, and the list of domains to which iterative queries +are currently being sent. +.sp +The first list includes all unique clients that are waiting for +recursion to complete, including the query that is awaiting a +response and the timestamp (seconds since the Unix epoch) of +when named started processing this client query. +.sp +The second list comprises of domains for which there are active +(or recently active) fetches in progress. It reports the number +of active fetches for each domain and the number of queries that +have been passed (allowed) or dropped (spilled) as a result of +the \fBfetches\-per\-zone\fP limit. (Note: these counters are not +cumulative over time; whenever the number of active fetches for +a domain drops to zero, the counter for that domain is deleted, +and the next time a fetch is sent to that domain, it is recreated +with the counters set to zero). +.UNINDENT +.INDENT 0.0 +.TP +.B refresh zone [class [view]] +This command schedules zone maintenance for the given zone. +.UNINDENT +.INDENT 0.0 +.TP +.B reload +This command reloads the configuration file and zones. +.INDENT 7.0 +.TP +.B zone [class [view]] +.UNINDENT +.sp +If a zone is specified, this command reloads only the given zone. +.UNINDENT +.INDENT 0.0 +.TP +.B retransfer zone [class [view]] +This command retransfers the given secondary zone from the primary server. +.sp +If the zone is configured to use \fBinline\-signing\fP, the signed +version of the zone is discarded; after the retransfer of the +unsigned version is complete, the signed version is regenerated +with new signatures. +.UNINDENT +.INDENT 0.0 +.TP +.B scan +This command scans the list of available network interfaces for changes, without +performing a full \fI\%rndc reconfig\fP or waiting for the +\fBinterface\-interval\fP timer. +.UNINDENT +.INDENT 0.0 +.TP +.B secroots [\-] [view ...] +This command dumps the security roots (i.e., trust anchors configured via +\fBtrust\-anchors\fP, or the \fBmanaged\-keys\fP or \fBtrusted\-keys\fP statements +[both deprecated], or \fBdnssec\-validation auto\fP) and negative trust anchors +for the specified views. If no view is specified, all views are +dumped. Security roots indicate whether they are configured as trusted +keys, managed keys, or initializing managed keys (managed keys that have not +yet been updated by a successful key refresh query). +.sp +If the first argument is \fB\-\fP, then the output is returned via the +\fBrndc\fP response channel and printed to the standard output. +Otherwise, it is written to the secroots dump file, which defaults to +\fBnamed.secroots\fP, but can be overridden via the \fBsecroots\-file\fP +option in \fI\%named.conf\fP\&. +.sp +See also \fI\%rndc managed\-keys\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B serve\-stale (on | off | reset | status) [class [view]] +This command enables, disables, resets, or reports the current status of +the serving of stale answers as configured in \fI\%named.conf\fP\&. +.sp +If serving of stale answers is disabled by \fBrndc\-serve\-stale off\fP, then it +remains disabled even if \fI\%named\fP is reloaded or reconfigured. \fBrndc +serve\-stale reset\fP restores the setting as configured in \fI\%named.conf\fP\&. +.sp +\fBrndc serve\-stale status\fP reports whether caching and serving of stale +answers is currently enabled or disabled. It also reports the values of +\fBstale\-answer\-ttl\fP and \fBmax\-stale\-ttl\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B showzone zone [class [view]] +This command prints the configuration of a running zone. +.sp +See also \fI\%rndc zonestatus\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B sign zone [class [view]] +This command fetches all DNSSEC keys for the given zone from the key directory (see +the \fBkey\-directory\fP option in the BIND 9 Administrator Reference +Manual). If they are within their publication period, they are merged into +the zone\(aqs DNSKEY RRset. If the DNSKEY RRset is changed, then the +zone is automatically re\-signed with the new key set. +.sp +This command requires that the zone be configured with a \fBdnssec\-policy\fP, or +that the \fBauto\-dnssec\fP zone option be set to \fBallow\fP or \fBmaintain\fP, +and also requires the zone to be configured to allow dynamic DNS. (See +\(dqDynamic Update Policies\(dq in the BIND 9 Administrator Reference Manual for more +details.) +.sp +See also \fI\%rndc loadkeys\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B signing [(\-list | \-clear keyid/algorithm | \-clear all | \-nsec3param (parameters | none) | \-serial value) zone [class [view]] +This command lists, edits, or removes the DNSSEC signing\-state records for the +specified zone. The status of ongoing DNSSEC operations, such as +signing or generating NSEC3 chains, is stored in the zone in the form +of DNS resource records of type \fBsig\-signing\-type\fP\&. +\fBrndc signing \-list\fP converts these records into a human\-readable +form, indicating which keys are currently signing or have finished +signing the zone, and which NSEC3 chains are being created or +removed. +.sp +\fBrndc signing \-clear\fP can remove a single key (specified in the +same format that \fBrndc signing \-list\fP uses to display it), or all +keys. In either case, only completed keys are removed; any record +indicating that a key has not yet finished signing the zone is +retained. +.sp +\fBrndc signing \-nsec3param\fP sets the NSEC3 parameters for a zone. +This is the only supported mechanism for using NSEC3 with +\fBinline\-signing\fP zones. Parameters are specified in the same format +as an NSEC3PARAM resource record: \fBhash algorithm\fP, \fBflags\fP, \fBiterations\fP, +and \fBsalt\fP, in that order. +.sp +Currently, the only defined value for \fBhash algorithm\fP is \fB1\fP, +representing SHA\-1. The \fBflags\fP may be set to \fB0\fP or \fB1\fP, +depending on whether the opt\-out bit in the NSEC3 +chain should be set. \fBiterations\fP defines the number of additional times to apply +the algorithm when generating an NSEC3 hash. The \fBsalt\fP is a string +of data expressed in hexadecimal, a hyphen (\fB\-\fP) if no salt is to be +used, or the keyword \fBauto\fP, which causes \fI\%named\fP to generate a +random 64\-bit salt. +.sp +The only recommended configuration is \fBrndc signing \-nsec3param 1 0 0 \- zone\fP, +i.e. no salt, no additional iterations, no opt\-out. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Do not use extra iterations, salt, or opt\-out unless all their implications +are fully understood. A higher number of iterations causes interoperability +problems and opens servers to CPU\-exhausting DoS attacks. +.UNINDENT +.UNINDENT +.sp +\fBrndc signing \-nsec3param none\fP removes an existing NSEC3 chain and +replaces it with NSEC. +.sp +\fBrndc signing \-serial value\fP sets the serial number of the zone to +\fBvalue\fP\&. If the value would cause the serial number to go backwards, it +is rejected. The primary use of this parameter is to set the serial number on inline +signed zones. +.UNINDENT +.INDENT 0.0 +.TP +.B stats +This command writes server statistics to the statistics file. (See the +\fBstatistics\-file\fP option in the BIND 9 Administrator Reference +Manual.) +.UNINDENT +.INDENT 0.0 +.TP +.B status +This command displays the status of the server. Note that the number of zones includes +the internal \fBbind/CH\fP zone and the default \fB\&./IN\fP hint zone, if +there is no explicit root zone configured. +.UNINDENT +.INDENT 0.0 +.TP +.B stop \-p +This command stops the server, making sure any recent changes made through dynamic +update or IXFR are first saved to the master files of the updated +zones. If \fB\-p\fP is specified, \fI\%named\fP\(aqs process ID is returned. +This allows an external process to determine when \fI\%named\fP has +completed stopping. +.sp +See also \fI\%rndc halt\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B sync \-clean [zone [class [view]]] +This command syncs changes in the journal file for a dynamic zone to the master +file. If the \(dq\-clean\(dq option is specified, the journal file is also +removed. If no zone is specified, then all zones are synced. +.UNINDENT +.INDENT 0.0 +.TP +.B tcp\-timeouts [initial idle keepalive advertised] +When called without arguments, this command displays the current values of the +\fBtcp\-initial\-timeout\fP, \fBtcp\-idle\-timeout\fP, +\fBtcp\-keepalive\-timeout\fP, and \fBtcp\-advertised\-timeout\fP options. +When called with arguments, these values are updated. This allows an +administrator to make rapid adjustments when under a +denial\-of\-service (DoS) attack. See the descriptions of these options in the BIND 9 +Administrator Reference Manual for details of their use. +.UNINDENT +.INDENT 0.0 +.TP +.B thaw [zone [class [view]]] +This command enables updates to a frozen dynamic zone. If no zone is specified, +then all frozen zones are enabled. This causes the server to reload +the zone from disk, and re\-enables dynamic updates after the load has +completed. After a zone is thawed, dynamic updates are no longer +refused. If the zone has changed and the \fBixfr\-from\-differences\fP +option is in use, the journal file is updated to reflect +changes in the zone. Otherwise, if the zone has changed, any existing +journal file is removed. +.sp +See also \fI\%rndc freeze\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B trace [level] +If no level is specified, this command increments the server\(aqs debugging +level by one. +.INDENT 7.0 +.TP +.B level +If specified, this command sets the server\(aqs debugging level to the +provided value. +.UNINDENT +.sp +See also \fI\%rndc notrace\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B tsig\-delete keyname [view] +This command deletes a given TKEY\-negotiated key from the server. This does not +apply to statically configured TSIG keys. +.UNINDENT +.INDENT 0.0 +.TP +.B tsig\-list +This command lists the names of all TSIG keys currently configured for use by +\fI\%named\fP in each view. The list includes both statically configured keys and +dynamic TKEY\-negotiated keys. +.UNINDENT +.INDENT 0.0 +.TP +.B validation (on | off | status) [view ...] +This command enables, disables, or checks the current status of DNSSEC validation. By +default, validation is enabled. +.sp +The cache is flushed when validation is turned on or off to avoid using data +that might differ between states. +.UNINDENT +.INDENT 0.0 +.TP +.B zonestatus zone [class [view]] +This command displays the current status of the given zone, including the master +file name and any include files from which it was loaded, when it was +most recently loaded, the current serial number, the number of nodes, +whether the zone supports dynamic updates, whether the zone is DNSSEC +signed, whether it uses automatic DNSSEC key management or inline +signing, and the scheduled refresh or expiry times for the zone. +.sp +See also \fI\%rndc showzone\fP\&. +.UNINDENT +.sp +\fBrndc\fP commands that specify zone names, such as \fI\%reload\fP +\fI\%retransfer\fP, or \fI\%zonestatus\fP, can be ambiguous when applied to zones +of type \fBredirect\fP\&. Redirect zones are always called \fB\&.\fP, and can be +confused with zones of type \fBhint\fP or with secondary copies of the root +zone. To specify a redirect zone, use the special zone name +\fB\-redirect\fP, without a trailing period. (With a trailing period, this +would specify a zone called \(dq\-redirect\(dq.) +.SH LIMITATIONS +.sp +There is currently no way to provide the shared secret for a \fBserver_key\fP +without using the configuration file. +.sp +Several error messages could be clearer. +.SH SEE ALSO +.sp +\fI\%rndc.conf(5)\fP, \fI\%rndc\-confgen(8)\fP, +\fI\%named(8)\fP, \fI\%named.conf(5)\fP, BIND 9 Administrator +Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/rndc.conf.5in b/doc/man/rndc.conf.5in new file mode 100644 index 0000000..33fd93c --- /dev/null +++ b/doc/man/rndc.conf.5in @@ -0,0 +1,196 @@ +.\" 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 "RNDC.CONF" "5" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +rndc.conf \- rndc configuration file +.SH SYNOPSIS +.sp +\fBrndc.conf\fP +.SH DESCRIPTION +.sp +\fBrndc.conf\fP is the configuration file for \fI\%rndc\fP, the BIND 9 name +server control utility. This file has a similar structure and syntax to +\fI\%named.conf\fP\&. Statements are enclosed in braces and terminated with a +semi\-colon. Clauses in the statements are also semi\-colon terminated. +The usual comment styles are supported: +.sp +C style: /* */ +.sp +C++ style: // to end of line +.sp +Unix style: # to end of line +.sp +\fBrndc.conf\fP is much simpler than \fI\%named.conf\fP\&. The file uses three +statements: an options statement, a server statement, and a key +statement. +.sp +The \fBoptions\fP statement contains five clauses. The \fBdefault\-server\fP +clause is followed by the name or address of a name server. This host +is used when no name server is given as an argument to \fI\%rndc\fP\&. +The \fBdefault\-key\fP clause is followed by the name of a key, which is +identified by a \fBkey\fP statement. If no \fBkeyid\fP is provided on the +rndc command line, and no \fBkey\fP clause is found in a matching +\fBserver\fP statement, this default key is used to authenticate the +server\(aqs commands and responses. The \fBdefault\-port\fP clause is followed +by the port to connect to on the remote name server. If no \fBport\fP +option is provided on the rndc command line, and no \fBport\fP clause is +found in a matching \fBserver\fP statement, this default port is used +to connect. The \fBdefault\-source\-address\fP and +\fBdefault\-source\-address\-v6\fP clauses can be used to set the IPv4 +and IPv6 source addresses respectively. +.sp +After the \fBserver\fP keyword, the server statement includes a string +which is the hostname or address for a name server. The statement has +three possible clauses: \fBkey\fP, \fBport\fP, and \fBaddresses\fP\&. The key +name must match the name of a key statement in the file. The port number +specifies the port to connect to. If an \fBaddresses\fP clause is supplied, +these addresses are used instead of the server name. Each address +can take an optional port. If an \fBsource\-address\fP or +\fBsource\-address\-v6\fP is supplied, it is used to specify the +IPv4 and IPv6 source address, respectively. +.sp +The \fBkey\fP statement begins with an identifying string, the name of the +key. The statement has two clauses. \fBalgorithm\fP identifies the +authentication algorithm for \fI\%rndc\fP to use; currently only HMAC\-MD5 +(for compatibility), HMAC\-SHA1, HMAC\-SHA224, HMAC\-SHA256 (default), +HMAC\-SHA384, and HMAC\-SHA512 are supported. This is followed by a secret +clause which contains the base\-64 encoding of the algorithm\(aqs +authentication key. The base\-64 string is enclosed in double quotes. +.sp +There are two common ways to generate the base\-64 string for the secret. +The BIND 9 program \fI\%rndc\-confgen\fP can be used to generate a random +key, or the \fBmmencode\fP program, also known as \fBmimencode\fP, can be +used to generate a base\-64 string from known input. \fBmmencode\fP does +not ship with BIND 9 but is available on many systems. See the Example +section for sample command lines for each. +.SH EXAMPLE +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +options { + default\-server localhost; + default\-key samplekey; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +server localhost { + key samplekey; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +server testserver { + key testkey; + addresses { localhost port 5353; }; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +key samplekey { + algorithm hmac\-sha256; + secret \(dq6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz\(dq; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +key testkey { + algorithm hmac\-sha256; + secret \(dqR3HI8P6BKw9ZwXwN3VZKuQ==\(dq; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In the above example, \fI\%rndc\fP by default uses the server at +localhost (127.0.0.1) and the key called \(dqsamplekey\(dq. Commands to the +localhost server use the \(dqsamplekey\(dq key, which must also be defined +in the server\(aqs configuration file with the same name and secret. The +key statement indicates that \(dqsamplekey\(dq uses the HMAC\-SHA256 algorithm +and its secret clause contains the base\-64 encoding of the HMAC\-SHA256 +secret enclosed in double quotes. +.sp +If \fI\%rndc \-s testserver\fP is used, then \fI\%rndc\fP connects to the server +on localhost port 5353 using the key \(dqtestkey\(dq. +.sp +To generate a random secret with \fI\%rndc\-confgen\fP: +.sp +\fI\%rndc\-confgen\fP +.sp +A complete \fBrndc.conf\fP file, including the randomly generated key, +is written to the standard output. Commented\-out \fBkey\fP and +\fBcontrols\fP statements for \fI\%named.conf\fP are also printed. +.sp +To generate a base\-64 secret with \fBmmencode\fP: +.sp +\fBecho \(dqknown plaintext for a secret\(dq | mmencode\fP +.SH NAME SERVER CONFIGURATION +.sp +The name server must be configured to accept rndc connections and to +recognize the key specified in the \fBrndc.conf\fP file, using the +controls statement in \fI\%named.conf\fP\&. See the sections on the +\fBcontrols\fP statement in the BIND 9 Administrator Reference Manual for +details. +.SH SEE ALSO +.sp +\fI\%rndc(8)\fP, \fI\%rndc\-confgen(8)\fP, \fBmmencode(1)\fP, BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/rndc.conf.rst b/doc/man/rndc.conf.rst new file mode 100644 index 0000000..f575060 --- /dev/null +++ b/doc/man/rndc.conf.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/rndc/rndc.conf.rst diff --git a/doc/man/rndc.rst b/doc/man/rndc.rst new file mode 100644 index 0000000..a330531 --- /dev/null +++ b/doc/man/rndc.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/rndc/rndc.rst diff --git a/doc/man/tsig-keygen.8in b/doc/man/tsig-keygen.8in new file mode 100644 index 0000000..c97ad29 --- /dev/null +++ b/doc/man/tsig-keygen.8in @@ -0,0 +1,66 @@ +.\" 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 "TSIG-KEYGEN" "8" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9" +.SH NAME +tsig-keygen \- TSIG key generation tool +.SH SYNOPSIS +.sp +\fBtsig\-keygen\fP [\fB\-a\fP algorithm] [\fB\-h\fP] [name] +.SH DESCRIPTION +.sp +\fBtsig\-keygen\fP is an utility that generates keys for use in TSIG signing. +The resulting keys can be used, for example, to secure dynamic DNS updates +to a zone, or for the \fI\%rndc\fP command channel. +.sp +A domain name can be specified on the command line to be used as the name +of the generated key. If no name is specified, the default is \fBtsig\-key\fP\&. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \-a algorithm +This option specifies the algorithm to use for the TSIG key. Available +choices are: hmac\-md5, hmac\-sha1, hmac\-sha224, hmac\-sha256, hmac\-sha384, +and hmac\-sha512. The default is hmac\-sha256. Options are +case\-insensitive, and the \(dqhmac\-\(dq prefix may be omitted. +.UNINDENT +.INDENT 0.0 +.TP +.B \-h +This option prints a short summary of options and arguments. +.UNINDENT +.SH SEE ALSO +.sp +\fI\%nsupdate(1)\fP, \fI\%named.conf(5)\fP, \fI\%named(8)\fP, BIND 9 Administrator Reference Manual. +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/tsig-keygen.rst b/doc/man/tsig-keygen.rst new file mode 100644 index 0000000..fbd957d --- /dev/null +++ b/doc/man/tsig-keygen.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +:orphan: + +.. include:: ../../bin/confgen/tsig-keygen.rst -- cgit v1.2.3