diff options
Diffstat (limited to 'doc/man')
81 files changed, 9685 insertions, 0 deletions
diff --git a/doc/man/Makefile.in b/doc/man/Makefile.in new file mode 100644 index 0000000..75794f7 --- /dev/null +++ b/doc/man/Makefile.in @@ -0,0 +1,275 @@ +# 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. + +srcdir = @srcdir@ +VPATH = @srcdir@ +top_srcdir = @top_srcdir@ +abs_srcdir = @abs_srcdir@ +builddir = @builddir@ +top_builddir = @top_builddir@ + +@BIND9_MAKE_RULES@ + +man1_MANS = \ + arpaname.1 \ + delv.1 \ + dig.1 \ + host.1 \ + mdig.1 \ + named-rrchecker.1 \ + nslookup.1 \ + nsupdate.1 + +man5_MANS = \ + named.conf.5 \ + rndc.conf.5 + +man8_MANS = \ + ddns-confgen.8 \ + dnssec-cds.8 \ + dnssec-checkds.8 \ + dnssec-coverage.8 \ + dnssec-dsfromkey.8 \ + dnssec-importkey.8 \ + dnssec-keyfromlabel.8 \ + dnssec-keygen.8 \ + dnssec-keymgr.8 \ + dnssec-revoke.8 \ + dnssec-settime.8 \ + dnssec-signzone.8 \ + dnssec-verify.8 \ + filter-aaaa.8 \ + named-checkconf.8 \ + named-checkzone.8 \ + named-compilezone.8 \ + named-journalprint.8 \ + named.8 \ + nsec3hash.8 \ + rndc-confgen.8 \ + rndc.8 \ + tsig-keygen.8 + +MANPAGES_RST = \ + arpaname.rst \ + ddns-confgen.rst \ + delv.rst \ + dig.rst \ + dnssec-cds.rst \ + dnssec-checkds.rst \ + dnssec-coverage.rst \ + dnssec-dsfromkey.rst \ + dnssec-importkey.rst \ + dnssec-keyfromlabel.rst \ + dnssec-keygen.rst \ + dnssec-keymgr.rst \ + dnssec-revoke.rst \ + dnssec-settime.rst \ + dnssec-signzone.rst \ + dnssec-verify.rst \ + dnstap-read.rst \ + filter-aaaa.rst \ + host.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 \ + pkcs11-destroy.rst \ + pkcs11-keygen.rst \ + pkcs11-list.rst \ + pkcs11-tokens.rst + +MANPAGES_IN = \ + arpaname.1in \ + ddns-confgen.8in \ + delv.1in \ + dig.1in \ + dnssec-cds.8in \ + dnssec-checkds.8in \ + dnssec-coverage.8in \ + dnssec-dsfromkey.8in \ + dnssec-importkey.8in \ + dnssec-keyfromlabel.8in \ + dnssec-keygen.8in \ + dnssec-keymgr.8in \ + dnssec-revoke.8in \ + dnssec-settime.8in \ + dnssec-signzone.8in \ + dnssec-verify.8in \ + dnstap-read.1in \ + filter-aaaa.8in \ + host.1in \ + mdig.1in \ + named-checkconf.8in \ + named-checkzone.8in \ + named-compilezone.8in \ + named-journalprint.8in \ + named-nzd2nzf.8in \ + named-rrchecker.1in \ + named.conf.5in \ + named.8in \ + nsec3hash.8in \ + nslookup.1in \ + nsupdate.1in \ + rndc-confgen.8in \ + rndc.conf.5in \ + rndc.8in \ + tsig-keygen.8in \ + pkcs11-destroy.8in \ + pkcs11-keygen.8in \ + pkcs11-list.8in \ + pkcs11-tokens.8in + +dnstap_man1_MANS = \ + dnstap-read.1 + +nzd_man8_MANS = \ + named-nzd2nzf.8 + +pkcs11_man8_MANS = \ + pkcs11-destroy.8 \ + pkcs11-keygen.8 \ + pkcs11-list.8 \ + pkcs11-tokens.8 + +BIND9_VERSION=@BIND9_VERSION@ +RELEASE_DATE=@RELEASE_DATE@ +BIND9_VERSIONSTRING=@BIND9_VERSIONSTRING@ + +# You can set these variables from the command line. +SPHINXBUILD = @SPHINX_BUILD@ +SPHINXBUILDDIR = ${builddir}/_build +SPHINX_W = -W + +common_SPHINXOPTS = \ + $(SPHINX_W) \ + -a \ + -v \ + -c "${abs_srcdir}" + +ALLSPHINXOPTS = \ + $(common_SPHINXOPTS) \ + -D version="${BIND9_VERSION}" \ + -D today="${RELEASE_DATE}" \ + -D release="${BIND9_VERSIONSTRING}" \ + $(SPHINXOPTS) \ + ${srcdir} + +man_SPHINXOPTS = \ + $(common_SPHINXOPTS) \ + -D version="@""BIND9_VERSION""@" \ + -D today="@""RELEASE_DATE""@" \ + -D release="@""BIND9_VERSIONSTRING""@" \ + $(SPHINXOPTS) \ + ${srcdir} + +# Put it first so that "make" without argument just builds manpages +all: man + @: + +man:: ootsetup $(man1_MANS) $(man5_MANS) $(man8_MANS) @DNSTAP_MANS@ @NZD_MANS@ @PKCS11_MANS@ + +doc:: @HTMLTARGET@ @PDFTARGET@ + +html dirhtml: + $(SPHINXBUILD) -b $@ -d "$(SPHINXBUILDDIR)"/.doctrees/$@ $(ALLSPHINXOPTS) "$(SPHINXBUILDDIR)"/$@ + +# copy in out-of-tree files in case sphinx-build isn't available +.NOTPARALLEL: +ootsetup: $(MANPAGES_IN) + for man in $(MANPAGES_IN); do \ + [ -e "$$man" ] || cp -f ${srcdir}/"$$man" .; \ + done + +$(MANPAGES_IN): $(MANPAGES_RST) + $(SPHINXBUILD) -b man -d "$(SPHINXBUILDDIR)"/.doctrees/$@ $(man_SPHINXOPTS) "$(SPHINXBUILDDIR)"/man + -for man in $(MANPAGES_IN); do \ + [ -e "$(SPHINXBUILDDIR)"/man/"$$(basename $$man in)" ] && \ + cp -f "$(SPHINXBUILDDIR)"/man/"$$(basename $$man in)" "$$man"; \ + done + +man_SUBST = sed \ + -e 's,[@]BIND9_VERSION[@],$(BIND9_VERSION),' \ + -e 's,[@]RELEASE_DATE[@],$(RELEASE_DATE),' \ + -e 's,[@]BIND9_VERSION_STRING[@],$(BIND9_VERSION_STRING),' \ + -e 's,[@]sysconfdir[@],$(sysconfdir),' \ + -e 's,[@]plugindir[@],$(plugindir),' + +$(man1_MANS): @MANSRCS@ + for m in $(man1_MANS); do \ + $(man_SUBST) $${m}in > $$m; \ + done + +$(man5_MANS): @MANSRCS@ + for m in $(man5_MANS); do \ + $(man_SUBST) $${m}in > $$m; \ + done + +$(man8_MANS): @MANSRCS@ + for m in $(man8_MANS); do \ + $(man_SUBST) $${m}in > $$m; \ + done + +$(dnstap_man1_MANS): @MANSRCS@ + for m in $(dnstap_man1_MANS); do \ + $(man_SUBST) $${m}in > $$m; \ + done + +$(nzd_man8_MANS): @MANSRCS@ + for m in $(nzd_man8_MANS); do \ + $(man_SUBST) $${m}in > $$m; \ + done + +$(pkcs11_man8_MANS): @MANSRCS@ + for m in $(pkcs11_man8_MANS); do \ + $(man_SUBST) $${m}in > $$m; \ + done + +.PHONY: help Makefile doc pdf man + +installdirs: + $(SHELL) ${top_srcdir}/mkinstalldirs ${DESTDIR}${mandir}/man1 + $(SHELL) ${top_srcdir}/mkinstalldirs ${DESTDIR}${mandir}/man5 + $(SHELL) ${top_srcdir}/mkinstalldirs ${DESTDIR}${mandir}/man8 + +install:: installdirs + for m in $(man1_MANS); do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man1/; done + for m in $(man5_MANS); do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man5/; done + for m in $(man8_MANS); do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man8/; done + for m in @DNSTAP_MANS@; do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man1/; done + for m in @NZD_MANS@; do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man8/; done + for m in @PKCS11_MANS@; do ${INSTALL_DATA} $$m ${DESTDIR}${mandir}/man8/; done + +uninstall:: + for m in $(man1_MANS); do rm -f ${DESTDIR}${mandir}/man1/$$m; done + for m in $(man5_MANS); do rm -f ${DESTDIR}${mandir}/man5/$$m; done + for m in $(man8_MANS); do rm -f ${DESTDIR}${mandir}/man8/$$m; done + for m in @DNSTAP_MANS@; do rm -f ${DESTDIR}${mandir}/man1/$$m; done + for m in @NZD_MANS@; do rm -f ${DESTDIR}${mandir}/man8/$$m; done + for m in @PKCS11_MANS@; do rm -f ${DESTDIR}${mandir}/man8/$$m; done + +docclean manclean maintainer-clean:: + rm -f $(MANPAGES_IN) + +clean:: + -rm -rf $(SPHINXBUILDDIR) + -rm -f $(man1_MANS) $(man5_MANS) $(man8_MANS) @DNSTAP_MANS@ @NZD_MANS@ @PKCS11_MANS@ diff --git a/doc/man/arpaname.1in b/doc/man/arpaname.1in new file mode 100644 index 0000000..2c25399 --- /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@" "@BIND9_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..266dfbb --- /dev/null +++ b/doc/man/conf.py @@ -0,0 +1,216 @@ +# 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. + +import datetime +from docutils.parsers.rst import roles + +# +# 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 +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/<section>/. +# 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, + 8, + ), + ( + "dnssec-checkds", + "dnssec-checkds", + "DNSSEC delegation consistency checking tool", + author, + 8, + ), + ( + "dnssec-coverage", + "dnssec-coverage", + "checks future DNSKEY coverage for a zone", + author, + 8, + ), + ("dnssec-dsfromkey", "dnssec-dsfromkey", "DNSSEC DS RR generation tool", author, 8), + ( + "dnssec-importkey", + "dnssec-importkey", + "import DNSKEY records from external systems so they can be managed", + author, + 8, + ), + ( + "dnssec-keyfromlabel", + "dnssec-keyfromlabel", + "DNSSEC key generation tool", + author, + 8, + ), + ("dnssec-keygen", "dnssec-keygen", "DNSSEC key generation tool", author, 8), + ( + "dnssec-keymgr", + "dnssec-keymgr", + "ensure correct DNSKEY coverage based on a defined policy", + author, + 8, + ), + ( + "dnssec-revoke", + "dnssec-revoke", + "set the REVOKED bit on a DNSSEC key", + author, + 8, + ), + ( + "dnssec-settime", + "dnssec-settime", + "set the key timing metadata for a DNSSEC key", + author, + 8, + ), + ("dnssec-signzone", "dnssec-signzone", "DNSSEC zone signing tool", author, 8), + ("dnssec-verify", "dnssec-verify", "DNSSEC zone verification tool", author, 8), + ( + "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, + ), + ("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, + 8, + ), + ( + "named-checkzone", + "named-checkzone", + "zone file validity checking or converting tool", + author, + 8, + ), + ( + "named-compilezone", + "named-compilezone", + "zone file validity checking or converting tool", + author, + 8, + ), + ( + "named-journalprint", + "named-journalprint", + "print zone journal in human-readable form", + author, + 8, + ), + ( + "named-nzd2nzf", + "named-nzd2nzf", + "convert an NZD database to NZF text format", + author, + 8, + ), + ( + "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, 8), + ("nslookup", "nslookup", "query Internet name servers interactively", author, 1), + ("nsupdate", "nsupdate", "dynamic DNS update utility", author, 1), + ("pkcs11-destroy", "pkcs11-destroy", "destroy PKCS#11 objects", author, 8), + ("pkcs11-keygen", "pkcs11-keygen", "generate keys on a PKCS#11 device", author, 8), + ("pkcs11-list", "pkcs11-list", "list PKCS#11 objects", author, 8), + ("pkcs11-tokens", "pkcs11-tokens", "list PKCS#11 available tokens", author, 8), + ("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), +] + + +def setup(app): + app.add_crossref_type("iscman", "iscman", "pair: %s; manual page") + # ignore :option: references to simplify doc backports to v9_16 branch + app.add_role_to_domain("std", "option", roles.code_role) diff --git a/doc/man/ddns-confgen.8in b/doc/man/ddns-confgen.8in new file mode 100644 index 0000000..97e1cf8 --- /dev/null +++ b/doc/man/ddns-confgen.8in @@ -0,0 +1,102 @@ +.\" 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@" "@BIND9_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 \fBrndc\fP command channel. +.sp +The key name can specified using \fB\-k\fP parameter and defaults to \fBddns\-key\fP\&. +The generated key is accompanied by configuration text and instructions that +can be used with \fBnsupdate\fP and \fBnamed\fP when setting up dynamic DNS, +including an example \fBupdate\-policy\fP statement. +(This usage is similar to the \fBrndc\-confgen\fP command for setting up +command\-channel security.) +.sp +Note that \fBnamed\fP itself can configure a local DDNS key for use with +\fBnsupdate \-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 \fBnsupdate\fP is to +be used from a remote system. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-a algorithm\fP +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. +.TP +.B \fB\-h\fP +This option prints a short summary of options and arguments. +.TP +.B \fB\-k keyname\fP +This option specifies the key name of the DDNS authentication key. The +default is \fBddns\-key\fP when neither the \fB\-s\fP nor \fB\-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. +.TP +.B \fB\-q\fP +This option enables quiet mode, which prints only the key, with no +explanatory text or usage examples. This is essentially identical to +\fBtsig\-keygen\fP\&. +.TP +.B \fB\-s name\fP +This option generates a configuration example to allow dynamic updates +of a single hostname. The example \fBnamed.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 \fB\-z\fP option. +.TP +.B \fB\-z zone\fP +This option generates a configuration example to allow +dynamic updates of a zone. The example \fBnamed.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 \fB\-s\fP option. +.UNINDENT +.SH SEE ALSO +.sp +\fBnsupdate(1)\fP, \fBnamed.conf(5)\fP, \fBnamed(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..9a2b186 --- /dev/null +++ b/doc/man/delv.1in @@ -0,0 +1,345 @@ +.\" 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@" "@BIND9_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 \fBnamed\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 \fBserver\fP +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 \fB\-4\fP or \fB\-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). +.TP +.B \fBname\fP +is the domain name to be looked up. +.TP +.B \fBtype\fP +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 \fB\-a anchor\-file\fP +This option specifies a file from which to read DNSSEC trust anchors. The default +is \fB/etc/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 \fB+root=NAME\fP options. +.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 +\fBnamed\fP, which means that if either of the keys in \fB/etc/bind.keys\fP is +revoked and rolled over, \fB/etc/bind.keys\fP must be updated to +use DNSSEC validation in \fBdelv\fP\&. +.TP +.B \fB\-b address\fP +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#<port>\fP +.TP +.B \fB\-c class\fP +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. +.TP +.B \fB\-d level\fP +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 +\fB+mtrace\fP, \fB+rtrace\fP, and \fB+vtrace\fP options below for +additional debugging details. +.TP +.B \fB\-h\fP +This option displays the \fBdelv\fP help usage output and exits. +.TP +.B \fB\-i\fP +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 +\fBdig +cd\fP\&.) +.TP +.B \fB\-m\fP +This option enables memory usage debugging. +.TP +.B \fB\-p port#\fP +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. +.TP +.B \fB\-q name\fP +This option sets the query name to \fBname\fP\&. While the query name can be +specified without using the \fB\-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). +.TP +.B \fB\-t type\fP +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 \fB\-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 \fB\-x\fP option is supplied +to indicate a reverse lookup, in which case it is \(dqPTR\(dq. +.TP +.B \fB\-v\fP +This option prints the \fBdelv\fP version and exits. +.TP +.B \fB\-x addr\fP +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 \fB\-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. +.TP +.B \fB\-4\fP +This option forces \fBdelv\fP to only use IPv4. +.TP +.B \fB\-6\fP +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 \fB+[no]cdflag\fP +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. +.TP +.B \fB+[no]class\fP +This option controls whether to display the CLASS when printing a record. The +default is to display the CLASS. +.TP +.B \fB+[no]ttl\fP +This option controls whether to display the TTL when printing a record. The +default is to display the TTL. +.TP +.B \fB+[no]rtrace\fP +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 +\fB\-d\fP option produces the same output, but affects other +logging categories as well. +.TP +.B \fB+[no]mtrace\fP +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 \fB\-d\fP option produces the same +output, but affects other logging categories as well. +.TP +.B \fB+[no]vtrace\fP +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 \fB\-d\fP option produces the +same output, but affects other logging categories as well. +.TP +.B \fB+[no]short\fP +This option toggles between verbose and terse answers. The default is to print the answer in a +verbose form. +.TP +.B \fB+[no]comments\fP +This option toggles the display of comment lines in the output. The default is to +print comments. +.TP +.B \fB+[no]rrcomments\fP +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. +.TP +.B \fB+[no]crypto\fP +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\&. +.TP +.B \fB+[no]trust\fP +This option controls whether to display the trust level when printing a record. +The default is to display the trust level. +.TP +.B \fB+[no]split[=W]\fP +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. +.TP +.B \fB+[no]all\fP +This option sets or clears the display options \fB+[no]comments\fP, +\fB+[no]rrcomments\fP, and \fB+[no]trust\fP as a group. +.TP +.B \fB+[no]multiline\fP +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. +.TP +.B \fB+[no]dnssec\fP +This option indicates whether to display RRSIG records in the \fBdelv\fP output. +The default is to do so. Note that (unlike in \fBdig\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 \fB\-i\fP or +\fB+noroot\fP\&. +.TP +.B \fB+[no]root[=ROOT]\fP +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 \fB\-a\fP must be used to specify a +file containing the key. +.TP +.B \fB+[no]tcp\fP +This option controls whether to use TCP when sending queries. The default is to +use UDP unless a truncated response has been received. +.TP +.B \fB+[no]unknownformat\fP +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. +.TP +.B \fB+[no]yaml\fP +This option prints response data in YAML format. +.UNINDENT +.SH FILES +.sp +\fB/etc/bind.keys\fP +.sp +\fB/etc/resolv.conf\fP +.SH SEE ALSO +.sp +\fBdig(1)\fP, \fBnamed(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..fd6d6f8 --- /dev/null +++ b/doc/man/dig.1in @@ -0,0 +1,670 @@ +.\" 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@" "@BIND9_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 \fB\-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 \fB\-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 \fB\-t\fP and \fB\-c\fP options to specify the type and +class, use the \fB\-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 \fBserver\fP +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 \fB\-4\fP or \fB\-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. +.TP +.B \fBname\fP +is the name of the resource record that is to be looked up. +.TP +.B \fBtype\fP +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 \fB\-4\fP +This option indicates that only IPv4 should be used. +.TP +.B \fB\-6\fP +This option indicates that only IPv6 should be used. +.TP +.B \fB\-b address[#port]\fP +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\&. +.TP +.B \fB\-c class\fP +This option sets the query class. The default \fBclass\fP is IN; other classes are +HS for Hesiod records or CH for Chaosnet records. +.TP +.B \fB\-f file\fP +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. +.TP +.B \fB\-k keyfile\fP +This option tells \fBnamed\fP to sign queries using TSIG using a key read from the given file. Key +files can be generated using \fBtsig\-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 +\fBnamed.conf\fP\&. +.TP +.B \fB\-m\fP +This option enables memory usage debugging. +.TP +.B \fB\-p port\fP +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. +.TP +.B \fB\-q name\fP +This option specifies the domain name to query. This is useful to distinguish the \fBname\fP +from other arguments. +.TP +.B \fB\-r\fP +This option indicates that options from \fB${HOME}/.digrc\fP should not be read. This is useful for +scripts that need predictable behavior. +.TP +.B \fB\-t type\fP +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 \fB\-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\&. +.TP +.B \fB\-u\fP +This option indicates that print query times should be provided in microseconds instead of milliseconds. +.TP +.B \fB\-v\fP +This option prints the version number and exits. +.TP +.B \fB\-x addr\fP +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 \fB\-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. +.TP +.B \fB\-y [hmac:]keyname:secret\fP +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 \fB\-k\fP option should be used, rather than the \fB\-y\fP option, +because with \fB\-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, \fB+cd\fP is equivalent to +\fB+cdflag\fP\&. The query options are: +.INDENT 0.0 +.TP +.B \fB+[no]aaflag\fP +This option is a synonym for \fB+[no]aaonly\fP\&. +.TP +.B \fB+[no]aaonly\fP +This option sets the \fBaa\fP flag in the query. +.TP +.B \fB+[no]additional\fP +This option displays [or does not display] the additional section of a reply. The +default is to display it. +.TP +.B \fB+[no]adflag\fP +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. +.TP +.B \fB+[no]all\fP +This option sets or clears all display flags. +.TP +.B \fB+[no]answer\fP +This option displays [or does not display] the answer section of a reply. The default +is to display it. +.TP +.B \fB+[no]authority\fP +This option displays [or does not display] the authority section of a reply. The +default is to display it. +.TP +.B \fB+[no]badcookie\fP +This option retries the lookup with a new server cookie if a BADCOOKIE response is +received. +.TP +.B \fB+[no]besteffort\fP +This option attempts to display the contents of messages which are malformed. The +default is to not display malformed answers. +.TP +.B \fB+bufsize[=B]\fP +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=0\fP disables EDNS (use +\fB+bufsize=0 +edns\fP to send an EDNS message with an advertised size +of 0 bytes). \fB+bufsize\fP restores the default buffer size. +.TP +.B \fB+[no]cdflag\fP +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. +.TP +.B \fB+[no]class\fP +This option displays [or does not display] the CLASS when printing the record. +.TP +.B \fB+[no]cmd\fP +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. +.TP +.B \fB+[no]comments\fP +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 +\fB+[no]cmd\fP, \fB+[no]question\fP, \fB+[no]stats\fP, and \fB+[no]rrcomments\fP\&. +.TP +.B \fB+[no]cookie=####\fP +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 \fB+trace\fP is set to better emulate the +default queries from a nameserver. +.TP +.B \fB+[no]crypto\fP +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\&. +.TP +.B \fB+[no]defname\fP +This option, which is deprecated, is treated as a synonym for \fB+[no]search\fP\&. +.TP +.B \fB+[no]dnssec\fP +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. +.TP +.B \fB+domain=somename\fP +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 \fB+search\fP option were +given. +.TP +.B \fB+dscp=value\fP +This option sets the DSCP code point to be used when sending the query. Valid DSCP +code points are in the range [0...63]. By default no code point is +explicitly set. +.TP +.B \fB+[no]edns[=#]\fP +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. +.TP +.B \fB+[no]ednsflags[=#]\fP +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. +.TP +.B \fB+[no]ednsnegotiation\fP +This option enables/disables EDNS version negotiation. By default, EDNS version +negotiation is enabled. +.TP +.B \fB+[no]ednsopt[=code[:value]]\fP +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. +.TP +.B \fB+[no]expire\fP +This option sends an EDNS Expire option. +.TP +.B \fB+[no]fail\fP +This option indicates that \fBnamed\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. +.TP +.B \fB+[no]header\-only\fP +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. +.TP +.B \fB+[no]identify\fP +This option shows [or does not show] the IP address and port number that supplied +the answer, when the \fB+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. +.TP +.B \fB+[no]idnin\fP +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. +.TP +.B \fB+[no]idnout\fP +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. +.TP +.B \fB+[no]ignore\fP +This option ignores [or does not ignore] truncation in UDP responses instead of retrying with TCP. By +default, TCP retries are performed. +.TP +.B \fB+[no]keepalive\fP +This option sends [or does not send] an EDNS Keepalive option. +.TP +.B \fB+[no]keepopen\fP +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\&. +.TP +.B \fB+[no]mapped\fP +This option allows [or does not allow] mapped IPv4\-over\-IPv6 addresses to be used. The default is +\fB+mapped\fP\&. +.TP +.B \fB+[no]multiline\fP +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. +.TP +.B \fB+ndots=D\fP +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 +\fB+search\fP is set. +.TP +.B \fB+[no]nsid\fP +When enabled, this option includes an EDNS name server ID request when sending a query. +.TP +.B \fB+[no]nssearch\fP +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. +.TP +.B \fB+[no]onesoa\fP +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. +.TP +.B \fB+[no]opcode=value\fP +When enabled, this option sets (restores) the DNS message opcode to the specified value. The +default value is QUERY (0). +.TP +.B \fB+padding=value\fP +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. +.TP +.B \fB+[no]qr\fP +This option toggles the display of the query message as it is sent. By default, the query +is not printed. +.TP +.B \fB+[no]question\fP +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. +.TP +.B \fB+[no]raflag\fP +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. +.TP +.B \fB+[no]rdflag\fP +This option is a synonym for \fB+[no]recurse\fP\&. +.TP +.B \fB+[no]recurse\fP +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 +\fB+nssearch\fP or \fB+trace\fP query option is used. +.TP +.B \fB+retry=T\fP +This option sets the number of times to retry UDP and TCP queries to server to \fBT\fP +instead of the default, 2. Unlike \fB+tries\fP, this does not include +the initial query. +.TP +.B \fB+[no]rrcomments\fP +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. +.TP +.B \fB+[no]search\fP +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 +\fB+ndots\fP, determines whether the name is treated as relative +and hence whether a search is eventually performed. +.TP +.B \fB+[no]short\fP +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. +.TP +.B \fB+[no]showsearch\fP +This option performs [or does not perform] a search showing intermediate results. +.TP +.B \fB+[no]sigchase\fP +This feature is now obsolete and has been removed; use \fBdelv\fP +instead. +.TP +.B \fB+split=W\fP +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. +.TP +.B \fB+[no]stats\fP +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. +.TP +.B \fB+[no]subnet=addr[/prefix\-length]\fP +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. +.TP +.B \fB+[no]tcflag\fP +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. +.TP +.B \fB+[no]tcp\fP +This option uses [or does not 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\&. +.TP +.B \fB+timeout=T\fP +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. +.TP +.B \fB+[no]topdown\fP +This feature is related to \fBdig +sigchase\fP, which is obsolete and +has been removed. Use \fBdelv\fP instead. +.TP +.B \fB+[no]trace\fP +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 +\fB+dnssec\fP is also set when \fB+trace\fP is set, to better emulate the +default queries from a name server. +.TP +.B \fB+tries=T\fP +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. +.TP +.B \fB+trusted\-key=####\fP +This option formerly specified trusted keys for use with \fBdig +sigchase\fP\&. This +feature is now obsolete and has been removed; use \fBdelv\fP instead. +.TP +.B \fB+[no]ttlid\fP +This option displays [or does not display] the TTL when printing the record. +.TP +.B \fB+[no]ttlunits\fP +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 \fB+ttlid\fP\&. +.TP +.B \fB+[no]unexpected\fP +This option accepts [or does not accept] answers from unexpected sources. By default, \fBdig\fP +will not accept a reply from a source other than the one to which it sent the +query. +.TP +.B \fB+[no]unknownformat\fP +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. +.TP +.B \fB+[no]vc\fP +This option uses [or does not use] TCP when querying name servers. This alternate +syntax to \fB+[no]tcp\fP is provided for backwards compatibility. The +\fBvc\fP stands for \(dqvirtual circuit.\(dq +.TP +.B \fB+[no]yaml\fP +When enabled, this option prints the responses (and, if \fB+qr\fP is in use, also the +outgoing queries) in a detailed YAML format. +.TP +.B \fB+[no]zflag\fP +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 \fB\-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 \fB+[no]cmd\fP and +\fB+[no]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 +\fB+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 \fB+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 +\fB+noidnin\fP and \fB+noidnout\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 +\fBdelv(1)\fP, \fBhost(1)\fP, \fBnamed(8)\fP, \fBdnssec\-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.8in b/doc/man/dnssec-cds.8in new file mode 100644 index 0000000..f915c35 --- /dev/null +++ b/doc/man/dnssec-cds.8in @@ -0,0 +1,229 @@ +.\" 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" "8" "@RELEASE_DATE@" "@BIND9_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 \fB\-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 \fB\-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 +\fBdnssec\-signzone\fP, or the output of \fBdnssec\-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 \fB\-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 \fB\-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, \fBdnssec\-cds \-u\fP writes an \fBnsupdate\fP script to the +standard output. The \fB\-u\fP and \fB\-i\fP options can be used together to +maintain a \fBdsset\-\fP file as well as emit an \fBnsupdate\fP script. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-a algorithm\fP +This option specifies a digest algorithm to use when converting CDNSKEY records to +DS records. This option can be repeated, so that multiple DS records +are created for each CDNSKEY record. This option has no effect when +using CDS 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. +.TP +.B \fB\-c class\fP +This option specifies the DNS class of the zones. +.TP +.B \fB\-D\fP +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. +.TP +.B \fB\-d path\fP +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 \fB\-s\fP option. +.TP +.B \fB\-f child\-file\fP +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. +.TP +.B \fB\-iextension\fP +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 \fB\-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. +.TP +.B \fB\-s start\-time\fP +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. +.TP +.B \fB\-T ttl\fP +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. +.TP +.B \fB\-u\fP +This option writes an \fBnsupdate\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 \fB\-T\fP option, or using the +\fBnsupdate\fP \fBttl\fP command. +.TP +.B \fB\-V\fP +This option prints version information. +.TP +.B \fB\-v level\fP +This option sets the debugging level. Level 1 is intended to be usefully verbose +for general users; higher levels are intended for developers. +.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 \fBdnssec\-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 +\fBdig\fP as in the script below. It is acceptable if the \fBdig\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 \fBnamed\fP, +\fBdnssec\-cds\fP can be used with \fBnsupdate\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 +\fBdig(1)\fP, \fBdnssec\-settime(8)\fP, \fBdnssec\-signzone(8)\fP, \fBnsupdate(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-checkds.8in b/doc/man/dnssec-checkds.8in new file mode 100644 index 0000000..8a1328b --- /dev/null +++ b/doc/man/dnssec-checkds.8in @@ -0,0 +1,96 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "DNSSEC-CHECKDS" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9" +.SH NAME +dnssec-checkds \- DNSSEC delegation consistency checking tool +.SH SYNOPSIS +.sp +\fBdnssec\-checkds\fP [\fB\-d\fP\fIdig path\fP] [\fB\-D\fP\fIdsfromkey path\fP] +[\fB\-f\fP\fIfile\fP] [\fB\-l\fP\fIdomain\fP] [\fB\-s\fP\fIfile\fP] {zone} +.SH DESCRIPTION +.sp +\fBdnssec\-checkds\fP verifies the correctness of Delegation Signer (DS) +resource records for keys in a specified zone. +.SH OPTIONS +.sp +\fB\-a\fP \fIalgorithm\fP +.INDENT 0.0 +.INDENT 3.5 +Specify a digest algorithm to use when converting the zones DNSKEY +records to expected DS records. This option can be repeated, so that +multiple records are checked for each DNSKEY record. +.sp +The \fIalgorithm\fP 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 +.UNINDENT +.sp +\fB\-f\fP \fIfile\fP +.INDENT 0.0 +.INDENT 3.5 +If a \fBfile\fP is specified, then the zone is read from that file to +find the DNSKEY records. If not, then the DNSKEY records for the zone +are looked up in the DNS. +.UNINDENT +.UNINDENT +.sp +\fB\-s\fP \fIfile\fP +.INDENT 0.0 +.INDENT 3.5 +Specifies a prepared dsset file, such as would be generated by +\fBdnssec\-signzone\fP, to use as a source for the DS RRset instead of +querying the parent. +.UNINDENT +.UNINDENT +.sp +\fB\-d\fP \fIdig path\fP +.INDENT 0.0 +.INDENT 3.5 +Specifies a path to a \fBdig\fP binary. Used for testing. +.UNINDENT +.UNINDENT +.sp +\fB\-D\fP \fIdsfromkey path\fP +.INDENT 0.0 +.INDENT 3.5 +Specifies a path to a \fBdnssec\-dsfromkey\fP binary. Used for testing. +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBdnssec\-dsfromkey\fP(8), \fBdnssec\-keygen\fP(8), +\fBdnssec\-signzone\fP(8), +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-checkds.rst b/doc/man/dnssec-checkds.rst new file mode 100644 index 0000000..a3c2431 --- /dev/null +++ b/doc/man/dnssec-checkds.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/python/dnssec-checkds.rst diff --git a/doc/man/dnssec-coverage.8in b/doc/man/dnssec-coverage.8in new file mode 100644 index 0000000..1dde5bc --- /dev/null +++ b/doc/man/dnssec-coverage.8in @@ -0,0 +1,192 @@ +.\" 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-COVERAGE" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9" +.SH NAME +dnssec-coverage \- checks future DNSKEY coverage for a zone +.SH SYNOPSIS +.sp +\fBdnssec\-coverage\fP [\fB\-K\fP\fIdirectory\fP] [\fB\-l\fP\fIlength\fP] +[\fB\-f\fP\fIfile\fP] [\fB\-d\fP\fIDNSKEY TTL\fP] [\fB\-m\fP\fImax TTL\fP] +[\fB\-r\fP\fIinterval\fP] [\fB\-c\fP\fIcompilezone path\fP] [\fB\-k\fP] [\fB\-z\fP] +[zone...] +.SH DESCRIPTION +.sp +\fBdnssec\-coverage\fP verifies that the DNSSEC keys for a given zone or a +set of zones have timing metadata set properly to ensure no future +lapses in DNSSEC coverage. +.sp +If \fBzone\fP is specified, then keys found in the key repository matching +that zone are scanned, and an ordered list is generated of the events +scheduled for that key (i.e., publication, activation, inactivation, +deletion). The list of events is walked in order of occurrence. Warnings +are generated if any event is scheduled which could cause the zone to +enter a state in which validation failures might occur: for example, if +the number of published or active keys for a given algorithm drops to +zero, or if a key is deleted from the zone too soon after a new key is +rolled, and cached data signed by the prior key has not had time to +expire from resolver caches. +.sp +If \fBzone\fP is not specified, then all keys in the key repository will +be scanned, and all zones for which there are keys will be analyzed. +(Note: This method of reporting is only accurate if all the zones that +have keys in a given repository share the same TTL parameters.) +.SH OPTIONS +.sp +\fB\-K\fP \fIdirectory\fP +.INDENT 0.0 +.INDENT 3.5 +Sets the directory in which keys can be found. Defaults to the +current working directory. +.UNINDENT +.UNINDENT +.sp +\fB\-f\fP \fIfile\fP +.INDENT 0.0 +.INDENT 3.5 +If a \fBfile\fP is specified, then the zone is read from that file; the +largest TTL and the DNSKEY TTL are determined directly from the zone +data, and the \fB\-m\fP and \fB\-d\fP options do not need to be specified +on the command line. +.UNINDENT +.UNINDENT +.sp +\fB\-l\fP \fIduration\fP +.INDENT 0.0 +.INDENT 3.5 +The length of time to check for DNSSEC coverage. Key events scheduled +further into the future than \fBduration\fP will be ignored, and +assumed to be correct. +.sp +The value of \fBduration\fP can be set in seconds, or in larger units +of time by adding a suffix: mi for minutes, h for hours, d for days, +w for weeks, mo for months, y for years. +.UNINDENT +.UNINDENT +.sp +\fB\-m\fP \fImaximum TTL\fP +.INDENT 0.0 +.INDENT 3.5 +Sets the value to be used as the maximum TTL for the zone or zones +being analyzed when determining whether there is a possibility of +validation failure. When a zone\-signing key is deactivated, there +must be enough time for the record in the zone with the longest TTL +to have expired from resolver caches before that key can be purged +from the DNSKEY RRset. If that condition does not apply, a warning +will be generated. +.sp +The length of the TTL can be set in seconds, or in larger units of +time by adding a suffix: mi for minutes, h for hours, d for days, w +for weeks, mo for months, y for years. +.sp +This option is not necessary if the \fB\-f\fP has been used to specify a +zone file. If \fB\-f\fP has been specified, this option may still be +used; it will override the value found in the file. +.sp +If this option is not used and the maximum TTL cannot be retrieved +from a zone file, a warning is generated and a default value of 1 +week is used. +.UNINDENT +.UNINDENT +.sp +\fB\-d\fP \fIDNSKEY TTL\fP +.INDENT 0.0 +.INDENT 3.5 +Sets the value to be used as the DNSKEY TTL for the zone or zones +being analyzed when determining whether there is a possibility of +validation failure. When a key is rolled (that is, replaced with a +new key), there must be enough time for the old DNSKEY RRset to have +expired from resolver caches before the new key is activated and +begins generating signatures. If that condition does not apply, a +warning will be generated. +.sp +The length of the TTL can be set in seconds, or in larger units of +time by adding a suffix: mi for minutes, h for hours, d for days, w +for weeks, mo for months, y for years. +.sp +This option is not necessary if \fB\-f\fP has been used to specify a +zone file from which the TTL of the DNSKEY RRset can be read, or if a +default key TTL was set using ith the \fB\-L\fP to \fBdnssec\-keygen\fP\&. If +either of those is true, this option may still be used; it will +override the values found in the zone file or the key file. +.sp +If this option is not used and the key TTL cannot be retrieved from +the zone file or the key file, then a warning is generated and a +default value of 1 day is used. +.UNINDENT +.UNINDENT +.sp +\fB\-r\fP \fIresign interval\fP +.INDENT 0.0 +.INDENT 3.5 +Sets the value to be used as the resign interval for the zone or +zones being analyzed when determining whether there is a possibility +of validation failure. This value defaults to 22.5 days, which is +also the default in \fBnamed\fP\&. However, if it has been changed by the +\fBsig\-validity\-interval\fP option in named.conf, then it should also +be changed here. +.sp +The length of the interval can be set in seconds, or in larger units +of time by adding a suffix: mi for minutes, h for hours, d for days, +w for weeks, mo for months, y for years. +.UNINDENT +.UNINDENT +.sp +\fB\-k\fP +.INDENT 0.0 +.INDENT 3.5 +Only check KSK coverage; ignore ZSK events. Cannot be used with +\fB\-z\fP\&. +.UNINDENT +.UNINDENT +.sp +\fB\-z\fP +.INDENT 0.0 +.INDENT 3.5 +Only check ZSK coverage; ignore KSK events. Cannot be used with +\fB\-k\fP\&. +.UNINDENT +.UNINDENT +.sp +\fB\-c\fP \fIcompilezone path\fP +.INDENT 0.0 +.INDENT 3.5 +Specifies a path to a \fBnamed\-compilezone\fP binary. Used for testing. +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBdnssec\-checkds\fP(8), \fBdnssec\-dsfromkey\fP(8), +\fBdnssec\-keygen\fP(8), \fBdnssec\-signzone\fP(8) +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-coverage.rst b/doc/man/dnssec-coverage.rst new file mode 100644 index 0000000..0e974ac --- /dev/null +++ b/doc/man/dnssec-coverage.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/python/dnssec-coverage.rst diff --git a/doc/man/dnssec-dsfromkey.8in b/doc/man/dnssec-dsfromkey.8in new file mode 100644 index 0000000..83f6a7a --- /dev/null +++ b/doc/man/dnssec-dsfromkey.8in @@ -0,0 +1,153 @@ +.\" 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" "8" "@RELEASE_DATE@" "@BIND9_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 \fB\-C\fP option. +.sp +By default, only KSKs are converted (keys with flags = 257). The +\fB\-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 \fBdnssec\-keygen\fP\&. +.sp +With the \fB\-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 \fB\-s\fP option, \fBdnssec\-dsfromkey\fP reads a \fBkeyset\-\fP file, +as generated by \fBdnssec\-keygen\fP \fB\-C\fP\&. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-1\fP +This option is an abbreviation for \fB\-a SHA1\fP\&. +.TP +.B \fB\-2\fP +This option is an abbreviation for \fB\-a SHA\-256\fP\&. +.TP +.B \fB\-a algorithm\fP +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. +.TP +.B \fB\-A\fP +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 \fB\-f\fP zone file mode. +.TP +.B \fB\-c class\fP +This option specifies the DNS class; the default is IN. This option is only useful in \fB\-s\fP keyset +or \fB\-f\fP zone file mode. +.TP +.B \fB\-C\fP +This option generates CDS records rather than DS records. +.TP +.B \fB\-f file\fP +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 \fBdig\fP +command as input, as in: +.sp +\fBdig dnskey example.com | dnssec\-dsfromkey \-f \- example.com\fP +.TP +.B \fB\-h\fP +This option prints usage information. +.TP +.B \fB\-K directory\fP +This option tells BIND 9 to look for key files or \fBkeyset\-\fP files in \fBdirectory\fP\&. +.TP +.B \fB\-s\fP +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. +.TP +.B \fB\-T TTL\fP +This option specifies the TTL of the DS records. By default the TTL is omitted. +.TP +.B \fB\-v level\fP +This option sets the debugging level. +.TP +.B \fB\-V\fP +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 \fBdnssec\-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 +\fBdnssec\-keygen(8)\fP, \fBdnssec\-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.8in b/doc/man/dnssec-importkey.8in new file mode 100644 index 0000000..8a50888 --- /dev/null +++ b/doc/man/dnssec-importkey.8in @@ -0,0 +1,126 @@ +.\" 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" "8" "@RELEASE_DATE@" "@BIND9_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 (\fB\-P\fP) and deletion (\fB\-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 \fB\-f filename\fP +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. +.TP +.B \fB\-K directory\fP +This option sets the directory in which the key files are to reside. +.TP +.B \fB\-L ttl\fP +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. +.TP +.B \fB\-h\fP +This option emits a usage message and exits. +.TP +.B \fB\-v level\fP +This option sets the debugging level. +.TP +.B \fB\-V\fP +This option prints version information. +.UNINDENT +.SH TIMING OPTIONS +.sp +Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the +argument begins with a \fB+\fP or \fB\-\fP, it is interpreted as an offset from +the present time. For convenience, if such an offset is followed by one +of the suffixes \fBy\fP, \fBmo\fP, \fBw\fP, \fBd\fP, \fBh\fP, or \fBmi\fP, then the offset 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. To +explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&. +.INDENT 0.0 +.TP +.B \fB\-P date/offset\fP +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. +.TP +.B \fB\-P sync date/offset\fP +This option sets the date on which CDS and CDNSKEY records that match this key +are to be published to the zone. +.TP +.B \fB\-D date/offset\fP +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.) +.TP +.B \fB\-D sync date/offset\fP +This option sets the date on which the CDS and CDNSKEY records that match this +key are to be deleted. +.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 +\fBdnssec\-keygen\fP\&. +.SH SEE ALSO +.sp +\fBdnssec\-keygen(8)\fP, \fBdnssec\-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.8in b/doc/man/dnssec-keyfromlabel.8in new file mode 100644 index 0000000..7bedc45 --- /dev/null +++ b/doc/man/dnssec-keyfromlabel.8in @@ -0,0 +1,277 @@ +.\" 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" "8" "@RELEASE_DATE@" "@BIND9_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 \fBdnssec\-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 \fB\-a algorithm\fP +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 \fB\-3\fP +option, then NSEC3RSASHA1 is used instead. +.sp +This option is mandatory except when using the +\fB\-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. + +.TP +.B \fB\-3\fP +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. +.TP +.B \fB\-E engine\fP +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). When BIND is +built with native PKCS#11 cryptography (\fB\-\-enable\-native\-pkcs11\fP), it +defaults to the path of the PKCS#11 provider library specified via +\fB\-\-with\-pkcs11\fP\&. +.TP +.B \fB\-l label\fP +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\&. +.sp +When BIND 9 is built with native PKCS#11 support, the label is a +PKCS#11 URI string in the format +\fBpkcs11:keyword\e =value[;\e keyword\e =value;...]\fP\&. Keywords +include \fBtoken\fP, which identifies the HSM; \fBobject\fP, which identifies +the key; and \fBpin\-source\fP, which identifies a file from which the +HSM\(aqs PIN code can be obtained. The label is stored in the +on\-disk \fBprivate\fP file. +.sp +If the label contains a \fBpin\-source\fP field, tools using the +generated key files are able to use the HSM for signing and other +operations without any need for an operator to manually enter a PIN. +Note: Making the HSM\(aqs PIN accessible in this manner may reduce the +security advantage of using an HSM; use caution +with this feature. +.TP +.B \fB\-n nametype\fP +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. +.TP +.B \fB\-C\fP +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 \fB\-C\fP option suppresses them. +.TP +.B \fB\-c class\fP +This option indicates that the DNS record containing the key should have the +specified class. If not specified, class IN is used. +.TP +.B \fB\-f flag\fP +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. +.TP +.B \fB\-G\fP +This option generates a key, but does not publish it or sign with it. This option is +incompatible with \fB\-P\fP and \fB\-A\fP\&. +.TP +.B \fB\-h\fP +This option prints a short summary of the options and arguments to +\fBdnssec\-keyfromlabel\fP\&. +.TP +.B \fB\-K directory\fP +This option sets the directory in which the key files are to be written. +.TP +.B \fB\-k\fP +This option generates KEY records rather than DNSKEY records. +.TP +.B \fB\-L\fP 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. +.TP +.B \fB\-p protocol\fP +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. +.TP +.B \fB\-S key\fP +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. +.TP +.B \fB\-t type\fP +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. +.TP +.B \fB\-v level\fP +This option sets the debugging level. +.TP +.B \fB\-V\fP +This option prints version information. +.TP +.B \fB\-y\fP +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. If the +argument begins with a \fB+\fP or \fB\-\fP, it is interpreted as an offset from +the present time. For convenience, if such an offset is followed by one +of the suffixes \fBy\fP, \fBmo\fP, \fBw\fP, \fBd\fP, \fBh\fP, or \fBmi\fP, then the offset 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. To +explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&. +.INDENT 0.0 +.TP +.B \fB\-P date/offset\fP +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 \fB\-G\fP option has not been used, the +default is the current date. +.TP +.B \fB\-P sync date/offset\fP +This option sets the date on which CDS and CDNSKEY records that match this key +are to be published to the zone. +.TP +.B \fB\-A date/offset\fP +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 \fB\-G\fP option has not been used, the default is the current date. +.TP +.B \fB\-R date/offset\fP +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. +.TP +.B \fB\-I date/offset\fP +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. +.TP +.B \fB\-D date/offset\fP +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.) +.TP +.B \fB\-D sync date/offset\fP +This option sets the date on which the CDS and CDNSKEY records that match this +key are to be deleted. +.TP +.B \fB\-i interval\fP +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 +\fBdnssec\-keygen(8)\fP, \fBdnssec\-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.8in b/doc/man/dnssec-keygen.8in new file mode 100644 index 0000000..84d4d68 --- /dev/null +++ b/doc/man/dnssec-keygen.8in @@ -0,0 +1,331 @@ +.\" 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" "8" "@RELEASE_DATE@" "@BIND9_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. +.sp +The \fBdnssec\-keymgr\fP command acts as a wrapper +around \fBdnssec\-keygen\fP, generating and updating keys +as needed to enforce defined security policies such as key rollover +scheduling. Using \fBdnssec\-keymgr\fP may be preferable +to direct use of \fBdnssec\-keygen\fP\&. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-3\fP +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. +.TP +.B \fB\-a algorithm\fP +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 \fB\-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 \fB\-3\fP +option, NSEC3RSASHA1 is used instead. +.sp +This parameter \fImust\fP be specified except when using the \fB\-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 +\fBtsig\-keygen\fP to generate TSIG keys. +.TP +.B \fB\-b keysize\fP +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 \fB\-f KSK\fP) default to 2048 bits. +.TP +.B \fB\-C\fP +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 \fB\-C\fP option suppresses them. +.TP +.B \fB\-c class\fP +This option indicates that the DNS record containing the key should have the +specified class. If not specified, class IN is used. +.TP +.B \fB\-d bits\fP +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. +.TP +.B \fB\-E engine\fP +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). When BIND is +built with native PKCS#11 cryptography (\fB\-\-enable\-native\-pkcs11\fP), it +defaults to the path of the PKCS#11 provider library specified via +\fB\-\-with\-pkcs11\fP\&. +.TP +.B \fB\-f flag\fP +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. +.TP +.B \fB\-G\fP +This option generates a key, but does not publish it or sign with it. This option is +incompatible with \fB\-P\fP and \fB\-A\fP\&. +.TP +.B \fB\-g generator\fP +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. +.TP +.B \fB\-h\fP +This option prints a short summary of the options and arguments to +\fBdnssec\-keygen\fP\&. +.TP +.B \fB\-K directory\fP +This option sets the directory in which the key files are to be written. +.TP +.B \fB\-k policy\fP +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. +.TP +.B \fB\-L ttl\fP +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. +.TP +.B \fB\-l file\fP +This option provides a configuration file that contains a \fBdnssec\-policy\fP statement +(matching the policy set with \fB\-k\fP). +.TP +.B \fB\-n nametype\fP +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. +.TP +.B \fB\-p protocol\fP +This option sets the protocol value for the generated key, for use with +\fB\-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. +.TP +.B \fB\-q\fP +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. +.TP +.B \fB\-S key\fP +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. +.TP +.B \fB\-s strength\fP +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. +.TP +.B \fB\-T rrtype\fP +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). +.TP +.B \fB\-t type\fP +This option indicates the type of the key for use with \fB\-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. +.TP +.B \fB\-V\fP +This option prints version information. +.TP +.B \fB\-v level\fP +This option sets the debugging level. +.UNINDENT +.SH TIMING OPTIONS +.sp +Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the +argument begins with a \fB+\fP or \fB\-\fP, it is interpreted as an offset from +the present time. For convenience, if such an offset is followed by one +of the suffixes \fBy\fP, \fBmo\fP, \fBw\fP, \fBd\fP, \fBh\fP, or \fBmi\fP, then the offset 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. To +explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&. +.INDENT 0.0 +.TP +.B \fB\-P date/offset\fP +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 \fB\-G\fP option has not been used, the +default is the current date. +.TP +.B \fB\-P sync date/offset\fP +This option sets the date on which CDS and CDNSKEY records that match this key +are to be published to the zone. +.TP +.B \fB\-A date/offset\fP +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 \fB\-G\fP option has not been used, the default is the current date. If set, +and \fB\-P\fP is not set, the publication date is set to the +activation date minus the prepublication interval. +.TP +.B \fB\-R date/offset\fP +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. +.TP +.B \fB\-I date/offset\fP +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. +.TP +.B \fB\-D date/offset\fP +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.) +.TP +.B \fB\-D sync date/offset\fP +This option sets the date on which the CDS and CDNSKEY records that match this +key are to be deleted. +.TP +.B \fB\-i interval\fP +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 \fBnamed\fP or \fBdnssec\-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 +\fBdnssec\-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-keymgr.8in b/doc/man/dnssec-keymgr.8in new file mode 100644 index 0000000..ae163db --- /dev/null +++ b/doc/man/dnssec-keymgr.8in @@ -0,0 +1,297 @@ +.\" 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-KEYMGR" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9" +.SH NAME +dnssec-keymgr \- ensure correct DNSKEY coverage based on a defined policy +.SH SYNOPSIS +.sp +\fBdnssec\-keymgr\fP [\fB\-K\fP\fIdirectory\fP] [\fB\-c\fP\fIfile\fP] [\fB\-f\fP] [\fB\-k\fP] [\fB\-q\fP] [\fB\-v\fP] [\fB\-z\fP] [\fB\-g\fP\fIpath\fP] [\fB\-s\fP\fIpath\fP] [zone...] +.SH DESCRIPTION +.sp +\fBdnssec\-keymgr\fP is a high level Python wrapper to facilitate the key +rollover process for zones handled by BIND. It uses the BIND commands +for manipulating DNSSEC key metadata: \fBdnssec\-keygen\fP and +\fBdnssec\-settime\fP\&. +.sp +DNSSEC policy can be read from a configuration file (default +/etc/dnssec\-policy.conf), from which the key parameters, publication and +rollover schedule, and desired coverage duration for any given zone can +be determined. This file may be used to define individual DNSSEC +policies on a per\-zone basis, or to set a \(dqdefault\(dq policy used for all +zones. +.sp +When \fBdnssec\-keymgr\fP runs, it examines the DNSSEC keys for one or more +zones, comparing their timing metadata against the policies for those +zones. If key settings do not conform to the DNSSEC policy (for example, +because the policy has been changed), they are automatically corrected. +.sp +A zone policy can specify a duration for which we want to ensure the key +correctness (\fBcoverage\fP). It can also specify a rollover period +(\fBroll\-period\fP). If policy indicates that a key should roll over +before the coverage period ends, then a successor key will automatically +be created and added to the end of the key series. +.sp +If zones are specified on the command line, \fBdnssec\-keymgr\fP will +examine only those zones. If a specified zone does not already have keys +in place, then keys will be generated for it according to policy. +.sp +If zones are \fInot\fP specified on the command line, then \fBdnssec\-keymgr\fP +will search the key directory (either the current working directory or +the directory set by the \fB\-K\fP option), and check the keys for all the +zones represented in the directory. +.sp +Key times that are in the past will not be updated unless the \fB\-f\fP is +used (see below). Key inactivation and deletion times that are less than +five minutes in the future will be delayed by five minutes. +.sp +It is expected that this tool will be run automatically and unattended +(for example, by \fBcron\fP). +.SH OPTIONS +.sp +\fB\-c\fP \fIfile\fP +.INDENT 0.0 +.INDENT 3.5 +If \fB\-c\fP is specified, then the DNSSEC policy is read from \fBfile\fP\&. +(If not specified, then the policy is read from +/etc/dnssec\-policy.conf; if that file doesnt exist, a built\-in global +default policy is used.) +.UNINDENT +.UNINDENT +.sp +\fB\-f\fP +.INDENT 0.0 +.INDENT 3.5 +Force: allow updating of key events even if they are already in the +past. This is not recommended for use with zones in which keys have +already been published. However, if a set of keys has been generated +all of which have publication and activation dates in the past, but +the keys have not been published in a zone as yet, then this option +can be used to clean them up and turn them into a proper series of +keys with appropriate rollover intervals. +.UNINDENT +.UNINDENT +.sp +\fB\-g\fP \fIkeygen\-path\fP +.INDENT 0.0 +.INDENT 3.5 +Specifies a path to a \fBdnssec\-keygen\fP binary. Used for testing. See +also the \fB\-s\fP option. +.UNINDENT +.UNINDENT +.sp +\fB\-h\fP +.INDENT 0.0 +.INDENT 3.5 +Print the \fBdnssec\-keymgr\fP help summary and exit. +.UNINDENT +.UNINDENT +.sp +\fB\-K\fP \fIdirectory\fP +.INDENT 0.0 +.INDENT 3.5 +Sets the directory in which keys can be found. Defaults to the +current working directory. +.UNINDENT +.UNINDENT +.sp +\fB\-k\fP +.INDENT 0.0 +.INDENT 3.5 +Only apply policies to KSK keys. See also the \fB\-z\fP option. +.UNINDENT +.UNINDENT +.sp +\fB\-q\fP +.INDENT 0.0 +.INDENT 3.5 +Quiet: suppress printing of \fBdnssec\-keygen\fP and \fBdnssec\-settime\fP\&. +.UNINDENT +.UNINDENT +.sp +\fB\-s\fP \fIsettime\-path\fP +.INDENT 0.0 +.INDENT 3.5 +Specifies a path to a \fBdnssec\-settime\fP binary. Used for testing. +See also the \fB\-g\fP option. +.UNINDENT +.UNINDENT +.sp +\fB\-v\fP +.INDENT 0.0 +.INDENT 3.5 +Print the \fBdnssec\-keymgr\fP version and exit. +.UNINDENT +.UNINDENT +.sp +\fB\-z\fP +.INDENT 0.0 +.INDENT 3.5 +Only apply policies to ZSK keys. See also the \fB\-k\fP option. +.UNINDENT +.UNINDENT +.SH POLICY CONFIGURATION +.sp +The dnssec\-policy.conf file can specify three kinds of policies: +.INDENT 0.0 +.INDENT 3.5 +· \fIPolicy classes\fP (\fBpolicy\fP\fIname\fP\fB{ ... };\fP) can be +inherited by zone policies or other policy classes; these can be used +to create sets of different security profiles. For example, a policy +class \fBnormal\fP might specify 1024\-bit key sizes, but a class +\fBextra\fP might specify 2048 bits instead; \fBextra\fP would be used +for zones that had unusually high security needs. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +· \fIAlgorithm policies:\fP (\fBalgorithm\-policy\fP\fIalgorithm\fP\fB{ ... +};\fP ) override default per\-algorithm settings. For example, by +default, RSASHA256 keys use 2048\-bit key sizes for both KSK and ZSK. +This can be modified using \fBalgorithm\-policy\fP, and the new key +sizes would then be used for any key of type RSASHA256. +.sp +· \fIZone policies:\fP (\fBzone\fP\fIname\fP\fB{ ... };\fP ) set policy for a +single zone by name. A zone policy can inherit a policy class by +including a \fBpolicy\fP option. Zone names beginning with digits +(i.e., 0\-9) must be quoted. If a zone does not have its own policy +then the \(dqdefault\(dq policy applies. +.UNINDENT +.UNINDENT +.sp +Options that can be specified in policies: +.sp +\fBalgorithm\fP \fIname\fP; +.INDENT 0.0 +.INDENT 3.5 +The key algorithm. If no policy is defined, the default is RSASHA256. +.UNINDENT +.UNINDENT +.sp +\fBcoverage\fP \fIduration\fP; +.INDENT 0.0 +.INDENT 3.5 +The length of time to ensure that keys will be correct; no action +will be taken to create new keys to be activated after this time. +This can be represented as a number of seconds, or as a duration +using human\-readable units (examples: \(dq1y\(dq or \(dq6 months\(dq). A default +value for this option can be set in algorithm policies as well as in +policy classes or zone policies. If no policy is configured, the +default is six months. +.UNINDENT +.UNINDENT +.sp +\fBdirectory\fP \fIpath\fP; +.INDENT 0.0 +.INDENT 3.5 +Specifies the directory in which keys should be stored. +.UNINDENT +.UNINDENT +.sp +\fBkey\-size\fP \fIkeytype\fP \fIsize\fP; +.INDENT 0.0 +.INDENT 3.5 +Specifies the number of bits to use in creating keys. The keytype is +either \(dqzsk\(dq or \(dqksk\(dq. A default value for this option can be set in +algorithm policies as well as in policy classes or zone policies. If +no policy is configured, the default is 2048 bits for RSA keys. +.UNINDENT +.UNINDENT +.sp +\fBkeyttl\fP \fIduration\fP; +.INDENT 0.0 +.INDENT 3.5 +The key TTL. If no policy is defined, the default is one hour. +.UNINDENT +.UNINDENT +.sp +\fBpost\-publish\fP \fIkeytype\fP \fIduration\fP; +.INDENT 0.0 +.INDENT 3.5 +How long after inactivation a key should be deleted from the zone. +Note: If \fBroll\-period\fP is not set, this value is ignored. The +keytype is either \(dqzsk\(dq or \(dqksk\(dq. A default duration for this option +can be set in algorithm policies as well as in policy classes or zone +policies. The default is one month. +.UNINDENT +.UNINDENT +.sp +\fBpre\-publish\fP \fIkeytype\fP \fIduration\fP; +.INDENT 0.0 +.INDENT 3.5 +How long before activation a key should be published. Note: If +\fBroll\-period\fP is not set, this value is ignored. The keytype is +either \(dqzsk\(dq or \(dqksk\(dq. A default duration for this option can be set +in algorithm policies as well as in policy classes or zone policies. +The default is one month. +.UNINDENT +.UNINDENT +.sp +\fBroll\-period\fP \fIkeytype\fP \fIduration\fP; +.INDENT 0.0 +.INDENT 3.5 +How frequently keys should be rolled over. The keytype is either +\(dqzsk\(dq or \(dqksk\(dq. A default duration for this option can be set in +algorithm policies as well as in policy classes or zone policies. If +no policy is configured, the default is one year for ZSKs. KSKs do +not roll over by default. +.UNINDENT +.UNINDENT +.sp +\fBstandby\fP \fIkeytype\fP \fInumber\fP; +.INDENT 0.0 +.INDENT 3.5 +Not yet implemented. +.UNINDENT +.UNINDENT +.SH REMAINING WORK +.INDENT 0.0 +.INDENT 3.5 +· Enable scheduling of KSK rollovers using the \fB\-P sync\fP and \fB\-D +sync\fP options to \fBdnssec\-keygen\fP and \fBdnssec\-settime\fP\&. Check the +parent zone (as in \fBdnssec\-checkds\fP) to determine when its safe for +the key to roll. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +· Allow configuration of standby keys and use of the REVOKE bit, for +keys that use RFC 5011 semantics. +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBdnssec\-coverage\fP(8), \fBdnssec\-keygen\fP(8), +\fBdnssec\-settime\fP(8), \fBdnssec\-checkds\fP(8) +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/dnssec-keymgr.rst b/doc/man/dnssec-keymgr.rst new file mode 100644 index 0000000..92fe728 --- /dev/null +++ b/doc/man/dnssec-keymgr.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/python/dnssec-keymgr.rst
\ No newline at end of file diff --git a/doc/man/dnssec-revoke.8in b/doc/man/dnssec-revoke.8in new file mode 100644 index 0000000..2b40587 --- /dev/null +++ b/doc/man/dnssec-revoke.8in @@ -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 "DNSSEC-REVOKE" "8" "@RELEASE_DATE@" "@BIND9_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 \fB\-h\fP +This option emits a usage message and exits. +.TP +.B \fB\-K directory\fP +This option sets the directory in which the key files are to reside. +.TP +.B \fB\-r\fP +This option indicates to remove the original keyset files after writing the new keyset files. +.TP +.B \fB\-v level\fP +This option sets the debugging level. +.TP +.B \fB\-V\fP +This option prints version information. +.TP +.B \fB\-E engine\fP +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). When BIND is +built with native PKCS#11 cryptography (\fB\-\-enable\-native\-pkcs11\fP), it +defaults to the path of the PKCS#11 provider library specified via +\fB\-\-with\-pkcs11\fP\&. +.TP +.B \fB\-f\fP +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. +.TP +.B \fB\-R\fP +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 +\fBdnssec\-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.8in b/doc/man/dnssec-settime.8in new file mode 100644 index 0000000..7ecaf49 --- /dev/null +++ b/doc/man/dnssec-settime.8in @@ -0,0 +1,246 @@ +.\" 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" "8" "@RELEASE_DATE@" "@BIND9_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 \fB\-P\fP, \fB\-A\fP, \fB\-R\fP, \fB\-I\fP, and +\fB\-D\fP options. The metadata can then be used by \fBdnssec\-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 \fB\-s\fP\&. With this option, it is also possible to update key +states with \fB\-d\fP (DS), \fB\-k\fP (DNSKEY), \fB\-r\fP (RRSIG of KSK), or \fB\-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 \fB\-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 \fB\-f\fP +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. +.TP +.B \fB\-K directory\fP +This option sets the directory in which the key files are to reside. +.TP +.B \fB\-L ttl\fP +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. +.TP +.B \fB\-h\fP +This option emits a usage message and exits. +.TP +.B \fB\-V\fP +This option prints version information. +.TP +.B \fB\-v level\fP +This option sets the debugging level. +.TP +.B \fB\-E engine\fP +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). When BIND is +built with native PKCS#11 cryptography (\fB\-\-enable\-native\-pkcs11\fP), it +defaults to the path of the PKCS#11 provider library specified via +\fB\-\-with\-pkcs11\fP\&. +.UNINDENT +.SH TIMING OPTIONS +.sp +Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the +argument begins with a \fB+\fP or \fB\-\fP, it is interpreted as an offset from +the present time. For convenience, if such an offset is followed by one +of the suffixes \fBy\fP, \fBmo\fP, \fBw\fP, \fBd\fP, \fBh\fP, or \fBmi\fP, then the offset 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. To +explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&. +.INDENT 0.0 +.TP +.B \fB\-P date/offset\fP +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. +.TP +.B \fB\-P ds date/offset\fP +This option Sets the date on which DS records that match this key have been +seen in the parent zone. +.TP +.B \fB\-P sync date/offset\fP +This option sets the date on which CDS and CDNSKEY records that match this key +are to be published to the zone. +.TP +.B \fB\-A date/offset\fP +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. +.TP +.B \fB\-R date/offset\fP +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. +.TP +.B \fB\-I date/offset\fP +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. +.TP +.B \fB\-D date/offset\fP +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.) +.TP +.B \fB\-D ds date/offset\fP +This option sets the date on which the DS records that match this key have +been seen removed from the parent zone. +.TP +.B \fB\-D sync date/offset\fP +This option sets the date on which the CDS and CDNSKEY records that match this +key are to be deleted. +.TP +.B \fB\-S predecessor key\fP +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. +.TP +.B \fB\-i interval\fP +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 \fB\-s\fP +This option indicates that when setting key timing data, the state file should also be updated. +.TP +.B \fB\-g state\fP +This option sets the goal state for this key. Must be HIDDEN or OMNIPRESENT. +.TP +.B \fB\-d state date/offset\fP +This option sets the DS state for this key as of the specified date, offset from the current date. +.TP +.B \fB\-k state date/offset\fP +This option sets the DNSKEY state for this key as of the specified date, offset from the current date. +.TP +.B \fB\-r state date/offset\fP +This option sets the RRSIG (KSK) state for this key as of the specified date, offset from the current date. +.TP +.B \fB\-z state date/offset\fP +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 \fB\-u\fP +This option indicates that times should be printed in Unix epoch format. +.TP +.B \fB\-p C/P/Pds/Psync/A/R/I/D/Dds/Dsync/all\fP +This option prints a specific metadata value or set of metadata values. +The \fB\-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 +\fBdnssec\-keygen(8)\fP, \fBdnssec\-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.8in b/doc/man/dnssec-signzone.8in new file mode 100644 index 0000000..d9599a4 --- /dev/null +++ b/doc/man/dnssec-signzone.8in @@ -0,0 +1,438 @@ +.\" 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" "8" "@RELEASE_DATE@" "@BIND9_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 \fB\-a\fP +This option verifies all generated signatures. +.TP +.B \fB\-c class\fP +This option specifies the DNS class of the zone. +.TP +.B \fB\-C\fP +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\&. +.TP +.B \fB\-d directory\fP +This option indicates the directory where BIND 9 should look for \fBdsset\-\fP or \fBkeyset\-\fP files. +.TP +.B \fB\-D\fP +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 (\fB\-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 \fB\-O raw\fP, +\fB\-O map\fP, or serial\-number updating. +.TP +.B \fB\-E engine\fP +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). When BIND is +built with native PKCS#11 cryptography (\fB\-\-enable\-native\-pkcs11\fP), it +defaults to the path of the PKCS#11 provider library specified via +\fB\-\-with\-pkcs11\fP\&. +.TP +.B \fB\-g\fP +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. +.TP +.B \fB\-K directory\fP +This option specifies the directory to search for DNSSEC keys. If not +specified, it defaults to the current directory. +.TP +.B \fB\-k key\fP +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. +.TP +.B \fB\-M maxttl\fP +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 +\fBnamed.conf\fP\&. (Note: This option is incompatible with \fB\-D\fP, +because it modifies non\-DNSSEC data in the output zone.) +.TP +.B \fB\-s start\-time\fP +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. +.TP +.B \fB\-e end\-time\fP +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\&. +.TP +.B \fB\-X extended end\-time\fP +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\&. +.TP +.B \fB\-f output\-file\fP +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\&. +.TP +.B \fB\-h\fP +This option prints a short summary of the options and arguments to +\fBdnssec\-signzone\fP\&. +.TP +.B \fB\-V\fP +This option prints version information. +.TP +.B \fB\-i interval\fP +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. +.TP +.B \fB\-I input\-format\fP +This option sets the format of the input zone file. Possible formats are \fBtext\fP +(the default), \fBraw\fP, and \fBmap\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. +.TP +.B \fB\-j jitter\fP +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. +.TP +.B \fB\-L serial\fP +When writing a signed zone to \(dqraw\(dq or \(dqmap\(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.) +.TP +.B \fB\-n ncpus\fP +This option specifies the number of threads to use. By default, one thread is +started for each detected CPU. +.TP +.B \fB\-N soa\-serial\-format\fP +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 +.TP +.B \fB\-o origin\fP +This option sets the zone origin. If not specified, the name of the zone file is +assumed to be the origin. +.TP +.B \fB\-O output\-format\fP +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 \fBmap\fP, +\fBraw\fP, and \fBraw=N\fP, which store the zone in binary formats +for rapid loading by \fBnamed\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 \fBnamed\fP; if N is 1, the file can be read by release +9.9.0 or higher. The default is 1. +.TP +.B \fB\-P\fP +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. +.TP +.B \fB\-Q\fP +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 \fB\-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). +.TP +.B \fB\-q\fP +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. +.TP +.B \fB\-R\fP +This option removes signatures from keys that are no longer published. +.sp +This option is similar to \fB\-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). +.TP +.B \fB\-S\fP +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 +.TP +.B \fB\-T ttl\fP +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 \fB\-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. +.TP +.B \fB\-t\fP +This option prints statistics at completion. +.TP +.B \fB\-u\fP +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. +.TP +.B \fB\-v level\fP +This option sets the debugging level. +.TP +.B \fB\-x\fP +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 \fBnamed\fP\&.) +.TP +.B \fB\-z\fP +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 +\fBnamed\fP\&.) +.TP +.B \fB\-3 salt\fP +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 +.TP +.B \fB\-H iterations\fP +This option indicates that, when generating an NSEC3 chain, BIND 9 should use this many iterations. The default +is 10. +.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. The default value has not been changed because the best practices has changed only after BIND 9.16 reached Extended Support Version status. +.UNINDENT +.UNINDENT +.TP +.B \fB\-A\fP +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 +.sp +Using this option twice (i.e., \fB\-AA\fP) turns the OPTOUT flag off for +all records. This is useful when using the \fB\-u\fP option to modify an +NSEC3 chain which previously had OPTOUT set. +.TP +.B \fBzonefile\fP +This option sets the file containing the zone to be signed. +.TP +.B \fBkey\fP +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 \fBdnssec\-keygen\fP +(Kexample.com.+013+17247). Because the \fB\-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 (\fB\-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 \fBnamed.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 +\fBdnssec\-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.8in b/doc/man/dnssec-verify.8in new file mode 100644 index 0000000..6413884 --- /dev/null +++ b/doc/man/dnssec-verify.8in @@ -0,0 +1,113 @@ +.\" 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" "8" "@RELEASE_DATE@" "@BIND9_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 \fB\-c class\fP +This option specifies the DNS class of the zone. +.TP +.B \fB\-E engine\fP +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). When BIND is +built with native PKCS#11 cryptography (\fB\-\-enable\-native\-pkcs11\fP), it +defaults to the path of the PKCS#11 provider library specified via +\fB\-\-with\-pkcs11\fP\&. +.TP +.B \fB\-I input\-format\fP +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. +.TP +.B \fB\-o origin\fP +This option indicates the zone origin. If not specified, the name of the zone file is +assumed to be the origin. +.TP +.B \fB\-v level\fP +This option sets the debugging level. +.TP +.B \fB\-V\fP +This option prints version information. +.TP +.B \fB\-q\fP +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. +.TP +.B \fB\-x\fP +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 \fB\-x\fP option in \fBdnssec\-signzone\fP\&. +.TP +.B \fB\-z\fP +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 \fB\-z\fP option in \fBdnssec\-signzone\fP\&. +.TP +.B \fBzonefile\fP +This option indicates the file containing the zone to be signed. +.UNINDENT +.SH SEE ALSO +.sp +\fBdnssec\-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..c6dc0d0 --- /dev/null +++ b/doc/man/dnstap-read.1in @@ -0,0 +1,67 @@ +.\" 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@" "@BIND9_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 \fB\-y\fP option is specified, a +longer and more detailed YAML format is used. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-m\fP +This option indicates trace memory allocations, and is used for debugging memory leaks. +.TP +.B \fB\-p\fP +This option prints the text form of the DNS +message that was encapsulated in the \fBdnstap\fP frame, after printing the \fBdnstap\fP data. +.TP +.B \fB\-x\fP +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. +.TP +.B \fB\-y\fP +This option prints \fBdnstap\fP data in a detailed YAML format. +.UNINDENT +.SH SEE ALSO +.sp +\fBnamed(8)\fP, \fBrndc(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-aaaa.8in b/doc/man/filter-aaaa.8in new file mode 100644 index 0000000..b4ef946 --- /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@" "@BIND9_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 \fBnamed\fP, enabling +\fBnamed\fP to omit some IPv6 addresses when responding to clients. +.sp +Until BIND 9.12, this feature was implemented natively in \fBnamed\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 +\fBnamed.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 \(dq/usr/local/lib/filter\-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..0747ded --- /dev/null +++ b/doc/man/host.1in @@ -0,0 +1,182 @@ +.\" 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@" "@BIND9_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 \fB\-4\fP +This option specifies that only IPv4 should be used for query transport. See also the \fB\-6\fP option. +.TP +.B \fB\-6\fP +This option specifies that only IPv6 should be used for query transport. See also the \fB\-4\fP option. +.TP +.B \fB\-a\fP +The \fB\-a\fP (\(dqall\(dq) option is normally equivalent to \fB\-v \-t ANY\fP\&. It +also affects the behavior of the \fB\-l\fP list zone option. +.TP +.B \fB\-A\fP +The \fB\-A\fP (\(dqalmost all\(dq) option is equivalent to \fB\-a\fP, except that RRSIG, +NSEC, and NSEC3 records are omitted from the output. +.TP +.B \fB\-c class\fP +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). +.TP +.B \fB\-C\fP +This option indicates that \fBnamed\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. +.TP +.B \fB\-d\fP +This option prints debugging traces, and is equivalent to the \fB\-v\fP verbose option. +.TP +.B \fB\-l\fP +This option tells \fBnamed\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 \fB\-l \-a\fP options print all records in the zone. +.TP +.B \fB\-N ndots\fP +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\&. +.TP +.B \fB\-p port\fP +This option specifies the port to query on the server. The default is 53. +.TP +.B \fB\-r\fP +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 \fB\-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. +.TP +.B \fB\-R number\fP +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. +.TP +.B \fB\-s\fP +This option tells \fBnamed\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. +.TP +.B \fB\-t type\fP +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 \fB\-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., \fB\-t IXFR=12345678\fP\&. +.TP +.B \fB\-T\fP; \fB\-U\fP +This option specifies TCP or UDP. By default, \fBhost\fP uses UDP when making queries; the +\fB\-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 \fB\-U\fP\&. +.TP +.B \fB\-m flag\fP +This option sets memory usage debugging: the flag can be \fBrecord\fP, \fBusage\fP, or +\fBtrace\fP\&. The \fB\-m\fP option can be specified more than once to set +multiple flags. +.TP +.B \fB\-v\fP +This option sets verbose output, and is equivalent to the \fB\-d\fP debug option. Verbose output +can also be enabled by setting the \fBdebug\fP option in +\fB/etc/resolv.conf\fP\&. +.TP +.B \fB\-V\fP +This option prints the version number and exits. +.TP +.B \fB\-w\fP +This option sets \(dqwait forever\(dq: the query timeout is set to the maximum possible. See +also the \fB\-W\fP option. +.TP +.B \fB\-W wait\fP +This options sets the length of the wait timeout, indicating that \fBnamed\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 \fB\-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 +\fBdig(1)\fP, \fBnamed(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..8ad1858 --- /dev/null +++ b/doc/man/mdig.1in @@ -0,0 +1,341 @@ +.\" 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@" "@BIND9_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 \fBdig\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 \fBdig\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 \fBdig\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 \fB\-f\fP +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. +.TP +.B \fB\-h\fP +This option causes \fBmdig\fP to print detailed help information, with the full list +of options, and exit. +.TP +.B \fB\-v\fP +This option causes \fBmdig\fP to print the version number and exit. +.UNINDENT +.SH GLOBAL OPTIONS +.INDENT 0.0 +.TP +.B \fB\-4\fP +This option forces \fBmdig\fP to only use IPv4 query transport. +.TP +.B \fB\-6\fP +This option forces \fBmdig\fP to only use IPv6 query transport. +.TP +.B \fB\-b address\fP +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#<port>\(dq +.TP +.B \fB\-m\fP +This option enables memory usage debugging. +.TP +.B \fB\-p port#\fP +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 \fB+[no]additional\fP +This option displays [or does not display] the additional section of a reply. The +default is to display it. +.TP +.B \fB+[no]all\fP +This option sets or clears all display flags. +.TP +.B \fB+[no]answer\fP +This option displays [or does not display] the answer section of a reply. The default +is to display it. +.TP +.B \fB+[no]authority\fP +This option displays [or does not display] the authority section of a reply. The +default is to display it. +.TP +.B \fB+[no]besteffort\fP +This option attempts to display [or does not display] the contents of messages which are malformed. The +default is to not display malformed answers. +.TP +.B \fB+burst\fP +This option delays queries until the start of the next second. +.TP +.B \fB+[no]cl\fP +This option displays [or does not display] the CLASS when printing the record. +.TP +.B \fB+[no]comments\fP +This option toggles the display of comment lines in the output. The default is to +print comments. +.TP +.B \fB+[no]continue\fP +This option toggles continuation on errors (e.g. timeouts). +.TP +.B \fB+[no]crypto\fP +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\&. +.TP +.B \fB+dscp[=value]\fP +This option sets the DSCP code point to be used when sending the query. Valid DSCP +code points are in the range [0...63]. By default no code point is +explicitly set. +.TP +.B \fB+[no]multiline\fP +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. +.TP +.B \fB+[no]question\fP +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. +.TP +.B \fB+[no]rrcomments\fP +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. +.TP +.B \fB+[no]short\fP +This option provides [or does not provide] a terse answer. The default is to print the answer in a +verbose form. +.TP +.B \fB+split=W\fP +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. +.TP +.B \fB+[no]tcp\fP +This option uses [or does not use] TCP when querying name servers. The default behavior +is to use UDP. +.TP +.B \fB+[no]ttlid\fP +This option displays [or does not display] the TTL when printing the record. +.TP +.B \fB+[no]ttlunits\fP +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. +.TP +.B \fB+[no]vc\fP +This option uses [or does not use] TCP when querying name servers. This alternate +syntax to \fB+[no]tcp\fP is provided for backwards compatibility. The +\fBvc\fP stands for \(dqvirtual circuit\(dq. +.UNINDENT +.SH LOCAL OPTIONS +.INDENT 0.0 +.TP +.B \fB\-c class\fP +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. +.TP +.B \fB\-t type\fP +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 \fB\-x\fP option is supplied to indicate a reverse lookup with +the \(dqPTR\(dq query type. +.TP +.B \fB\-x addr\fP +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 \fB+[no]aaflag\fP +This is a synonym for \fB+[no]aaonly\fP\&. +.TP +.B \fB+[no]aaonly\fP +This sets the \fBaa\fP flag in the query. +.TP +.B \fB+[no]adflag\fP +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. +.TP +.B \fB+bufsize=B\fP +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. +.TP +.B \fB+[no]cdflag\fP +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. +.TP +.B \fB+[no]cookie=####\fP +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\&. +.TP +.B \fB+[no]dnssec\fP +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. +.TP +.B \fB+[no]edns[=#]\fP +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. +.TP +.B \fB+[no]ednsflags[=#]\fP +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. +.TP +.B \fB+[no]ednsopt[=code[:value]]\fP +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. +.TP +.B \fB+[no]expire\fP +This toggles sending of an EDNS Expire option. +.TP +.B \fB+[no]nsid\fP +This toggles inclusion of an EDNS name server ID request when sending a query. +.TP +.B \fB+[no]recurse\fP +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. +.TP +.B \fB+retry=T\fP +This sets the number of times to retry UDP queries to server to \fBT\fP +instead of the default, 2. Unlike \fB+tries\fP, this does not include +the initial query. +.TP +.B \fB+[no]subnet=addr[/prefix\-length]\fP +This sends [or does not send] an EDNS Client Subnet option with the specified IP +address or network prefix. +.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. +.TP +.B \fB+timeout=T\fP +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. +.TP +.B \fB+tries=T\fP +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. +.TP +.B \fB+udptimeout=T\fP +This sets the timeout between UDP query retries to \fBT\fP\&. +.TP +.B \fB+[no]unknownformat\fP +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. +.TP +.B \fB+[no]yaml\fP +This toggles printing of the responses in a detailed YAML format. +.TP +.B \fB+[no]zflag\fP +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 +\fBdig(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.8in b/doc/man/named-checkconf.8in new file mode 100644 index 0000000..a54628e --- /dev/null +++ b/doc/man/named-checkconf.8in @@ -0,0 +1,108 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "NAMED-CHECKCONF" "8" "@RELEASE_DATE@" "@BIND9_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 +\fBnamed\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/etc/named.conf\fP is read by default. +.sp +Note: files that \fBnamed\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 +\fBnamed\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 \fB\-h\fP +This option prints the usage summary and exits. +.TP +.B \fB\-j\fP +When loading a zonefile, this option instructs \fBnamed\fP to read the journal if it exists. +.TP +.B \fB\-l\fP +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). +.TP +.B \fB\-c\fP +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. +.TP +.B \fB\-i\fP +This option ignores warnings on deprecated options. +.TP +.B \fB\-p\fP +This option prints out the \fBnamed.conf\fP and included files in canonical form if +no errors were detected. See also the \fB\-x\fP option. +.TP +.B \fB\-t directory\fP +This option instructs \fBnamed\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the +configuration file are processed as if run by a similarly chrooted +\fBnamed\fP\&. +.TP +.B \fB\-v\fP +This option prints the version of the \fBnamed\-checkconf\fP program and exits. +.TP +.B \fB\-x\fP +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 \fBnamed.conf\fP and related files +to be shared \- for example, when submitting bug reports \- +without compromising private data. This option cannot be used without +\fB\-p\fP\&. +.TP +.B \fB\-z\fP +This option performs a test load of all zones of type \fBprimary\fP found in \fBnamed.conf\fP\&. +.TP +.B \fBfilename\fP +This indicates the name of the configuration file to be checked. If not specified, +it defaults to \fB/etc/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 +\fBnamed(8)\fP, \fBnamed\-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.8in b/doc/man/named-checkzone.8in new file mode 100644 index 0000000..3eff3d8 --- /dev/null +++ b/doc/man/named-checkzone.8in @@ -0,0 +1,204 @@ +.\" 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" "8" "@RELEASE_DATE@" "@BIND9_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 \fBnamed\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 \fB\-d\fP +This option enables debugging. +.TP +.B \fB\-h\fP +This option prints the usage summary and exits. +.TP +.B \fB\-q\fP +This option sets quiet mode, which only sets an exit code to indicate +successful or failed completion. +.TP +.B \fB\-v\fP +This option prints the version of the \fBnamed\-checkzone\fP program and exits. +.TP +.B \fB\-j\fP +When loading a zone file, this option tells \fBnamed\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. +.TP +.B \fB\-J filename\fP +When loading the zone file, this option tells \fBnamed\fP to read the journal from the given file, if +it exists. This implies \fB\-j\fP\&. +.TP +.B \fB\-c class\fP +This option specifies the class of the zone. If not specified, \fBIN\fP is assumed. +.TP +.B \fB\-i mode\fP +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. +.TP +.B \fB\-f format\fP +This option specifies the format of the zone file. Possible formats are +\fBtext\fP (the default), \fBraw\fP, and \fBmap\fP\&. +.TP +.B \fB\-F format\fP +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 \fBmap\fP, \fBraw\fP, and \fBraw=N\fP, which +store the zone in a binary format for rapid loading by \fBnamed\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 \fBnamed\fP; if N is 1, the +file can only be read by release 9.9.0 or higher. The default is 1. +.TP +.B \fB\-k mode\fP +This option performs \fBcheck\-names\fP checks with the specified failure mode. +Possible modes are \fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.TP +.B \fB\-l ttl\fP +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 \fBnamed.conf\fP\&. +.TP +.B \fB\-L serial\fP +When compiling a zone to \fBraw\fP or \fBmap\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. +.TP +.B \fB\-m mode\fP +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\&. +.TP +.B \fB\-M mode\fP +This option checks whether a MX record refers to a CNAME. Possible modes are +\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.TP +.B \fB\-n mode\fP +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\&. +.TP +.B \fB\-o filename\fP +This option writes the zone output to \fBfilename\fP\&. If \fBfilename\fP is \fB\-\fP, then +the zone output is written to standard output. +.TP +.B \fB\-r mode\fP +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\&. +.TP +.B \fB\-s style\fP +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. +.TP +.B \fB\-S mode\fP +This option checks whether an SRV record refers to a CNAME. Possible modes are +\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.TP +.B \fB\-t directory\fP +This option tells \fBnamed\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the +configuration file are processed as if run by a similarly chrooted +\fBnamed\fP\&. +.TP +.B \fB\-T mode\fP +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\&. +.TP +.B \fB\-w directory\fP +This option instructs \fBnamed\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 +\fBnamed.conf\fP\&. +.TP +.B \fB\-D\fP +This option dumps the zone file in canonical format. +.TP +.B \fB\-W mode\fP +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\&. +.TP +.B \fBzonename\fP +This indicates the domain name of the zone being checked. +.TP +.B \fBfilename\fP +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 +\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-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.8in b/doc/man/named-compilezone.8in new file mode 100644 index 0000000..493223e --- /dev/null +++ b/doc/man/named-compilezone.8in @@ -0,0 +1,206 @@ +.\" 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" "8" "@RELEASE_DATE@" "@BIND9_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 \fBnamed\fP\&. +When manually specified otherwise, the check levels must at least be as +strict as those specified in the \fBnamed\fP configuration file. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-d\fP +This option enables debugging. +.TP +.B \fB\-h\fP +This option prints the usage summary and exits. +.TP +.B \fB\-q\fP +This option sets quiet mode, which only sets an exit code to indicate +successful or failed completion. +.TP +.B \fB\-v\fP +This option prints the version of the \fBnamed\-checkzone\fP program and exits. +.TP +.B \fB\-j\fP +When loading a zone file, this option tells \fBnamed\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. +.TP +.B \fB\-J filename\fP +When loading the zone file, this option tells \fBnamed\fP to read the journal from the given file, if +it exists. This implies \fB\-j\fP\&. +.TP +.B \fB\-c class\fP +This option specifies the class of the zone. If not specified, \fBIN\fP is assumed. +.TP +.B \fB\-i mode\fP +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. +.TP +.B \fB\-f format\fP +This option specifies the format of the zone file. Possible formats are +\fBtext\fP (the default), \fBraw\fP, and \fBmap\fP\&. +.TP +.B \fB\-F format\fP +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 \fBmap\fP, \fBraw\fP, and \fBraw=N\fP, which +store the zone in a binary format for rapid loading by \fBnamed\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 \fBnamed\fP; if N is 1, the +file can only be read by release 9.9.0 or higher. The default is 1. +.TP +.B \fB\-k mode\fP +This option performs \fBcheck\-names\fP checks with the specified failure mode. +Possible modes are \fBfail\fP (the default), \fBwarn\fP, and \fBignore\fP\&. +.TP +.B \fB\-l ttl\fP +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 \fBnamed.conf\fP\&. +.TP +.B \fB\-L serial\fP +When compiling a zone to \fBraw\fP or \fBmap\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. +.TP +.B \fB\-m mode\fP +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\&. +.TP +.B \fB\-M mode\fP +This option checks whether a MX record refers to a CNAME. Possible modes are +\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.TP +.B \fB\-n mode\fP +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\&. +.TP +.B \fB\-o filename\fP +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\&. +.TP +.B \fB\-r mode\fP +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\&. +.TP +.B \fB\-s style\fP +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. +.TP +.B \fB\-S mode\fP +This option checks whether an SRV record refers to a CNAME. Possible modes are +\fBfail\fP, \fBwarn\fP (the default), and \fBignore\fP\&. +.TP +.B \fB\-t directory\fP +This option tells \fBnamed\fP to chroot to \fBdirectory\fP, so that \fBinclude\fP directives in the +configuration file are processed as if run by a similarly chrooted +\fBnamed\fP\&. +.TP +.B \fB\-T mode\fP +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\&. +.TP +.B \fB\-w directory\fP +This option instructs \fBnamed\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 +\fBnamed.conf\fP\&. +.TP +.B \fB\-D\fP +This option dumps the zone file in canonical format. This is always enabled for +\fBnamed\-compilezone\fP\&. +.TP +.B \fB\-W mode\fP +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\&. +.TP +.B \fBzonename\fP +This indicates the domain name of the zone being checked. +.TP +.B \fBfilename\fP +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 +\fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBnamed\-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.8in b/doc/man/named-journalprint.8in new file mode 100644 index 0000000..6f8d89a --- /dev/null +++ b/doc/man/named-journalprint.8in @@ -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" "8" "@RELEASE_DATE@" "@BIND9_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 \fBnamed\fP when changes are +made to dynamic zones (e.g., by \fBnsupdate\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 \fBnamed\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 +\fBnamed\fP is running. +.SH SEE ALSO +.sp +\fBnamed(8)\fP, \fBnsupdate(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.8in b/doc/man/named-nzd2nzf.8in new file mode 100644 index 0000000..f245015 --- /dev/null +++ b/doc/man/named-nzd2nzf.8in @@ -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" "8" "@RELEASE_DATE@" "@BIND9_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 \fBnamed\fP via \fBrndc 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 \fBfilename\fP +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..3348558 --- /dev/null +++ b/doc/man/named-rrchecker.1in @@ -0,0 +1,70 @@ +.\" 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@" "@BIND9_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 \fB\-h\fP +This option prints out the help menu. +.TP +.B \fB\-o origin\fP +This option specifies the origin to be used when interpreting +the record. +.TP +.B \fB\-p\fP +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. +.TP +.B \fB\-u\fP +This option prints out the resulting record in unknown record form. +.TP +.B \fB\-C\fP, \fB\-T\fP, and \fB\-P\fP +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, \fBnamed(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..b501b46 --- /dev/null +++ b/doc/man/named.8in @@ -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 "NAMED" "8" "@RELEASE_DATE@" "@BIND9_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\-S\fP #max\-socks] [\fB\-t\fP directory] [\fB\-U\fP #listeners] [\fB\-u\fP user] [\fB\-v\fP] [\fB\-V\fP] [\fB\-X\fP lock\-file] [\fB\-x\fP cache\-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/etc/named.conf\fP, reads any initial data, and +listens for queries. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-4\fP +This option tells \fBnamed\fP to use only IPv4, even if the host machine is capable of IPv6. \fB\-4\fP and +\fB\-6\fP are mutually exclusive. +.TP +.B \fB\-6\fP +This option tells \fBnamed\fP to use only IPv6, even if the host machine is capable of IPv4. \fB\-4\fP and +\fB\-6\fP are mutually exclusive. +.TP +.B \fB\-c config\-file\fP +This option tells \fBnamed\fP to use \fBconfig\-file\fP as its configuration file instead of the default, +\fB/etc/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 +.sp +\fB\-C\fP +.INDENT 0.0 +.INDENT 3.5 +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 \fBnamed\fP +at runtime. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \fB\-d debug\-level\fP +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. +.TP +.B \fB\-D string\fP +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. +.TP +.B \fB\-E engine\-name\fP +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). When BIND is +built with native PKCS#11 cryptography (\fB\-\-enable\-native\-pkcs11\fP), it +defaults to the path of the PKCS#11 provider library specified via +\fB\-\-with\-pkcs11\fP\&. +.TP +.B \fB\-f\fP +This option runs the server in the foreground (i.e., do not daemonize). +.TP +.B \fB\-g\fP +This option runs the server in the foreground and forces all logging to \fBstderr\fP\&. +.TP +.B \fB\-L logfile\fP +This option sets the log to the file \fBlogfile\fP by default, instead of the system log. +.UNINDENT +.sp +\fB\-M option\fP +.INDENT 0.0 +.INDENT 3.5 +This option sets the default (comma\-separated) memory context +options. The possible flags are: +.INDENT 0.0 +.IP \(bu 2 +\fBexternal\fP: use system\-provided memory allocation functions; this +is the implicit default. +.IP \(bu 2 +\fBinternal\fP: use the internal memory manager. +.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 +.UNINDENT +.INDENT 0.0 +.TP +.B \fB\-m flag\fP +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<isc/mem.h>\fP\&. +.TP +.B \fB\-n #cpus\fP +This option controls the number of CPUs that \fBnamed\fP assumes the +presence of. If not specified, \fBnamed\fP tries to determine the +number of CPUs present automatically; if it fails, a single CPU is +assumed to be present. +.sp +\fBnamed\fP creates two threads per each CPU present (one thread for +receiving and sending client traffic and another thread for sending +and receiving resolver traffic) and then on top of that a single +thread for handling time\-based events. +.TP +.B \fB\-p port\fP +This option listens for queries on \fBport\fP\&. If not specified, the default is +port 53. +.TP +.B \fB\-s\fP +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 \fB\-S #max\-socks\fP +This option allows \fBnamed\fP to use up to \fB#max\-socks\fP sockets. The default value is +21000 on systems built with default configuration options, and 4096 +on systems built with \fBconfigure \-\-with\-tuning=small\fP\&. +.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 \fB\-t directory\fP +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 \fB\-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 \fB\-U #listeners\fP +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 \fB\-n\fP has been set to a higher value than the number of detected +CPUs, then \fB\-U\fP may be increased as high as that value, but no +higher. On Windows, the number of UDP listeners is hardwired to 1 and +this option has no effect. +.TP +.B \fB\-u user\fP +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 \fB\-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 \fB\-v\fP +This option reports the version number and exits. +.TP +.B \fB\-V\fP +This option reports the version number, build options, supported +cryptographics algorithms, and exits. +.TP +.B \fB\-X lock\-file\fP +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 +\fBnamed.conf\fP\&. If set to \fBnone\fP, the lock file check is disabled. +.TP +.B \fB\-x cache\-file\fP +This option loads data from \fBcache\-file\fP into the cache of the default view. +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This option must not be used in normal operations. It is only of interest to BIND 9 +developers and may be removed or changed in a future release. +.UNINDENT +.UNINDENT +.SH SIGNALS +.sp +In routine operation, signals should not be used to control the +nameserver; \fBrndc\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/etc/named.conf\fP +The default configuration file. +.TP +.B \fB/var/run/named/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, \fBnamed\-checkconf(8)\fP, \fBnamed\-checkzone(8)\fP, \fBrndc(8)\fP, \fBnamed.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..c87afa2 --- /dev/null +++ b/doc/man/named.conf.5in @@ -0,0 +1,1175 @@ +.\" 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@" "@BIND9_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 \fBnamed\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: /* */ +.INDENT 0.0 +.INDENT 3.5 +C++ style: // to end of line +.UNINDENT +.UNINDENT +.sp +Unix style: # to end of line +.SS ACL +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +acl string { address_match_element; ... }; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS CONTROLS +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +controls { + inet ( ipv4_address | ipv6_address | + * ) [ port ( integer | * ) ] allow + { address_match_element; ... } [ + keys { string; ... } ] [ read\-only + boolean ]; + unix quoted_string perm integer + owner integer group integer [ + keys { string; ... } ] [ read\-only + boolean ]; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS DLZ +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +dlz string { + database string; + search boolean; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS DNSSEC\-POLICY +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +dnssec\-policy string { + dnskey\-ttl duration; + keys { ( csk | ksk | zsk ) [ ( key\-directory ) ] lifetime + duration_or_unlimited algorithm string [ integer ]; ... }; + max\-zone\-ttl duration; + nsec3param [ iterations integer ] [ optout boolean ] [ + salt\-length integer ]; + parent\-ds\-ttl duration; + parent\-propagation\-delay duration; + publish\-safety duration; + purge\-keys duration; + retire\-safety duration; + signatures\-refresh duration; + signatures\-validity duration; + signatures\-validity\-dnskey duration; + zone\-propagation\-delay duration; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS DYNDB +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +dyndb string quoted_string { + unspecified\-text }; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS KEY +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +key string { + algorithm string; + secret string; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS LOGGING +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +logging { + category string { string; ... }; + channel string { + buffered boolean; + file quoted_string [ versions ( unlimited | integer ) ] + [ size size ] [ suffix ( increment | timestamp ) ]; + null; + print\-category boolean; + print\-severity boolean; + print\-time ( iso8601 | iso8601\-utc | local | boolean ); + severity log_severity; + stderr; + syslog [ syslog_facility ]; + }; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS MANAGED\-KEYS +.sp +See DNSSEC\-KEYS. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +managed\-keys { string ( static\-key + | initial\-key | static\-ds | + initial\-ds ) integer integer + integer quoted_string; ... };, deprecated +.ft P +.fi +.UNINDENT +.UNINDENT +.SS MASTERS +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +masters string [ port integer ] [ dscp + integer ] { ( remote\-servers | + ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key + string ]; ... }; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS OPTIONS +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +options { + allow\-new\-zones boolean; + allow\-notify { address_match_element; ... }; + allow\-query { address_match_element; ... }; + allow\-query\-cache { address_match_element; ... }; + allow\-query\-cache\-on { address_match_element; ... }; + allow\-query\-on { address_match_element; ... }; + allow\-recursion { address_match_element; ... }; + allow\-recursion\-on { address_match_element; ... }; + allow\-transfer { address_match_element; ... }; + allow\-update { address_match_element; ... }; + allow\-update\-forwarding { address_match_element; ... }; + also\-notify [ port integer ] [ dscp integer ] { ( + remote\-servers | ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key string ]; ... }; + alt\-transfer\-source ( ipv4_address | * ) [ port ( integer | * ) + ] [ dscp integer ]; + alt\-transfer\-source\-v6 ( ipv6_address | * ) [ port ( integer | + * ) ] [ dscp integer ]; + answer\-cookie boolean; + attach\-cache string; + auth\-nxdomain boolean; // default changed + auto\-dnssec ( allow | maintain | off );// deprecated + automatic\-interface\-scan boolean; + avoid\-v4\-udp\-ports { portrange; ... }; + avoid\-v6\-udp\-ports { portrange; ... }; + bindkeys\-file quoted_string; + blackhole { address_match_element; ... }; + cache\-file quoted_string;// deprecated + catalog\-zones { zone string [ default\-masters [ port integer ] + [ dscp integer ] { ( remote\-servers | ipv4_address [ port + integer ] | ipv6_address [ port integer ] ) [ key + string ]; ... } ] [ zone\-directory quoted_string ] [ + in\-memory boolean ] [ min\-update\-interval duration ]; ... }; + check\-dup\-records ( fail | warn | ignore ); + check\-integrity boolean; + check\-mx ( fail | warn | ignore ); + check\-mx\-cname ( fail | warn | ignore ); + check\-names ( primary | master | + secondary | slave | response ) ( + fail | warn | ignore ); + check\-sibling boolean; + check\-spf ( warn | ignore ); + check\-srv\-cname ( fail | warn | ignore ); + check\-wildcard boolean; + clients\-per\-query integer; + cookie\-algorithm ( aes | siphash24 ); + cookie\-secret string; + coresize ( default | unlimited | sizeval ); + datasize ( default | unlimited | sizeval ); + deny\-answer\-addresses { address_match_element; ... } [ + except\-from { string; ... } ]; + deny\-answer\-aliases { string; ... } [ except\-from { string; ... + } ]; + dialup ( notify | notify\-passive | passive | refresh | boolean ); + directory quoted_string; + disable\-algorithms string { string; + ... }; + disable\-ds\-digests string { string; + ... }; + disable\-empty\-zone string; + dns64 netprefix { + break\-dnssec boolean; + clients { address_match_element; ... }; + exclude { address_match_element; ... }; + mapped { address_match_element; ... }; + recursive\-only boolean; + suffix ipv6_address; + }; + dns64\-contact string; + dns64\-server string; + dnskey\-sig\-validity integer; + dnsrps\-enable boolean; + dnsrps\-options { unspecified\-text }; + dnssec\-accept\-expired boolean; + dnssec\-dnskey\-kskonly boolean; + dnssec\-loadkeys\-interval integer; + dnssec\-must\-be\-secure string boolean; + dnssec\-policy string; + dnssec\-secure\-to\-insecure boolean; + dnssec\-update\-mode ( maintain | no\-resign ); + dnssec\-validation ( yes | no | auto ); + dnstap { ( all | auth | client | forwarder | resolver | update ) [ + ( query | response ) ]; ... }; + dnstap\-identity ( quoted_string | none | hostname ); + dnstap\-output ( file | unix ) quoted_string [ size ( unlimited | + size ) ] [ versions ( unlimited | integer ) ] [ suffix ( + increment | timestamp ) ]; + dnstap\-version ( quoted_string | none ); + dscp integer; + dual\-stack\-servers [ port integer ] { ( quoted_string [ port + integer ] [ dscp integer ] | ipv4_address [ port + integer ] [ dscp integer ] | ipv6_address [ port + integer ] [ dscp integer ] ); ... }; + dump\-file quoted_string; + edns\-udp\-size integer; + empty\-contact string; + empty\-server string; + empty\-zones\-enable boolean; + fetch\-quota\-params integer fixedpoint fixedpoint fixedpoint; + fetches\-per\-server integer [ ( drop | fail ) ]; + fetches\-per\-zone integer [ ( drop | fail ) ]; + files ( default | unlimited | sizeval ); + flush\-zones\-on\-shutdown boolean; + forward ( first | only ); + forwarders [ port integer ] [ dscp integer ] { ( ipv4_address + | ipv6_address ) [ port integer ] [ dscp integer ]; ... }; + fstrm\-set\-buffer\-hint integer; + fstrm\-set\-flush\-timeout integer; + fstrm\-set\-input\-queue\-size integer; + fstrm\-set\-output\-notify\-threshold integer; + fstrm\-set\-output\-queue\-model ( mpsc | spsc ); + fstrm\-set\-output\-queue\-size integer; + fstrm\-set\-reopen\-interval duration; + geoip\-directory ( quoted_string | none ); + glue\-cache boolean; + heartbeat\-interval integer; + hostname ( quoted_string | none ); + interface\-interval duration; + ixfr\-from\-differences ( primary | master | secondary | slave | + boolean ); + keep\-response\-order { address_match_element; ... }; + key\-directory quoted_string; + lame\-ttl duration; + listen\-on [ port integer ] [ dscp + integer ] { + address_match_element; ... }; + listen\-on\-v6 [ port integer ] [ dscp + integer ] { + address_match_element; ... }; + lmdb\-mapsize sizeval; + lock\-file ( quoted_string | none ); + managed\-keys\-directory quoted_string; + masterfile\-format ( map | raw | text ); + masterfile\-style ( full | relative ); + match\-mapped\-addresses boolean; + max\-cache\-size ( default | unlimited | sizeval | percentage ); + max\-cache\-ttl duration; + max\-clients\-per\-query integer; + max\-ixfr\-ratio ( unlimited | percentage ); + max\-journal\-size ( default | unlimited | sizeval ); + max\-ncache\-ttl duration; + max\-records integer; + max\-recursion\-depth integer; + max\-recursion\-queries integer; + max\-refresh\-time integer; + max\-retry\-time integer; + max\-rsa\-exponent\-size integer; + max\-stale\-ttl duration; + max\-transfer\-idle\-in integer; + max\-transfer\-idle\-out integer; + max\-transfer\-time\-in integer; + max\-transfer\-time\-out integer; + max\-udp\-size integer; + max\-zone\-ttl ( unlimited | duration ); + memstatistics boolean; + memstatistics\-file quoted_string; + message\-compression boolean; + min\-cache\-ttl duration; + min\-ncache\-ttl duration; + min\-refresh\-time integer; + min\-retry\-time integer; + minimal\-any boolean; + minimal\-responses ( no\-auth | no\-auth\-recursive | boolean ); + multi\-master boolean; + new\-zones\-directory quoted_string; + no\-case\-compress { address_match_element; ... }; + nocookie\-udp\-size integer; + notify ( explicit | master\-only | primary\-only | boolean ); + notify\-delay integer; + notify\-rate integer; + notify\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + notify\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) ] + [ dscp integer ]; + notify\-to\-soa boolean; + nta\-lifetime duration; + nta\-recheck duration; + nxdomain\-redirect string; + parental\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + parental\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) + ] [ dscp integer ]; + pid\-file ( quoted_string | none ); + port integer; + preferred\-glue string; + prefetch integer [ integer ]; + provide\-ixfr boolean; + qname\-minimization ( strict | relaxed | disabled | off ); + query\-source ( ( [ address ] ( ipv4_address | * ) [ port ( + integer | * ) ] ) | ( [ [ address ] ( ipv4_address | * ) ] + port ( integer | * ) ) ) [ dscp integer ]; + query\-source\-v6 ( ( [ address ] ( ipv6_address | * ) [ port ( + integer | * ) ] ) | ( [ [ address ] ( ipv6_address | * ) ] + port ( integer | * ) ) ) [ dscp integer ]; + querylog boolean; + random\-device ( quoted_string | none ); + rate\-limit { + all\-per\-second integer; + errors\-per\-second integer; + exempt\-clients { address_match_element; ... }; + ipv4\-prefix\-length integer; + ipv6\-prefix\-length integer; + log\-only boolean; + max\-table\-size integer; + min\-table\-size integer; + nodata\-per\-second integer; + nxdomains\-per\-second integer; + qps\-scale integer; + referrals\-per\-second integer; + responses\-per\-second integer; + slip integer; + window integer; + }; + recursing\-file quoted_string; + recursion boolean; + recursive\-clients integer; + request\-expire boolean; + request\-ixfr boolean; + request\-nsid boolean; + require\-server\-cookie boolean; + reserved\-sockets integer; + resolver\-nonbackoff\-tries integer; + resolver\-query\-timeout integer; + resolver\-retry\-interval integer; + response\-padding { address_match_element; ... } block\-size + integer; + response\-policy { zone string [ add\-soa boolean ] [ log + boolean ] [ max\-policy\-ttl duration ] [ min\-update\-interval + duration ] [ policy ( cname | disabled | drop | given | no\-op + | nodata | nxdomain | passthru | tcp\-only quoted_string ) ] [ + recursive\-only boolean ] [ nsip\-enable boolean ] [ + nsdname\-enable boolean ]; ... } [ add\-soa boolean ] [ + break\-dnssec boolean ] [ max\-policy\-ttl duration ] [ + min\-update\-interval duration ] [ min\-ns\-dots integer ] [ + nsip\-wait\-recurse boolean ] [ qname\-wait\-recurse boolean ] + [ recursive\-only boolean ] [ nsip\-enable boolean ] [ + nsdname\-enable boolean ] [ dnsrps\-enable boolean ] [ + dnsrps\-options { unspecified\-text } ]; + reuseport boolean; + root\-delegation\-only [ exclude { string; ... } ]; + root\-key\-sentinel boolean; + rrset\-order { [ class string ] [ type string ] [ name + quoted_string ] string string; ... }; + secroots\-file quoted_string; + send\-cookie boolean; + serial\-query\-rate integer; + serial\-update\-method ( date | increment | unixtime ); + server\-id ( quoted_string | none | hostname ); + servfail\-ttl duration; + session\-keyalg string; + session\-keyfile ( quoted_string | none ); + session\-keyname string; + sig\-signing\-nodes integer; + sig\-signing\-signatures integer; + sig\-signing\-type integer; + sig\-validity\-interval integer [ integer ]; + sortlist { address_match_element; ... }; + stacksize ( default | unlimited | sizeval ); + stale\-answer\-client\-timeout ( disabled | off | integer ); + stale\-answer\-enable boolean; + stale\-answer\-ttl duration; + stale\-cache\-enable boolean; + stale\-refresh\-time duration; + startup\-notify\-rate integer; + statistics\-file quoted_string; + synth\-from\-dnssec boolean; + tcp\-advertised\-timeout integer; + tcp\-clients integer; + tcp\-idle\-timeout integer; + tcp\-initial\-timeout integer; + tcp\-keepalive\-timeout integer; + tcp\-listen\-queue integer; + tkey\-dhkey quoted_string integer; + tkey\-domain quoted_string; + tkey\-gssapi\-credential quoted_string; + tkey\-gssapi\-keytab quoted_string; + transfer\-format ( many\-answers | one\-answer ); + transfer\-message\-size integer; + transfer\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + transfer\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) + ] [ dscp integer ]; + transfers\-in integer; + transfers\-out integer; + transfers\-per\-ns integer; + trust\-anchor\-telemetry boolean; // experimental + try\-tcp\-refresh boolean; + update\-check\-ksk boolean; + update\-quota integer; + use\-alt\-transfer\-source boolean; + use\-v4\-udp\-ports { portrange; ... }; + use\-v6\-udp\-ports { portrange; ... }; + v6\-bias integer; + validate\-except { string; ... }; + version ( quoted_string | none ); + zero\-no\-soa\-ttl boolean; + zero\-no\-soa\-ttl\-cache boolean; + zone\-statistics ( full | terse | none | boolean ); +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS PARENTAL\-AGENTS +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +parental\-agents string [ port integer ] [ + dscp integer ] { ( remote\-servers | + ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key + string ]; ... }; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS PLUGIN +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +plugin ( query ) string [ { unspecified\-text + } ]; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS PRIMARIES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +primaries string [ port integer ] [ dscp + integer ] { ( remote\-servers | + ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key + string ]; ... }; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS SERVER +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +server netprefix { + bogus boolean; + edns boolean; + edns\-udp\-size integer; + edns\-version integer; + keys server_key; + max\-udp\-size integer; + notify\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + notify\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) ] + [ dscp integer ]; + padding integer; + provide\-ixfr boolean; + query\-source ( ( [ address ] ( ipv4_address | * ) [ port ( + integer | * ) ] ) | ( [ [ address ] ( ipv4_address | * ) ] + port ( integer | * ) ) ) [ dscp integer ]; + query\-source\-v6 ( ( [ address ] ( ipv6_address | * ) [ port ( + integer | * ) ] ) | ( [ [ address ] ( ipv6_address | * ) ] + port ( integer | * ) ) ) [ dscp integer ]; + request\-expire boolean; + request\-ixfr boolean; + request\-nsid boolean; + send\-cookie boolean; + tcp\-keepalive boolean; + tcp\-only boolean; + transfer\-format ( many\-answers | one\-answer ); + transfer\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + transfer\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) + ] [ dscp integer ]; + transfers integer; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS STATISTICS\-CHANNELS +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +statistics\-channels { + inet ( ipv4_address | ipv6_address | + * ) [ port ( integer | * ) ] [ + allow { address_match_element; ... + } ]; +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS TRUST\-ANCHORS +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +trust\-anchors { string ( static\-key | + initial\-key | static\-ds | initial\-ds ) + integer integer integer + quoted_string; ... }; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS TRUSTED\-KEYS +.sp +Deprecated \- see DNSSEC\-KEYS. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +trusted\-keys { string integer + integer integer + quoted_string; ... };, deprecated +.ft P +.fi +.UNINDENT +.UNINDENT +.SS VIEW +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +view string [ class ] { + allow\-new\-zones boolean; + allow\-notify { address_match_element; ... }; + allow\-query { address_match_element; ... }; + allow\-query\-cache { address_match_element; ... }; + allow\-query\-cache\-on { address_match_element; ... }; + allow\-query\-on { address_match_element; ... }; + allow\-recursion { address_match_element; ... }; + allow\-recursion\-on { address_match_element; ... }; + allow\-transfer { address_match_element; ... }; + allow\-update { address_match_element; ... }; + allow\-update\-forwarding { address_match_element; ... }; + also\-notify [ port integer ] [ dscp integer ] { ( + remote\-servers | ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key string ]; ... }; + alt\-transfer\-source ( ipv4_address | * ) [ port ( integer | * ) + ] [ dscp integer ]; + alt\-transfer\-source\-v6 ( ipv6_address | * ) [ port ( integer | + * ) ] [ dscp integer ]; + attach\-cache string; + auth\-nxdomain boolean; // default changed + auto\-dnssec ( allow | maintain | off );// deprecated + cache\-file quoted_string;// deprecated + catalog\-zones { zone string [ default\-masters [ port integer ] + [ dscp integer ] { ( remote\-servers | ipv4_address [ port + integer ] | ipv6_address [ port integer ] ) [ key + string ]; ... } ] [ zone\-directory quoted_string ] [ + in\-memory boolean ] [ min\-update\-interval duration ]; ... }; + check\-dup\-records ( fail | warn | ignore ); + check\-integrity boolean; + check\-mx ( fail | warn | ignore ); + check\-mx\-cname ( fail | warn | ignore ); + check\-names ( primary | master | + secondary | slave | response ) ( + fail | warn | ignore ); + check\-sibling boolean; + check\-spf ( warn | ignore ); + check\-srv\-cname ( fail | warn | ignore ); + check\-wildcard boolean; + clients\-per\-query integer; + deny\-answer\-addresses { address_match_element; ... } [ + except\-from { string; ... } ]; + deny\-answer\-aliases { string; ... } [ except\-from { string; ... + } ]; + dialup ( notify | notify\-passive | passive | refresh | boolean ); + disable\-algorithms string { string; + ... }; + disable\-ds\-digests string { string; + ... }; + disable\-empty\-zone string; + dlz string { + database string; + search boolean; + }; + dns64 netprefix { + break\-dnssec boolean; + clients { address_match_element; ... }; + exclude { address_match_element; ... }; + mapped { address_match_element; ... }; + recursive\-only boolean; + suffix ipv6_address; + }; + dns64\-contact string; + dns64\-server string; + dnskey\-sig\-validity integer; + dnsrps\-enable boolean; + dnsrps\-options { unspecified\-text }; + dnssec\-accept\-expired boolean; + dnssec\-dnskey\-kskonly boolean; + dnssec\-loadkeys\-interval integer; + dnssec\-must\-be\-secure string boolean; + dnssec\-policy string; + dnssec\-secure\-to\-insecure boolean; + dnssec\-update\-mode ( maintain | no\-resign ); + dnssec\-validation ( yes | no | auto ); + dnstap { ( all | auth | client | forwarder | resolver | update ) [ + ( query | response ) ]; ... }; + dual\-stack\-servers [ port integer ] { ( quoted_string [ port + integer ] [ dscp integer ] | ipv4_address [ port + integer ] [ dscp integer ] | ipv6_address [ port + integer ] [ dscp integer ] ); ... }; + dyndb string quoted_string { + unspecified\-text }; + edns\-udp\-size integer; + empty\-contact string; + empty\-server string; + empty\-zones\-enable boolean; + fetch\-quota\-params integer fixedpoint fixedpoint fixedpoint; + fetches\-per\-server integer [ ( drop | fail ) ]; + fetches\-per\-zone integer [ ( drop | fail ) ]; + forward ( first | only ); + forwarders [ port integer ] [ dscp integer ] { ( ipv4_address + | ipv6_address ) [ port integer ] [ dscp integer ]; ... }; + glue\-cache boolean; + ixfr\-from\-differences ( primary | master | secondary | slave | + boolean ); + key string { + algorithm string; + secret string; + }; + key\-directory quoted_string; + lame\-ttl duration; + lmdb\-mapsize sizeval; + managed\-keys { string ( + static\-key | initial\-key + | static\-ds | initial\-ds + ) integer integer + integer + quoted_string; ... };, deprecated + masterfile\-format ( map | raw | text ); + masterfile\-style ( full | relative ); + match\-clients { address_match_element; ... }; + match\-destinations { address_match_element; ... }; + match\-recursive\-only boolean; + max\-cache\-size ( default | unlimited | sizeval | percentage ); + max\-cache\-ttl duration; + max\-clients\-per\-query integer; + max\-ixfr\-ratio ( unlimited | percentage ); + max\-journal\-size ( default | unlimited | sizeval ); + max\-ncache\-ttl duration; + max\-records integer; + max\-recursion\-depth integer; + max\-recursion\-queries integer; + max\-refresh\-time integer; + max\-retry\-time integer; + max\-stale\-ttl duration; + max\-transfer\-idle\-in integer; + max\-transfer\-idle\-out integer; + max\-transfer\-time\-in integer; + max\-transfer\-time\-out integer; + max\-udp\-size integer; + max\-zone\-ttl ( unlimited | duration ); + message\-compression boolean; + min\-cache\-ttl duration; + min\-ncache\-ttl duration; + min\-refresh\-time integer; + min\-retry\-time integer; + minimal\-any boolean; + minimal\-responses ( no\-auth | no\-auth\-recursive | boolean ); + multi\-master boolean; + new\-zones\-directory quoted_string; + no\-case\-compress { address_match_element; ... }; + nocookie\-udp\-size integer; + notify ( explicit | master\-only | primary\-only | boolean ); + notify\-delay integer; + notify\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + notify\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) ] + [ dscp integer ]; + notify\-to\-soa boolean; + nta\-lifetime duration; + nta\-recheck duration; + nxdomain\-redirect string; + parental\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + parental\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) + ] [ dscp integer ]; + plugin ( query ) string [ { + unspecified\-text } ]; + preferred\-glue string; + prefetch integer [ integer ]; + provide\-ixfr boolean; + qname\-minimization ( strict | relaxed | disabled | off ); + query\-source ( ( [ address ] ( ipv4_address | * ) [ port ( + integer | * ) ] ) | ( [ [ address ] ( ipv4_address | * ) ] + port ( integer | * ) ) ) [ dscp integer ]; + query\-source\-v6 ( ( [ address ] ( ipv6_address | * ) [ port ( + integer | * ) ] ) | ( [ [ address ] ( ipv6_address | * ) ] + port ( integer | * ) ) ) [ dscp integer ]; + rate\-limit { + all\-per\-second integer; + errors\-per\-second integer; + exempt\-clients { address_match_element; ... }; + ipv4\-prefix\-length integer; + ipv6\-prefix\-length integer; + log\-only boolean; + max\-table\-size integer; + min\-table\-size integer; + nodata\-per\-second integer; + nxdomains\-per\-second integer; + qps\-scale integer; + referrals\-per\-second integer; + responses\-per\-second integer; + slip integer; + window integer; + }; + recursion boolean; + request\-expire boolean; + request\-ixfr boolean; + request\-nsid boolean; + require\-server\-cookie boolean; + resolver\-nonbackoff\-tries integer; + resolver\-query\-timeout integer; + resolver\-retry\-interval integer; + response\-padding { address_match_element; ... } block\-size + integer; + response\-policy { zone string [ add\-soa boolean ] [ log + boolean ] [ max\-policy\-ttl duration ] [ min\-update\-interval + duration ] [ policy ( cname | disabled | drop | given | no\-op + | nodata | nxdomain | passthru | tcp\-only quoted_string ) ] [ + recursive\-only boolean ] [ nsip\-enable boolean ] [ + nsdname\-enable boolean ]; ... } [ add\-soa boolean ] [ + break\-dnssec boolean ] [ max\-policy\-ttl duration ] [ + min\-update\-interval duration ] [ min\-ns\-dots integer ] [ + nsip\-wait\-recurse boolean ] [ qname\-wait\-recurse boolean ] + [ recursive\-only boolean ] [ nsip\-enable boolean ] [ + nsdname\-enable boolean ] [ dnsrps\-enable boolean ] [ + dnsrps\-options { unspecified\-text } ]; + root\-delegation\-only [ exclude { string; ... } ]; + root\-key\-sentinel boolean; + rrset\-order { [ class string ] [ type string ] [ name + quoted_string ] string string; ... }; + send\-cookie boolean; + serial\-update\-method ( date | increment | unixtime ); + server netprefix { + bogus boolean; + edns boolean; + edns\-udp\-size integer; + edns\-version integer; + keys server_key; + max\-udp\-size integer; + notify\-source ( ipv4_address | * ) [ port ( integer | * + ) ] [ dscp integer ]; + notify\-source\-v6 ( ipv6_address | * ) [ port ( integer + | * ) ] [ dscp integer ]; + padding integer; + provide\-ixfr boolean; + query\-source ( ( [ address ] ( ipv4_address | * ) [ port + ( integer | * ) ] ) | ( [ [ address ] ( + ipv4_address | * ) ] port ( integer | * ) ) ) [ + dscp integer ]; + query\-source\-v6 ( ( [ address ] ( ipv6_address | * ) [ + port ( integer | * ) ] ) | ( [ [ address ] ( + ipv6_address | * ) ] port ( integer | * ) ) ) [ + dscp integer ]; + request\-expire boolean; + request\-ixfr boolean; + request\-nsid boolean; + send\-cookie boolean; + tcp\-keepalive boolean; + tcp\-only boolean; + transfer\-format ( many\-answers | one\-answer ); + transfer\-source ( ipv4_address | * ) [ port ( integer | + * ) ] [ dscp integer ]; + transfer\-source\-v6 ( ipv6_address | * ) [ port ( + integer | * ) ] [ dscp integer ]; + transfers integer; + }; + servfail\-ttl duration; + sig\-signing\-nodes integer; + sig\-signing\-signatures integer; + sig\-signing\-type integer; + sig\-validity\-interval integer [ integer ]; + sortlist { address_match_element; ... }; + stale\-answer\-client\-timeout ( disabled | off | integer ); + stale\-answer\-enable boolean; + stale\-answer\-ttl duration; + stale\-cache\-enable boolean; + stale\-refresh\-time duration; + synth\-from\-dnssec boolean; + transfer\-format ( many\-answers | one\-answer ); + transfer\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + transfer\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) + ] [ dscp integer ]; + trust\-anchor\-telemetry boolean; // experimental + trust\-anchors { string ( static\-key | + initial\-key | static\-ds | initial\-ds + ) integer integer integer + quoted_string; ... }; + trusted\-keys { string + integer integer + integer + quoted_string; ... };, deprecated + try\-tcp\-refresh boolean; + update\-check\-ksk boolean; + use\-alt\-transfer\-source boolean; + v6\-bias integer; + validate\-except { string; ... }; + zero\-no\-soa\-ttl boolean; + zero\-no\-soa\-ttl\-cache boolean; + zone string [ class ] { + allow\-notify { address_match_element; ... }; + allow\-query { address_match_element; ... }; + allow\-query\-on { address_match_element; ... }; + allow\-transfer { address_match_element; ... }; + allow\-update { address_match_element; ... }; + allow\-update\-forwarding { address_match_element; ... }; + also\-notify [ port integer ] [ dscp integer ] { ( + remote\-servers | ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key string ]; + ... }; + alt\-transfer\-source ( ipv4_address | * ) [ port ( + integer | * ) ] [ dscp integer ]; + alt\-transfer\-source\-v6 ( ipv6_address | * ) [ port ( + integer | * ) ] [ dscp integer ]; + auto\-dnssec ( allow | maintain | off );// deprecated + check\-dup\-records ( fail | warn | ignore ); + check\-integrity boolean; + check\-mx ( fail | warn | ignore ); + check\-mx\-cname ( fail | warn | ignore ); + check\-names ( fail | warn | ignore ); + check\-sibling boolean; + check\-spf ( warn | ignore ); + check\-srv\-cname ( fail | warn | ignore ); + check\-wildcard boolean; + database string; + delegation\-only boolean; + dialup ( notify | notify\-passive | passive | refresh | + boolean ); + dlz string; + dnskey\-sig\-validity integer; + dnssec\-dnskey\-kskonly boolean; + dnssec\-loadkeys\-interval integer; + dnssec\-policy string; + dnssec\-secure\-to\-insecure boolean; + dnssec\-update\-mode ( maintain | no\-resign ); + file quoted_string; + forward ( first | only ); + forwarders [ port integer ] [ dscp integer ] { ( + ipv4_address | ipv6_address ) [ port integer ] [ + dscp integer ]; ... }; + in\-view string; + inline\-signing boolean; + ixfr\-from\-differences boolean; + journal quoted_string; + key\-directory quoted_string; + masterfile\-format ( map | raw | text ); + masterfile\-style ( full | relative ); + masters [ port integer ] [ dscp integer ] { ( + remote\-servers | ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key string ]; + ... }; + max\-ixfr\-ratio ( unlimited | percentage ); + max\-journal\-size ( default | unlimited | sizeval ); + max\-records integer; + max\-refresh\-time integer; + max\-retry\-time integer; + max\-transfer\-idle\-in integer; + max\-transfer\-idle\-out integer; + max\-transfer\-time\-in integer; + max\-transfer\-time\-out integer; + max\-zone\-ttl ( unlimited | duration ); + min\-refresh\-time integer; + min\-retry\-time integer; + multi\-master boolean; + notify ( explicit | master\-only | primary\-only | boolean ); + notify\-delay integer; + notify\-source ( ipv4_address | * ) [ port ( integer | * + ) ] [ dscp integer ]; + notify\-source\-v6 ( ipv6_address | * ) [ port ( integer + | * ) ] [ dscp integer ]; + notify\-to\-soa boolean; + parental\-agents [ port integer ] [ dscp integer ] { ( + remote\-servers | ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key string ]; + ... }; + parental\-source ( ipv4_address | * ) [ port ( integer | + * ) ] [ dscp integer ]; + parental\-source\-v6 ( ipv6_address | * ) [ port ( + integer | * ) ] [ dscp integer ]; + primaries [ port integer ] [ dscp integer ] { ( + remote\-servers | ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key string ]; + ... }; + request\-expire boolean; + request\-ixfr boolean; + serial\-update\-method ( date | increment | unixtime ); + server\-addresses { ( ipv4_address | ipv6_address ); ... }; + server\-names { string; ... }; + sig\-signing\-nodes integer; + sig\-signing\-signatures integer; + sig\-signing\-type integer; + sig\-validity\-interval integer [ integer ]; + transfer\-source ( ipv4_address | * ) [ port ( integer | + * ) ] [ dscp integer ]; + transfer\-source\-v6 ( ipv6_address | * ) [ port ( + integer | * ) ] [ dscp integer ]; + try\-tcp\-refresh boolean; + type ( primary | master | secondary | slave | mirror | + delegation\-only | forward | hint | redirect | + static\-stub | stub ); + update\-check\-ksk boolean; + update\-policy ( local | { ( deny | grant ) string ( + 6to4\-self | external | krb5\-self | krb5\-selfsub | + krb5\-subdomain | ms\-self | ms\-selfsub | ms\-subdomain | + name | self | selfsub | selfwild | subdomain | tcp\-self + | wildcard | zonesub ) [ string ] rrtypelist; ... } ); + use\-alt\-transfer\-source boolean; + zero\-no\-soa\-ttl boolean; + zone\-statistics ( full | terse | none | boolean ); + }; + zone\-statistics ( full | terse | none | boolean ); +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.SS ZONE +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone string [ class ] { + allow\-notify { address_match_element; ... }; + allow\-query { address_match_element; ... }; + allow\-query\-on { address_match_element; ... }; + allow\-transfer { address_match_element; ... }; + allow\-update { address_match_element; ... }; + allow\-update\-forwarding { address_match_element; ... }; + also\-notify [ port integer ] [ dscp integer ] { ( + remote\-servers | ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key string ]; ... }; + alt\-transfer\-source ( ipv4_address | * ) [ port ( integer | * ) + ] [ dscp integer ]; + alt\-transfer\-source\-v6 ( ipv6_address | * ) [ port ( integer | + * ) ] [ dscp integer ]; + auto\-dnssec ( allow | maintain | off );// deprecated + check\-dup\-records ( fail | warn | ignore ); + check\-integrity boolean; + check\-mx ( fail | warn | ignore ); + check\-mx\-cname ( fail | warn | ignore ); + check\-names ( fail | warn | ignore ); + check\-sibling boolean; + check\-spf ( warn | ignore ); + check\-srv\-cname ( fail | warn | ignore ); + check\-wildcard boolean; + database string; + delegation\-only boolean; + dialup ( notify | notify\-passive | passive | refresh | boolean ); + dlz string; + dnskey\-sig\-validity integer; + dnssec\-dnskey\-kskonly boolean; + dnssec\-loadkeys\-interval integer; + dnssec\-policy string; + dnssec\-secure\-to\-insecure boolean; + dnssec\-update\-mode ( maintain | no\-resign ); + file quoted_string; + forward ( first | only ); + forwarders [ port integer ] [ dscp integer ] { ( ipv4_address + | ipv6_address ) [ port integer ] [ dscp integer ]; ... }; + in\-view string; + inline\-signing boolean; + ixfr\-from\-differences boolean; + journal quoted_string; + key\-directory quoted_string; + masterfile\-format ( map | raw | text ); + masterfile\-style ( full | relative ); + masters [ port integer ] [ dscp integer ] { ( remote\-servers + | ipv4_address [ port integer ] | ipv6_address [ port + integer ] ) [ key string ]; ... }; + max\-ixfr\-ratio ( unlimited | percentage ); + max\-journal\-size ( default | unlimited | sizeval ); + max\-records integer; + max\-refresh\-time integer; + max\-retry\-time integer; + max\-transfer\-idle\-in integer; + max\-transfer\-idle\-out integer; + max\-transfer\-time\-in integer; + max\-transfer\-time\-out integer; + max\-zone\-ttl ( unlimited | duration ); + min\-refresh\-time integer; + min\-retry\-time integer; + multi\-master boolean; + notify ( explicit | master\-only | primary\-only | boolean ); + notify\-delay integer; + notify\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + notify\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) ] + [ dscp integer ]; + notify\-to\-soa boolean; + parental\-agents [ port integer ] [ dscp integer ] { ( + remote\-servers | ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key string ]; ... }; + parental\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + parental\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) + ] [ dscp integer ]; + primaries [ port integer ] [ dscp integer ] { ( + remote\-servers | ipv4_address [ port integer ] | + ipv6_address [ port integer ] ) [ key string ]; ... }; + request\-expire boolean; + request\-ixfr boolean; + serial\-update\-method ( date | increment | unixtime ); + server\-addresses { ( ipv4_address | ipv6_address ); ... }; + server\-names { string; ... }; + sig\-signing\-nodes integer; + sig\-signing\-signatures integer; + sig\-signing\-type integer; + sig\-validity\-interval integer [ integer ]; + transfer\-source ( ipv4_address | * ) [ port ( integer | * ) ] [ + dscp integer ]; + transfer\-source\-v6 ( ipv6_address | * ) [ port ( integer | * ) + ] [ dscp integer ]; + try\-tcp\-refresh boolean; + type ( primary | master | secondary | slave | mirror | + delegation\-only | forward | hint | redirect | static\-stub | + stub ); + update\-check\-ksk boolean; + update\-policy ( local | { ( deny | grant ) string ( 6to4\-self | + external | krb5\-self | krb5\-selfsub | krb5\-subdomain | ms\-self + | ms\-selfsub | ms\-subdomain | name | self | selfsub | selfwild + | subdomain | tcp\-self | wildcard | zonesub ) [ string ] + rrtypelist; ... } ); + use\-alt\-transfer\-source boolean; + zero\-no\-soa\-ttl boolean; + zone\-statistics ( full | terse | none | boolean ); +}; +.ft P +.fi +.UNINDENT +.UNINDENT +.SH FILES +.sp +\fB/etc/named.conf\fP +.SH SEE ALSO +.sp +\fBddns\-confgen(8)\fP, \fBnamed(8)\fP, \fBnamed\-checkconf(8)\fP, \fBrndc(8)\fP, \fBrndc\-confgen(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.8in b/doc/man/nsec3hash.8in new file mode 100644 index 0000000..32d85d1 --- /dev/null +++ b/doc/man/nsec3hash.8in @@ -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 "NSEC3HASH" "8" "@RELEASE_DATE@" "@BIND9_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 \fBsalt\fP +This is the salt provided to the hash algorithm. +.TP +.B \fBalgorithm\fP +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. +.TP +.B \fBflags\fP +This is provided for compatibility with NSEC3 record presentation format, but +is ignored since the flags do not affect the hash. +.TP +.B \fBiterations\fP +This is the number of additional times the hash should be performed. +.TP +.B \fBdomain\fP +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..f009105 --- /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@" "@BIND9_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 \fBhost\fP using the current default server or +using \fBserver\fP, if specified. If \fBhost\fP is an Internet address and the +query type is A or PTR, the name of the host is returned. If \fBhost\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 +\fBdig(1)\fP, \fBhost(1)\fP, \fBnamed(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..5a2d02f --- /dev/null +++ b/doc/man/nsupdate.1in @@ -0,0 +1,385 @@ +.\" 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@" "@BIND9_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/etc/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. \fBddns\-confgen\fP can generate suitable +configuration fragments. \fBnsupdate\fP uses the \fB\-y\fP or \fB\-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 \fB\-g\fP flag. A non\-standards\-compliant variant of GSS\-TSIG +used by Windows 2000 can be switched on with the \fB\-o\fP flag. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-4\fP +This option sets use of IPv4 only. +.TP +.B \fB\-6\fP +This option sets use of IPv6 only. +.TP +.B \fB\-d\fP +This option sets debug mode, which provides tracing information about the update +requests that are made and the replies received from the name server. +.TP +.B \fB\-D\fP +This option sets extra debug mode. +.TP +.B \fB\-i\fP +This option forces interactive mode, even when standard input is not a terminal. +.TP +.B \fB\-k keyfile\fP +This option indicates the file containing the TSIG authentication key. Keyfiles may be in +two formats: a single file containing a \fBnamed.conf\fP\-format \fBkey\fP +statement, which may be generated automatically by \fBddns\-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 +\fBdnssec\-keygen\fP\&. The \fB\-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. +.TP +.B \fB\-l\fP +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/var/run/named/session.key\fP, which is automatically +generated by \fBnamed\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 \fB\-k\fP option. +.TP +.B \fB\-L level\fP +This option sets the logging debug level. If zero, logging is disabled. +.TP +.B \fB\-p port\fP +This option sets the port to use for connections to a name server. The default is +53. +.TP +.B \fB\-P\fP +This option prints the list of private BIND\-specific resource record types whose +format is understood by \fBnsupdate\fP\&. See also the \fB\-T\fP option. +.TP +.B \fB\-r udpretries\fP +This option sets the number of UDP retries. The default is 3. If zero, only one update +request is made. +.TP +.B \fB\-t timeout\fP +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. +.TP +.B \fB\-T\fP +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 \fB\-T\fP option can be combined with the \fB\-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, (<backslash> +<hash> <space> <length> <space> <hexstring>). +.TP +.B \fB\-u udptimeout\fP +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. +.TP +.B \fB\-v\fP +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. +.TP +.B \fB\-V\fP +This option prints the version number and exits. +.TP +.B \fB\-y [hmac:]keyname:secret\fP +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 \fB\-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 \fB\-y\fP or \fB\-k\fP\&. +.TP +.B \fBgsstsig\fP +This command uses GSS\-TSIG to sign the updates. This is equivalent to specifying +\fB\-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 \fB\-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 [yes_or_no]\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/var/run/named/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 \fBdnssec\-keygen\fP\&. +.TP +.B \fBK{name}.+157.+{random}.private\fP +Base\-64 encoding of the HMAC\-MD5 key created by \fBdnssec\-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, +\fBnamed(8)\fP, \fBddns\-confgen(8)\fP, \fBdnssec\-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/pkcs11-destroy.8in b/doc/man/pkcs11-destroy.8in new file mode 100644 index 0000000..be5941e --- /dev/null +++ b/doc/man/pkcs11-destroy.8in @@ -0,0 +1,74 @@ +.\" 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 "PKCS11-DESTROY" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9" +.SH NAME +pkcs11-destroy \- destroy PKCS#11 objects +pkcs11\-destroy \- destroy PKCS#11 objects +.sp +\fBpkcs11\-destroy\fP [\fB\-m\fP module] [\fB\-s\fP slot] [\fB\-i\fP ID] [\fB\-l\fP label] [\fB\-p\fP PIN] [\fB\-w\fP seconds] +.sp +\fBpkcs11\-destroy\fP destroys keys stored in a PKCS#11 device, identified +by their \fBID\fP or \fBlabel\fP\&. +.sp +Matching keys are displayed before being destroyed. By default, there is +a five\-second delay to allow the user to interrupt the process before +the destruction takes place. +.INDENT 0.0 +.TP +.B \fB\-m module\fP +This option specifies the PKCS#11 provider module. This must be the full path to a +shared library object implementing the PKCS#11 API for the device. +.TP +.B \fB\-s slot\fP +This option opens the session with the given PKCS#11 slot. The default is slot 0. +.TP +.B \fB\-i ID\fP +This option destroys keys with the given object ID. +.TP +.B \fB\-l label\fP +This option destroys keys with the given label. +.TP +.B \fB\-p PIN\fP +This option specifies the \fBPIN\fP for the device. If no \fBPIN\fP is provided on the command +line, \fBpkcs11\-destroy\fP prompts for it. +.TP +.B \fB\-w seconds\fP +This option specifies how long, in seconds, to pause before carrying out key destruction. The +default is 5 seconds. If set to \fB0\fP, destruction is +immediate. +.UNINDENT +.sp +\fBpkcs11\-keygen(8)\fP, \fBpkcs11\-list(8)\fP, \fBpkcs11\-tokens(8)\fP +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/pkcs11-destroy.rst b/doc/man/pkcs11-destroy.rst new file mode 100644 index 0000000..da48cef --- /dev/null +++ b/doc/man/pkcs11-destroy.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/pkcs11/pkcs11-destroy.rst diff --git a/doc/man/pkcs11-keygen.8in b/doc/man/pkcs11-keygen.8in new file mode 100644 index 0000000..8ea542e --- /dev/null +++ b/doc/man/pkcs11-keygen.8in @@ -0,0 +1,95 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "PKCS11-KEYGEN" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9" +.SH NAME +pkcs11-keygen \- generate keys on a PKCS#11 device +.SH SYNOPSIS +.sp +\fBpkcs11\-keygen\fP [\fB\-a\fP algorithm] [\fB\-b\fP keysize] [\fB\-e\fP] [\fB\-i\fP id] [\fB\-m\fP module] [\fB\-P\fP] [\fB\-p\fP PIN] [\fB\-q\fP] [\fB\-S\fP] [\fB\-s\fP slot] label +.SH DESCRIPTION +.sp +\fBpkcs11\-keygen\fP causes a PKCS#11 device to generate a new key pair +with the given \fBlabel\fP (which must be unique) and with \fBkeysize\fP +bits of prime. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-a algorithm\fP +This option specifies the key algorithm class: supported classes are RSA, DSA, DH, +ECC, and ECX. In addition to these strings, the \fBalgorithm\fP can be +specified as a DNSSEC signing algorithm to be used with this +key; for example, NSEC3RSASHA1 maps to RSA, ECDSAP256SHA256 maps to +ECC, and ED25519 to ECX. The default class is \fBRSA\fP\&. +.TP +.B \fB\-b keysize\fP +This option creates the key pair with \fBkeysize\fP bits of prime. For ECC keys, the +only valid values are 256 and 384, and the default is 256. For ECX +keys, the only valid values are 256 and 456, and the default is 256. +.TP +.B \fB\-e\fP +For RSA keys only, this option specifies use of a large exponent. +.TP +.B \fB\-i id\fP +This option creates key objects with \fBid\fP\&. The ID is either an unsigned short 2\-byte +or an unsigned long 4\-byte number. +.TP +.B \fB\-m module\fP +This option specifies the PKCS#11 provider module. This must be the full path to a +shared library object implementing the PKCS#11 API for the device. +.TP +.B \fB\-P\fP +This option sets the new private key to be non\-sensitive and extractable, and +allows the private key data to be read from the PKCS#11 device. The +default is for private keys to be sensitive and non\-extractable. +.TP +.B \fB\-p PIN\fP +This option specifies the \fBPIN\fP for the device. If no \fBPIN\fP is provided on the command +line, \fBpkcs11\-keygen\fP prompts for it. +.TP +.B \fB\-q\fP +This option sets quiet mode, which suppresses unnecessary output. +.TP +.B \fB\-S\fP +For Diffie\-Hellman (DH) keys only, this option specifies use of a special prime of 768\-, 1024\-, +or 1536\-bit size and base (AKA generator) 2. If not specified, bit +size defaults to 1024. +.TP +.B \fB\-s slot\fP +This option opens the session with the given PKCS#11 slot. The default is slot 0. +.UNINDENT +.SH SEE ALSO +.sp +\fBpkcs11\-destroy(8)\fP, \fBpkcs11\-list(8)\fP, \fBpkcs11\-tokens(8)\fP, \fBdnssec\-keyfromlabel(8)\fP +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/pkcs11-keygen.rst b/doc/man/pkcs11-keygen.rst new file mode 100644 index 0000000..ea392b6 --- /dev/null +++ b/doc/man/pkcs11-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/pkcs11/pkcs11-keygen.rst diff --git a/doc/man/pkcs11-list.8in b/doc/man/pkcs11-list.8in new file mode 100644 index 0000000..e833db7 --- /dev/null +++ b/doc/man/pkcs11-list.8in @@ -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 "PKCS11-LIST" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9" +.SH NAME +pkcs11-list \- list PKCS#11 objects +.sp +\fBpkcs11\-list\fP [\fB\-P\fP] [\fB\-m\fP module] [\fB\-s\fP slot] [\fB\-i\fP ID \fB] [\-l\fP label] [\fB\-p\fP PIN] +.SH DESCRIPTION +.sp +\fBpkcs11\-list\fP lists the PKCS#11 objects with \fBID\fP or \fBlabel\fP or, by +default, all objects. The object class, label, and ID are displayed for +all keys. For private or secret keys, the extractability attribute is +also displayed, as either \fBtrue\fP, \fBfalse\fP, or \fBnever\fP\&. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-P\fP +This option lists only the public objects. (Note that on some PKCS#11 devices, all +objects are private.) +.TP +.B \fB\-m module\fP +This option specifies the PKCS#11 provider module. This must be the full path to a +shared library object implementing the PKCS#11 API for the device. +.TP +.B \fB\-s slot\fP +This option opens the session with the given PKCS#11 slot. The default is slot 0. +.TP +.B \fB\-i ID\fP +This option lists only key objects with the given object ID. +.TP +.B \fB\-l label\fP +This option lists only key objects with the given label. +.TP +.B \fB\-p PIN\fP +This option specifies the \fBPIN\fP for the device. If no \fBPIN\fP is provided on the command +line, \fBpkcs11\-list\fP prompts for it. +.UNINDENT +.SH SEE ALSO +.sp +\fBpkcs11\-destroy(8)\fP, \fBpkcs11\-keygen(8)\fP, \fBpkcs11\-tokens(8)\fP +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/pkcs11-list.rst b/doc/man/pkcs11-list.rst new file mode 100644 index 0000000..a2eebef --- /dev/null +++ b/doc/man/pkcs11-list.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/pkcs11/pkcs11-list.rst diff --git a/doc/man/pkcs11-tokens.8in b/doc/man/pkcs11-tokens.8in new file mode 100644 index 0000000..4c29201 --- /dev/null +++ b/doc/man/pkcs11-tokens.8in @@ -0,0 +1,58 @@ +.\" 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 "PKCS11-TOKENS" "8" "@RELEASE_DATE@" "@BIND9_VERSION@" "BIND 9" +.SH NAME +pkcs11-tokens \- list PKCS#11 available tokens +.SH SYNOPSIS +.sp +\fBpkcs11\-tokens\fP [\fB\-m\fP module] [\fB\-v\fP] +.SH DESCRIPTION +.sp +\fBpkcs11\-tokens\fP lists the PKCS#11 available tokens with defaults from +the slot/token scan performed at application initialization. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-m module\fP +This option specifies the PKCS#11 provider module. This must be the full path to a +shared library object implementing the PKCS#11 API for the device. +.TP +.B \fB\-v\fP +This option makes the PKCS#11 libisc initialization verbose. +.UNINDENT +.SH SEE ALSO +.sp +\fBpkcs11\-destroy(8)\fP, \fBpkcs11\-keygen(8)\fP, \fBpkcs11\-list(8)\fP +.SH AUTHOR +Internet Systems Consortium +.SH COPYRIGHT +2023, Internet Systems Consortium +.\" Generated by docutils manpage writer. +. diff --git a/doc/man/pkcs11-tokens.rst b/doc/man/pkcs11-tokens.rst new file mode 100644 index 0000000..3c8129d --- /dev/null +++ b/doc/man/pkcs11-tokens.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/pkcs11/pkcs11-tokens.rst diff --git a/doc/man/rndc-confgen.8in b/doc/man/rndc-confgen.8in new file mode 100644 index 0000000..fb7f6aa --- /dev/null +++ b/doc/man/rndc-confgen.8in @@ -0,0 +1,119 @@ +.\" 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@" "@BIND9_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 \fBrndc\fP\&. It can be +used as a convenient alternative to writing the \fBrndc.conf\fP file and +the corresponding \fBcontrols\fP and \fBkey\fP statements in \fBnamed.conf\fP +by hand. Alternatively, it can be run with the \fB\-a\fP option to set up a +\fBrndc.key\fP file and avoid the need for a \fBrndc.conf\fP file and a +\fBcontrols\fP statement altogether. +.SH OPTIONS +.INDENT 0.0 +.TP +.B \fB\-a\fP +This option sets automatic \fBrndc\fP configuration, which creates a file \fBrndc.key\fP +in \fB/etc\fP (or a different \fBsysconfdir\fP specified when BIND +was built) that is read by both \fBrndc\fP and \fBnamed\fP on startup. +The \fBrndc.key\fP file defines a default command channel and +authentication key allowing \fBrndc\fP to communicate with \fBnamed\fP on +the local host with no further configuration. +.sp +If a more elaborate configuration than that generated by +\fBrndc\-confgen \-a\fP is required, for example if rndc is to be used +remotely, run \fBrndc\-confgen\fP without the \fB\-a\fP option +and set up \fBrndc.conf\fP and \fBnamed.conf\fP as directed. +.TP +.B \fB\-A algorithm\fP +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. +.TP +.B \fB\-b keysize\fP +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. +.TP +.B \fB\-c keyfile\fP +This option is used with the \fB\-a\fP option to specify an alternate location for +\fBrndc.key\fP\&. +.TP +.B \fB\-h\fP +This option prints a short summary of the options and arguments to +\fBrndc\-confgen\fP\&. +.TP +.B \fB\-k keyname\fP +This option specifies the key name of the \fBrndc\fP authentication key. This must be a +valid domain name. The default is \fBrndc\-key\fP\&. +.TP +.B \fB\-p port\fP +This option specifies the command channel port where \fBnamed\fP listens for +connections from \fBrndc\fP\&. The default is 953. +.TP +.B \fB\-s address\fP +This option specifies the IP address where \fBnamed\fP listens for command\-channel +connections from \fBrndc\fP\&. The default is the loopback address +127.0.0.1. +.TP +.B \fB\-t chrootdir\fP +This option is used with the \fB\-a\fP option to specify a directory where \fBnamed\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 \fBnamed\fP\&. +.TP +.B \fB\-u user\fP +This option is used with the \fB\-a\fP option to set the owner of the generated \fBrndc.key\fP file. +If \fB\-t\fP is also specified, only the file in the chroot +area has its owner changed. +.UNINDENT +.SH EXAMPLES +.sp +To allow \fBrndc\fP to be used with no manual configuration, run: +.sp +\fBrndc\-confgen \-a\fP +.sp +To print a sample \fBrndc.conf\fP file and the corresponding \fBcontrols\fP and +\fBkey\fP statements to be manually inserted into \fBnamed.conf\fP, run: +.sp +\fBrndc\-confgen\fP +.SH SEE ALSO +.sp +\fBrndc(8)\fP, \fBrndc.conf(5)\fP, \fBnamed(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..dba9922 --- /dev/null +++ b/doc/man/rndc.8in @@ -0,0 +1,627 @@ +.\" 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@" "@BIND9_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 key_id] [[\fB\-4\fP] | [\fB\-6\fP]] {command} +.SH DESCRIPTION +.sp +\fBrndc\fP controls the operation of a name server; it supersedes the +\fBndc\fP utility. 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 \fBnamed\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 key_id 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 \fB\-4\fP +This option indicates use of IPv4 only. +.TP +.B \fB\-6\fP +This option indicates use of IPv6 only. +.TP +.B \fB\-b source\-address\fP +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. +.TP +.B \fB\-c config\-file\fP +This option indicates \fBconfig\-file\fP as the configuration file instead of the default, +\fB/etc/rndc.conf\fP\&. +.TP +.B \fB\-k key\-file\fP +This option indicates \fBkey\-file\fP as the key file instead of the default, +\fB/etc/rndc.key\fP\&. The key in \fB/etc/rndc.key\fP is used to +authenticate commands sent to the server if the config\-file does not +exist. +.TP +.B \fB\-s server\fP +\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. +.TP +.B \fB\-p port\fP +This option instructs BIND 9 to send commands to TCP port \fBport\fP instead of its default control +channel port, 953. +.TP +.B \fB\-q\fP +This option sets quiet mode, where message text returned by the server is not printed +unless there is an error. +.TP +.B \fB\-r\fP +This option instructs \fBrndc\fP to print the result code returned by \fBnamed\fP +after executing the requested command (e.g., ISC_R_SUCCESS, +ISC_R_FAILURE, etc.). +.TP +.B \fB\-V\fP +This option enables verbose logging. +.TP +.B \fB\-y key_id\fP +This option indicates use of the key \fBkey_id\fP from the configuration file. For control message validation to succeed, \fBkey_id\fP must be known +by \fBnamed\fP with the same algorithm and secret string. If no \fBkey_id\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 \fBaddzone\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] \fIconfiguration\fP +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 \fBnamed.conf\fP\&. +.sp +The configuration is saved in a file called \fBviewname.nzf\fP (or, if +\fBnamed\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 \fBnamed\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 master; file \(dqexample.com.db\(dq; };\(aq\fP +.sp +(Note the brackets around and semi\-colon after the zone configuration +text.) +.sp +See also \fBrndc delzone\fP and \fBrndc modzone\fP\&. +.TP +\fBdelzone\fP [\fB\-clean\fP] \fIzone\fP [\fIclass\fP [\fIview\fP]] +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 +\fBnamed.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 +\fBnamed.conf\fP\&. +.sp +See also \fBrndc addzone\fP and \fBrndc modzone\fP\&. +.TP +\fBdnssec\fP ( \fB\-status\fP | \fB\-rollover\fP \fB\-key\fP id [\fB\-alg\fP \fIalgorithm\fP] [\fB\-when\fP \fItime\fP] | \fB\-checkds\fP [\fB\-key\fP \fIid\fP [\fB\-alg\fP \fIalgorithm\fP]] [\fB\-when\fP \fItime\fP] ( \fIpublished\fP | \fIwithdrawn\fP )) \fIzone\fP [\fIclass\fP [\fIview\fP]] +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 \fBnamed\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. +.TP +\fBdnstap\fP ( \fB\-reopen\fP | \fB\-roll\fP [\fInumber\fP] ) +This command closes and re\-opens DNSTAP output files. +.sp +\fBrndc dnstap \-reopen\fP allows +the output file to be renamed externally, so that \fBnamed\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. +.TP +\fBdumpdb\fP [\fB\-all\fP | \fB\-cache\fP | \fB\-zones\fP | \fB\-adb\fP | \fB\-bad\fP | \fB\-expired\fP | \fB\-fail\fP] [\fIview ...\fP] +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.) +.TP +.B \fBflush\fP +This command flushes the server\(aqs cache. +.TP +.B \fBflushname\fP \fIname\fP [\fIview\fP] +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. +.TP +.B \fBflushtree\fP \fIname\fP [\fIview\fP] +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. +.TP +.B \fBfreeze\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]] +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 \fBrndc thaw\fP\&. +.TP +\fBhalt\fP [\fB\-p\fP] +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, \fBnamed\fP\(aqs process ID is returned. This allows +an external process to determine when \fBnamed\fP has completed +halting. +.sp +See also \fBrndc stop\fP\&. +.TP +.B \fBloadkeys\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]] +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 \fBrndc 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.) +.TP +.B \fBmanaged\-keys\fP (\fIstatus\fP | \fIrefresh\fP | \fIsync\fP | \fIdestroy\fP) [\fIclass\fP [\fIview\fP]] +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 \fBnamed\fP is +restarted or reconfigured, and all existing key maintenance states +are deleted. +.sp +Running \fBrndc reconfig\fP or restarting \fBnamed\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 +.TP +.B \fBmodzone\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] \fIconfiguration\fP +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 \fBnamed.conf\fP\&. +.sp +If the zone was originally added via \fBrndc 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 \fBnamed.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 +\fBnamed.conf\fP\&. +.sp +See also \fBrndc addzone\fP and \fBrndc delzone\fP\&. +.TP +.B \fBnotify\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +This command resends NOTIFY messages for the zone. +.TP +.B \fBnotrace\fP +This command sets the server\(aqs debugging level to 0. +.sp +See also \fBrndc trace\fP\&. +.TP +\fBnta\fP [( \fB\-class\fP \fIclass\fP | \fB\-dump\fP | \fB\-force\fP | \fB\-remove\fP | \fB\-lifetime\fP \fIduration\fP)] \fIdomain\fP [\fIview\fP] +This command sets a DNSSEC negative trust anchor (NTA) for \fBdomain\fP, with a +lifetime of \fBduration\fP\&. The default lifetime is configured in +\fBnamed.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), \fBnamed\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 \fBnamed\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, \fBnamed\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. +.TP +.B \fBquerylog\fP [(\fIon\fP | \fIoff\fP)] +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 \fBnamed.conf\fP, or by specifying \fBquerylog yes;\fP in the +\fBoptions\fP section of \fBnamed.conf\fP\&. +.TP +.B \fBreconfig\fP +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 \fBreload\fP when there is a large number of zones, because it +avoids the need to examine the modification times of the zone files. +.TP +.B \fBrecursing\fP +This command dumps the list of queries \fBnamed\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). +.TP +.B \fBrefresh\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +This command schedules zone maintenance for the given zone. +.TP +.B \fBreload\fP +This command reloads the configuration file and zones. +.TP +.B \fBreload\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +This command reloads the given zone. +.TP +.B \fBretransfer\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +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. +.TP +.B \fBscan\fP +This command scans the list of available network interfaces for changes, without +performing a full \fBreconfig\fP or waiting for the +\fBinterface\-interval\fP timer. +.TP +\fBsecroots\fP [\fB\-\fP] [\fIview\fP ...] +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 \fBnamed.conf\fP\&. +.sp +See also \fBrndc managed\-keys\fP\&. +.TP +\fBserve\-stale\fP (\fBon\fP | \fBoff\fP | \fBreset\fP | \fBstatus\fP) [\fIclass\fP [\fIview\fP]] +This command enables, disables, resets, or reports the current status of the serving +of stale answers as configured in \fBnamed.conf\fP\&. +.sp +If serving of stale answers is disabled by \fBrndc\-serve\-stale off\fP, +then it remains disabled even if \fBnamed\fP is reloaded or +reconfigured. \fBrndc serve\-stale reset\fP restores the setting as +configured in \fBnamed.conf\fP\&. +.sp +\fBrndc serve\-stale status\fP reports whether serving of stale +answers is currently enabled, disabled by the configuration, or +disabled by \fBrndc\fP\&. It also reports the values of +\fBstale\-answer\-ttl\fP and \fBmax\-stale\-ttl\fP\&. +.TP +.B \fBshowzone\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +This command prints the configuration of a running zone. +.sp +See also \fBrndc zonestatus\fP\&. +.TP +.B \fBsign\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +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 \fBrndc loadkeys\fP\&. +.TP +\fBsigning\fP [(\fB\-list\fP | \fB\-clear\fP \fIkeyid/algorithm\fP | \fB\-clear\fP \fIall\fP | \fB\-nsec3param\fP ( \fIparameters\fP | none ) | \fB\-serial\fP \fIvalue\fP ) \fIzone\fP [\fIclass\fP [\fIview\fP]] +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 \fBnamed\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. +.TP +.B \fBstats\fP +This command writes server statistics to the statistics file. (See the +\fBstatistics\-file\fP option in the BIND 9 Administrator Reference +Manual.) +.TP +.B \fBstatus\fP +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. +.TP +\fBstop\fP \fB\-p\fP +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, \fBnamed(8)\(ga\(aqs process ID is returned. +This allows an external process to determine when \(ga\(ganamed\fP has +completed stopping. +.sp +See also \fBrndc halt\fP\&. +.TP +\fBsync\fP \fB\-clean\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]] +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. +.TP +.B \fBtcp\-timeouts\fP [\fIinitial\fP \fIidle\fP \fIkeepalive\fP \fIadvertised\fP] +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. +.TP +.B \fBthaw\fP [\fIzone\fP [\fIclass\fP [\fIview\fP]]] +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 \fBrndc freeze\fP\&. +.TP +.B \fBtrace\fP +This command increments the server\(aqs debugging level by one. +.TP +.B \fBtrace\fP \fIlevel\fP +This command sets the server\(aqs debugging level to an explicit value. +.sp +See also \fBrndc notrace\fP\&. +.TP +.B \fBtsig\-delete\fP \fIkeyname\fP [\fIview\fP] +This command deletes a given TKEY\-negotiated key from the server. This does not +apply to statically configured TSIG keys. +.TP +.B \fBtsig\-list\fP +This command lists the names of all TSIG keys currently configured for use by +\fBnamed\fP in each view. The list includes both statically configured keys and +dynamic TKEY\-negotiated keys. +.TP +\fBvalidation\fP (\fBon\fP | \fBoff\fP | \fBstatus\fP) [\fIview\fP ...]\(ga\(ga +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. +.TP +.B \fBzonestatus\fP \fIzone\fP [\fIclass\fP [\fIview\fP]] +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 \fBrndc showzone\fP\&. +.UNINDENT +.sp +\fBrndc\fP commands that specify zone names, such as \fBreload\fP, +\fBretransfer\fP, or \fBzonestatus\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 \fBkey_id\fP +without using the configuration file. +.sp +Several error messages could be clearer. +.SH SEE ALSO +.sp +\fBrndc.conf(5)\fP, \fBrndc\-confgen(8)\fP, +\fBnamed(8)\fP, \fBnamed.conf(5)\fP, \fBndc(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.conf.5in b/doc/man/rndc.conf.5in new file mode 100644 index 0000000..54a0847 --- /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@" "@BIND9_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 \fBrndc\fP, the BIND 9 name +server control utility. This file has a similar structure and syntax to +\fBnamed.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 \fBnamed.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 \fBrndc\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 \fBrndc\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 \fBrndc\-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, \fBrndc\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 \fBrndc \-s testserver\fP is used, then \fBrndc\fP connects to the server +on localhost port 5353 using the key \(dqtestkey\(dq. +.sp +To generate a random secret with \fBrndc\-confgen\fP: +.sp +\fBrndc\-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 \fBnamed.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 \fBnamed.conf\fP\&. See the sections on the +\fBcontrols\fP statement in the BIND 9 Administrator Reference Manual for +details. +.SH SEE ALSO +.sp +\fBrndc(8)\fP, \fBrndc\-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..e094902 --- /dev/null +++ b/doc/man/tsig-keygen.8in @@ -0,0 +1,64 @@ +.\" 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@" "@BIND9_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 \fBrndc\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 \fB\-a algorithm\fP +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. +.TP +.B \fB\-h\fP +This option prints a short summary of options and arguments. +.UNINDENT +.SH SEE ALSO +.sp +\fBnsupdate(1)\fP, \fBnamed.conf(5)\fP, \fBnamed(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 |