diff options
Diffstat (limited to 'doc/arm/build.inc.rst')
| -rw-r--r-- | doc/arm/build.inc.rst | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/doc/arm/build.inc.rst b/doc/arm/build.inc.rst new file mode 100644 index 0000000..ccd0d32 --- /dev/null +++ b/doc/arm/build.inc.rst @@ -0,0 +1,183 @@ +.. 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. + +.. _build_bind: + +Building BIND 9 +--------------- + +To build on a Unix or Linux system, use: + +:: + + $ autoreconf -fi ### (only if building from the git repository) + $ ./configure + $ make + +Several environment variables affect compilation, and they can be set +before running ``configure``. The most significant ones are: + ++--------------------+-------------------------------------------------+ +| Variable | Description | ++====================+=================================================+ +| ``CC`` | The C compiler to use. ``configure`` tries to | +| | figure out the right one for supported systems. | ++--------------------+-------------------------------------------------+ +| ``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`` | The linker flags. Defaults to an 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 + +If using Emacs, the ``make tags`` command may be helpful. + +.. _build_dependencies: + +Required Libraries +~~~~~~~~~~~~~~~~~~ + +To build BIND 9, the following packages must be installed: + +- ``libcrypto``, ``libssl`` +- ``libuv`` +- ``perl`` +- ``pkg-config`` / ``pkgconfig`` / ``pkgconf`` + +BIND 9.18 requires ``libuv`` 1.0.0 or higher, using ``libuv`` >= 1.40.0 +is recommended. Compiling or running with ``libuv`` 1.35.0 or 1.36.0 is +not supported, as this could lead to an assertion failure in the UDP +receive code. 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=<PREFIX>`` 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, the following tools must also be +installed: + +- ``autoconf`` (includes ``autoreconf``) +- ``automake`` +- ``libtool`` + +Optional Features +~~~~~~~~~~~~~~~~~ + +To see a full list of configuration options, run ``configure --help``. + +To improve performance, use of the ``jemalloc`` library +(http://jemalloc.net/) is strongly recommended. + +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: + +- 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 ``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`` +(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`` (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, ``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 :iscman:`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 :iscman:`nsupdate` and :iscman:`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 +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 +(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 +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 :iscman:`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 :iscman:`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``. + +The option ``--sysconfdir`` can be specified to set the directory where +configuration files such as :iscman:`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.) |