From ccfe6825085a94467bef8823391876e407626def Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Mon, 17 Jan 2022 19:49:48 +0100 Subject: [PATCH 01/15] Clarify XoT usage and warn about the unauthenticated mode --- doc/arm/reference.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 2a851361c0..9faafb90f4 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -886,6 +886,18 @@ used by multiple stub and secondary zones in their ``primaries`` or keyword ``masters``, which can still be used, but is no longer the preferred terminology.) +To force the zone transfer requests to be sent over TLS, use ``tls`` keyword, +e.g. ``primaries { 192.0.2.1 tls tls-configuration-name; };``, +where ``tls-configuration-name`` refers to a previously defined +:ref:`tls statement `. + +.. warning:: + + Please note that TLS connections to primaries are currently + **not authenticated**. This mode provides protection from passive observers + but does not protect from man-in-the-middle attacks on zone transfers. + + .. _options_grammar: ``options`` Statement Grammar @@ -2435,6 +2447,12 @@ for details on how to specify IP address lists. allows outgoing zone transfers to any host using the TLS transport over port 853. +.. warning:: + + Please note that incoming TLS connections are currently + **not authenticated at the TLS level**. + Please use :ref:`tsig` to authenticate requestors. + ``blackhole`` This specifies a list of addresses which the server does not accept queries from or use to resolve a query. Queries from these addresses are not From 3b457598494593a458fded0fb7b7545e4ae60600 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Fri, 21 Jan 2022 11:13:05 +0100 Subject: [PATCH 02/15] Document that tls statement is subject to change --- doc/arm/reference.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 9faafb90f4..7207d1b23d 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -4834,6 +4834,12 @@ The following options can be specified in a ``tls`` statement: or the TLS certificate and key pair is planned to be used across multiple BIND instances. +.. warning:: + + TLS configuration is subject to change and incompatible changes might + be introduced in the future. Users of TLS are encouraged to carefully + read release notes when upgrading. + The options described above are used to control different aspects of TLS functioning. Thus, most of them have no well-defined default values, as these depend on the cryptographic library version in use From 49a32c076cdd70b3b048399c8ad661c3758050d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 19 Jan 2022 11:47:10 +0100 Subject: [PATCH 03/15] Update BIND version number in PLATFORMS.md to 9.19 --- PLATFORMS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/PLATFORMS.md b/PLATFORMS.md index cee85d1931..e4d1b919d1 100644 --- a/PLATFORMS.md +++ b/PLATFORMS.md @@ -35,7 +35,7 @@ The following C11 features are used in BIND 9: The C11 variants are preferred. -BIND 9.17 requires a fairly recent version of `libuv` (at least 1.x). For +BIND 9.19 requires a fairly recent version of `libuv` (at least 1.x). For some of the older systems listed below, you will have to install an updated `libuv` package from sources such as EPEL, PPA, or other native sources for updated packages. The other option is to build and install `libuv` from @@ -59,7 +59,7 @@ offer support on a "best effort" basis for some. ### Regularly tested platforms -As of Dec 2021, BIND 9.17 is fully supported and regularly tested on the +As of Jan 2022, BIND 9.19 is fully supported and regularly tested on the following systems: * Debian 9, 10, 11 @@ -108,7 +108,7 @@ platforms. ## Unsupported platforms -These are platforms on which BIND 9.17 is known *not* to build or run: +These are platforms on which BIND 9.19 is known *not* to build or run: * Platforms without at least OpenSSL 1.0.2 * Windows From d2bbd4d81ceb27f20ccb21a762a6e1dd6096a897 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 19 Jan 2022 15:24:39 +0100 Subject: [PATCH 04/15] Convert PLATFORMS file from Markdown to reStructuredText Converted using pandoc 2.14.2-9 on Arch Linux: $ pandoc -f markdown -t rst PLATFORMS.md > PLATFORMS.rst The pandoc-generated copyright header was subsequently replaced with usual one for .rst files. --- PLATFORMS.md | 119 ---------------------------------------------- PLATFORMS.rst | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+), 119 deletions(-) delete mode 100644 PLATFORMS.md create mode 100644 PLATFORMS.rst diff --git a/PLATFORMS.md b/PLATFORMS.md deleted file mode 100644 index e4d1b919d1..0000000000 --- a/PLATFORMS.md +++ /dev/null @@ -1,119 +0,0 @@ - -## Supported platforms - -In general, this version of BIND will build and run on any POSIX-compliant -system with a C11-compliant C compiler, BSD-style sockets with RFC-compliant -IPv6 support, and POSIX-compliant threads, plus the following mandatory -libraries: - -- `libuv` for asynchronous I/O operations and event loops -- `libssl` and `libcrypto` from OpenSSL for cryptography - -Use of the following libraries is optional: - -- `libjemalloc` for improved memory allocation performance -- `libnghttp2` for DNS-over-HTTPS (DoH) support - -The following C11 features are used in BIND 9: - -* Atomic operations support, either in the form of C11 atomics or - `__atomic` builtin operations. - -* Thread Local Storage support, either in the form of C11 - `_Thread_local`/`thread_local`, or the `__thread` GCC extension. - -The C11 variants are preferred. - -BIND 9.19 requires a fairly recent version of `libuv` (at least 1.x). For -some of the older systems listed below, you will have to install an updated -`libuv` package from sources such as EPEL, PPA, or other native sources for -updated packages. The other option is to build and install `libuv` from -source. - -Certain optional BIND features have additional library dependencies. -These include: - -* `libfstrm` and `libprotobuf-c` for DNSTAP -* `libidn2` for display of internationalized domain names in `dig` -* `libjson-c` for JSON statistics -* `libmaxminddb` for geolocation -* `libnghttp2` for DNS over HTTPS -* `libxml2` for XML statistics -* `libz` for compression of the HTTP statistics channel -* `readline` for line editing in `nsupdate` and `nslookup` - -ISC regularly tests BIND on many operating systems and architectures, but -lacks the resources to test all of them. Consequently, ISC is only able to -offer support on a "best effort" basis for some. - -### Regularly tested platforms - -As of Jan 2022, BIND 9.19 is fully supported and regularly tested on the -following systems: - -* Debian 9, 10, 11 -* Ubuntu LTS 18.04, 20.04 -* Fedora 35 -* Red Hat Enterprise Linux / CentOS / Oracle Linux 7, 8 -* FreeBSD 12.3, 13.0 -* OpenBSD 7.0 -* Alpine Linux 3.15 - -The amd64, i386, armhf and arm64 CPU architectures are all fully supported. - -### Best effort - -The following are platforms on which BIND is known to build and run. -ISC makes every effort to fix bugs on these platforms, but may be unable -to do so quickly due to lack of hardware, less familiarity on the part -of engineering staff, and other constraints. None of these are tested -regularly by ISC. - -* macOS 10.12+ -* Solaris 11 -* NetBSD -* Other Linux distributions still supported by their vendors, such as: - * Ubuntu 20.10+ - * Gentoo - * Arch Linux -* OpenWRT/LEDE 17.01+ -* Other CPU architectures (mips, mipsel, sparc, ...) - -### Community maintained - -These systems may not all have the required dependencies for building BIND -easily available, although it will be possible in many cases to compile -those directly from source. The community and interested parties may wish -to help with maintenance, and we welcome patch contributions, although we -cannot guarantee that we will accept them. All contributions will be -assessed against the risk of adverse effect on officially supported -platforms. - -* Platforms past or close to their respective EOL dates, such as: - * Ubuntu 14.04, 16.04 (Ubuntu ESM releases are not supported) - * CentOS 6 - * Debian Jessie - * FreeBSD 10.x, 11.x - -## Unsupported platforms - -These are platforms on which BIND 9.19 is known *not* to build or run: - -* Platforms without at least OpenSSL 1.0.2 -* Windows -* Solaris 10 and older -* Platforms that don't support IPv6 Advanced Socket API (RFC 3542) -* Platforms that don't support atomic operations (via compiler or library) -* Linux without NPTL (Native POSIX Thread Library) -* Platforms on which `libuv` cannot be compiled diff --git a/PLATFORMS.rst b/PLATFORMS.rst new file mode 100644 index 0000000000..cc991ebf94 --- /dev/null +++ b/PLATFORMS.rst @@ -0,0 +1,129 @@ +.. 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. + +Supported platforms +------------------- + +In general, this version of BIND will build and run on any +POSIX-compliant system with a C11-compliant C compiler, BSD-style +sockets with RFC-compliant IPv6 support, and POSIX-compliant threads, +plus the following mandatory libraries: + +- ``libuv`` for asynchronous I/O operations and event loops +- ``libssl`` and ``libcrypto`` from OpenSSL for cryptography + +Use of the following libraries is optional: + +- ``libjemalloc`` for improved memory allocation performance +- ``libnghttp2`` for DNS-over-HTTPS (DoH) support + +The following C11 features are used in BIND 9: + +- Atomic operations support, either in the form of C11 atomics or + ``__atomic`` builtin operations. + +- Thread Local Storage support, either in the form of C11 + ``_Thread_local``/``thread_local``, or the ``__thread`` GCC + extension. + +The C11 variants are preferred. + +BIND 9.19 requires a fairly recent version of ``libuv`` (at least 1.x). +For some of the older systems listed below, you will have to install an +updated ``libuv`` package from sources such as EPEL, PPA, or other +native sources for updated packages. The other option is to build and +install ``libuv`` from source. + +Certain optional BIND features have additional library dependencies. +These include: + +- ``libfstrm`` and ``libprotobuf-c`` for DNSTAP +- ``libidn2`` for display of internationalized domain names in ``dig`` +- ``libjson-c`` for JSON statistics +- ``libmaxminddb`` for geolocation +- ``libnghttp2`` for DNS over HTTPS +- ``libxml2`` for XML statistics +- ``libz`` for compression of the HTTP statistics channel +- ``readline`` for line editing in ``nsupdate`` and ``nslookup`` + +ISC regularly tests BIND on many operating systems and architectures, +but lacks the resources to test all of them. Consequently, ISC is only +able to offer support on a “best effort” basis for some. + +Regularly tested platforms +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As of Jan 2022, BIND 9.19 is fully supported and regularly tested on the +following systems: + +- Debian 9, 10, 11 +- Ubuntu LTS 18.04, 20.04 +- Fedora 35 +- Red Hat Enterprise Linux / CentOS / Oracle Linux 7, 8 +- FreeBSD 12.3, 13.0 +- OpenBSD 7.0 +- Alpine Linux 3.15 + +The amd64, i386, armhf and arm64 CPU architectures are all fully +supported. + +Best effort +~~~~~~~~~~~ + +The following are platforms on which BIND is known to build and run. ISC +makes every effort to fix bugs on these platforms, but may be unable to +do so quickly due to lack of hardware, less familiarity on the part of +engineering staff, and other constraints. None of these are tested +regularly by ISC. + +- macOS 10.12+ +- Solaris 11 +- NetBSD +- Other Linux distributions still supported by their vendors, such as: + + - Ubuntu 20.10+ + - Gentoo + - Arch Linux + +- OpenWRT/LEDE 17.01+ +- Other CPU architectures (mips, mipsel, sparc, …) + +Community maintained +~~~~~~~~~~~~~~~~~~~~ + +These systems may not all have the required dependencies for building +BIND easily available, although it will be possible in many cases to +compile those directly from source. The community and interested parties +may wish to help with maintenance, and we welcome patch contributions, +although we cannot guarantee that we will accept them. All contributions +will be assessed against the risk of adverse effect on officially +supported platforms. + +- Platforms past or close to their respective EOL dates, such as: + + - Ubuntu 14.04, 16.04 (Ubuntu ESM releases are not supported) + - CentOS 6 + - Debian Jessie + - FreeBSD 10.x, 11.x + +Unsupported platforms +--------------------- + +These are platforms on which BIND 9.19 is known *not* to build or run: + +- Platforms without at least OpenSSL 1.0.2 +- Windows +- Solaris 10 and older +- Platforms that don’t support IPv6 Advanced Socket API (RFC 3542) +- Platforms that don’t support atomic operations (via compiler or + library) +- Linux without NPTL (Native POSIX Thread Library) +- Platforms on which ``libuv`` cannot be compiled From f693c9b1a7b4565a47b3f997f9bedcc313488e4a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 19 Jan 2022 15:40:56 +0100 Subject: [PATCH 05/15] Replace duplicate Supported Operating Systems in the ARM by PLATFORMS.rst --- PLATFORMS.rst => doc/arm/platforms.rst | 0 doc/arm/requirements.rst | 8 +------- 2 files changed, 1 insertion(+), 7 deletions(-) rename PLATFORMS.rst => doc/arm/platforms.rst (100%) diff --git a/PLATFORMS.rst b/doc/arm/platforms.rst similarity index 100% rename from PLATFORMS.rst rename to doc/arm/platforms.rst diff --git a/doc/arm/requirements.rst b/doc/arm/requirements.rst index 82ab4fa55d..fdd343def6 100644 --- a/doc/arm/requirements.rst +++ b/doc/arm/requirements.rst @@ -72,10 +72,4 @@ servers share their cached data. .. _supported_os: -Supported Operating Systems ---------------------------- - -ISC BIND 9 compiles and runs on many Unix-like operating -systems and on Microsoft Windows Server 2012 R2, 2016, and Windows 10. -For an up-to-date list of supported systems, see the PLATFORMS.md file -in the top-level directory of the BIND 9 source distribution. +.. include:: platforms.rst From 920a2e730bf2eed04303373547f070e6cb1c0ce4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 19 Jan 2022 16:30:18 +0100 Subject: [PATCH 06/15] Replace all occurences of PLATFORMS file with reference to the ARM The conf.py exclude_patterns now includes platforms.rst to avoid problems with redefining labels: https://github.com/sphinx-doc/sphinx/issues/1668#issuecomment-71376208 --- README.md | 4 +++- doc/arm/Makefile.am | 1 + doc/arm/conf.py | 1 + doc/arm/notes.rst | 18 +----------------- doc/arm/platforms.rst | 2 ++ doc/arm/requirements.rst | 4 +--- 6 files changed, 9 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 099332c4d5..760171172e 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,9 @@ CHANGES file format. For up-to-date versions and release notes, see [https://www.isc.org/download/](https://www.isc.org/download/). -For information about supported platforms, see [PLATFORMS](PLATFORMS.md). +For information about supported platforms, see the +["Supported Platforms"](doc/arm/platforms.rst) section in the BIND 9 +Administrator Reference Manual. ### Reporting bugs and getting help diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am index 894f0aeebc..c92797dfac 100644 --- a/doc/arm/Makefile.am +++ b/doc/arm/Makefile.am @@ -20,6 +20,7 @@ EXTRA_DIST = \ manpages.rst \ notes.rst \ pkcs11.rst \ + platforms.rst \ plugins.rst \ reference.rst \ requirements.rst \ diff --git a/doc/arm/conf.py b/doc/arm/conf.py index 43e9d62bfd..ce06ac4721 100644 --- a/doc/arm/conf.py +++ b/doc/arm/conf.py @@ -150,6 +150,7 @@ exclude_patterns = [ 'logging-cattegories.rst', 'managed-keys.rst', 'pkcs11.rst', + 'platforms.rst', 'plugins.rst' ] diff --git a/doc/arm/notes.rst b/doc/arm/notes.rst index 92e7489b1c..7a0c6a6f9e 100644 --- a/doc/arm/notes.rst +++ b/doc/arm/notes.rst @@ -27,23 +27,7 @@ detailed list of changes and bug fixes. Supported Platforms ------------------- -To build on Unix-like systems, BIND requires support for POSIX.1c -threads (IEEE Std 1003.1c-1995), the Advanced Sockets API for IPv6 -(:rfc:`3542`), and standard atomic operations provided by the C -compiler. - -The libuv asynchronous I/O library and the OpenSSL cryptography library -must be available for the target platform. A PKCS#11 provider can be -used instead of OpenSSL for Public Key cryptography (i.e., DNSSEC -signing and validation), but OpenSSL is still required for general -cryptography operations such as hashing and random number generation. - -More information can be found in the ``PLATFORMS.md`` file that is -included in the source distribution of BIND 9. If your compiler and -system libraries provide the above features, BIND 9 should compile and -run. If that is not the case, the BIND development team will generally -accept patches that add support for systems that are still supported by -their respective vendors. +See the :ref:`supported_os` section in the :ref:`Requirements` chapter. Download -------- diff --git a/doc/arm/platforms.rst b/doc/arm/platforms.rst index cc991ebf94..670657c01a 100644 --- a/doc/arm/platforms.rst +++ b/doc/arm/platforms.rst @@ -9,6 +9,8 @@ .. See the COPYRIGHT file distributed with this work for additional .. information regarding copyright ownership. +.. _supported_os: + Supported platforms ------------------- diff --git a/doc/arm/requirements.rst b/doc/arm/requirements.rst index fdd343def6..6151e593e0 100644 --- a/doc/arm/requirements.rst +++ b/doc/arm/requirements.rst @@ -9,7 +9,7 @@ .. See the COPYRIGHT file distributed with this work for additional .. information regarding copyright ownership. -.. Requirements: +.. _Requirements: BIND Resource Requirements ========================== @@ -70,6 +70,4 @@ much memory or CPU power as in the first alternative, but this has the disadvantage of making many more external queries, as none of the name servers share their cached data. -.. _supported_os: - .. include:: platforms.rst From 3bd4318fccdd14bd194662ebe56e43aaed08d735 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 19 Jan 2022 16:36:27 +0100 Subject: [PATCH 07/15] Link to ISC KB for most up-to-date platform support statuses --- doc/arm/platforms.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/arm/platforms.rst b/doc/arm/platforms.rst index 670657c01a..913f65d8d9 100644 --- a/doc/arm/platforms.rst +++ b/doc/arm/platforms.rst @@ -14,6 +14,11 @@ Supported platforms ------------------- +Current support status of various platforms and BIND 9 versions can be +found in the ISC Knowledgebase: + +https://kb.isc.org/docs/supported-platforms + In general, this version of BIND will build and run on any POSIX-compliant system with a C11-compliant C compiler, BSD-style sockets with RFC-compliant IPv6 support, and POSIX-compliant threads, From 5c6b50027a7bacda362c0d5aa4c72e6d16e7a49f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 20 Jan 2022 10:24:38 +0100 Subject: [PATCH 08/15] Convert "Building BIND" section from README.md to reStructuredText Converted using pandoc 2.14.2-9 on Arch Linux: $ pandoc --shift-heading-level-by=-1 -f markdown -t rst README.md > doc/arm/build.rst Plus hand-edit to remove sections other than Building BIND 9, remove misindentation in section headers, and add a standard copyright header. --- doc/arm/Makefile.am | 1 + doc/arm/build.rst | 171 +++++++++++++++++++++++++++++++++++++++ doc/arm/conf.py | 1 + doc/arm/requirements.rst | 1 + 4 files changed, 174 insertions(+) create mode 100644 doc/arm/build.rst diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am index c92797dfac..feebea0737 100644 --- a/doc/arm/Makefile.am +++ b/doc/arm/Makefile.am @@ -5,6 +5,7 @@ EXTRA_DIST = \ conf.py \ isc-logo.pdf \ advanced.rst \ + build.rst \ catz.rst \ configuration.rst \ dlz.rst \ diff --git a/doc/arm/build.rst b/doc/arm/build.rst new file mode 100644 index 0000000000..b20b1c8396 --- /dev/null +++ b/doc/arm/build.rst @@ -0,0 +1,171 @@ +.. 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. + +Building BIND 9 +--------------- + +At a minimum, BIND requires a Unix or Linux system with an ANSI C +compiler, basic POSIX support, and a 64-bit integer type. BIND also +requires the ``libuv`` asynchronous I/O library, the ``nghttp2`` HTTP/2 +library, the ``jemalloc`` memory allocation library, and the OpenSSL +cryptography library. On Linux, BIND requires the ``libcap`` library to +set process privileges, though this requirement can be overridden by +disabling capability support at compile time. See `Compile-time +options <#opts>`__ below for details on other libraries that may be +required to support optional features. + +Successful builds have been observed on many versions of Linux and Unix, +including RHEL/CentOS/Oracle Linux, Fedora, Debian, Ubuntu, SLES, +openSUSE, Slackware, Alpine, FreeBSD, NetBSD, OpenBSD, macOS, Solaris, +OpenIndiana, OmniOS CE, HP-UX, and OpenWRT. + +To build on a Unix or Linux system, use: + +:: + + $ autoreconf -fi (if you are building in the git repository) + $ ./configure + $ make + +If you’re using Emacs, you might find ``make tags`` helpful. + +Several environment variables, which can be set before running +``configure``, affect compilation. Significant ones are: + ++--------------------+-------------------------------------------------+ +| Variable | Description | ++====================+=================================================+ +| ``CC`` | The C compiler to use. ``configure`` tries to | +| | figure out the right one for supported systems. | ++--------------------+-------------------------------------------------+ +| ``CFLAGS`` | C compiler flags. Defaults to include -g and/or | +| | -O2 as supported by the compiler. Please | +| | include ‘-g’ if you need to set ``CFLAGS``. | ++--------------------+-------------------------------------------------+ +| ``LDFLAGS`` | Linker flags. Defaults to empty string. | ++--------------------+-------------------------------------------------+ + +Additional environment variables affecting the build are listed at the +end of the ``configure`` help text, which can be obtained by running the +command: + +:: + + $ ./configure --help + +macOS +~~~~~ + +Building on macOS assumes that the “Command Tools for Xcode” are +installed. These can be downloaded from +https://developer.apple.com/download/more/ or, if you have Xcode already +installed, you can run ``xcode-select --install``. (Note that an Apple +ID may be required to access the download page.) + +Dependencies +~~~~~~~~~~~~ + +To build BIND you need to have the following packages installed: + +:: + + libuv + pkg-config / pkgconfig / pkgconf + +To build BIND from the git repository, you need the following tools +installed: + +:: + + autoconf (includes autoreconf) + automake + libtool + +Compile-time options +~~~~~~~~~~~~~~~~~~~~ + +To see a full list of configuration options, run ``configure --help``. + +For the server to support DNSSEC, you need to build it with crypto +support. To use OpenSSL, you must have OpenSSL 1.0.2e or newer +installed. If the OpenSSL library is installed in a nonstandard +location, specify the prefix using ``--with-openssl=`` on the +configure command line. To use a PKCS#11 hardware service module for +cryptographic operations, it will be necessary to compile and use +engine_pkcs11 from the OpenSC project. + +To support DNS over HTTPS, the server must be linked with +``libnghttp2``. + +To support the HTTP statistics channel, the server must be linked with +at least one of the following libraries: ``libxml2`` http://xmlsoft.org +or ``json-c`` https://github.com/json-c/json-c. If these are installed +at a nonstandard location, then: + +- for ``libxml2``, specify the prefix using ``--with-libxml2=/prefix``. +- for ``json-c``, adjust ``PKG_CONFIG_PATH``. + +To support compression on the HTTP statistics channel, the server must +be linked against ``libzlib``. If this is installed in a nonstandard +location, specify the prefix using ``--with-zlib=/prefix``. + +To support storing configuration data for runtime-added zones in an LMDB +database, the server must be linked with ``liblmdb``. If this is +installed in a nonstandard location, specify the prefix using +``with-lmdb=/prefix``. + +To support MaxMind GeoIP2 location-based ACLs, the server must be linked +with ``libmaxminddb``. This is turned on by default if the library is +found; if the library is installed in a nonstandard location, specify +the prefix using ``--with-maxminddb=/prefix``. GeoIP2 support can be +switched off with ``--disable-geoip``. + +For DNSTAP packet logging, you must have installed ``libfstrm`` +https://github.com/farsightsec/fstrm and ``libprotobuf-c`` +https://developers.google.com/protocol-buffers, and BIND must be +configured with ``--enable-dnstap``. + +Certain compiled-in constants and default settings can be decreased to +values better suited to small machines, e.g. OpenWRT boxes, by +specifying ``--with-tuning=small`` on the ``configure`` command line. +This decreases memory usage by using smaller structures, but degrades +performance. + +On Linux, process capabilities are managed in user space using the +``libcap`` library, which can be installed on most Linux systems via the +``libcap-dev`` or ``libcap-devel`` package. Process capability support +can also be disabled by configuring with ``--disable-linux-caps``. + +On some platforms it is necessary to explicitly request large file +support to handle files bigger than 2GB. This can be done by using +``--enable-largefile`` on the ``configure`` command line. + +Support for the “fixed” rrset-order option can be enabled or disabled by +specifying ``--enable-fixed-rrset`` or ``--disable-fixed-rrset`` on the +configure command line. By default, fixed rrset-order is disabled to +reduce memory footprint. + +The ``--enable-querytrace`` option causes ``named`` to log every step of +processing every query. The ``--enable-singletrace`` option turns on the +same verbose tracing, but allows an individual query to be separately +traced by setting its query ID to 0. These options should only be +enabled when debugging, because they have a significant negative impact +on query performance. + +``make install`` installs ``named`` and the various BIND 9 libraries. By +default, installation is into /usr/local, but this can be changed with +the ``--prefix`` option when running ``configure``. + +You may specify the option ``--sysconfdir`` to set the directory where +configuration files like ``named.conf`` go by default, and +``--localstatedir`` to set the default parent directory of +``run/named.pid``. ``--sysconfdir`` defaults to ``$prefix/etc`` and +``--localstatedir`` defaults to ``$prefix/var``. diff --git a/doc/arm/conf.py b/doc/arm/conf.py index ce06ac4721..35d8b20de6 100644 --- a/doc/arm/conf.py +++ b/doc/arm/conf.py @@ -143,6 +143,7 @@ exclude_patterns = [ '.DS_Store', '*.grammar.rst', '*.zoneopts.rst', + 'build.rst', 'catz.rst', 'dlz.rst', 'dnssec.rst', diff --git a/doc/arm/requirements.rst b/doc/arm/requirements.rst index 6151e593e0..09f0f427ef 100644 --- a/doc/arm/requirements.rst +++ b/doc/arm/requirements.rst @@ -71,3 +71,4 @@ disadvantage of making many more external queries, as none of the name servers share their cached data. .. include:: platforms.rst +.. include:: build.rst From 933ed9d537cb9fd58d66da056785785cbd3ba989 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 20 Jan 2022 10:47:31 +0100 Subject: [PATCH 09/15] Replace Building BIND 9 section in README with reference to ARM --- README.md | 142 ++---------------------------------------------------- 1 file changed, 3 insertions(+), 139 deletions(-) diff --git a/README.md b/README.md index 760171172e..564ae059df 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,6 @@ information regarding copyright ownership. 1. [Reporting bugs and getting help](#help) 1. [Contributing to BIND](#contrib) 1. [Building BIND](#build) -1. [macOS](#macos) -1. [Dependencies](#dependencies) -1. [Compile-time options](#opts) 1. [Automated testing](#testing) 1. [Documentation](#doc) 1. [Change log](#changes) @@ -127,142 +124,9 @@ including your patch as an attachment, preferably generated by ### Building BIND 9 -At a minimum, BIND requires a Unix or Linux system with an ANSI C compiler, -basic POSIX support, and a 64-bit integer type. BIND also requires the -`libuv` asynchronous I/O library, the `nghttp2` HTTP/2 library, the -`jemalloc` memory allocation library, and the OpenSSL cryptography -library. On Linux, BIND requires the `libcap` library to set process -privileges, though this requirement can be overridden by disabling -capability support at compile time. See [Compile-time options](#opts) -below for details on other libraries that may be required to support -optional features. - -Successful builds have been observed on many versions of Linux and Unix, -including RHEL/CentOS/Oracle Linux, Fedora, Debian, Ubuntu, SLES, openSUSE, -Slackware, Alpine, FreeBSD, NetBSD, OpenBSD, macOS, Solaris, OpenIndiana, -OmniOS CE, HP-UX, and OpenWRT. - -To build on a Unix or Linux system, use: - - $ autoreconf -fi (if you are building in the git repository) - $ ./configure - $ make - -If you're using Emacs, you might find `make tags` helpful. - -Several environment variables, which can be set before running `configure`, -affect compilation. Significant ones are: - -|Variable|Description | -|--------------------|-----------------------------------------------| -|`CC`|The C compiler to use. `configure` tries to figure out the right one for supported systems.| -|`CFLAGS`|C compiler flags. Defaults to include -g and/or -O2 as supported by the compiler. Please include '-g' if you need to set `CFLAGS`. | -|`LDFLAGS`|Linker flags. Defaults to empty string.| - -Additional environment variables affecting the build are listed at the -end of the `configure` help text, which can be obtained by running the -command: - - $ ./configure --help - -#### macOS - -Building on macOS assumes that the "Command Tools for Xcode" are installed. -These can be downloaded from -[https://developer.apple.com/download/more/](https://developer.apple.com/download/more/) -or, if you have Xcode already installed, you can run `xcode-select --install`. -(Note that an Apple ID may be required to access the download page.) - -#### Dependencies - -To build BIND you need to have the following packages installed: - - libuv - pkg-config / pkgconfig / pkgconf - -To build BIND from the git repository, you need the following tools -installed: - - autoconf (includes autoreconf) - automake - libtool - -#### Compile-time options - -To see a full list of configuration options, run `configure --help`. - -For the server to support DNSSEC, you need to build it with crypto support. -To use OpenSSL, you must have OpenSSL 1.0.2e or newer installed. If the -OpenSSL library is installed in a nonstandard location, specify the prefix -using `--with-openssl=` on the configure command line. To use a -PKCS#11 hardware service module for cryptographic operations, it will -be necessary to compile and use engine_pkcs11 from the OpenSC project. - -To support DNS over HTTPS, the server must be linked with `libnghttp2`. - -To support the HTTP statistics channel, the server must be linked with at -least one of the following libraries: `libxml2` -[http://xmlsoft.org](http://xmlsoft.org) or `json-c` -[https://github.com/json-c/json-c](https://github.com/json-c/json-c). -If these are installed at a nonstandard location, then: - -* for `libxml2`, specify the prefix using `--with-libxml2=/prefix`. -* for `json-c`, adjust `PKG_CONFIG_PATH`. - -To support compression on the HTTP statistics channel, the server must be -linked against `libzlib`. If this is installed in a nonstandard location, -specify the prefix using `--with-zlib=/prefix`. - -To support storing configuration data for runtime-added zones in an LMDB -database, the server must be linked with `liblmdb`. If this is installed in a -nonstandard location, specify the prefix using `with-lmdb=/prefix`. - -To support MaxMind GeoIP2 location-based ACLs, the server must be linked -with `libmaxminddb`. This is turned on by default if the library is -found; if the library is installed in a nonstandard location, -specify the prefix using `--with-maxminddb=/prefix`. GeoIP2 support -can be switched off with `--disable-geoip`. - -For DNSTAP packet logging, you must have installed `libfstrm` -[https://github.com/farsightsec/fstrm](https://github.com/farsightsec/fstrm) -and `libprotobuf-c` -[https://developers.google.com/protocol-buffers](https://developers.google.com/protocol-buffers), -and BIND must be configured with `--enable-dnstap`. - -Certain compiled-in constants and default settings can be decreased to -values better suited to small machines, e.g. OpenWRT boxes, by specifying -`--with-tuning=small` on the `configure` command line. This decreases -memory usage by using smaller structures, but degrades performance. - -On Linux, process capabilities are managed in user space using -the `libcap` library, which can be installed on most Linux systems via -the `libcap-dev` or `libcap-devel` package. Process capability support can -also be disabled by configuring with `--disable-linux-caps`. - -On some platforms it is necessary to explicitly request large file support -to handle files bigger than 2GB. This can be done by using -`--enable-largefile` on the `configure` command line. - -Support for the "fixed" rrset-order option can be enabled or disabled by -specifying `--enable-fixed-rrset` or `--disable-fixed-rrset` on the -configure command line. By default, fixed rrset-order is disabled to -reduce memory footprint. - -The `--enable-querytrace` option causes `named` to log every step of -processing every query. The `--enable-singletrace` option turns on the -same verbose tracing, but allows an individual query to be separately -traced by setting its query ID to 0. These options should only be enabled -when debugging, because they have a significant negative impact on query -performance. - -`make install` installs `named` and the various BIND 9 libraries. By -default, installation is into /usr/local, but this can be changed with the -`--prefix` option when running `configure`. - -You may specify the option `--sysconfdir` to set the directory where -configuration files like `named.conf` go by default, and `--localstatedir` -to set the default parent directory of `run/named.pid`. `--sysconfdir` -defaults to `$prefix/etc` and `--localstatedir` defaults to `$prefix/var`. +For information about building BIND 9, see the +["Building BIND 9"](doc/arm/build.rst) section in the BIND 9 +Administrator Reference Manual. ### Automated testing From 2c81fa9013350989b13dec4cfb3b947a25cf9579 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 19 Jan 2022 16:37:04 +0100 Subject: [PATCH 10/15] Deduplicate text between Building BIND 9 / Supported Platforms in the ARM Supported Platforms section is now really only about platforms and not libraries. Libraries were moved to the Building BIND section. We now have section for required libraries, and second with optional features. Wordy explanations were taken verbatim from the original README.md. --- doc/arm/build.rst | 65 +++++++++++++++++++++---------------------- doc/arm/platforms.rst | 34 +++------------------- 2 files changed, 35 insertions(+), 64 deletions(-) diff --git a/doc/arm/build.rst b/doc/arm/build.rst index b20b1c8396..1dae9d0b7d 100644 --- a/doc/arm/build.rst +++ b/doc/arm/build.rst @@ -12,21 +12,6 @@ Building BIND 9 --------------- -At a minimum, BIND requires a Unix or Linux system with an ANSI C -compiler, basic POSIX support, and a 64-bit integer type. BIND also -requires the ``libuv`` asynchronous I/O library, the ``nghttp2`` HTTP/2 -library, the ``jemalloc`` memory allocation library, and the OpenSSL -cryptography library. On Linux, BIND requires the ``libcap`` library to -set process privileges, though this requirement can be overridden by -disabling capability support at compile time. See `Compile-time -options <#opts>`__ below for details on other libraries that may be -required to support optional features. - -Successful builds have been observed on many versions of Linux and Unix, -including RHEL/CentOS/Oracle Linux, Fedora, Debian, Ubuntu, SLES, -openSUSE, Slackware, Alpine, FreeBSD, NetBSD, OpenBSD, macOS, Solaris, -OpenIndiana, OmniOS CE, HP-UX, and OpenWRT. - To build on a Unix or Linux system, use: :: @@ -70,37 +55,42 @@ https://developer.apple.com/download/more/ or, if you have Xcode already installed, you can run ``xcode-select --install``. (Note that an Apple ID may be required to access the download page.) -Dependencies -~~~~~~~~~~~~ +.. _build_dependencies: + +Required libraries +~~~~~~~~~~~~~~~~~~ To build BIND you need to have the following packages installed: -:: +- ``libuv`` for asynchronous I/O operations and event loops +- ``libssl`` and ``libcrypto`` from OpenSSL for cryptography +- ``pkg-config / pkgconfig / pkgconf`` for build system support - libuv - pkg-config / pkgconfig / pkgconf +BIND 9.19 requires a fairly recent version of ``libuv`` (at least 1.x). +For some older systems, you will have to install an updated ``libuv`` +package from sources such as EPEL, PPA, or other native sources for updated +packages. The other option is to build and install ``libuv`` from source. + +OpenSSL 1.0.2e or newer is required. +If the OpenSSL library is installed in a nonstandard location, +specify the prefix using ``--with-openssl=`` on the +configure command line. To use a PKCS#11 hardware service module for +cryptographic operations, it will be necessary to compile and use +engine_pkcs11 from the OpenSC project. To build BIND from the git repository, you need the following tools installed: -:: +- ``autoconf`` (includes autoreconf) +- ``automake`` +- ``libtool`` - autoconf (includes autoreconf) - automake - libtool - -Compile-time options -~~~~~~~~~~~~~~~~~~~~ +Optional features +~~~~~~~~~~~~~~~~~ To see a full list of configuration options, run ``configure --help``. -For the server to support DNSSEC, you need to build it with crypto -support. To use OpenSSL, you must have OpenSSL 1.0.2e or newer -installed. If the OpenSSL library is installed in a nonstandard -location, specify the prefix using ``--with-openssl=`` on the -configure command line. To use a PKCS#11 hardware service module for -cryptographic operations, it will be necessary to compile and use -engine_pkcs11 from the OpenSC project. +To improve performance, ``libjemalloc`` library is strongly recommended. To support DNS over HTTPS, the server must be linked with ``libnghttp2``. @@ -133,6 +123,13 @@ https://github.com/farsightsec/fstrm and ``libprotobuf-c`` https://developers.google.com/protocol-buffers, and BIND must be configured with ``--enable-dnstap``. +To support internationalized domain names in ``dig``, you must have installed +``libidn2``. If the library is installed in a nonstandard location, specify +the prefix using ``--with-libidn2=/prefix`` or adjust ``PKG_CONFIG_PATH``. + +For line editing in ``nsupdate`` and ``nslookup``, you must have installed +``readline`` library. + Certain compiled-in constants and default settings can be decreased to values better suited to small machines, e.g. OpenWRT boxes, by specifying ``--with-tuning=small`` on the ``configure`` command line. diff --git a/doc/arm/platforms.rst b/doc/arm/platforms.rst index 913f65d8d9..9fb8069a1b 100644 --- a/doc/arm/platforms.rst +++ b/doc/arm/platforms.rst @@ -11,7 +11,7 @@ .. _supported_os: -Supported platforms +Supported Platforms ------------------- Current support status of various platforms and BIND 9 versions can be @@ -21,16 +21,8 @@ https://kb.isc.org/docs/supported-platforms In general, this version of BIND will build and run on any POSIX-compliant system with a C11-compliant C compiler, BSD-style -sockets with RFC-compliant IPv6 support, and POSIX-compliant threads, -plus the following mandatory libraries: - -- ``libuv`` for asynchronous I/O operations and event loops -- ``libssl`` and ``libcrypto`` from OpenSSL for cryptography - -Use of the following libraries is optional: - -- ``libjemalloc`` for improved memory allocation performance -- ``libnghttp2`` for DNS-over-HTTPS (DoH) support +sockets with RFC-compliant IPv6 support, POSIX-compliant threads, and +the :ref:`required libraries `. The following C11 features are used in BIND 9: @@ -43,24 +35,6 @@ The following C11 features are used in BIND 9: The C11 variants are preferred. -BIND 9.19 requires a fairly recent version of ``libuv`` (at least 1.x). -For some of the older systems listed below, you will have to install an -updated ``libuv`` package from sources such as EPEL, PPA, or other -native sources for updated packages. The other option is to build and -install ``libuv`` from source. - -Certain optional BIND features have additional library dependencies. -These include: - -- ``libfstrm`` and ``libprotobuf-c`` for DNSTAP -- ``libidn2`` for display of internationalized domain names in ``dig`` -- ``libjson-c`` for JSON statistics -- ``libmaxminddb`` for geolocation -- ``libnghttp2`` for DNS over HTTPS -- ``libxml2`` for XML statistics -- ``libz`` for compression of the HTTP statistics channel -- ``readline`` for line editing in ``nsupdate`` and ``nslookup`` - ISC regularly tests BIND on many operating systems and architectures, but lacks the resources to test all of them. Consequently, ISC is only able to offer support on a “best effort” basis for some. @@ -121,7 +95,7 @@ supported platforms. - Debian Jessie - FreeBSD 10.x, 11.x -Unsupported platforms +Unsupported Platforms --------------------- These are platforms on which BIND 9.19 is known *not* to build or run: From 4b1c70de90b3aefdd03cde91e78b17276c41d750 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 20 Jan 2022 11:31:40 +0100 Subject: [PATCH 11/15] Rework doc/arm/build.rst - Revise the list of required libraries. - Apply miscellaneous tweaks to style, formatting, and ordering. --- doc/arm/build.rst | 167 ++++++++++++++++++++++++---------------------- 1 file changed, 89 insertions(+), 78 deletions(-) diff --git a/doc/arm/build.rst b/doc/arm/build.rst index 1dae9d0b7d..a243511907 100644 --- a/doc/arm/build.rst +++ b/doc/arm/build.rst @@ -16,14 +16,12 @@ To build on a Unix or Linux system, use: :: - $ autoreconf -fi (if you are building in the git repository) - $ ./configure - $ make + $ autoreconf -fi ### (only if building from the git repository) + $ ./configure + $ make -If you’re using Emacs, you might find ``make tags`` helpful. - -Several environment variables, which can be set before running -``configure``, affect compilation. Significant ones are: +Several environment variables affect compilation, and they can be set +before running ``configure``. The most significant ones are: +--------------------+-------------------------------------------------+ | Variable | Description | @@ -31,11 +29,11 @@ Several environment variables, which can be set before running | ``CC`` | The C compiler to use. ``configure`` tries to | | | figure out the right one for supported systems. | +--------------------+-------------------------------------------------+ -| ``CFLAGS`` | C compiler flags. Defaults to include -g and/or | -| | -O2 as supported by the compiler. Please | -| | include ‘-g’ if you need to set ``CFLAGS``. | +| ``CFLAGS`` | The C compiler flags. Defaults to include -g | +| | and/or -O2 as supported by the compiler. Please | +| | include ``-g`` if ``CFLAGS`` needs to be set. | +--------------------+-------------------------------------------------+ -| ``LDFLAGS`` | Linker flags. Defaults to empty string. | +| ``LDFLAGS`` | The linker flags. Defaults to an empty string. | +--------------------+-------------------------------------------------+ Additional environment variables affecting the build are listed at the @@ -44,91 +42,93 @@ command: :: - $ ./configure --help + $ ./configure --help -macOS -~~~~~ - -Building on macOS assumes that the “Command Tools for Xcode” are -installed. These can be downloaded from -https://developer.apple.com/download/more/ or, if you have Xcode already -installed, you can run ``xcode-select --install``. (Note that an Apple -ID may be required to access the download page.) +If using Emacs, the ``make tags`` command may be helpful. .. _build_dependencies: -Required libraries +Required Libraries ~~~~~~~~~~~~~~~~~~ -To build BIND you need to have the following packages installed: +To build BIND 9, the following packages must be installed: -- ``libuv`` for asynchronous I/O operations and event loops -- ``libssl`` and ``libcrypto`` from OpenSSL for cryptography -- ``pkg-config / pkgconfig / pkgconf`` for build system support +- ``libcrypto``, ``libssl`` +- ``libuv`` +- ``perl`` +- ``pkg-config`` / ``pkgconfig`` / ``pkgconf`` -BIND 9.19 requires a fairly recent version of ``libuv`` (at least 1.x). -For some older systems, you will have to install an updated ``libuv`` -package from sources such as EPEL, PPA, or other native sources for updated -packages. The other option is to build and install ``libuv`` from source. +BIND 9.19 requires ``libuv`` 1.x or higher. On older systems, an updated +``libuv`` package needs to be installed from sources such as EPEL, PPA, +or other native sources. The other option is to build and install +``libuv`` from source. -OpenSSL 1.0.2e or newer is required. -If the OpenSSL library is installed in a nonstandard location, -specify the prefix using ``--with-openssl=`` on the -configure command line. To use a PKCS#11 hardware service module for -cryptographic operations, it will be necessary to compile and use -engine_pkcs11 from the OpenSC project. +OpenSSL 1.0.2e or newer is required. If the OpenSSL library is installed +in a nonstandard location, specify the prefix using +``--with-openssl=`` on the ``configure`` command line. To use a +PKCS#11 hardware service module for cryptographic operations, +``engine_pkcs11`` from the OpenSC project must be compiled and used. -To build BIND from the git repository, you need the following tools +To build BIND from the git repository, the following tools must also be installed: -- ``autoconf`` (includes autoreconf) +- ``autoconf`` (includes ``autoreconf``) - ``automake`` - ``libtool`` -Optional features +Optional Features ~~~~~~~~~~~~~~~~~ To see a full list of configuration options, run ``configure --help``. -To improve performance, ``libjemalloc`` library is strongly recommended. +To improve performance, use of the ``jemalloc`` library +(http://jemalloc.net/) is strongly recommended. -To support DNS over HTTPS, the server must be linked with -``libnghttp2``. +To support :rfc:`DNS over HTTPS (DoH) <8484>`, the server must be linked +with ``libnghttp2`` (https://nghttp2.org/). If the library is +unavailable, ``--disable-doh`` can be used to disable DoH support. To support the HTTP statistics channel, the server must be linked with -at least one of the following libraries: ``libxml2`` http://xmlsoft.org -or ``json-c`` https://github.com/json-c/json-c. If these are installed -at a nonstandard location, then: +at least one of the following libraries: ``libxml2`` +(http://xmlsoft.org) or ``json-c`` (https://github.com/json-c/json-c). +If these are installed at a nonstandard location, then: -- for ``libxml2``, specify the prefix using ``--with-libxml2=/prefix``. -- for ``json-c``, adjust ``PKG_CONFIG_PATH``. +- for ``libxml2``, specify the prefix using ``--with-libxml2=/prefix``, +- for ``json-c``, adjust ``PKG_CONFIG_PATH``. To support compression on the HTTP statistics channel, the server must -be linked against ``libzlib``. If this is installed in a nonstandard -location, specify the prefix using ``--with-zlib=/prefix``. +be linked against ``zlib`` (https://zlib.net/). If this is installed in +a nonstandard location, specify the prefix using +``--with-zlib=/prefix``. To support storing configuration data for runtime-added zones in an LMDB -database, the server must be linked with ``liblmdb``. If this is -installed in a nonstandard location, specify the prefix using -``with-lmdb=/prefix``. +database, the server must be linked with ``liblmdb`` +(https://github.com/LMDB/lmdb). If this is installed in a nonstandard +location, specify the prefix using ``--with-lmdb=/prefix``. To support MaxMind GeoIP2 location-based ACLs, the server must be linked -with ``libmaxminddb``. This is turned on by default if the library is -found; if the library is installed in a nonstandard location, specify -the prefix using ``--with-maxminddb=/prefix``. GeoIP2 support can be -switched off with ``--disable-geoip``. +with ``libmaxminddb`` (https://maxmind.github.io/libmaxminddb/). This is +turned on by default if the library is found; if the library is +installed in a nonstandard location, specify the prefix using +``--with-maxminddb=/prefix``. GeoIP2 support can be switched off with +``--disable-geoip``. -For DNSTAP packet logging, you must have installed ``libfstrm`` -https://github.com/farsightsec/fstrm and ``libprotobuf-c`` -https://developers.google.com/protocol-buffers, and BIND must be -configured with ``--enable-dnstap``. +For DNSTAP packet logging, ``libfstrm`` +(https://github.com/farsightsec/fstrm) and ``libprotobuf-c`` +(https://developers.google.com/protocol-buffers) must be installed, and +BIND must be configured with ``--enable-dnstap``. -To support internationalized domain names in ``dig``, you must have installed -``libidn2``. If the library is installed in a nonstandard location, specify -the prefix using ``--with-libidn2=/prefix`` or adjust ``PKG_CONFIG_PATH``. +To support internationalized domain names in ``dig``, ``libidn2`` +(https://www.gnu.org/software/libidn/#libidn2) must be installed. If the +library is installed in a nonstandard location, specify the prefix using +``--with-libidn2=/prefix`` or adjust ``PKG_CONFIG_PATH``. -For line editing in ``nsupdate`` and ``nslookup``, you must have installed -``readline`` library. +For line editing in ``nsupdate`` and ``nslookup``, either the +``readline`` (https://tiswww.case.edu/php/chet/readline/rltop.html) or +the ``libedit`` library (https://www.thrysoee.dk/editline/) must be +installed. If these are installed at a nonstandard location, adjust +``PKG_CONFIG_PATH``. ``readline`` is used by default, and ``libedit`` +can be explicitly requested using ``--with-readline=libedit``. Certain compiled-in constants and default settings can be decreased to values better suited to small machines, e.g. OpenWRT boxes, by @@ -137,32 +137,43 @@ This decreases memory usage by using smaller structures, but degrades performance. On Linux, process capabilities are managed in user space using the -``libcap`` library, which can be installed on most Linux systems via the -``libcap-dev`` or ``libcap-devel`` package. Process capability support -can also be disabled by configuring with ``--disable-linux-caps``. +``libcap`` library +(https://git.kernel.org/pub/scm/libs/libcap/libcap.git/), which can be +installed on most Linux systems via the ``libcap-dev`` or +``libcap-devel`` package. Process capability support can also be +disabled by configuring with ``--disable-linux-caps``. On some platforms it is necessary to explicitly request large file support to handle files bigger than 2GB. This can be done by using ``--enable-largefile`` on the ``configure`` command line. -Support for the “fixed” rrset-order option can be enabled or disabled by +Support for the “fixed” RRset-order option can be enabled or disabled by specifying ``--enable-fixed-rrset`` or ``--disable-fixed-rrset`` on the -configure command line. By default, fixed rrset-order is disabled to +``configure`` command line. By default, fixed RRset-order is disabled to reduce memory footprint. -The ``--enable-querytrace`` option causes ``named`` to log every step of -processing every query. The ``--enable-singletrace`` option turns on the -same verbose tracing, but allows an individual query to be separately -traced by setting its query ID to 0. These options should only be -enabled when debugging, because they have a significant negative impact -on query performance. +The ``--enable-querytrace`` option causes ``named`` to log every step +while processing every query. The ``--enable-singletrace`` option turns +on the same verbose tracing, but allows an individual query to be +separately traced by setting its query ID to 0. These options should +only be enabled when debugging, because they have a significant negative +impact on query performance. ``make install`` installs ``named`` and the various BIND 9 libraries. By default, installation is into /usr/local, but this can be changed with the ``--prefix`` option when running ``configure``. -You may specify the option ``--sysconfdir`` to set the directory where -configuration files like ``named.conf`` go by default, and -``--localstatedir`` to set the default parent directory of +The option ``--sysconfdir`` can be specified to set the directory where +configuration files such as ``named.conf`` go by default; +``--localstatedir`` can be used to set the default parent directory of ``run/named.pid``. ``--sysconfdir`` defaults to ``$prefix/etc`` and ``--localstatedir`` defaults to ``$prefix/var``. + +macOS +~~~~~ + +Building on macOS assumes that the “Command Tools for Xcode” are +installed. These can be downloaded from +https://developer.apple.com/download/more/ or, if Xcode is already +installed, simply run ``xcode-select --install``. (Note that an Apple ID +may be required to access the download page.) From b1af79acc70d9a7dbe0352f5150494e434b9670a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 20 Jan 2022 14:07:25 +0100 Subject: [PATCH 12/15] Add RFCs listed in doc/misc/rfc-compliance to doc/arm/general.rst There were three RFCs listed in list of "RFCs we implement" but missing in the ARM. Command to compare lists in the two documents: diff <(grep -o '^ RFC[0-9]\+' doc/misc/rfc-compliance | sed -e 's/[^0-9]//g' | sort -n) <(grep '^:rfc:`' doc/arm/general.rst | sed -e 's/^.*`\([0-9]*\)`.*$/\1/' | sort -n) --- doc/arm/general.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/arm/general.rst b/doc/arm/general.rst index 77348f8253..28107748f6 100644 --- a/doc/arm/general.rst +++ b/doc/arm/general.rst @@ -243,6 +243,9 @@ Implementation Notes for DNS Security (DNSSEC).* February 2013. [11] :rfc:`7216` - M. Thomson and R. Bellis. *Location Information Server (LIS) Discovery Using IP Addresses and Reverse DNS.* April 2014. +:rfc:`7050` - T. Savolainen, J. Korhonen, and D. Wing. *Discovery of the IPv6 +Prefix Used for IPv6 Address Synthesis.* November 2013. [21] + :rfc:`7344` - W. Kumari, O. Gudmundsson, and G. Barwood. *Automating DNSSEC Delegation Trust Maintenance.* September 2014. [12] @@ -257,9 +260,15 @@ Wessels. *DNS Transport over TCP - Implementation Requirements.* March 2016. :rfc:`7830` - A. Mayrhofer. *The EDNS(0) Padding Option.* May 2016. [13] +:rfc:`8078` - O. Gudmundsson and P. Wouters. *Managing DS Records from the +Parent via CDS/CDNSKEY.* March 2017. [22] + :rfc:`8080` - O. Sury and R. Edmonds. *Edwards-Curve Digital Security Algorithm (EdDSA) for DNSSEC.* February 2017. +:rfc:`8880` - S. Cheshire and D. Schinazi. *Special Use Domain Name +'ipv4only.arpa'.* August 2020. + :rfc:`8482` - J. Abley, O. Gudmundsson, M. Majkowski, and E. Hunt. *Providing Minimal-Sized Responses to DNS Queries That Have QTYPE=ANY.* January 2019. @@ -369,6 +378,9 @@ March 1999. :rfc:`3123` - P. Koch. *A DNS RR Type for Lists of Address Prefixes (APL RR).* June 2001. +:rfc:`5205` - P. Nikander and J. Laganier. *Host Identity Protocol (HIP) +Domain Name System (DNS) Extension.* April 2008. + :rfc:`6742` - RJ Atkinson, SN Bhatti, U. St. Andrews, and S. Rose. *DNS Resource Records for the Identifier-Locator Network Protocol (ILNP).* November 2012. @@ -592,6 +604,10 @@ everywhere with or without ``--with-libidn2``. [20] Section 5.1 - DNAME records are fully supported. +[21] RFC 7050 is updated by RFC 8880. + +[22] Updating of parent zones is not yet implemented. + .. _internet_drafts: Internet Drafts From 4379e16996d2505cf004c52d72982e2dc28babbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 20 Jan 2022 17:04:00 +0100 Subject: [PATCH 13/15] Reword RFC section in the ARM Add couple links and caveant for uninitiated readers. --- doc/arm/general.rst | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/doc/arm/general.rst b/doc/arm/general.rst index 28107748f6..36a27a61af 100644 --- a/doc/arm/general.rst +++ b/doc/arm/general.rst @@ -63,17 +63,27 @@ Bibliography (and Suggested Reading) Requests for Comment (RFCs) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Specification documents for the Internet protocol suite, including the +DNS, are published as part of the `Request for Comments`_ (RFCs) series +of technical notes. The standards themselves are defined by the +`Internet Engineering Task Force`_ (IETF) and the `Internet Engineering +Steering Group`_ (IESG). RFCs can be viewed online at: +https://www.rfc-editor.org/. + +While reading RFCs, please keep in mind that :rfc:`not all RFCs are +standards <1796>`, and also that the validity of documents does change +over time. Every RFC needs to be interpreted in the context of other +documents. + BIND 9 strives for strict compliance with IETF standards. To the best of our knowledge, BIND 9 complies with the following RFCs, with the caveats and exceptions listed in the numbered notes below. Many of these RFCs were written by current or former ISC staff members. The list is non-exhaustive. -Specification documents for the Internet protocol suite, including the -DNS, are published as part of the Request for Comments (RFCs) series of -technical notes. The standards themselves are defined by the Internet -Engineering Task Force (IETF) and the Internet Engineering Steering -Group (IESG). RFCs can be viewed online at: https://datatracker.ietf.org/doc/ . +.. _Internet Engineering Steering Group: https://www.ietf.org/about/groups/iesg/ +.. _Internet Engineering Task Force: https://www.ietf.org/about/ +.. _Request for Comments: https://www.ietf.org/standards/rfcs/ Some of these RFCs, though DNS-related, are not concerned with implementing software. From 8c82b0f2d02c0d2b0ac4c43ca82cba589fb6edf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 20 Jan 2022 17:18:06 +0100 Subject: [PATCH 14/15] Remove RFCs not implemented in BIND from list in the ARM This commit partially removes extra RFCs which are not listed in file doc/misc/rfc-compliance. Most of the removed RFCs are either outright obsolete, irrelevant, or not implemented. Rationale: - 974 - obsolete - 1033 - ops info, hardly followed today - 1464 - ops info - 1591 - policy - 1537 - obsolete - 1713 - obsolete - 1794 - notimp - 2010 - ops info - 2052 - obsolete - 2065 - obsolete - 2137 - obsolete - 2168 - obsolete - 2240 - obsolete - 2345 - not dns - 2352 - not dns - 2540 - notimp - 2825 - notimp, info, obsolete - 2826 - notimp - 2929 - obsolete - 3071 - policy - 3090 - obsolete - 3258 - notimp - 6594 - iana, SSHFP - 7216 - not dns - 8482 - notimp - 8490 - notimp Probably most notable RFCs removed are: - 8482 for special ANY handling - 8490 for Stateful Operations As far as I can tell BIND does not implement those. --- doc/arm/general.rst | 73 --------------------------------------------- 1 file changed, 73 deletions(-) diff --git a/doc/arm/general.rst b/doc/arm/general.rst index 36a27a61af..a6402a0b82 100644 --- a/doc/arm/general.rst +++ b/doc/arm/general.rst @@ -227,10 +227,6 @@ Addressing of IPv4/IPv6 Translators.* October 2010. *DNS64: DNS Extensions for Network Address Translation from IPv6 Clients to IPv4 Servers.* April 2011. [8] -:rfc:`6594` - O. Sury. *Use of the SHA-256 Algorithm with RSA, Digital -Signature Algorithm (DSA), and Elliptic Curve DSA (ECDSA) in SSHFP Resource -Records.* April 2012. - :rfc:`6604` - D. Eastlake, 3rd. *xNAME RCODE and Status Bits Clarification.* April 2012. @@ -250,9 +246,6 @@ Updates.* August 2012. [10] :rfc:`6840` - S. Weiler, Ed., and D. Blacka, Ed. *Clarifications and Implementation Notes for DNS Security (DNSSEC).* February 2013. [11] -:rfc:`7216` - M. Thomson and R. Bellis. *Location Information Server (LIS) -Discovery Using IP Addresses and Reverse DNS.* April 2014. - :rfc:`7050` - T. Savolainen, J. Korhonen, and D. Wing. *Discovery of the IPv6 Prefix Used for IPv6 Address Synthesis.* November 2013. [21] @@ -279,12 +272,6 @@ Parent via CDS/CDNSKEY.* March 2017. [22] :rfc:`8880` - S. Cheshire and D. Schinazi. *Special Use Domain Name 'ipv4only.arpa'.* August 2020. -:rfc:`8482` - J. Abley, O. Gudmundsson, M. Majkowski, and E. Hunt. *Providing -Minimal-Sized Responses to DNS Queries That Have QTYPE=ANY.* January 2019. - -:rfc:`8490` - R. Bellis, S. Cheshire, J. Dickinson, S. Dickinson, T. Lemon, -and T. Pusateri. *DNS Stateful Operations.* March 2019. - :rfc:`8624` - P. Wouters and O. Sury. *Algorithm Implementation Requirements and Usage Guidance for DNSSEC.* June 2019. @@ -300,35 +287,14 @@ Deployed DNS Software.* October 1993. :rfc:`1536` - A. Kumar, J. Postel, C. Neuman, P. Danzig, and S. Miller. *Common DNS Implementation Errors and Suggested Fixes.* October 1993. -:rfc:`1591` - J. Postel. *Domain Name System Structure and Delegation.* March 1994. - :rfc:`1706` - B. Manning and R. Colella. *DNS NSAP Resource Records.* October 1994. -:rfc:`1713` - A. Romao. *Tools for DNS Debugging.* November 1994. - -:rfc:`1794` - T. Brisco. *DNS Support for Load Balancing.* April 1995. - :rfc:`1912` - D. Barr. *Common DNS Operational and Configuration Errors.* February 1996. :rfc:`2230` - R. Atkinson. *Key Exchange Delegation Record for the DNS.* November 1997. -:rfc:`2352` - O. Vaughan. *A Convention for Using Legal Names as Domain Names.* May -1998. - -:rfc:`2825` - IAB and L. Daigle. *A Tangled Web: Issues of I18N, Domain Names, and -the Other Internet Protocols.* May 2000. - -:rfc:`2826` - Internet Architecture Board. *IAB Technical Comment on the Unique -DNS Root.* May 2000. - -:rfc:`3071` - J. Klensin. *Reflections on the DNS, RFC 1591, and Categories of -Domains.* February 2001. - -:rfc:`3258` - T. Hardie. *Distributing Authoritative Name Servers via Shared -Unicast Addresses.* April 2002. - :rfc:`3363` - R. Bush, A. Durand, B. Fink, O. Gudmundsson, and T. Hain. *Representing Internet Protocol Version 6 (IPv6) Addresses in the Domain Name System (DNS).* August 2002. [14] @@ -370,21 +336,12 @@ Experimental RFCs :rfc:`1183` - C. F. Everhart, L. A. Mamakos, R. Ullmann, P. Mockapetris. *New DNS RR Definitions.* October 1990. -:rfc:`1464` - R. Rosenbaum. *Using the Domain Name System to Store Arbitrary -String Attributes.* May 1993. - :rfc:`1712` - C. Farrell, M. Schulze, S. Pleitner, and D. Baldoni. *DNS Encoding of Geographical Location.* November 1994. :rfc:`1876` - C. Davis, P. Vixie, T. Goodwin, and I. Dickinson. *A Means for Expressing Location Information in the Domain Name System.* January 1996. -:rfc:`2345` - J. Klensin, T. Wolf, and G. Oglesby. *Domain Names and Company Name -Retrieval.* May 1998. - -:rfc:`2540` - D. Eastlake, 3rd. *Detached Domain Name System (DNS) Information.* -March 1999. - :rfc:`3123` - P. Koch. *A DNS RR Type for Lists of Address Prefixes (APL RR).* June 2001. @@ -438,43 +395,19 @@ Aggregation and Renumbering.* July 2000. [4] RFCs of Type "Unknown" ---------------------- -:rfc:`1033` - M. Lottor. *Domain Administrators Operations Guide.* November 1987. - :rfc:`1101` - P. Mockapetris. *DNS Encoding of Network Names and Other Types.* April 1989. Obsoleted and Unimplemented Experimental RFCs --------------------------------------------- -:rfc:`974` - C. Partridge. *Mail Routing and the Domain System.* January 1986. - :rfc:`1521` - N. Borenstein and N. Freed. *MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies.* September 1993 [16] -:rfc:`1537` - P. Beertema. *Common DNS Data File Configuration Errors.* October -1993. - :rfc:`1750` - D. Eastlake, 3rd, S. Crocker, and J. Schiller. *Randomness Recommendations for Security.* December 1994. -:rfc:`2010` - B. Manning and P. Vixie. *Operational Criteria for Root Name Servers.* -October 1996. - -:rfc:`2052` - A. Gulbrandsen and P. Vixie. *A DNS RR for Specifying the Location of -Services.* October 1996. - -:rfc:`2065` - D. Eastlake, 3rd and C. Kaufman. *Domain Name System Security Extensions.* -January 1997. - -:rfc:`2137` - D. Eastlake, 3rd. *Secure Domain Name System Dynamic Update.* April -1997. - -:rfc:`2168` - R. Daniel and M. Mealling. *Resolution of Uniform Resource Identifiers -Using the Domain Name System.* June 1997. - -:rfc:`2240` - O. Vaughan. *A Legal Basis for Domain Name Allocation.* November 1997. - :rfc:`2535` - D. Eastlake, 3rd. *Domain Name System Security Extensions.* March 1999. [17] [18] @@ -493,15 +426,9 @@ Name System (DNS).* March 1999. :rfc:`2915` - M. Mealling and R. Daniel. *The Naming Authority Pointer (NAPTR) DNS Resource Record.* September 2000. -:rfc:`2929` - D. Eastlake, 3rd, E. Brunner-Williams, and B. Manning. *Domain Name System -(DNS) IANA Considerations.* September 2000. - :rfc:`3008` - B. Wellington. *Domain Name System Security (DNSSEC) Signing Authority.* November 2000. -:rfc:`3090` - E. Lewis. *DNS Security Extension Clarification on Zone Status.* -March 2001. - :rfc:`3152` - R. Bush. *Delegation of IP6.ARPA.* August 2001. :rfc:`3445` - D. Massey and S. Rose. *Limiting the Scope of the KEY Resource Record From ee3ba3cac99a7708322d6a0731e24bbc4a159448 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Fri, 21 Jan 2022 13:46:49 +0100 Subject: [PATCH 15/15] Fix incorrect RFC footnote about A6 RR type in RFC4033 A6 type is not mentioned anywhere in RFC4033. --- doc/arm/general.rst | 2 +- doc/misc/rfc-compliance | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/arm/general.rst b/doc/arm/general.rst index a6402a0b82..16bdde269a 100644 --- a/doc/arm/general.rst +++ b/doc/arm/general.rst @@ -170,7 +170,7 @@ DNS (GSS-TSIG).* October 2003. DNS.* March 2005. :rfc:`4033` - R. Arends, R. Austein, M. Larson, D. Massey, and S. Rose. *DNS Security -Introduction and Requirements.* March 2005. [4] +Introduction and Requirements.* March 2005. :rfc:`4034` - R. Arends, R. Austein, M. Larson, D. Massey, and S. Rose. *Resource Records for the DNS Security Extensions.* March 2005. diff --git a/doc/misc/rfc-compliance b/doc/misc/rfc-compliance index 4f9bf24832..9e40d30ad4 100644 --- a/doc/misc/rfc-compliance +++ b/doc/misc/rfc-compliance @@ -57,7 +57,7 @@ or Best Current Practice (BCP) documents. The list is non exhaustive. RFC3597 RFC3645 RFC4025 - RFC4033 [18] + RFC4033 RFC4034 RFC4035 RFC4074