## File: README.md PowerDNS is copyright © by PowerDNS.COM BV and lots of contributors, using the GNU GPLv2 license (see NOTICE for the exact license and exception used). All documentation can be found on https://doc.powerdns.com/ This file may lag behind at times. For most recent updates, always check https://doc.powerdns.com/authoritative/changelog/ Another good place to look for information is: https://doc.powerdns.com/authoritative/appendices/compiling.html To file bugs, head towards: https://github.com/PowerDNS/pdns/issues But please check if the issue is already reported there first. DOCKER ------ This README is mirrored from GitHub to dockerhub. For information about our Docker images, please refer to https://github.com/PowerDNS/pdns/blob/master/Docker-README.md SOURCE CODE / GIT ----------------- Source code is available on GitHub: ```sh git clone https://github.com/PowerDNS/pdns.git ``` This repository contains the sources for the PowerDNS Recursor, the PowerDNS Authoritative Server, and dnsdist (a powerful DNS loadbalancer). All three can be built from this repository. However, they are also released separately as .tar.bz2, .deb, and .rpm packages. The different releases can be built by the help of pdns-builder, which uses a docker-based build process. To get started with this, run these commands in the root of this repository: ```sh git submodule init git submodule update ./builder/build.sh ``` This will bring up a USAGE-page which will explain how to build the different releases. COMPILING Authoritative Server ------------------------------ The PowerDNS Authoritative Server depends on Boost, OpenSSL and Lua, and requires a compiler with C++-2017 support. On Debian, the following is useful: ```sh apt install g++ libboost-all-dev libtool make pkg-config default-libmysqlclient-dev libssl-dev libluajit-5.1-dev python3-venv ``` When building from git, the following packages are also required: ```sh apt install autoconf automake ragel bison flex ``` For Ubuntu, the following packages should be installed: ```sh apt install libcurl4-openssl-dev luajit lua-yaml-dev libyaml-cpp-dev libtolua-dev lua5.3 autoconf automake ragel bison flex g++ libboost-all-dev libtool make pkg-config libssl-dev lua-yaml-dev libyaml-cpp-dev libluajit-5.1-dev libcurl4 gawk libsqlite3-dev python3-venv # For DNSSEC ed25519 (algorithm 15) support with --with-libsodium apt install libsodium-dev # If using the gmysql (Generic MySQL) backend apt install default-libmysqlclient-dev # If using the gpgsql (Generic PostgreSQL) backend apt install libpq-dev # If using --enable-systemd (will create the service scripts so it can be managed with systemctl/service) apt install libsystemd0 libsystemd-dev # If using the geoip backend apt install libmaxminddb-dev libmaxminddb0 libgeoip1 libgeoip-dev ``` Then generate the configure file: ```sh autoreconf -vi ``` To compile a very clean version, use: ```sh ./configure --with-modules="" --disable-lua-records make # make install ``` This generates a PowerDNS Authoritative Server binary with no modules built in. See https://doc.powerdns.com/authoritative/backends/index.html for a list of available modules. When `./configure` is run without `--with-modules`, the bind and gmysql module are built-in by default and the pipe-backend is compiled for runtime loading. To add multiple modules, try: ```sh ./configure --with-modules="bind gmysql gpgsql" ``` Note that you will need the development headers for PostgreSQL as well in this case. See https://doc.powerdns.com/authoritative/appendices/compiling.html for more details. If you run into C++11-related symbol trouble, please try passing `CPPFLAGS=-D_GLIBCXX_USE_CXX11_ABI=0` (or 1) to `./configure` to make sure you are compatible with the installed dependencies. Compiling the Recursor ---------------------- See [README.md](pdns/recursordist/README.md) in `pdns/recursordist/`. Compiling dnsdist ----------------- See [README.md](pdns/dnsdistdist/README.md) in `pdns/dnsdistdist`. Building the HTML documentation ------------------------------- The HTML documentation (as seen [on the PowerDNS docs site](https://doc.powerdns.com/authoritative/)) is built from ReStructured Text (rst) files located in `docs`. They are compiled into HTML files using [Sphinx](https://www.sphinx-doc.org/en/master/index.html), a documentation generator tool which is built in Python. Install the dependencies under "COMPILING", and run autoreconf if you haven't already: ```sh autoreconf -vi ``` Enter the `docs` folder, and use make to build the HTML docs. ``` cd docs make html-docs ``` The HTML documentation will now be available in `html-docs`. FreeBSD Notes ------------- You need to compile using gmake - regular make only appears to work, but doesn't in fact. Use gmake, not make. The clang compiler installed through FreeBSD's package manager does not expose all of the C++17 features needed under the default `std=gnuc++14`. Force the compiler to use `std=c++17` mode instead. ```sh export CXXFLAGS=-std=c++17 ``` macOS Notes ----------- PowerDNS Authoritative Server is available through Homebrew: ``` brew install pdns ``` If you want to compile yourself, the dependencies can be installed using Homebrew. You need to tell configure where to find OpenSSL, too. ```sh brew install boost lua pkg-config ragel openssl ./configure --with-modules="" PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig make -j4 ``` Additionally, for PostgreSQL support, run `brew install postgresql` and add `--with-modules="gpgsql"` to `./configure`. For MySQL support, run `brew install mariadb` and add `--with-modules="gmysql"` to `./configure`. Linux notes ----------- None really. --- ## File: docs/backends/bind.rst BIND zone file backend ====================== * Native: Yes * Primary: Yes * Secondary: Yes * Producer: No * Consumer: No * Autosecondary: Experimental * DNS Update: No * DNSSEC: Yes * Disabled data: No * Comments: No * Search: Yes * Views: No * API: Read-only * Multiple instances: No * Zone caching: Yes * Module name: bind * Launch: ``bind`` The BIND backend started life as a demonstration of the versatility of PowerDNS but quickly gained in importance when there appeared to be demand for a BIND 'work-alike'. The BIND backend parses a BIND-style ``named.conf`` and extracts information about zones from it. It makes no attempt to honour other configuration flags, which you should configure (when available) using the PowerDNS native configuration. Unique to this PowerDNS backend is that it serves from plain zone files, which allows for hand-crafting zone files, only takes a tiny footprint in terms of server resource usage while being :ref:`performant efficiently `. .. note:: Because this backend retrieves its configuration from plain files and not a database, the HTTP API is unable to process changes for this backend. This effectively makes the API read-only for zones hosted by the BIND backend. Configuration Parameters ------------------------ .. _setting-bind-config: ``bind-config`` ~~~~~~~~~~~~~~~ Location of the BIND configuration file to parse. PowerDNS does not support every directive supported by BIND. It supports the following blocks and directives: * ``options`` * ``directory`` * ``also-notify`` * ``zone`` * ``file`` * ``type`` * ``masters`` * ``primaries`` (added in version 4.9.0) * ``also-notify`` Unknown directives will be ignored. .. _setting-bind-check-interval: ``bind-check-interval`` ~~~~~~~~~~~~~~~~~~~~~~~ Interval in seconds to check for zone file changes. Default is 0 (disabled). See :ref:`bind-operation` section for more information. .. _setting-bind-dnssec-db: ``bind-dnssec-db`` ~~~~~~~~~~~~~~~~~~ Filename to store and access our DNSSEC metadatabase, empty for none. To run secondary DNSSEC-enabled domains (where the RRSIGS are in the AXFR), a ``bind-dnssec-db`` is required. This is because the :ref:`metadata-presigned` domain metadata is set during the zonetransfer. You can use ``pdnsutil create-bind-db`` to make this database file for you. .. warning:: If this is left empty on slaves and a presigned zone is transferred, it will (silently) serve it without DNSSEC. This in turn results in serving the domain as bogus. .. _setting-bind-dnssec-db-journal-mode: ``bind-dnssec-db-journal-mode`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ SQLite3 journal mode to set. The default is WAL. Set to empty to leave the journal mode alone. .. _setting-bind-hybrid: ``bind-hybrid`` ~~~~~~~~~~~~~~~ Store DNSSEC keys and metadata storage in another backend. See the :ref:`dnssec-modes-hybrid-bind` documentation. .. _setting-bind-ignore-broken-records: ``bind-ignore-broken-records`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Setting this option to ``yes`` makes PowerDNS ignore out of zone records when loading zone files. Autoprimary support (experimental) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _setting-bind-autoprimaries: ``bind-autoprimaries`` ~~~~~~~~~~~~~~~~~~~~~~ .. versionchanged:: 4.9.0 This was called ``bind-supermasters`` before 4.9.0. Specifies file where to read list of autoprimaries. BIND backend only checks IP address of primary server. The file must contain one IP and account per line, separated by whitespace. BIND backend can only read this file, not write it. .. _setting-bind-autoprimary-config: ``bind-autoprimary-config`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionchanged:: 4.9.0 This was called ``bind-supermaster-config`` before 4.9.0. When a new zone is configured via the autosecondary mechanism, bindbackend *writes* a zone entry to this file. Your ``bind-config`` file should have an ``include`` statement to make sure this file is read on startup. .. _setting-bind-autoprimary-destdir: ``bind-autoprimary-destdir`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionchanged:: 4.9.0 This was called ``bind-supermaster-destdir`` before 4.9.0. Each new zone configured via the autosecondary mechanism gets a zone file in this directory. This directory must be writable. .. _bind-operation: Operation --------- On launch, the BIND backend first parses the ``named.conf`` to determine which zones need to be loaded. These will then be parsed and made available for serving, as they are parsed. So a ``named.conf`` with 100.000 zones may take 20 seconds to load, but after 10 seconds, 50.000 zones will already be available. While a domain is being loaded, it is not yet available, to prevent incomplete answers. Reloading is currently done only when a request (or zone transfer) for a zone comes in, and then only after :ref:`setting-bind-check-interval` seconds have passed since the last check. If a change occurred, access to the zone is disabled, the file is reloaded, access is restored, and the question is answered. For regular zones, reloading is fast enough to answer the question which lead to the reload within the DNS timeout. If :ref:`setting-bind-check-interval` is specified as zero, no checks will be performed until the ``pdns_control reload`` command is issued. Please note that also the :ref:`setting-xfr-cycle-interval` setting controls how often a primary would notify a secondary about changes. Especially in 'hidden primary' configurations, where servers usually don't receive regular queries, you may want to lower that setting to a value as low as :ref:`setting-bind-check-interval`. pdns\_control commands ---------------------- ``bind-add-zone `` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add zone ``domain`` from ``filename`` to PowerDNS's BIND backend. Zone will be loaded at first request. .. note:: This does not add the zone to the :ref:`setting-bind-config` file. ``bind-domain-extended-status [domain ...]`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 4.3.0 Output an extended status of a domain or domains, containing much more information than the simple domain status, like the number of records currently loaded, whether pdns is primary or secondary for the domain, the list of primaries, various timers, etc ``bind-domain-status [domain ...]`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Output status of domain or domains. Can be one of: * ``seen in named.conf, not parsed``, * ``parsed successfully at