ddns.xml 39.3 KB
Newer Older
1 2 3 4 5 6 7 8
<!--
 - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
 -
 - 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 http://mozilla.org/MPL/2.0/.
-->

9 10
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dhcp-ddns-server">
11
    <title>The DHCP-DDNS Server</title>
12

13 14 15 16
    <section id="dhcp-ddns-overview">
      <title>Overview</title>
      <para>
      The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts
17 18
      the client side of the DDNS protocol (defined in  <link
      xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2136">RFC 2136</link>)
19 20 21 22 23 24
      on behalf of the DHCPv4 and DHCPv6 servers (kea-dhcp4 and kea-dhcp6
      respectively). The DHCP servers construct DDNS update requests, known
      as NameChangeRequests (NCRs), based upon DHCP lease change events and
      then post these to D2. D2 attempts to match each such request to the
      appropriate DNS server(s) and carry out the necessary conversation with
      those servers to update the DNS data.
25
    </para>
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
    <section id="dhcp-ddns-dns-server-selection">
      <title>DNS Server selection</title>
      <para>
      In order 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.
      </para>
      <para>
      When conducting forward domain matching, D2 will compare the FQDN in
      the request against the name of each forward DDNS Domain. 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 will simply disregard the forward update portion of requests.
      </para>
      <para>
      When conducting reverse domain matching, D2 constructs a reverse
      FQDN from the lease address in the request and compare 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, it is possible to 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. Finally, if there are no reverse DDNS Domains defined, D2 will
      simply disregard the reverse update portion of requests.
      </para>
    </section>
62
    <section xml:id="dhcp-ddns-conflict-resolution">
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
      <title>Conflict Resolution</title>
        <para>
        D2 implements the conflict resolution strategy prescribed by
        <ulink url="http://tools.ietf.org/html/rfc4703">RFC 4703</ulink>.
        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 who wishes to update or remove
        existing forward entries for an FQDN may only do so if their client
        matches that of the DHCID RR.
        </para>
        <para>
        In other words, the DHCID RR maps an FQDN to the client to whom it
        belongs and thereafter only changes to that mapping should only be
        done by or at the behest of that client.
        </para>
        <para>
        Currently, conflict detection is always performed.  Future releases may
        offer alternative behavior.
        </para>
    </section>
    <section id="dhcp-ddns-dual-stack">
      <title>Dual Stack Environments</title>
      <para>
        <ulink url="http://tools.ietf.org/html/rfc4703#section-5.2">RFC 4703,
        sec. 5.2,</ulink> describes issues that may arise with dual stack
        clients. These are clients that wish to have have both IPv4 and IPv6
        mappings for the same FQDN.  In order for this work properly, such
        clients are required to embed ther IPv6 DUID within their IPv4 client
        identifier option as described in
        <ulink url="http://tools.ietf.org/html/rfc4361">RFC 4703</ulink>.
        In this way, DNS upates for both IPv4 and IPv6 can be managed under
        the same DHCID RR. Support for this does not yet exist in Kea but is
98
        called for in the ticket, http://oldkea.isc.org/ticket/4519, which we
99
        hope to include in a future release.
100 101 102
      </para>
    </section>
    </section>
103 104
    <section id="dhcp-ddns-server-start-stop">
      <title>Starting and Stopping the DHCP-DDNS Server</title>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
105

106
      <para>
107 108 109
      <command>kea-dhcp-ddns</command> is the Kea DHCP-DDNS server
      and, due to the nature of DDNS, it is run alongside either the
      DHCPv4 or DHCPv6 components (or both).  Like other parts of
110
      Kea, it is a separate binary that can be run on its own or through
Jeremy C. Reed's avatar
Jeremy C. Reed committed
111
      <command>keactrl</command> (see <xref linkend="keactrl"/>). In
112
      normal operation, controlling <command>kea-dhcp-ddns</command>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
113
      with <command>keactrl</command> is recommended. However, it is also
Tomek Mrugalski's avatar
Tomek Mrugalski committed
114 115
      possible to run the DHCP-DDNS server directly. It accepts the
      following command-line switches:
116
      </para>
117

Tomek Mrugalski's avatar
Tomek Mrugalski committed
118 119 120 121 122 123 124 125 126 127 128
      <itemizedlist>
          <listitem>
            <simpara>
            <command>-c <replaceable>file</replaceable></command> -
            specifies the configuration file. This is the only mandatory
            switch.</simpara>
          </listitem>
          <listitem>
            <simpara>
            <command>-d</command> - specifies whether the server
            logging should be switched to debug/verbose mode. In verbose mode,
129
            the logging severity and debuglevel specified in the configuration
Tomek Mrugalski's avatar
Tomek Mrugalski committed
130 131 132 133 134 135 136
            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.</simpara>
          </listitem>
          <listitem>
            <simpara>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
137
              <command>-v</command> - prints out Kea version and exits.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
138 139 140 141
            </simpara>
          </listitem>
          <listitem>
            <simpara>
142 143 144 145 146
              <command>-W</command> - prints out the Kea configuration report
              and exits. The report is a copy of the
              <filename>config.report</filename> file produced by
              <userinput>./configure</userinput>: it is embedded in the
              executable binary.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
147 148
            </simpara>
          </listitem>
149 150
          <listitem>
            <simpara>
151 152 153 154 155 156 157 158
            <command>-t <replaceable>file</replaceable></command>
            specifies the configuration file to be tested. Kea-dhcp-ddns
            will attempt to load it, and will conduct sanity checks.
            Note that certain checks are possible only while running
            the actual server. The actual status is reported with exit
            code (0 = configuration looks ok, 1 = error encountered).
            Kea will print out log messages to standard output and error
            to standard error when testing configuration.</simpara>
159
          </listitem>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
160 161
      </itemizedlist>

162 163 164 165 166
      <para>
            The <filename>config.report</filename> may also be accessed more
            directly.  The following command may be used to extract this
            information.  The binary <userinput>path</userinput> may be found
            in the install directory or in the <filename>.libs</filename>
167
            subdirectory in the source tree. For example
168
            <filename>kea/src/bin/d2/.libs/kea-dhcp-ddns</filename>.
169 170 171 172 173
<screen>
strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
</screen>
      </para>

174 175 176 177
      <para>
      Upon start up the module will load its configuration and begin listening
      for NCRs based on that configuration.
      </para>
178 179 180 181 182 183 184 185

      <para>
        During startup the server will attempt to create a PID file of the
        form: [localstatedir]/[conf name].kea-dhcp-ddns.pid
        where:
        <itemizedlist>
            <listitem>
            <simpara><command>localstatedir</command>: The value as passed into the
Jeremy C. Reed's avatar
Jeremy C. Reed committed
186
            build configure script. It defaults to "/usr/local/var".  Note
187 188 189 190 191
            that this value may be overridden at run time by setting the environment
            variable KEA_PIDFILE_DIR.  This is intended primarily for testing purposes.
            </simpara>
            </listitem>
            <listitem>
192
            <simpara><command>conf name</command>: The configuration file name
193 194 195 196 197 198 199 200 201
            used to start the server, minus all preceding path and file extension.
            For example, given a pathname of "/usr/local/etc/kea/myconf.txt", the
            portion used would be "myconf".
            </simpara>
            </listitem>
        </itemizedlist>
        If the file already exists and contains the PID of a live process,
        the server will issue a DHCP_DDNS_ALREADY_RUNNING log message and exit. It
        is possible, though unlikely, that the file is a remnant of a system crash
202
        and the process to which the PID belongs is unrelated to Kea.  In such a
203 204 205 206
        case it would be necessary to manually delete the PID file.
      </para>


207
    </section> <!-- end start-stop -->
208
    <section xml:id="d2-configuration">
209 210
      <title>Configuring the DHCP-DDNS Server</title>
      <para>
211 212
        Before starting <command>kea-dhcp-ddns</command> module for the
        first time, a configuration file needs to be created. The following default
Josh Soref's avatar
Josh Soref committed
213
        configuration is a template that can be customized to your requirements.
214
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
215
<userinput>"DhcpDdns": {
216
    "ip-address": "127.0.0.1",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
217
    "port": 53001,
218 219 220 221 222
    "dns-server-timeout": 100,
    "ncr-protocol": "UDP",
    "ncr-format": "JSON",
    "tsig-keys": [ ],
    "forward-ddns": {
223
        "ddns-domains": [ ]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
224
    },
225
    "reverse-ddns": {
226
        "ddns-domains": [ ]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
227 228
    }
}</userinput>
229 230 231 232 233 234
</screen>
      </para>
      <para>
      The configuration can be divided as follows, each of which is described
      in its own section:
      </para>
235 236 237
        <itemizedlist>
          <listitem>
            <simpara>
238
        <emphasis>Global Server Parameters</emphasis> - values which control connectivity and global server behavior
239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <emphasis>TSIG Key Info</emphasis> - defines the TSIG keys used for secure traffic with DNS servers
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <emphasis>Forward DDNS</emphasis> - defines the catalog of Forward DDNS Domains
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <emphasis>Reverse DDNS</emphasis> - defines the catalog of Forward DDNS Domains
            </simpara>
          </listitem>
        </itemizedlist>
257
      <section xml:id="d2-server-parameter-config">
258
        <title>Global Server Parameters</title>
259 260 261
      <itemizedlist>

      <listitem><simpara>
262
      <command>ip-address</command> - IP address on which D2
263 264 265 266 267 268
      listens for requests. The default is the local loopback interface at
      address 127.0.0.1. You may specify either an IPv4 or IPv6 address.
      </simpara></listitem>

      <listitem><simpara>
      <command>port</command> - Port on which D2 listens for requests.  The default value
269
      is 53001.
270 271 272
      </simpara></listitem>

      <listitem><simpara>
273
      <command>dns-server-timeout</command> - The maximum amount
274 275 276 277 278
      of time in milliseconds, that D2 will wait for a response from a
      DNS server to a single DNS update message.
      </simpara></listitem>

      <listitem><simpara>
279
      <command>ncr-protocol</command> - Socket protocol to use when sending requests to D2.
280
      Currently only UDP is supported.  TCP may be available in a future release.
281 282 283
      </simpara></listitem>

      <listitem><simpara>
284
      <command>ncr-format</command> - Packet format to use when sending requests to D2.
285 286
      Currently only JSON format is supported.  Other formats may be available
      in future releases.
287 288 289
      </simpara></listitem>

      </itemizedlist>
290 291 292 293 294
        <para>
        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:
295
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
296
"DhcpDdns": {
297
    <userinput>"ip-address": "192.168.1.10",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
298 299 300 301
    "port": 900,</userinput>
    ...
    }
}</screen>
302 303 304 305 306 307 308 309 310 311 312
        </para>
        <warning>
          <simpara>
            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, but
            note that local users may still communicate with the
            DHCP-DDNS server.  A future version of Kea will implement
            authentication to guard against such attacks.
          </simpara>
