kea/doc/sphinx/arm/ddns.rst

.. _dhcp-ddns-server:

********************
The DHCP-DDNS Server
********************

.. _dhcp-ddns-overview:

Overview
========

The DHCP-DDNS Server (:iscman:`kea-dhcp-ddns`, known informally as D2) conducts
the client side of the Dynamic DNS protocol (DDNS, defined in `RFC
2136 <https://tools.ietf.org/html/rfc2136>`__) on behalf of the DHCPv4
and DHCPv6 servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`, respectively).
The DHCP servers construct DDNS update requests, known as NameChangeRequests
(NCRs), based on DHCP lease change events and then post them to D2. D2
attempts to match each request to the appropriate DNS server(s) and
carries out the necessary conversation with those servers to update the
DNS data.

The Kea hook library :ischooklib:`libdhcp_ddns_tuning.so` provides the ability
for both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` to generate host names
procedurally based on an expression, to skip DDNS updates on a per-client basis,
or to fine-tune various DNS update aspects. Please refer to the :ref:`hooks-ddns-tuning`
documentation for the configuration options.

.. _dhcp-ddns-dns-server-selection:

DNS Server Selection
--------------------

To match a request to the appropriate DNS servers, D2 must have
a catalog of servers from which to select. In fact, D2 has two such
catalogs, one for forward DNS and one for reverse DNS; these catalogs
are referred to as "DDNS domain lists." Each list consists of one or more
named DDNS domains. Further, each DDNS domain has a list of one or more
DNS servers that publish the DNS data for that domain.

When conducting forward-domain matching, D2 compares the fully qualified
domain name (FQDN) in the request against the name of each forward DDNS
domain in its catalog. The domain whose name matches the longest portion
of the FQDN is considered the best match. For example, if the FQDN is
"myhost.sample.example.com.", and there are two forward domains in the
catalog, "sample.example.com." and "example.com.", the former is
regarded as the best match. In some cases, it may not be possible to
find a suitable match. Given the same two forward domains there would be
no match for the FQDN "bogus.net", so the request would be rejected.
Finally, if there are no forward DDNS domains defined, D2 simply
disregards the forward-update portion of requests.

When conducting reverse-domain matching, D2 constructs a reverse FQDN
from the lease address in the request and compares that against the name
of each reverse DDNS domain. Again, the domain whose name matches the
longest portion of the FQDN is considered the best match. For instance,
if the lease address is "172.16.1.40" and there are two reverse domains
in the catalog, "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the
former is the best match. As with forward matching, D2 may not find a
suitable match. Given the same two domains, there would be no match for
the lease address, "192.168.1.50", and the request would be rejected.
As with forward-domain matching, if there are no reverse DDNS domains defined, D2 simply
disregards the reverse-update portion of requests.

.. _dhcp-ddns-conflict-resolution:

Conflict Resolution
-------------------

D2 implements the conflict resolution strategy prescribed by `RFC
4703 <https://tools.ietf.org/html/rfc4703>`__. Conflict resolution is
intended to prevent different clients from mapping to the same FQDN at
the same time. To make this possible, the RFC requires that forward DNS
entries for a given FQDN must be accompanied by a DHCID resource record
(RR). This record contains a client identifier that uniquely identifies
the client to whom the name belongs. Furthermore, any DNS updater that
wishes to update or remove existing forward entries for an FQDN may only
do so if their client matches that of the DHCID RR.

In other words, the DHCID RR maps an FQDN to the client to whom it
belongs, and thereafter changes to that mapping can only be done by
or at the behest of that client.

Conflict resolution can be indirectly enabled or disabled via
the configuration parameter ``ddns-use-conflict-resolution``, supported
by both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`. These servers use this parameter to
set a flag within each NameChangeRequest they send that tells D2
whether conflict resolution should be employed for that request.
By default, conflict resolution is enabled. For more details, please refer
to discussions of ``ddns-use-conflict-resolution`` in :ref:`dhcp4-ddns-config` and :ref:`dhcp6-ddns-config`.

When conflict resolution is disabled, D2 still adds DHCID RRs but does
not use them to enforce client ownership of DNS entries. Disabling it should
only be used after careful consideration.

.. _dhcp-ddns-dual-stack:

Dual-Stack Environments
-----------------------

`RFC 4703, section
5.2, <https://tools.ietf.org/html/rfc4703#section-5.2>`__ describes
issues that may arise with dual-stack clients. These are clients that
wish to have both IPv4 and IPv6 mappings for the same FQDN.
To work properly, clients must embed their IPv6 DUID
within their IPv4 client identifier option, as described in `RFC
4361 <https://tools.ietf.org/html/rfc4361>`__. In this way, DNS updates
for both IPv4 and IPv6 can be managed under the same DHCID RR. This feature
is supported by Kea beginning with release 2.1.2.

