diff options
Diffstat (limited to 'doc/arm/configuration.rst')
| -rw-r--r-- | doc/arm/configuration.rst | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/doc/arm/configuration.rst b/doc/arm/configuration.rst new file mode 100644 index 0000000..0b8d8ec --- /dev/null +++ b/doc/arm/configuration.rst @@ -0,0 +1,320 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +.. Configuration: + +Name Server Configuration +========================= + +In this chapter we provide some suggested configurations, along with +guidelines for their use. We suggest reasonable values for certain +option settings. + +.. _sample_configuration: + +Sample Configurations +--------------------- + +.. _cache_only_sample: + +A Caching-only Name Server +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following sample configuration is appropriate for a caching-only +name server for use by clients internal to a corporation. All queries +from outside clients are refused using the ``allow-query`` option. +The same effect can be achieved using suitable firewall +rules. + +:: + + // Two corporate subnets we wish to allow queries from. + acl corpnets { 192.168.4.0/24; 192.168.7.0/24; }; + options { + // Working directory + directory "/etc/namedb"; + + allow-query { corpnets; }; + }; + // Provide a reverse mapping for the loopback + // address 127.0.0.1 + zone "0.0.127.in-addr.arpa" { + type primary; + file "localhost.rev"; + notify no; + }; + +.. _auth_only_sample: + +An Authoritative-only Name Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This sample configuration is for an authoritative-only server that is +the primary server for ``example.com`` and a secondary server for the subdomain +``eng.example.com``. + +:: + + options { + // Working directory + directory "/etc/namedb"; + // Do not allow access to cache + allow-query-cache { none; }; + // This is the default + allow-query { any; }; + // Do not provide recursive service + recursion no; + }; + + // Provide a reverse mapping for the loopback + // address 127.0.0.1 + zone "0.0.127.in-addr.arpa" { + type primary; + file "localhost.rev"; + notify no; + }; + // We are the primary server for example.com + zone "example.com" { + type primary; + file "example.com.db"; + // IP addresses of secondary servers allowed to + // transfer example.com + allow-transfer { + 192.168.4.14; + 192.168.5.53; + }; + }; + // We are a secondary server for eng.example.com + zone "eng.example.com" { + type secondary; + file "eng.example.com.bk"; + // IP address of eng.example.com primary server + masters { 192.168.4.12; }; + }; + +.. _load_balancing: + +Load Balancing +-------------- + +A primitive form of load balancing can be achieved in the DNS by using +multiple records (such as multiple A records) for one name. + +For example, assuming three HTTP servers with network addresses of +10.0.0.1, 10.0.0.2, and 10.0.0.3, a set of records such as the following +means that clients will connect to each machine one-third of the time: + ++-----------+------+----------+----------+----------------------------+ +| Name | TTL | CLASS | TYPE | Resource Record (RR) Data | ++-----------+------+----------+----------+----------------------------+ +| www | 600 | IN | A | 10.0.0.1 | ++-----------+------+----------+----------+----------------------------+ +| | 600 | IN | A | 10.0.0.2 | ++-----------+------+----------+----------+----------------------------+ +| | 600 | IN | A | 10.0.0.3 | ++-----------+------+----------+----------+----------------------------+ + +When a resolver queries for these records, BIND rotates them and +responds to the query with the records in a different order. In the +example above, clients randomly receive records in the order 1, 2, +3; 2, 3, 1; and 3, 1, 2. Most clients use the first record returned +and discard the rest. + +For more detail on ordering responses, check the ``rrset-order`` +sub-statement in the ``options`` statement; see :ref:`rrset_ordering`. + +.. _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 ``dig``, ``host``, and ``nslookup`` programs are all command-line +tools for manually querying name servers. They differ in style and +output format. + +``dig`` + ``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`. + +``host`` + The ``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`. + +``nslookup`` + ``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 ``nslookup``. Use ``dig`` + instead. + +.. _admin_tools: + +Administrative Tools +^^^^^^^^^^^^^^^^^^^^ + +Administrative tools play an integral part in the management of a +server. + +``named-checkconf`` + The ``named-checkconf`` program checks the syntax of a ``named.conf`` + file. + + For more information and a list of available commands and options, + see :ref:`man_named-checkconf`. + +``named-checkzone`` + The ``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`. + +``named-compilezone`` + This tool is similar to ``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`. + +``rndc`` + The remote name daemon control (``rndc``) program allows the system + administrator to control the operation of a name server. + + See :ref:`man_rndc` for details of the available ``rndc`` + commands. + + ``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 ``rndc`` + configuration file is ``/etc/rndc.conf``, but an alternate location + can be specified with the ``-c`` option. If the configuration file is + not found, ``rndc`` also looks in ``/etc/rndc.key`` (or whatever + ``sysconfdir`` was defined when the BIND build was configured). The + ``rndc.key`` file is generated by running ``rndc-confgen -a`` as + described in :ref:`controls_statement_definition_and_usage`. + + The format of the configuration file is similar to that of + ``named.conf``, but is limited to only four statements: the ``options``, + ``key``, ``server``, and ``include`` statements. These statements are + what associate the secret keys to the servers with which they are + meant to be shared. The order of statements is not significant. + + The ``options`` statement has three clauses: ``default-server``, + ``default-key``, and ``default-port``. ``default-server`` takes a + host name or address argument and represents the server that is + contacted if no ``-s`` option is provided on the command line. + ``default-key`` takes the name of a key as its argument, as defined + by a ``key`` statement. ``default-port`` specifies the port to which + ``rndc`` should connect if no port is given on the command line or in + a ``server`` statement. + + The ``key`` statement defines a key to be used by ``rndc`` when + authenticating with ``named``. Its syntax is identical to the ``key`` + statement in ``named.conf``. The keyword ``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 ``key`` statement has two clauses: ``algorithm`` and ``secret``. + While the configuration parser accepts any string as the argument + to ``algorithm``, currently only the strings ``hmac-md5``, + ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, + ``hmac-sha384``, and ``hmac-sha512`` have any meaning. The secret + is a Base64-encoded string as specified in :rfc:`3548`. + + The ``server`` statement associates a key defined using the ``key`` + statement with a server. The keyword ``server`` is followed by a host + name or address. The ``server`` statement has two clauses: ``key`` + and ``port``. The ``key`` clause specifies the name of the key to be + used when communicating with this server, and the ``port`` clause can + be used to specify the port ``rndc`` should connect to on the 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 ``/etc/rndc.conf``, allows the + command: + + ``$ 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 statement for ``rndc_key``. + + Running the ``rndc-confgen`` program conveniently creates an + ``rndc.conf`` file, and also displays the corresponding + ``controls`` statement needed to add to ``named.conf``. + Alternatively, it is possible to run ``rndc-confgen -a`` to set up an + ``rndc.key`` file and not modify ``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 ``named.conf`` and reload | +| | the database. | ++--------------+-------------------------------------------------------+ +| ``SIGTERM`` | Causes the server to clean up and exit. | ++--------------+-------------------------------------------------------+ +| ``SIGINT`` | Causes the server to clean up and exit. | ++--------------+-------------------------------------------------------+ + +.. include:: plugins.rst |