313
<!-- see ticket #3514 -->
314
        </warning>
315 316
<note>
<simpara>
317
If the ip-address and port are changed, it will be necessary to change the
318 319 320 321 322
corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
</simpara>
</note>
      </section> <!-- "d2-server-parameter-config" -->

323
      <section xml:id="d2-tsig-key-list-config">
324 325 326
        <title>TSIG Key List</title>
        <para>
        A DDNS protocol exchange can be conducted with or without TSIG
327 328
        (defined in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf/org/html/rfc2845">RFC
        2845</link>). This configuration section allows the administrator
329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413
        to define the set of TSIG keys that may be used in such
        exchanges.</para>

        <para>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 will use 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 will be working with there must be a
        corresponding TSIG key in the TSIG Key list.</para>

        <para>
        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:
        <itemizedlist>
          <listitem>
            <simpara>
              <command>name</command> -
              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. So long as it 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).
              It cannot be blank.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>algorithm</command> -
              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:
              <itemizedlist>
                <listitem>
                   <command>HMAC-MD5</command>
                </listitem>
                <listitem>
                    <command>HMAC-SHA1</command>
                </listitem>
                <listitem>
                  <command>HMAC-SHA224</command>
              </listitem>
              <listitem>
                  <command>HMAC-SHA256</command>
              </listitem>
              <listitem>
                  <command>HMAC-SHA384</command>
                  </listitem>
              <listitem>
                  <command>HMAC-SHA512</command>
              </listitem>
              </itemizedlist>
              This value is not case sensitive.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>digest-bits</command> -
              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, be greater
              than 80 and the half of the full length. Note in BIND9
              this parameter is appended after a dash to the algorithm
              name.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              <command>secret</command> -
              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.
            </simpara>
          </listitem>
        </itemizedlist>
        </para>
        <para>
        As an example, suppose that a domain D2 will be updating is
        maintained by a BIND9 DNS server which requires dynamic updates
        to be secured with TSIG.  Suppose further that the entry for
        the TSIG key in BIND9's named.conf file looks like this:
