diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am index 52bc19b9fb..2b97c8ed7e 100644 --- a/doc/arm/Makefile.am +++ b/doc/arm/Makefile.am @@ -8,9 +8,12 @@ EXTRA_DIST = \ chapter10.rst \ chapter1.rst \ chapter2.rst \ - configuration.rst \ + chapter3.rst \ + chapter4.rst \ + configuration.inc.rst \ conf.py \ dlz.inc.rst \ + dns-ops.inc.rst \ dnssec-guide.rst \ dnssec.inc.rst \ dns-security-overview.dia \ diff --git a/doc/arm/chapter3.rst b/doc/arm/chapter3.rst new file mode 100644 index 0000000000..9a51e7e77a --- /dev/null +++ b/doc/arm/chapter3.rst @@ -0,0 +1,12 @@ +.. 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. + +.. include:: configuration.inc.rst \ No newline at end of file diff --git a/doc/arm/chapter4.rst b/doc/arm/chapter4.rst new file mode 100644 index 0000000000..305a27517d --- /dev/null +++ b/doc/arm/chapter4.rst @@ -0,0 +1,13 @@ +.. 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. + +.. include:: dns-ops.inc.rst +.. include:: plugins.inc.rst \ No newline at end of file diff --git a/doc/arm/configuration.inc.rst b/doc/arm/configuration.inc.rst new file mode 100644 index 0000000000..2c6684737a --- /dev/null +++ b/doc/arm/configuration.inc.rst @@ -0,0 +1,128 @@ +.. 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: + +Configurations and Zone Files +============================= + +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 { + 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 { + // 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 + primaries { 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`. + diff --git a/doc/arm/configuration.rst b/doc/arm/dns-ops.inc.rst similarity index 68% rename from doc/arm/configuration.rst rename to doc/arm/dns-ops.inc.rst index 807891c5a3..8bffba9bfe 100644 --- a/doc/arm/configuration.rst +++ b/doc/arm/dns-ops.inc.rst @@ -9,123 +9,6 @@ .. 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 { - 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 { - // 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 - primaries { 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 @@ -206,6 +89,8 @@ server. 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. @@ -312,4 +197,3 @@ described in the following table. These signals can be sent using the | ``SIGINT`` | Causes the server to clean up and exit. | +--------------+-------------------------------------------------------------+ -.. include:: plugins.inc.rst diff --git a/doc/arm/index.rst b/doc/arm/index.rst index 771e8405c7..684a20e9fe 100644 --- a/doc/arm/index.rst +++ b/doc/arm/index.rst @@ -19,7 +19,8 @@ BIND 9 Administrator Reference Manual chapter1 chapter2 - configuration + chapter3 + chapter4 reference advanced security diff --git a/doc/arm/plugins.inc.rst b/doc/arm/plugins.inc.rst index 09b79439e6..86a6bdbba1 100644 --- a/doc/arm/plugins.inc.rst +++ b/doc/arm/plugins.inc.rst @@ -12,7 +12,7 @@ .. _module-info: Plugins -------- +~~~~~~~ Plugins are a mechanism to extend the functionality of :iscman:`named` using dynamically loadable libraries. By using plugins, core server