.. _dhcp-ddns-server-start-stop:

Starting and Stopping the DHCP-DDNS Server
==========================================

:iscman:`kea-dhcp-ddns` is the Kea DHCP-DDNS server and, due to the nature of
DDNS, it runs alongside either the DHCPv4 or DHCPv6 component (or both).
Like other parts of Kea, it is a separate binary that can be run on its
own or through :iscman:`keactrl` (see :ref:`keactrl`). In normal
operation, controlling :iscman:`kea-dhcp-ddns` with :iscman:`keactrl` is
recommended; however, it is also possible to run the DHCP-DDNS server
directly. It accepts the following command-line switches:

-  ``-c file`` - specifies the configuration file. This is the only
   mandatory switch.

-  ``-d`` - specifies whether server logging should be switched to
   debug/verbose mode. In verbose mode, the logging severity and
   debuglevel specified in the configuration file are ignored and
   "debug" severity and the maximum debuglevel (99) are assumed. The
   flag is convenient for temporarily switching the server into maximum
   verbosity, e.g. when debugging.

-  ``-v`` - displays the Kea version and exits.

-  ``-V`` - displays the extended Kea version and exits.

-  ``-W`` - displays the Kea configuration report and exits. The report
   is a copy of the ``config.report`` file produced by ``./configure``;
   it is embedded in the executable binary.

-  ``-t file`` - specifies the configuration file to be tested.
   :iscman:`kea-dhcp-ddns` attempts to load it and conducts sanity checks.
   Certain checks are possible only while running the actual
   server. The actual status is reported with an exit code (0 =
   configuration looks okay, 1 = error encountered). Kea prints out log
   messages to standard output and errors to standard error when testing
   the configuration.

   The contents of the ``config.report`` file may also be accessed by examining
   certain libraries in the installation tree or in the source tree.

   .. code-block:: shell

    # from installation using libkea-process.so
    $ strings ${prefix}/lib/libkea-process.so | sed -n 's/;;;; //p'

    # from sources using libkea-process.so
    $ strings src/lib/process/.libs/libkea-process.so | sed -n 's/;;;; //p'

    # from sources using libkea-process.a
    $ strings src/lib/process/.libs/libkea-process.a | sed -n 's/;;;; //p'

    # from sources using libcfgrpt.a
    $ strings src/lib/process/cfgrpt/.libs/libcfgrpt.a | sed -n 's/;;;; //p'

Upon startup, the module loads its configuration and begins listening
for NCRs based on that configuration.

During startup, the server attempts to create a PID file of the form:
``[runstatedir]/[conf name].kea-dhcp-ddns.pid`` where:

-  ``runstatedir`` - is the value as passed into the build configure
   script; it defaults to "/usr/local/var/run". Note that this value may be
   overridden at runtime by setting the environment variable
   ``KEA_PIDFILE_DIR``. This is intended primarily for testing purposes.

-  ``conf name`` - is the configuration file name used to start the server,
   minus all preceding paths and the file extension. For example, given
   a pathname of "/usr/local/etc/kea/myconf.txt", the portion used would
   be "myconf".

If the file already exists and contains the PID of a live process, the
server issues a ``DHCP_DDNS_ALREADY_RUNNING`` log message and exits. It
is possible, though unlikely, that the file is a remnant of a system
crash and the process to which the PID belongs is unrelated to Kea. In
such a case it is necessary to manually delete the PID file.

.. _d2-configuration:

Configuring the DHCP-DDNS Server
================================

Before starting the :iscman:`kea-dhcp-ddns` module for the first time, a
configuration file must be created. The following default configuration
is a template that can be customized to individual requirements.

::

   "DhcpDdns": {
       "ip-address": "127.0.0.1",
       "port": 53001,
       "dns-server-timeout": 500,
       "ncr-protocol": "UDP",
       "ncr-format": "JSON",
       "tsig-keys": [ ],
       "forward-ddns": {
           "ddns-domains": [ ]
       },
       "reverse-ddns": {
           "ddns-domains": [ ]
       }
   }

The configuration can be divided into the following sections, each of
which is described below:

-  *Global Server Parameters* - define values which control connectivity and
   global server behavior.

-  *Control Sockets* - defines the Control Socket list.

-  *TSIG Key Info* - defines the TSIG keys used for secure traffic with
   DNS servers.

-  *Forward DDNS* - defines the catalog of forward DDNS domains.

-  *Reverse DDNS* - defines the catalog of reverse DDNS domains.

.. _d2-server-parameter-config:

Global Server Parameters
------------------------

-  ``ip-address`` - the IP address on which D2 listens for requests. The
   default is the local loopback interface at address 127.0.0.1.
   Either an IPv4 or IPv6 address may be specified.