414 415 416 417 418 419 420 421
<screen>
   :
   key "key.four.example.com." {
       algorithm hmac-sha224;
       secret "bZEG7Ow8OgAUPfLWV3aAUQ==";
   };
   :
</screen>
422
        By default, the TSIG Key list is empty:
423
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
424
"DhcpDdns": {
425
   <userinput>"tsig-keys": [ ]</userinput>,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
426 427
   ...
}
428
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
429

430
        We must extend the list with a new key:
431
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
432
"DhcpDdns": {
433
    "tsig-keys": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
434
    <userinput>    {
435 436 437 438
            "name": "key.four.example.com.",
            "algorithm": "HMAC-SHA224",
            "secret": "bZEG7Ow8OgAUPfLWV3aAUQ=="
        }</userinput>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
439 440 441
    ],
    ...
}
442
</screen>
443
        </para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
444

445 446
        <para>These steps would be repeated for each TSIG key needed.  Note that
        the same TSIG key can be used with more than one domain.</para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
447
      </section>
448
        <!-- "d2-tsig-key-list-config" -->
449

450
      <section xml:id="d2-forward-ddns-config">
451 452 453 454 455
        <title>Forward DDNS</title>
        <para>
        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.
456
<screen>
457
"DhcpDdns": {
458
    <userinput>"forward-ddns": {
459
        "ddns-domains": [ ]
460
    }</userinput>,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
461
    ...
462
}
463
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
464

