upstream/bind9
1
0
Fork 0
mirror of https://github.com/isc-projects/bind9.git synced 2026-04-29 18:09:11 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
bind9/bin/named/named.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

226 lines
7.5 KiB
ReStructuredText
Raw Normal View History

Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
..
.. SPDX-License-Identifier: MPL-2.0
Update the copyright information in all files in the repository This commit converts the license handling to adhere to the REUSE specification. It specifically: 1. Adds used licnses to LICENSES/ directory 2. Add "isc" template for adding the copyright boilerplate 3. Changes all source files to include copyright and SPDX license header, this includes all the C sources, documentation, zone files, configuration files. There are notes in the doc/dev/copyrights file on how to add correct headers to the new files. 4. Handle the rest that can't be modified via .reuse/dep5 file. The binary (or otherwise unmodifiable) files could have license places next to them in <foo>.license file, but this would lead to cluttered repository and most of the files handled in the .reuse/dep5 file are system test files.
2021-06-03 02:37:05 -04:00
..
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
.. 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/.
Update the copyright information in all files in the repository This commit converts the license handling to adhere to the REUSE specification. It specifically: 1. Adds used licnses to LICENSES/ directory 2. Add "isc" template for adding the copyright boilerplate 3. Changes all source files to include copyright and SPDX license header, this includes all the C sources, documentation, zone files, configuration files. There are notes in the doc/dev/copyrights file on how to add correct headers to the new files. 4. Handle the rest that can't be modified via .reuse/dep5 file. The binary (or otherwise unmodifiable) files could have license places next to them in <foo>.license file, but this would lead to cluttered repository and most of the files handled in the .reuse/dep5 file are system test files.
2021-06-03 02:37:05 -04:00
..
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
.. See the COPYRIGHT file distributed with this work for additional
.. information regarding copyright ownership.
.. highlight: console
Introduce new Sphinx role iscman for ISC manual pages The new directive and role "iscman" allow to tag & reference man pages in our source tree. Essentially it is just namespacing for ISC man pages, but it comes with couple benefits. Differences from .. _man_program label we formerly used: - Does not expand :ref:`man_program` into full text of the page header. - Generates index entry with category "manual page". - Rendering style is closer to ubiquitous to the one produced by ``named`` syntax. Differences from Sphinx built-in :manpage: role: - Supports all builders with support for cross-references. - Generates internal links (unlike :manpage: which generates external URLs). - Checks that target exists withing our source tree.
2022-03-03 09:32:35 -05:00
.. iscman:: named
Add semantic markup for program names into manual pages It allows to cross-reference options in man pages from other documents using :option:`named -g` syntax.
2022-03-02 10:36:34 -05:00
.. program:: named
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
.. _man_named:
named - Internet domain name server
-----------------------------------
Synopsis
~~~~~~~~
Remove OpenSSL Engine support The OpenSSL 1.x Engines support has been deprecated in the OpenSSL 3.x and is going to be removed. Remove the OpenSSL Engine support in favor of OpenSSL Providers.
2024-08-05 05:40:42 -04:00
:program:`named` [ [**-4**] | [**-6**] ] [**-c** config-file] [**-C**] [**-d** debug-level] [**-D** string] [**-f**] [**-g**] [**-L** logfile] [**-M** option] [**-m** flag] [**-n** #cpus] [**-p** port] [**-s**] [**-t** directory] [**-u** user] [**-v**] [**-V**] ]
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Description
~~~~~~~~~~~
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
:program:`named` is a Domain Name System (DNS) server, part of the BIND 9
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
distribution from ISC. For more information on the DNS, see :rfc:`1033`,
:rfc:`1034`, and :rfc:`1035`.
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
When invoked without arguments, :program:`named` reads the default
Use compile-time paths in the manual pages Replace the hard-coded paths for various BIND 9 files (configuration, pid, etc.) in the man pages and ARM with compile-time values using the sphinx-build replace system. This is more complicated, because the restructured text specification doesn't allow |substitions| inside ``code-blocks``, so for each specific file we had to create own substition which is sub-optimal, but it is only way how to do this without adding Sphinx extension.
2022-01-24 06:13:24 -05:00
configuration file |named_conf|, reads any initial data, and
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
listens for queries.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Options
~~~~~~~
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -4
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
This option tells :program:`named` to use only IPv4, even if the host machine is capable of IPv6. :option:`-4` and
Add hyperlinks from program options to definition in man pages Side-effect of hyperlinking is that typos in program and option names are now detected by Sphinx. Candidate -options were detected using: find -name *.rst | xargs grep '``-[^`]' and then modified from ``-o`` to :option:`-o` using regex s/``\(-[^`]\+\)``/:option:`\1`/ + manual modifications where necessary. Non-hyphenated options were detected by looking at context around program names: find bin -name *.rst | xargs -I{} -n1 basename {} .rst | sort -u and grepping for program name with trailing whitespace. Stand-alone program names like ``named`` are not hyperlinked in this commit.
2022-03-02 10:54:31 -05:00
:option:`-6` are mutually exclusive.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -6
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
This option tells :program:`named` to use only IPv6, even if the host machine is capable of IPv4. :option:`-4` and
Add hyperlinks from program options to definition in man pages Side-effect of hyperlinking is that typos in program and option names are now detected by Sphinx. Candidate -options were detected using: find -name *.rst | xargs grep '``-[^`]' and then modified from ``-o`` to :option:`-o` using regex s/``\(-[^`]\+\)``/:option:`\1`/ + manual modifications where necessary. Non-hyphenated options were detected by looking at context around program names: find bin -name *.rst | xargs -I{} -n1 basename {} .rst | sort -u and grepping for program name with trailing whitespace. Stand-alone program names like ``named`` are not hyperlinked in this commit.
2022-03-02 10:54:31 -05:00
:option:`-6` are mutually exclusive.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -c config-file
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
This option tells :program:`named` to use ``config-file`` as its configuration file instead of the default,
Use compile-time paths in the manual pages Replace the hard-coded paths for various BIND 9 files (configuration, pid, etc.) in the man pages and ARM with compile-time values using the sphinx-build replace system. This is more complicated, because the restructured text specification doesn't allow |substitions| inside ``code-blocks``, so for each specific file we had to create own substition which is sub-optimal, but it is only way how to do this without adding Sphinx extension.
2022-01-24 06:13:24 -05:00
|named_conf|. To ensure that the configuration file
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
can be reloaded after the server has changed its working directory
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
due to to a possible ``directory`` option in the configuration file,
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
``config-file`` should be an absolute pathname.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Export built-in default configuration for named binary It might be useful to display built-in configuration with all its values. It should make it easier to test what default values has changed in a new release. Related: #1326
2022-03-23 07:52:33 -04:00
.. option:: -C
This option prints out the default built-in configuration and exits.
NOTE: This is for debugging purposes only and is not an
accurate representation of the actual configuration used by :iscman:`named`
at runtime.
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -d debug-level
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
This option sets the daemon's debug level to ``debug-level``. Debugging traces from
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
:program:`named` become more verbose as the debug level increases.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -D string
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
This option specifies a string that is used to identify a instance of :program:`named`
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
in a process listing. The contents of ``string`` are not examined.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -f
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
This option runs the server in the foreground (i.e., do not daemonize).
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Allow FIPS mode to be enabled at run time in named If FIPS mode is supported by the OS 'named -F' will turn on FIPS mode.
2022-06-29 00:10:06 -04:00
.. option:: -F
This options turns on FIPS (US Federal Information Processing Standards)
mode if the underlying crytographic library supports running in FIPS
mode.
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -g
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
This option runs the server in the foreground and forces all logging to ``stderr``.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -L logfile
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
This option sets the log to the file ``logfile`` by default, instead of the system log.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -M option
Update documentation for named's -M option Remove "external" from the list of legal values for the -M command-line option as it has not been allowed since the internal memory allocator was removed by commit 55ace5d3aa4cb8c1b70a94679e1dd6d716dfd8bb. Make the style of the relevant paragraph more in line with the next one and split its contents up into an unordered list of options for improved readability.
2022-07-15 04:23:03 -04:00
This option sets the default (comma-separated) memory context
options. The possible flags are:
- ``fill``: 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 :program:`named` has been compiled with
``--enable-developer``.
- ``nofill``: disable the behavior enabled by ``fill``; this is the
implicit default unless :program:`named` has been compiled with
``--enable-developer``.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -m flag
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
This option turns on memory usage debugging flags. Possible flags are ``usage``,
Finalize removal of memory debug flags size and mctx Commit 4b3d0c66009d30f5c0bc12ee128fc59f1d853f44 has removed them, but did not remove few traces in documentation and help. Remove them from remaining places.
2024-10-09 09:32:07 -04:00
``trace`` and ``record``. These correspond to the
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
``ISC_MEM_DEBUGXXXX`` flags described in ``<isc/mem.h>``.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -n #cpus
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
This option creates ``#cpus`` worker threads to take advantage of multiple CPUs. If
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
not specified, :program:`named` tries to determine the number of CPUs
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
present and creates one thread per CPU. If it is unable to determine
the number of CPUs, a single worker thread is created.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -p value
DoT test Preliminary test for DNSoverTLS - add the dot-port template to system tests, test a simple query to an authoritative.
2020-10-12 17:06:55 -04:00
This option specifies the port(s) on which the server will listen
for queries. If ``value`` is of the form ``<portnum>`` or
``dns=<portnum>``, the server will listen for DNS queries on
``portnum``; if not not specified, the default is port 53. If
``value`` is of the form ``tls=<portnum>``, the server will
listen for TLS queries on ``portnum``; the default is 853.
Add parser support for DoH configuration options This commit adds stub parser support and tests for: - an "http" global option for HTTP/2 endpoint configuration. - command line options to set http or https port numbers by specifying -p http=PORT or -p https=PORT. (NOTE: this change only affects syntax; specifying HTTP and HTTPS ports on the command line currently has no effect.) - named.conf options "http-port" and "https-port" - HTTPSPORT environment variable for use when running tests.
2020-09-16 15:21:32 -04:00
If ``value`` is of the form ``https=<portnum>``, the server will
listen for HTTPS queries on ``portnum``; the default is 443.
Initial support for DNS-over-HTTP(S) This commit completes the support for DNS-over-HTTP(S) built on top of nghttp2 and plugs it into the BIND. Support for both GET and POST requests is present, as required by RFC8484. Both encrypted (via TLS) and unencrypted HTTP/2 connections are supported. The latter are mostly there for debugging/troubleshooting purposes and for the means of encryption offloading to third-party software (as might be desirable in some environments to simplify TLS certificates management).
2020-12-07 07:19:10 -05:00
If ``value`` is of the form ``http=<portnum>``, the server will
listen for HTTP queries on ``portnum``; the default is 80.
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -s
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
This option writes memory usage statistics to ``stdout`` on exit.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
.. note::
This option is mainly of interest to BIND 9 developers and may be
removed or changed in a future release.
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -t directory
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
This option tells :program:`named` to chroot to ``directory`` after processing the command-line arguments, but
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
before reading the configuration file.
.. warning::
Add hyperlinks from program options to definition in man pages Side-effect of hyperlinking is that typos in program and option names are now detected by Sphinx. Candidate -options were detected using: find -name *.rst | xargs grep '``-[^`]' and then modified from ``-o`` to :option:`-o` using regex s/``\(-[^`]\+\)``/:option:`\1`/ + manual modifications where necessary. Non-hyphenated options were detected by looking at context around program names: find bin -name *.rst | xargs -I{} -n1 basename {} .rst | sort -u and grepping for program name with trailing whitespace. Stand-alone program names like ``named`` are not hyperlinked in this commit.
2022-03-02 10:54:31 -05:00
This option should be used in conjunction with the :option:`-u` option,
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
as chrooting a process running as root doesn't enhance security on
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
most systems; the way ``chroot`` is defined allows a process
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
with root privileges to escape a chroot jail.
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -U #listeners
Properly document that named -U <n> is no-op now We don't create <n> UDP dispatches anymore and -U <n> option to named is a no-op for a while. Properly document that in the named man page.
2024-04-24 07:55:11 -04:00
This option has been removed. Attempts to use it now result in a warning.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -u user
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
This option sets the setuid to ``user`` after completing privileged operations, such as
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
creating sockets that listen on privileged ports.
.. note::
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
On Linux, :program:`named` uses the kernel's capability mechanism to drop
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
all root privileges except the ability to ``bind`` to a
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
privileged port and set process resource limits. Unfortunately,
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
this means that the :option:`-u` option only works when :program:`named` is run
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
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
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
``setuid``.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -v
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
This option reports the version number and exits.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -V
Document list of crypto algorithms in named -V output
2022-09-27 09:10:58 -04:00
This option reports the version number, build options, supported
cryptographics algorithms, and exits.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Denote all command line options using semantic markup (.. option::) The markup allows referencing individual options, and also makes them more legible (no more thin red text on gray background). Most of the work was done using regexes: s/^``-\(.*\)``$/.. option:: -\1\r/ s/^``+\(.*\)``$/.. option:: +\1\r/ on bin/**/*.rst files along with visual inspection and hand-edits, mostly for positional arguments. Regex for rndc.rst: s/^``\(.*\)``/.. option:: \1\r/ + hand edits to remove extra asterisk and whitespace here and there.
2022-03-02 09:12:17 -05:00
.. option:: -X lock-file
Remove the lock-file configuration and -X argument to named The lock-file configuration (both from configuration file and -X argument to named) has better alternatives nowadays. Modern process supervisor should be used to ensure that a single named process is running on a given configuration. Alternatively, it's possible to wrap the named with flock(1).
2023-10-26 05:55:54 -04:00
This option has been removed and using it will cause a fatal error.
Mark the lock-file configuration option as deprecated This is first step in removing the lock-file configuration option, it marks both the `lock-file` configuration directive and -X option to named as deprecated.
2023-10-26 05:08:49 -04:00
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Signals
~~~~~~~
In routine operation, signals should not be used to control the
Hyperlink program names to their manual pages Use the new role :iscman: to replace all occurences or ``binary`` with :iscman:`binary`, creating a hyperlink to the manual page. Generated using: find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done Additional hand-edits were done mainly around filter-aaaa and filter-a which are program names and and option names at the same time. Couple more edits was neede to fix .rst syntax broken by automatic replacement.
2022-03-03 16:17:04 -05:00
nameserver; :iscman:`rndc` should be used instead.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
SIGHUP
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
This signal forces a reload of the server.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
SIGINT, SIGTERM
Text edits to manual paages This commit updates the wording in following man pages: * ddns-confgen.rst * delv.rst * dig.rst * dnssec-dsfromkey.rst * dnssec-importkey.rst * dnssec-keyfromlabel.rst * dnssec-keygen.rst * dnssec-revoke.rst * dnssec-settime.rst * dnssec-signzone.rst * dnssec-verify.rst * dnstap-read.rst * filter-aaaa.rst * host.rst * mdig.rst * named-checkconf.rst * named-checkzone.rst * named-nzd2nzf.rst * named.conf.rst * named.rst * nsec3hash.rst * nsupdate.rst * pkcs11-destroy.rst * pkcs11-keygen.rst * pkcs11-list.rst * pkcs11-tokens.rst * rndc-confgen.rst * rndc.rst
2020-06-03 20:24:08 -04:00
These signals shut down the server.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
The result of sending any other signals to the server is undefined.
Configuration
~~~~~~~~~~~~~
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
The :program:`named` configuration file is too complex to describe in detail
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
here. A complete description is provided in the BIND 9 Administrator
Reference Manual.
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
:program:`named` inherits the ``umask`` (file creation mode mask) from the
parent process. If files created by :program:`named`, such as journal files,
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
need to have custom permissions, the ``umask`` should be set explicitly
Use semantic markup for :program: self-references Sphinx has it's own :program: syntax for refering to program names. Use it for self-references in manual pages. These self-references are not clickable and not as eye-cathing as links, which is a good thing. There is no point in attracting attention to ``dig`` several times on a single page dedicated to dig itself. Substituted automatically using: find bin -name *.rst | xargs fgrep --files-with-matches '.. program' | xargs -n1 bash /tmp/repl.sh With /tmp/repl.sh being: BASE=$(basename "$1" .rst) sed -i -e "s/\`\`$BASE\`\`/:program:\`$BASE\`/g" "$1"
2022-03-03 10:00:43 -05:00
in the script used to start the :program:`named` process.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
Files
~~~~~
Use compile-time paths in the manual pages Replace the hard-coded paths for various BIND 9 files (configuration, pid, etc.) in the man pages and ARM with compile-time values using the sphinx-build replace system. This is more complicated, because the restructured text specification doesn't allow |substitions| inside ``code-blocks``, so for each specific file we had to create own substition which is sub-optimal, but it is only way how to do this without adding Sphinx extension.
2022-01-24 06:13:24 -05:00
|named_conf|
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
The default configuration file.
Use compile-time paths in the manual pages Replace the hard-coded paths for various BIND 9 files (configuration, pid, etc.) in the man pages and ARM with compile-time values using the sphinx-build replace system. This is more complicated, because the restructured text specification doesn't allow |substitions| inside ``code-blocks``, so for each specific file we had to create own substition which is sub-optimal, but it is only way how to do this without adding Sphinx extension.
2022-01-24 06:13:24 -05:00
|named_pid|
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 06:49:47 -04:00
The default process-id file.
See Also
~~~~~~~~
Add internal hyperlinks to See Also section of manual pages Replace :manpage: with :iscman: to generate internal hyperlinks. That way reader can use links even when offline, and jumps to man pages for the same version. Formerly HTML version of man pages did not have links in See Also section because :manpage: role in Sphinx can generate only external hyperlinks - and we do not have that enabled. Enabling the Sphinx :manpage: linking could reliably create hyperlinks only to external URLs, but that would take users to another version of docs. Generated by: find bin -name '*.rst' | xargs sed -i -e 's/:manpage:`\([^(]\+\)(\([0-9]\))`/:iscman:`\1(\2) <\1>`/g' + hand-edit to revert change for mmencode reference which is not provided in our source tree.
2022-03-04 07:10:25 -05:00
:rfc:`1033`, :rfc:`1034`, :rfc:`1035`, :iscman:`named-checkconf(8) <named-checkconf>`, :iscman:`named-checkzone(8) <named-checkzone>`, :iscman:`rndc(8) <rndc>`, :iscman:`named.conf(5) <named.conf>`, BIND 9 Administrator Reference Manual.
Reference in a new issue Copy permalink