-  ``port`` - the port on which D2 listens for requests. The default value
   is 53001.

-  ``dns-server-timeout`` - the maximum amount of time, in milliseconds,
   that D2 will wait for a response from a DNS server to a single DNS
   update message.  The default is 500 ms.

-  ``ncr-protocol`` - the socket protocol to use when sending requests to
   D2. Currently only UDP is supported.

-  ``ncr-format`` - the packet format to use when sending requests to D2.
   Currently only JSON format is supported.

D2 must listen for change requests on a known address and port. By
default it listens at 127.0.0.1 on port 53001. The following example
illustrates how to change D2's global parameters so it will listen at
192.168.1.10 port 900:

::

   "DhcpDdns": {
       "ip-address": "192.168.1.10",
       "port": 900,
       ...
   }

.. warning::

   It is possible for a malicious attacker to send bogus
   NameChangeRequests to the DHCP-DDNS server. Addresses other than the
   IPv4 or IPv6 loopback addresses (127.0.0.1 or ::1) should only be
   used for testing purposes; note that local users may still
   communicate with the DHCP-DDNS server.

.. note::

   If the ``ip-address`` and ``port`` are changed, the corresponding values in
   the DHCP servers' ``dhcp-ddns`` configuration section must be changed.

.. _d2-ctrl-channels:

Management API for the D2 Server
--------------------------------

The management API allows the issuing of specific management commands,
such as configuration retrieval or shutdown. For more details, see
:ref:`ctrl-channel`. By default there are no sockets
open; to instruct Kea to open a socket, the following entry in the
configuration file can be used:

::

   "DhcpDdns": {
       "control-sockets": [
           {
               "socket-type": "unix",
               "socket-name": "/path/to/the/unix/socket"
           }
       ],
       ...
   }

.. note:

   For backward compatibility the ``control-socket`` keyword is still
   recognized by Kea version newer than 2.7.2: a ``control-socket`` entry
   is put into a ``control-sockets`` list by the configuration parser.

.. _d2-unix-ctrl-channel:

UNIX Control Socket
~~~~~~~~~~~~~~~~~~~

Until Kea server 2.7.2 the only supported communication channel type was
the UNIX stream socket with ``socket-type`` set to ``unix`` and
``socket-name`` to the file path of the UNIX/LOCAL socket.

The length of the path specified by the ``socket-name`` parameter is
restricted by the maximum length for the UNIX socket name on the
operating system, i.e. the size of the ``sun_path`` field in the
``sockaddr_un`` structure, decreased by 1. This value varies on
different operating systems, between 91 and 107 characters. Typical
values are 107 on Linux and 103 on FreeBSD.

Kea supports only one ``unix`` control socket in the "control-sockets" list.

Communication over the control channel is conducted using JSON structures.
See the `Control Channel section in the Kea Developer's
Guide <https://reports.kea.isc.org/dev_guide/d2/d96/ctrlSocket.html>`__
for more details.

The D2 server supports the following operational commands:

- :isccmd:`build-report`
- :isccmd:`config-get`
- :isccmd:`config-hash-get`
- :isccmd:`config-reload`
- :isccmd:`config-set`
- :isccmd:`config-test`
- :isccmd:`config-write`
- :isccmd:`list-commands`
- :isccmd:`shutdown`
- :isccmd:`status-get`
- :isccmd:`version-get`

Since Kea version 2.0.0, the D2 server also supports the following
operational commands for statistics:

- :isccmd:`statistic-get`
- :isccmd:`statistic-get`-all
- :isccmd:`statistic-reset`
- :isccmd:`statistic-reset`-all

The :isccmd:`shutdown` command supports the extra ``type`` argument, which controls the
way the D2 server cleans up on exit.
The supported shutdown types are:

-  ``normal`` - stops the queue manager and finishes all current transactions
   before exiting. This is the default.

-  ``drain_first`` - stops the queue manager but continues processing requests
   from the queue until it is empty.

-  ``now`` - exits immediately.

An example command may look like this:

::

   {
       "command": "shutdown",
       "arguments": {
           "exit-value": 3,
           "type": "drain_first"
       }
   }

.. _d2-http-ctrl-channel:

HTTP/HTTPS Control Socket
~~~~~~~~~~~~~~~~~~~~~~~~~

The ``socket-type`` must be ``http`` or ``https`` (when the type is ``https``
TLS is required). The ``socket-address`` (default ``127.0.0.1``) and
``socket-port`` (default 8000) specify an IP address and port to which
the HTTP service will be bound.

The ``trust-anchor``, ``cert-file``, ``key-file``, and ``cert-required``
parameters specify the TLS setup for HTTP, i.e. HTTPS. If these parameters
are not specified, HTTP is used. The TLS/HTTPS support in Kea is
described in :ref:`tls`.