465 466 467
        By default, this list is empty, which will cause the server to ignore
        the forward update portions of requests.
        </para>
468
        <section xml:id="add-forward-ddns-domain">
469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517
          <title>Adding Forward DDNS Domains</title>
          <para>
          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.  You will need one forward DDNS
          Domain for each zone you wish to service.  It may very well
          be that some or all of your zones are maintained by the same
          servers. You will still need one DDNS Domain per zone. Remember
          that matching a request to the appropriate server(s) is done
          by zone and a DDNS Domain only defines a single zone.
          </para>
          <para>
          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:
          <itemizedlist>
            <listitem>
              <simpara>
              <command>name</command> -
              The fully qualified domain name (or zone) that this DDNS Domain
              can update.  This is value used to compare against the request
              FQDN during forward matching.  It must be unique within the
              catalog.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
              <command>key-name</command> -
              If TSIG is used with this domain's servers, this
              value should be the name of the key from within the TSIG Key List
              to use.  If the value is blank (the default), TSIG will not be
              used in DDNS conversations with this domain's servers.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
              <command>dns-servers</command> -
              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, it will move to next one in the list and
              so on until the it achieves success or the list is exhausted.
              </simpara>
            </listitem>
          </itemizedlist>
        To create a new forward DDNS Domain, one must add a new domain
        element and set its parameters:
518
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
519
"DhcpDdns": {
520
    "forward-ddns": {
521 522 523 524 525 526 527 528
        "ddns-domains": [
            <userinput>{
                "name": "other.example.com.",
                "key-name": "",
                "dns-servers": [
                ]
            }</userinput>
        ]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
529 530
    }
}
531 532
</screen>

