diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 15:59:48 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 15:59:48 +0000 |
commit | 3b9b6d0b8e7f798023c9d109c490449d528fde80 (patch) | |
tree | 2e1c188dd7b8d7475cd163de9ae02c428343669b /doc/arm/dns-ops.inc.rst | |
parent | Initial commit. (diff) | |
download | bind9-3b9b6d0b8e7f798023c9d109c490449d528fde80.tar.xz bind9-3b9b6d0b8e7f798023c9d109c490449d528fde80.zip |
Adding upstream version 1:9.18.19.upstream/1%9.18.19upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | doc/arm/dns-ops.inc.rst | 243 |
1 files changed, 243 insertions, 0 deletions
diff --git a/doc/arm/dns-ops.inc.rst b/doc/arm/dns-ops.inc.rst new file mode 100644 index 0000000..abb6bcf --- /dev/null +++ b/doc/arm/dns-ops.inc.rst @@ -0,0 +1,243 @@ +.. 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. + +.. _ns_operations: + +Name Server Operations +---------------------- + +.. _tools: + +Tools for Use With the Name Server Daemon +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes several indispensable diagnostic, administrative, +and monitoring tools available to the system administrator for +controlling and debugging the name server daemon. + +.. _diagnostic_tools: + +Diagnostic Tools +^^^^^^^^^^^^^^^^ + +The :iscman:`dig`, :iscman:`host`, and :iscman:`nslookup` programs are all command-line +tools for manually querying name servers. They differ in style and +output format. + +:iscman:`dig` + :iscman:`dig` is the most versatile and complete of these lookup tools. It + has two modes: simple interactive mode for a single query, and batch + mode, which executes a query for each in a list of several query + lines. All query options are accessible from the command line. + + For more information and a list of available commands and options, + see :ref:`man_dig`. + +:iscman:`host` + The :iscman:`host` utility emphasizes simplicity and ease of use. By + default, it converts between host names and Internet addresses, but + its functionality can be extended with the use of options. + + For more information and a list of available commands and options, + see :ref:`man_host`. + +:iscman:`nslookup` + :iscman:`nslookup` 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 is used to print just the + name and requested information for a host or domain. + + Due to its arcane user interface and frequently inconsistent + behavior, we do not recommend the use of :iscman:`nslookup`. Use :iscman:`dig` + instead. + +.. _admin_tools: + +Administrative Tools +^^^^^^^^^^^^^^^^^^^^ + +Administrative tools play an integral part in the management of a +server. + +:iscman:`named-checkconf` + The :iscman:`named-checkconf` program checks the syntax of a :iscman:`named.conf` + file. + + For more information and a list of available commands and options, + see :ref:`man_named-checkconf`. + +:iscman:`named-checkzone` + The :iscman:`named-checkzone` program checks a zone file for syntax and + consistency. + + For more information and a list of available commands and options, + see :ref:`man_named-checkzone`. + +:iscman:`named-compilezone` + This tool is similar to :iscman:`named-checkzone` but it always dumps the zone content + to a specified file (typically in a different format). + + For more information and a list of available commands and options, + see :ref:`man_named-compilezone`. + +.. _ops_rndc: + +:iscman:`rndc` + The remote name daemon control (:iscman:`rndc`) program allows the system + administrator to control the operation of a name server. + + See :ref:`man_rndc` for details of the available :iscman:`rndc` + commands. + + :iscman:`rndc` requires a configuration file, since all communication with + the server is authenticated with digital signatures that rely on a + shared secret, and there is no way to provide that secret other than + with a configuration file. The default location for the :iscman:`rndc` + configuration file is |rndc_conf|, but an alternate location + can be specified with the :option:`-c <rndc -c>` option. If the configuration file is + not found, :iscman:`rndc` also looks in |rndc_key| (or whatever + ``sysconfdir`` was defined when the BIND build was configured). The + ``rndc.key`` file is generated by running :option:`rndc-confgen -a` as + described in :any:`controls`. + + The format of the configuration file is similar to that of + :iscman:`named.conf`, but is limited to only three blocks: the :rndcconf:ref:`options`, + :rndcconf:ref:`key`, :rndcconf:ref:`server`, and the :ref:`include_grammar`. These blocks are + what associate the secret keys to the servers with which they are + meant to be shared. The order of blocks is not significant. + +.. rndcconf:statement:: options + + .. rndcconf:statement:: default-server + + :any:`default-server` takes a + host name or address argument and represents the server that is + contacted if no :option:`-s <rndc -s>` option is provided on the command line. + + .. rndcconf:statement:: default-key + + :any:`default-key` takes the name of a key as its argument, as defined + by a :rndcconf:ref:`key` block. + + .. rndcconf:statement:: default-port + + :any:`default-port` specifies the port to which + :iscman:`rndc` should connect if no port is given on the command line or in + a :rndcconf:ref:`server` block. + + .. rndcconf:statement:: default-source-address + .. rndcconf:statement:: default-source-address-v6 + + :any:`default-source-address` and :any:`default-source-address-v6` specify + the IPv4 and IPv6 source address used to communicate with the server + if no address is given on the command line or in a + :rndcconf:ref:`server` block. + +.. rndcconf:statement:: key + + The :rndcconf:ref:`key` block defines a key to be used by :iscman:`rndc` when + authenticating with :iscman:`named`. Its syntax is identical to the :namedconf:ref:`key` + statement in :iscman:`named.conf`. The keyword :rndcconf:ref:`key` is followed by a key + name, which must be a valid domain name, though it need not actually + be hierarchical; thus, a string like ``rndc_key`` is a valid name. + The :rndcconf:ref:`key` block has two statements: :rndcconf:ref:`algorithm` and :rndcconf:ref:`secret`. + + .. rndcconf:statement:: algorithm + + While the configuration parser accepts any string as the argument + to :rndcconf:ref:`algorithm`, currently only the strings ``hmac-md5``, + ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, + ``hmac-sha384``, and ``hmac-sha512`` have any meaning. + + .. rndcconf:statement:: secret + + The secret + is a Base64-encoded string as specified in :rfc:`3548`. + +.. rndcconf:statement:: server + + The :rndcconf:ref:`server` block specifies connection parameters for a given server. + The server can be specified as a host name or address. + + .. rndcconf:statement:: addresses + + Specifies one or more addresses to use when communicating with this + server. + + :rndcconf:ref:`key` + Associates a key defined using the :rndcconf:ref:`key` statement with a + server. + + .. rndcconf:statement:: port + + Specifes the port :iscman:`rndc` should connect to on the server. + + .. rndcconf:statement:: source-address + .. rndcconf:statement:: source-address-v6 + + Overrides :rndcconf:ref:`default-source-address` and + :rndcconf:ref:`default-source-address-v6` for this specific server. + + A sample minimal configuration file is as follows: + + :: + + key rndc_key { + algorithm "hmac-sha256"; + secret + "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K"; + }; + options { + default-server 127.0.0.1; + default-key rndc_key; + }; + + This file, if installed as |rndc_conf|, allows the + command: + + :option:`rndc reload` + + to connect to 127.0.0.1 port 953 and causes the name server to reload, + if a name server on the local machine is running with the following + controls statements: + + :: + + controls { + inet 127.0.0.1 + allow { localhost; } keys { rndc_key; }; + }; + + and it has an identical key block for ``rndc_key``. + + Running the :iscman:`rndc-confgen` program conveniently creates an + :iscman:`rndc.conf` file, and also displays the corresponding + :any:`controls` statement needed to add to :iscman:`named.conf`. + Alternatively, it is possible to run :option:`rndc-confgen -a` to set up an + ``rndc.key`` file and not modify :iscman:`named.conf` at all. + +Signals +~~~~~~~ + +Certain Unix signals cause the name server to take specific actions, as +described in the following table. These signals can be sent using the +``kill`` command. + ++--------------+-------------------------------------------------------------+ +| ``SIGHUP`` | Causes the server to read :iscman:`named.conf` and reload | +| | the database. | ++--------------+-------------------------------------------------------------+ +| ``SIGTERM`` | Causes the server to clean up and exit. | ++--------------+-------------------------------------------------------------+ +| ``SIGINT`` | Causes the server to clean up and exit. | ++--------------+-------------------------------------------------------------+ + |