Basic HTTP authentication protects
against unauthorized uses of the control agent by local users. For
protection against remote attackers, HTTPS and reverse proxy of
:ref:`agent-secure-connection` provide stronger security.

The authentication is described in the ``authentication`` block
with the mandatory ``type`` parameter, which selects the authentication.
Currently only the basic HTTP authentication (type basic) is supported.

The ``realm`` authentication parameter (default ``kea-dhcp-ddns-server``
is used for error messages when the basic HTTP authentication is required
but the client is not authorized.

When the ``clients`` authentication list is configured and not empty,
basic HTTP authentication is required. Each element of the list
specifies a user ID and a password. The user ID is mandatory, must
not be empty, and must not contain the colon (:) character. The
password is optional; when it is not specified an empty password
is used.

.. note::

   The basic HTTP authentication user ID and password are encoded
   in UTF-8, but the current Kea JSON syntax only supports the Latin-1
   (i.e. 0x00..0xff) Unicode subset.

To avoid exposing the user ID and/or the associated
password, these values can be read from files. The syntax is extended by:

-  The ``directory`` authentication parameter, which handles the common
   part of file paths. The default value is the empty string.

-  The ``password-file`` client parameter, which, alongside the ``directory``
   parameter, specifies the path of a file that can contain the password,
   or when no user ID is given, the whole basic HTTP authentication secret.

-  The ``user-file`` client parameter, which, with the ``directory`` parameter,
   specifies the path of a file where the user ID can be read.

Since Kea-2.7.6 Kea supports multiple HTTP/HTTPS connections.
Both IPv4 and IPv6 addresses can be used.
A different address or port must be specified when using the "config-set"
command to switch from HTTP to HTTPS or from HTTPS to HTTP.

When files are used, they are read when the configuration is loaded,
to detect configuration errors as soon as possible.

::

   "DhcpDdns": {
       "control-sockets": [
           {
               "socket-type": "https",
               "socket-address": "10.20.30.40",
               "socket-port": 8005,
               "trust-anchor": "/path/to/the/ca-cert.pem",
               "cert-file": "/path/to/the/agent-cert.pem",
               "key-file": "/path/to/the/agent-key.pem",
               "cert-required": true,
               "authentication": {
                   "type": "basic",
                   "realm": "kea-dhcp-ddns-server",
                   "clients": [
                   {
                       "user": "admin",
                       "password": "1234"
                   } ]
               }
           },
           {
               "socket-type": "http",
               "socket-address": "2010:30:40::50",
               "socket-port": 8004
           }
       ],
       ...
   }

.. _d2-tsig-key-list-config:

TSIG Key List
-------------

A DDNS protocol exchange can be conducted with or without a transaction
signature, or TSIG (defined
in `RFC 2845 <https://tools.ietf.org/html/rfc2845>`__). This
configuration section allows the administrator to define the set of TSIG
keys that may be used in such exchanges.

To use TSIG when updating entries in a DNS domain, a key must be defined
in the TSIG key list and referenced by name in that domain's
configuration entry. When D2 matches a change request to a domain, it
checks whether the domain has a TSIG key associated with it. If so, D2
uses that key to sign DNS update messages sent to and verify
responses received from the domain's DNS server(s). For each TSIG key
required by the DNS servers that D2 is working with, there must be
a corresponding TSIG key in the TSIG key list.

As one might gather from the name, the ``tsig-key`` section of the D2
configuration lists the TSIG keys. Each entry describes a TSIG key used
by one or more DNS servers to authenticate requests and sign responses.
Every entry in the list has three parameters:

-  ``name`` - is a unique text label used to identify this key within the
   list. This value is used to specify which key (if any) should be used
   when updating a specific domain. As long as the name is unique its
   content is arbitrary, although for clarity and ease of maintenance it
   is recommended that it match the name used on the DNS server(s). This
   field cannot be blank.

-  ``algorithm`` - specifies which hashing algorithm should be used with
   this key. This value must specify the same algorithm used for the key
   on the DNS server(s). The supported algorithms are listed below:

   -  HMAC-MD5
   -  HMAC-SHA1
   -  HMAC-SHA224
   -  HMAC-SHA256
   -  HMAC-SHA384
   -  HMAC-SHA512

   This value is not case-sensitive.

-  ``digest-bits`` - is used to specify the minimum truncated length in
   bits. The default value 0 means truncation is forbidden; non-zero
   values must be an integral number of octets, and be greater than both
   80 and half of the full length. (Note that in BIND 9 this parameter
   is appended to the algorithm name, after a dash.)

-  ``secret`` - is used to specify the shared secret key code for this
   key. This value is case-sensitive and must exactly match the value
   specified on the DNS server(s). It is a base64-encoded text value.

- ``secret-file`` - since Kea 2.5.8, this more secure alternative is supported.
  This value specifies the file name where the secret can be found, i.e. the base64-encoded
  secret is the content of the file.

As an example, suppose that a domain D2 will be updating is maintained
by a BIND 9 DNS server, which requires dynamic updates to be secured
with TSIG. Suppose further that the entry for the TSIG key in BIND 9's
named.conf file looks like this:

::

      :
      key "key.four.example.com." {
          algorithm hmac-sha224;
          secret "bZEG7Ow8OgAUPfLWV3aAUQ==";
      };
      :

By default, the TSIG key list is empty:

::

   "DhcpDdns": {
      "tsig-keys": [ ],
      ...
   }

A new key must be added to the list:

::

   "DhcpDdns": {
       "tsig-keys": [
           {
               "name": "key.four.example.com.",
               "algorithm": "HMAC-SHA224",
               "secret": "bZEG7Ow8OgAUPfLWV3aAUQ=="
           }
       ],
       ...
   }

These steps must be repeated for each TSIG key needed, although the
same TSIG key can be used with more than one domain.

.. _d2-forward-ddns-config:

Forward DDNS
------------

The forward DDNS section is used to configure D2's forward-update
behavior. Currently it contains a single parameter, the catalog of
forward DDNS domains, which is a list of structures.

::

   "DhcpDdns": {
       "forward-ddns": {
           "ddns-domains": [ ]
       },
       ...
   }

By default, this list is empty, which causes the server to ignore
the forward-update portions of requests.

.. _add-forward-ddns-domain:

Adding Forward DDNS Domains
~~~~~~~~~~~~~~~~~~~~~~~~~~~

A forward DDNS domain maps a forward DNS zone to a set of DNS servers
which maintain the forward DNS data (i.e. name-to-address mapping) for
that zone. Each zone served needs one forward DDNS domain.
Some or all of the zones may be maintained by the same
servers, but one DDNS domain is still needed for each zone. Remember that
matching a request to the appropriate server(s) is done by zone and a
DDNS domain only defines a single zone.

This section describes how to add forward DDNS domains; repeat these
steps for each forward DDNS domain desired. Each forward DDNS domain has
the following parameters:

-  ``name`` - this is the fully qualified domain name (or zone) that this DDNS
   domain can update. This value is compared against the request FQDN
   during forward matching. It must be unique within the catalog.

-  ``key-name`` - if TSIG is used with this domain's servers, this value
   should be the name of the key from the TSIG key list. If the
   value is blank (the default), TSIG will not be used in DDNS
   conversations with this domain's servers.

-  ``dns-servers`` - this is a list of one or more DNS servers which can conduct
   the server side of the DDNS protocol for this domain. The servers are
   used in a first-to-last preference; in other words, when D2 begins to
   process a request for this domain, it will pick the first server in
   this list and attempt to communicate with it. If that attempt fails,
   D2 will move to the next one in the list and so on, until either it
   is successful or the list is exhausted.

To create a new forward DDNS domain, add a new domain element and set
its parameters:

::

   "DhcpDdns": {
       "forward-ddns": {
           "ddns-domains": [
               {
                   "name": "other.example.com.",
                   "key-name": "",
                   "dns-servers": [
                   ]
               }
           ]
       }
   }

It is possible to add a domain without any servers; however, if that
domain matches a request, the request will fail. To make the domain
useful, at least one DNS server must be added to it.

.. _add-forward-dns-servers:

Adding Forward DNS Servers
^^^^^^^^^^^^^^^^^^^^^^^^^^

This section describes how to add DNS servers to a forward DDNS domain.
Repeat these instructions as needed for all the servers in each domain.

Forward DNS server entries represent actual DNS servers which support
the server side of the DDNS protocol. Each forward DNS server has the
following parameters:

-  ``hostname`` - the resolvable host name of the DNS server; this
   parameter is not yet implemented.

-  ``ip-address`` - the IP address at which the server listens for DDNS
   requests. This may be either an IPv4 or an IPv6 address.

-  ``port`` - the port on which the server listens for DDNS requests. It
   defaults to the standard DNS service port of 53.

To create a new forward DNS server, a new server element must be added to
the domain and its parameters filled in. If, for example, the service is
running at "172.88.99.10", set the forward DNS server as follows:

::

   "DhcpDdns": {
       "forward-ddns": {
           "ddns-domains": [
               {
                   "name": "other.example.com.",
                   "key-name": "",
                   "dns-servers": [
                       {
                           "ip-address": "172.88.99.10",
                           "port": 53
                       }
                   ]
               }
           ]
       }
   }

.. note::

   Since ``hostname`` is not yet supported, the parameter ``ip-address``
   must be set to the address of the DNS server.

.. _d2-reverse-ddns-config:

Reverse DDNS
------------

The reverse DDNS section is used to configure D2's reverse update
behavior, and the concepts are the same as for the forward DDNS section.
Currently it contains a single parameter, the catalog of reverse DDNS
domains, which is a list of structures.

::

   "DhcpDdns": {
       "reverse-ddns": {
           "ddns-domains": [ ]
       },
       ...
   }

By default, this list is empty, which causes the server to ignore
the reverse-update portions of requests.

.. _add-reverse-ddns-domain:

Adding Reverse DDNS Domains
~~~~~~~~~~~~~~~~~~~~~~~~~~~

A reverse DDNS domain maps a reverse DNS zone to a set of DNS servers
which maintain the reverse DNS data (address-to-name mapping) for that
zone. Each zone served needs one reverse DDNS domain.
Some or all of the zones may be maintained by the same servers, but
one DDNS domain entry is needed for each zone. Remember that
matching a request to the appropriate server(s) is done by zone and a
DDNS domain only defines a single zone.

This section describes how to add reverse DDNS domains; repeat these
steps for each reverse DDNS domain desired. Each reverse DDNS domain has
the following parameters:

-  ``name`` - this is the fully qualified reverse zone that this DDNS domain can
   update. This is the value used during reverse matching, which
   compares it with a reversed version of the request's lease address.
   The zone name should follow the appropriate standards; for example,
   to support the IPv4 subnet 172.16.1, the name should be
   "1.16.172.in-addr.arpa.". Similarly, to support an IPv6 subnet of
   2001:db8:1, the name should be "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa."
   The name must be unique within the catalog.

-  ``key-name`` - if TSIG is used with this domain's servers,
   this value should be the name of the key from the TSIG key list. If
   the value is blank (the default), TSIG will not be used in DDNS
   conversations with this domain's servers.

-  ``dns-servers`` - this is a list of one or more DNS servers which can conduct
   the server side of the DDNS protocol for this domain. Currently, the
   servers are used in a first-to-last preference; in other words, when
   D2 begins to process a request for this domain, it will pick the
   first server in this list and attempt to communicate with it. If that
   attempt fails, D2 will move to the next one in the list and so on,
   until either it is successful or the list is exhausted.

To create a new reverse DDNS domain, a new domain element must be added
and its parameters set. For example, to support subnet 2001:db8:1::, the
following configuration could be used:

::

   "DhcpDdns": {
       "reverse-ddns": {
           "ddns-domains": [
               {
                   "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
                   "key-name": "",
                   "dns-servers": [
                   ]
               }
           ]
       }
   }

It is possible to add a domain without any servers; however, if that
domain matches a request, the request will fail. To make the domain
useful, at least one DNS server must be added to it.

.. _add-reverse-dns-servers:

Adding Reverse DNS Servers
^^^^^^^^^^^^^^^^^^^^^^^^^^

This section describes how to add DNS servers to a reverse DDNS domain.
Repeat these instructions as needed for all the servers in each domain.

Reverse DNS server entries represent actual DNS servers which support
the server side of the DDNS protocol. Each reverse DNS server has the
following parameters:

-  ``hostname`` - the resolvable host name of the DNS server; this value
   is currently ignored.

-  ``ip-address`` - the IP address at which the server listens for DDNS
   requests.

-  ``port`` - the port on which the server listens for DDNS requests. It
   defaults to the standard DNS service port of 53.

To create a new reverse DNS server, a new server
element must be added to the domain and its parameters specified. If, for example, the
service is running at "172.88.99.10", then set it as follows:

::

   "DhcpDdns": {
       "reverse-ddns": {
           "ddns-domains": [
               {
                   "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
                   "key-name": "",
                   "dns-servers": [
                       {
                           "ip-address": "172.88.99.10",
                           "port": 53
                       }
                   ]
               }
           ]
       }
   }

.. note::

   Since ``hostname`` is not yet supported, the parameter ``ip-address``
   must be set to the address of the DNS server.

.. _per-server-keys:

Per-DNS-Server TSIG Keys
~~~~~~~~~~~~~~~~~~~~~~~~

Since Kea version 2.0.0, a TSIG key can be specified in a DNS server
configuration. The priority rule is:

-  if a not-empty key name is specified in a DNS server entry, this TSIG
   key protects DNS updates sent to this server.

-  if the DNS server entry is empty, but a
   not-empty key name is specified in the parent's domain entry, the parent domain's
   TSIG key protects DNS updates sent to this server.

-  if the DNS server entry is empty, and no key name is specified in its parent
   domain entry, no TSIG protects DNS updates sent to this server.

For instance, in this configuration:

::

   "DhcpDdns": {
       "forward-ddns": {
           "ddns-domains": [
               {
                   "name": "other.example.com.",
                   "key-name": "foo",
                   "dns-servers": [
                       {
                           "ip-address": "172.88.99.10",
                           "port": 53
                       },
                       {
                           "ip-address": "172.88.99.11",
                           "port": 53,
                           "key-name": "bar"
                       }
                   ]
               }
           ]
       },
       "reverse-ddns": {
           "ddns-domains": [
               {
                   "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
                   "dns-servers": [
                       {
                           "ip-address": "172.88.99.12",
                           "port": 53
                       },
                       {
                           "ip-address": "172.88.99.13",
                           "port": 53,
                           "key-name": "bar"
                       }
                   ]
               }
           ]
       },
       "tsig-keys": [
           {
               "name": "foo",
               "algorithm": "HMAC-MD5",
               "secret": "LSWXnfkKZjdPJI5QxlpnfQ=="
           },
           {
               "name": "bar",
               "algorithm": "HMAC-SHA224",
               "secret": "bZEG7Ow8OgAUPfLWV3aAUQ=="
           }
       ]
   }


The 172.88.99.10 server will use the "foo" TSIG key, the 172.88.99.11 and
172.88.99.13 servers will use the "bar" key. and 172.88.99.12 will not use TSIG.

.. _d2-user-contexts:

User Contexts in DDNS
---------------------

See :ref:`user-context` for additional background regarding the user
context idea.

User contexts can be specified on a global scope, a DDNS domain, a DNS server,
a TSIG key, and loggers. One other useful usage is the ability to store
comments or descriptions; the parser translates a "comment" entry into a
user context with the entry, which allows a comment to be attached
inside the configuration itself.

.. _d2-example-config:

Example DHCP-DDNS Server Configuration
--------------------------------------

This section provides a sample DHCP-DDNS server configuration, based on
a small example network. Let's suppose our example network has three
domains, each with their own subnet.

.. table:: Our example network

   +------------------+-----------------+-----------------+-----------------+
   | Domain           | Subnet          | Forward DNS     | Reverse DNS     |
   |                  |                 | Servers         | Servers         |
   +==================+=================+=================+=================+
   | four.example.com | 192.0.2.0/24    | 172.16.1.5,     | 172.16.1.5,     |
   |                  |                 | 172.16.2.5      | 172.16.2.5      |
   +------------------+-----------------+-----------------+-----------------+
   | six.example.com  | 2001:db8:1::/64 | 3001:1::50      | 3001:1::51      |
   +------------------+-----------------+-----------------+-----------------+
   | example.com      | 192.0.0.0/16    | 172.16.2.5      | 172.16.2.5      |
   +------------------+-----------------+-----------------+-----------------+

We need to construct three forward DDNS domains:

.. table:: Forward DDNS domains needed

   +----+-------------------+------------------------+
   | #  | DDNS Domain Name  | DNS Servers            |
   +====+===================+========================+
   | 1. | four.example.com. | 172.16.1.5, 172.16.2.5 |
   +----+-------------------+------------------------+
   | 2. | six.example.com.  | 3001:1::50             |
   +----+-------------------+------------------------+
   | 3. | example.com.      | 172.16.2.5             |
   +----+-------------------+------------------------+

As discussed earlier, FQDN-to-domain matching is based on the longest
match. The FQDN "myhost.four.example.com." matches the first domain
("four.example.com"), while "admin.example.com." matches the third
domain ("example.com"). The FQDN "other.example.net." fails to
match any domain and is rejected.

The following example configuration specifies the forward DDNS domains.

::

   "DhcpDdns": {
       "comment": "example configuration: forward part",
       "forward-ddns": {
           "ddns-domains": [
               {
                   "name": "four.example.com.",
                   "key-name": "",
                   "dns-servers": [
                       { "ip-address": "172.16.1.5" },
                       { "ip-address": "172.16.2.5" }
                   ]
               },
               {
                   "name": "six.example.com.",
                   "key-name": "",
                   "dns-servers": [
                       { "ip-address": "2001:db8::1" }
                   ]
               },
               {
                   "name": "example.com.",
                   "key-name": "",
                   "dns-servers": [
                       { "ip-address": "172.16.2.5" }
                   ],
                   "user-context": { "backup": false }
               },
               ...
           ]
       }
   }

Similarly, we need to construct the three reverse DDNS domains:

.. table:: Reverse DDNS domains needed

   +----+-----------------------------------+------------------------+
   | #  | DDNS Domain Name                  | DNS Servers            |
   +====+===================================+========================+
   | 1. | 2.0.192.in-addr.arpa.             | 172.16.1.5, 172.16.2.5 |
   +----+-----------------------------------+------------------------+
   | 2. | 1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa. | 3001:1::50             |
   +----+-----------------------------------+------------------------+
   | 3. | 0.182.in-addr.arpa.               | 172.16.2.5             |
   +----+-----------------------------------+------------------------+

An address of "192.0.2.150" matches the first domain,
"2001:db8:1::10" matches the second domain, and "192.0.50.77" matches the
third domain.

These reverse DDNS domains are specified as follows:

::

   "DhcpDdns": {
       "comment": "example configuration: reverse part",
       "reverse-ddns": {
           "ddns-domains": [
               {
                   "name": "2.0.192.in-addr.arpa.",
                   "key-name": "",
                   "dns-servers": [
                       { "ip-address": "172.16.1.5" },
                       { "ip-address": "172.16.2.5" }
                   ]
               },
               {
                   "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
                   "key-name": "",
                   "dns-servers": [
                       { "ip-address": "2001:db8::1" }
                   ]
               },
               {
                   "name": "0.192.in-addr.arpa.",
                   "key-name": "",
                   "dns-servers": [
                       { "ip-address": "172.16.2.5" }
                   ]
               },
               ...
           ]
       }
   }

DHCP-DDNS Server Statistics
===========================

Kea version 2.0.0 introduced statistics support for DHCP-DDNS.

Statistics are divided into three groups: NameChangeRequests, DNS updates,
and per-TSIG-key DNS updates. While the statistics of the first two groups
are cumulative, i.e. not affected by configuration change or reload,
per-key statistics are reset to 0 when the underlying object is
(re)created.

Currently Kea's statistics management has the following limitations:

-  only integer samples (i.e. a counter and a timestamp) are used;
-  the maximum sample count is 1;
-  there is no API to remove one or all statistics;
-  there is no API to set the maximum sample count or age.

.. note::

    Hook libraries, such as the ISC subscriber-only GSS-TSIG library,
    make new statistics available in Kea.

More information about Kea statistics can be found at :ref:`stats`.

NCR Statistics
--------------

The NameChangeRequest statistics are:

-  ``ncr-received`` - the number of received valid NCRs
-  ``ncr-invalid`` - the number of received invalid NCRs
-  ``ncr-error`` - the number of errors in NCR receptions other than an I/O cancel on shutdown
-  ``queue-mgr-queue-full`` - the number of times the NCR receive queue reached maxium capacity

DNS Update Statistics
---------------------

The global DNS update statistics are:

-  ``update-sent`` - the number of DNS updates sent
-  ``update-signed`` - the number of DNS updates sent and protected by TSIG
-  ``update-unsigned`` - the number of DNS updates sent and not protected by TSIG
-  ``update-success`` - the number of DNS updates which successfully completed
-  ``update-timeout`` - the number of DNS updates which completed on timeout
-  ``update-error`` - the number of DNS updates which completed with an error other than
   timeout

Per-TSIG-Key DNS Update Statistics
----------------------------------

The per TSIG key DNS update statistics are:

-  ``update-sent`` - the number of DNS updates sent
-  ``update-success`` - the number of DNS updates which successfully completed
-  ``update-timeout`` - the number of DNS updates which completed on timeout
-  ``update-error`` - the number of DNS updates which completed with an error other than
   timeout

The name format for per-key statistics is ``key[<key-DNS-name>].<stat-name>``:
for instance, the name of the ``update-sent`` statistics for the
``key.example.com.`` TSIG key is ``key[key.example.com.].update-sent``.

DHCP-DDNS Server Limitations
============================

The following are the current limitations of the DHCP-DDNS server.

-  Requests received from the DHCP servers are placed in a queue until
   they are processed. Currently, all queued requests are lost if the
   server shuts down.

Supported Standards
===================

The following RFCs are supported by the DHCP-DDNS server:

- *Secret Key Transaction Authentication for DNS (TSIG)*, `RFC 2845
  <https://tools.ietf.org/html/rfc2845>`__: All DNS update packets sent and
  received by the DHCP-DDNS server can be protected by TSIG signatures.

- *Dynamic Updates in the Domain Name System (DNS UPDATE)*, `RFC 2136
  <https://tools.ietf.org/html/rfc2136>`__: The complete DNS update mechanism is
  supported.

- *Resolution of Fully Qualified Domain Name (FQDN) Conflicts among Dynamic Host
  Configuration Protocol (DHCP) Clients*, `RFC 4703
  <https://tools.ietf.org/html/rfc4703>`__: DHCP-DDNS takes care of
  conflict resolution, for both DHCPv4 and DHCPv6 servers.

- *A DNS Resource Record (RR) for Encoding Dynamic Host Configuration Protocol
  (DHCP) Information (DHCID RR)*, `RFC 4701
  <https://tools.ietf.org/html/rfc4701>`__: The DHCP-DDNS server uses DHCID
  records.