533 534 535 536 537 538
        It is permissible to add a domain without any servers. If that domain
        should be matched to a request, however, the request will fail.  In
        order to make the domain useful though, we must add at least one DNS
        server to it.
        </para>

539
        <section xml:id="add-forward-dns-servers">
540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575
          <title>Adding Forward DNS Servers</title>
          <para>
          This section describes how to add DNS servers to a Forward DDNS Domain.
          Repeat them for as many servers as desired for a each domain.
          </para>
          <para>
          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:
          <itemizedlist>
            <listitem>
              <simpara>
              <command>hostname</command> -
              The resolvable host name of the DNS server. This value is not
              yet implemented.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
              <command>ip-address</command> -
              The IP address at which the server listens for DDNS requests.
              This may be either an IPv4 or an IPv6 address.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
              <command>port</command> -
              The port on which the server listens for DDNS requests. It
              defaults to the standard DNS service port of 53.
              </simpara>
            </listitem>
          </itemizedlist>
          To create a new forward DNS Server, one must add a new server
          element to the domain and fill in its parameters.  If for
        example the service is running at "172.88.99.10", then set it as
        follows:
576
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
577
"DhcpDdns": {
578
    "forward-ddns": {
579 580 581 582 583 584 585 586 587 588 589 590 591
        "ddns-domains": [
            {
                "name": "other.example.com.",
                "key-name": "",
                "dns-servers": [
                    <userinput>{
                        "hostname": "",
                        "ip-address": "172.88.99.10",
                        "port": 53
                    }</userinput>
                ]
            }
        ]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
592 593
    }
}
594
</screen>
595
          </para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
596

597
    <note><simpara>
598 599
        As stated earlier, "hostname" is not yet supported so, the parameter
        "ip-address" must be set to the address of the DNS server.
600 601
    </simpara></note>

602
        </section> <!-- "add-forward-dns-servers" -->
603 604 605 606 607

      </section> <!-- "add-forward-ddns-domains" -->

      </section> <!-- "d2-forward-ddns-config" -->

608
      <section xml:id="d2-reverse-ddns-config">
609 610 611 612 613 614
        <title>Reverse DDNS</title>
        <para>
        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.
615
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
616
"DhcpDdns": {
617
    <userinput>"reverse-ddns": {
618
        "ddns-domains": [ ]
619 620
    }</userinput>
    ...
Tomek Mrugalski's avatar
Tomek Mrugalski committed
621
}
622
</screen>
623 624 625
        By default, this list is empty, which will cause the server to ignore
        the reverse update portions of requests.
        </para>
626
        <section xml:id="add-reverse-ddns-domain">
627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683
          <title>Adding Reverse DDNS Domains</title>
          <para>
          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.  You will need one reverse DDNS Domain
          for each zone you wish to service.  It may very well be that
          some or all of your zones are maintained by the same servers;
          even then, you will still need one DDNS Domain entry 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.
          </para>
          <para>
          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:
          <itemizedlist>
            <listitem>
              <simpara>
              <command>name</command> -
              The fully qualified reverse zone that this DDNS Domain
              can update.  This is the value used during reverse matching
              which will compare it with a reversed version of the request's
              lease address. The zone name should follow the appropriate
              standards: for example, to 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."
              Whatever the name, it must be unique within the catalog.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
              <command>key-name</command> -
              If TSIG should be used with this domain's servers, then this
              value should be the name of that 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.  Currently
              this value is not used as TSIG has not been implemented.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
              <command>dns-servers</command> -
              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, it will move to next one in the list and
              so on until the it achieves success or the list is exhausted.
              </simpara>
            </listitem>
          </itemizedlist>
        To create a new reverse DDNS Domain, one must add a new domain element
        and set its parameters. For example, to support subnet 2001:db8:1::,
        the following configuration could be used:
684
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
685
"DhcpDdns": {
686
    "reverse-ddns": {
687 688 689 690 691 692 693 694
        "ddns-domains": [
            <userinput>{
                "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
                "key-name": "",
                "dns-servers": [
                ]
            }</userinput>
        ]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
695 696
    }
}
697
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
698

699 700 701 702 703 704
        It is permissible to add a domain without any servers. If that domain
        should be matched to a request, however, the request will fail.  In
        order to make the domain useful though, we must add at least one DNS
        server to it.
        </para>

705
        <section xml:id="add-reverse-dns-servers">
706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740
          <title>Adding Reverse DNS Servers</title>
          <para>
          This section describes how to add DNS servers to a Reverse DDNS Domain.
          Repeat them for as many servers as desired for each domain.
          </para>
          <para>
          Reverse DNS Server entries represents a actual DNS servers which
          support the server side of the DDNS protocol. Each Reverse DNS Server
          has the following parameters:
          <itemizedlist>
            <listitem>
              <simpara>
              <command>hostname</command> -
              The resolvable host name of the DNS server. This value is
              currently ignored.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
              <command>ip-address</command> -
              The IP address at which the server listens for DDNS requests.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
              <command>port</command> -
              The port on which the server listens for DDNS requests. It
              defaults to the standard DNS service port of 53.
              </simpara>
            </listitem>
          </itemizedlist>
          To create a new reverse DNS Server, one must first add a new server
          element to the domain and fill in its parameters.  If for
        example the service is running at "172.88.99.10", then set it as
        follows:
741
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
742
"DhcpDdns": {
743
    "reverse-ddns": {
744 745 746 747 748 749 750 751 752 753 754 755 756
        "ddns-domains": [
            {
                "name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
                "key-name": "",
                "dns-servers": [
                    <userinput>{
                        "hostname": "",
                        "ip-address": "172.88.99.10",
                        "port": 53
                    }</userinput>
                ]
            }
        ]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
757 758
    }
}
759
</screen>
760 761 762 763 764
</para>

    <note>
    <simpara>
    As stated earlier, "hostname" is not yet supported so, the parameter
765
    "ip-address" must be set to the address of the DNS server.
766 767
    </simpara>
    </note>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
768

769
        </section> <!-- "add-reverse-dns-servers" -->
770 771 772 773 774

      </section> <!-- "add-reverse-ddns-domains" -->

      </section> <!-- "d2-reverse-ddns-config" -->

775
      <section xml:id="d2-user-contexts">
776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798
        <title>User context in DDNS</title>

        <note>
          <para>User contexts were designed for hook libraries which
          are not yet supported for DHCP-DDNS server configuration.</para>
        </note>

        <para>
          User contexts can store arbitrary data as long as it is valid JSON
          syntax and its top level element is a map (i.e. the data must be
          enclosed in curly brackets).
        </para>

        <para>
          User contexts can be specified on either global scope, ddns
          domain, dns server, 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, this allows to attach a comment inside the
          configuration itself.
        </para>
      </section> <!-- "d2-user-contexts" -->

799
      <section xml:id="d2-example-config">
800 801 802 803 804 805 806 807
        <title>Example DHCP-DDNS Server Configuration</title>
        <para>
        This section provides an example 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>
          <title>Our example network</title>
808 809 810 811 812
          <tgroup cols="4" align="left">
          <colspec colname="domain"/>
          <colspec colname="subnet"/>
          <colspec colname="fservers"/>
          <colspec colname="rservers"/>
813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847
          <thead>
            <row>
              <entry>Domain</entry>
              <entry>Subnet</entry>
              <entry>Forward DNS Servers</entry>
              <entry>Reverse DNS Servers</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>four.example.com</entry>
              <entry>192.0.2.0/24</entry>
              <entry>172.16.1.5, 172.16.2.5</entry>
              <entry>172.16.1.5, 172.16.2.5</entry>
            </row>
            <row>
              <entry>six.example.com</entry>
              <entry>2001:db8:1::/64</entry>
              <entry>3001:1::50</entry>
              <entry>3001:1::51</entry>
            </row>
            <row>
              <entry>example.com</entry>
              <entry>192.0.0.0/16</entry>
              <entry>172.16.2.5</entry>
              <entry>172.16.2.5</entry>
            </row>
          </tbody>
          </tgroup>
        </table>
        </para>
        <para>
        We need to construct three forward DDNS Domains:
        <table>
          <title>Forward DDNS Domains Needed</title>
848 849 850 851
          <tgroup cols="3" align="left">
          <colspec colname="num"/>
          <colspec colname="name"/>
          <colspec colname="servers"/>
852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886
          <thead>
            <row>
              <entry>#</entry>
              <entry>DDNS Domain Name</entry>
              <entry>DNS Servers</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>1.</entry>
              <entry>four.example.com.</entry>
              <entry>172.16.1.5, 172.16.2.5</entry>
            </row>
            <row>
              <entry>2.</entry>
              <entry>six.example.com.</entry>
              <entry>3001:1::50</entry>
            </row>
            <row>
              <entry>3.</entry>
              <entry>example.com.</entry>
              <entry>172.16.2.5</entry>
            </row>
          </tbody>
          </tgroup>
        </table>
        As discussed earlier, FQDN to domain matching is based on the longest
        match. The FQDN, "myhost.four.example.com.", will match the first
        domain ("four.example.com") while "admin.example.com." will match the
        third domain ("example.com"). The
        FQDN, "other.example.net." will fail to match any domain and would
        be rejected.
        </para>
        <para>
        The following example configuration specified the Forward DDNS Domains.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
887 888
<screen><userinput>
"DhcpDdns": {
889
    "comment": "example configuration: forward part",
890
    "forward-ddns": {
891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911
        "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" }
912 913
                ],
                "user-context": { "backup": false }
914 915 916
            },

        ]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
917 918
    }
}</userinput>
919
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
920

921 922 923 924 925
        </para>
        <para>
        Similarly, we need to construct the three reverse DDNS Domains:
        <table>
          <title>Reverse DDNS Domains Needed</title>
926 927 928 929
          <tgroup cols="3" align="left">
          <colspec colname="num"/>
          <colspec colname="DDNS Domain name"/>
          <colspec colname="DDNS Domain DNS Servers"/>
930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961
          <thead>
            <row>
              <entry>#</entry>
              <entry>DDNS Domain Name</entry>
              <entry>DNS Servers</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>1.</entry>
              <entry>2.0.192.in-addr.arpa.</entry>
              <entry>172.16.1.5, 172.16.2.5</entry>
            </row>
            <row>
              <entry>2.</entry>
              <entry>1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa.</entry>
              <entry>3001:1::50</entry>
            </row>
            <row>
              <entry>3.</entry>
              <entry>0.182.in-addr.arpa.</entry>
              <entry>172.16.2.5</entry>
            </row>
          </tbody>
          </tgroup>
        </table>
        An address of "192.0.2.150" will match the first domain,
        "2001:db8:1::10" will match the second domain, and "192.0.50.77"
        the third domain.
        </para>
        <para>
        These Reverse DDNS Domains are specified as follows:
Tomek Mrugalski's avatar
Tomek Mrugalski committed
962 963 964

<screen><userinput>
"DhcpDdns": {
965
    "comment": "example configuration: reverse part",
966
    "reverse-ddns": {
967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990
        "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" }
                ]
            }
        ]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
991 992
    }
}</userinput>
993
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
994

995 996
        </para>
        </section> <!-- end of "d2-example" -->
997 998 999 1000 1001
    </section> <!-- end of section "d2-configuration" -->
    <section>
      <title>DHCP-DDNS Server Limitations</title>
      <para>The following are the current limitations of the DHCP-DDNS Server.</para>
      <itemizedlist>
1002 1003 1004 1005 1006 1007 1008
        <listitem>
          <simpara>
            Requests received from the DHCP servers are placed in a
            queue until they are processed.  Currently all queued requests
            are lost when the server shuts down.
          </simpara>
        </listitem>
1009 1010
      </itemizedlist>
    </section>
1011
  </chapter>