ddns.xml 30.6 KB
Newer Older
1 2 3 4 5 6 7 8 9
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash  "&#x2014;" >
]>

  <chapter id="dhcp-ddns-server">
    <title>The DHCP-DDNS Server</title>
    <para>
10
    The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts the client side of
11 12
    the DDNS protocol (defined in <ulink url="http://tools.ietf.org/html/rfc2136">RFC 2136</ulink>)
    on behalf of the DHCPv4 and DHCPv6
13
    servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP servers construct
14 15 16 17 18 19
    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.
    </para>
    <para>
20
    In order to match a request to the appropriate DNS servers, D2 must have a
21 22 23
    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
24
    Domains. Further, each DDNS Domain has a list of one or more DNS
25 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
    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 id="dhcp-ddns-server-start-stop">
      <title>Starting and Stopping the DHCP-DDNS Server</title>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
54

55
      <para>
56 57 58
      <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
59
      Kea, it is a separate binary that can be run on its own or through
Jeremy C. Reed's avatar
Jeremy C. Reed committed
60
      <command>keactrl</command> (see <xref linkend="keactrl"/>). In
61
      normal operation, controlling <command>kea-dhcp-ddns</command>
Jeremy C. Reed's avatar
Jeremy C. Reed committed
62
      with <command>keactrl</command> is recommended. However, it is also
Tomek Mrugalski's avatar
Tomek Mrugalski committed
63 64
      possible to run the DHCP-DDNS server directly. It accepts the
      following command-line switches:
65
      </para>
66

Tomek Mrugalski's avatar
Tomek Mrugalski committed
67 68 69 70 71 72 73 74 75 76 77
      <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,
78
            the logging severity and debuglevel specified in the configuration
Tomek Mrugalski's avatar
Tomek Mrugalski committed
79 80 81 82 83 84 85
            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
86
              <command>-v</command> - prints out Kea version and exits.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
87 88 89 90
            </simpara>
          </listitem>
          <listitem>
            <simpara>
91 92 93 94 95
              <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
96 97
            </simpara>
          </listitem>
98 99 100 101 102 103
          <listitem>
            <simpara>
              <command>-W</command> - prints out Kea configuration report
              and exits.
            </simpara>
          </listitem>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
104 105
      </itemizedlist>

106 107 108 109 110
      <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>
111
            subdirectory in the source tree. For example
112
            <filename>kea/src/bin/d2/.libs/kea-dhcp-ddns</filename>.
113 114 115 116 117
<screen>
strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
</screen>
      </para>

118 119 120 121
      <para>
      Upon start up the module will load its configuration and begin listening
      for NCRs based on that configuration.
      </para>
122 123 124 125 126 127 128 129

      <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
130
            build configure script. It defaults to "/usr/local/var".  Note
131 132 133 134 135
            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>
136
            <simpara><command>conf name</command>: The configuration file name
137 138 139 140 141 142 143 144 145
            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
146
        and the process to which the PID belongs is unrelated to Kea.  In such a
147 148 149 150
        case it would be necessary to manually delete the PID file.
      </para>


151 152 153 154
    </section> <!-- end start-stop -->
    <section id="d2-configuration">
      <title>Configuring the DHCP-DDNS Server</title>
      <para>
155
	Before starting <command>kea-dhcp-ddns</command> module for the
Tomek Mrugalski's avatar
Tomek Mrugalski committed
156
	first time, a configuration file needs to be created. The following default
157
	configuration is a template that can be customised to your requirements.
158
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
159
<userinput>"DhcpDdns": {
160
    "ip-address": "127.0.0.1",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
161
    "port": 53001,
162 163 164 165 166 167
    "dns-server-timeout": 100,
    "ncr-protocol": "UDP",
    "ncr-format": "JSON",
    "tsig-keys": [ ],
    "forward-ddns": {
	"ddns-domains": [ ]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
168
    },
169 170
    "reverse-ddns": {
	"ddns-domains": [ ]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
171 172
    }
}</userinput>
173 174 175 176 177 178
</screen>
      </para>
      <para>
      The configuration can be divided as follows, each of which is described
      in its own section:
      </para>
179 180 181
	<itemizedlist>
	  <listitem>
	    <simpara>
182
        <emphasis>Global Server Parameters</emphasis> - values which control connectivity and global server behavior
183 184 185 186
	    </simpara>
	  </listitem>
	  <listitem>
	    <simpara>
187
	      <emphasis>TSIG Key Info</emphasis> - defines the TSIG keys used for secure traffic with DNS servers
188 189 190 191
	    </simpara>
	  </listitem>
	  <listitem>
	    <simpara>
192
	      <emphasis>Forward DDNS</emphasis> - defines the catalog of Forward DDNS Domains
193 194 195 196
	    </simpara>
	  </listitem>
	  <listitem>
	    <simpara>
197
	      <emphasis>Reverse DDNS</emphasis> - defines the catalog of Forward DDNS Domains
198 199 200
	    </simpara>
	  </listitem>
	</itemizedlist>
201
      <section id="d2-server-parameter-config">
202
	<title>Global Server Parameters</title>
203 204 205
      <itemizedlist>

      <listitem><simpara>
206
      <command>ip-address</command> - IP address on which D2
207 208 209 210 211 212
      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
213
      is 53001.
214 215 216
      </simpara></listitem>

      <listitem><simpara>
217
      <command>dns-server-timeout</command> - The maximum amount
218 219 220 221 222
      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>
223
      <command>ncr-protocol</command> - Socket protocol to use when sending requests to D2.
224
      Currently only UDP is supported.  TCP may be available in a future release.
225 226 227
      </simpara></listitem>

      <listitem><simpara>
228
      <command>ncr-format</command> - Packet format to use when sending requests to D2.
229 230
      Currently only JSON format is supported.  Other formats may be available
      in future releases.
231 232 233
      </simpara></listitem>

      </itemizedlist>
234 235 236 237 238
	<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:
239
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
240
"DhcpDdns": {
241
    <userinput>"ip-address": "192.168.1.10",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
242 243 244 245
    "port": 900,</userinput>
    ...
    }
}</screen>
246 247 248
	</para>
	<warning>
	  <simpara>
249 250 251 252 253 254
	    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
255 256
	    authentication to guard against such attacks.
	  </simpara>
257
<!-- see ticket #3514 -->
258
	</warning>
259 260
<note>
<simpara>
261
If the ip-address and port are changed, it will be necessary to change the
262 263 264 265 266 267
corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
</simpara>
</note>
      </section> <!-- "d2-server-parameter-config" -->

      <section id="d2-tsig-key-list-config">
268 269 270 271 272 273 274
	<title>TSIG Key List</title>
	<para>
	A DDNS protocol exchange can be conducted with or without TSIG
	(defined in <ulink url="http://tools.ietf/org/html/rfc2845">RFC
	2845</ulink>). This configuration section allows the administrator
	to define the set of TSIG keys that may be used in such
	exchanges.</para>
275

276 277 278 279 280 281 282 283 284
	<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>
285

286
	<para>
287
	As one might gather from the name, the tsig-key section of the
288 289 290 291 292 293
	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>
294
	      <command>name</command> -
295 296 297 298 299 300 301 302 303 304
	      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>
305
	      <command>algorithm</command> -
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
	      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>
332 333
	  <listitem>
	    <simpara>
334
	      <command>digest-bits</command> -
335
	      is used to specify the minimum truncated length in bits.
336
	      The default value 0 means truncation is forbidden, non-zero
337 338 339 340 341 342
	      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>
343 344
	  <listitem>
	    <simpara>
345
	      <command>secret</command> -
346 347 348 349 350 351 352 353 354 355 356 357
	      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:
358 359 360 361 362 363 364 365
<screen>
   :
   key "key.four.example.com." {
       algorithm hmac-sha224;
       secret "bZEG7Ow8OgAUPfLWV3aAUQ==";
   };
   :
</screen>
366
	By default, the TSIG Key list is empty:
367
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
368
"DhcpDdns": {
369
   <userinput>"tsig-keys": [ ]</userinput>,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
370 371
   ...
}
372
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
373

374
	We must extend the list with a new key:
375
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
376
"DhcpDdns": {
377
    "tsig-keys": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
378
    <userinput>    {
379
	    "name": "key.four.example.com.",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
380 381
	    "algorithm": "HMAC-SHA224",
	    "secret": "bZEG7Ow8OgAUPfLWV3aAUQ=="
382
	}</userinput>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
383 384 385
    ],
    ...
}
386
</screen>
387
	</para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
388

389 390
	<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
391
      </section>
392
	<!-- "d2-tsig-key-list-config" -->
393 394

      <section id="d2-forward-ddns-config">
395 396 397 398 399
	<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.
400
<screen>
401
"DhcpDdns": {
402 403
    <userinput>"forward-ddns": {
	"ddns-domains": [ ]
404
    }</userinput>,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
405
    ...
406
}
407
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
408

409 410 411 412 413 414
	By default, this list is empty, which will cause the server to ignore
	the forward update portions of requests.
	</para>
	<section id="add-forward-ddns-domain">
	  <title>Adding Forward DDNS Domains</title>
	  <para>
415 416 417 418 419 420 421 422
	  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.
423 424
	  </para>
	  <para>
425
	  This section describes how to add Forward DDNS Domains. Repeat these
426 427 428 429 430
	  steps for each Forward DDNS Domain desired.  Each Forward DDNS Domain
	  has the following parameters:
	  <itemizedlist>
	    <listitem>
	      <simpara>
431
	      <command>name</command> -
432 433 434 435 436 437 438 439
	      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>
440
	      <command>key-name</command> -
441 442 443
	      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
444
	      used in DDNS conversations with this domain's servers.
445 446 447 448
	      </simpara>
	    </listitem>
	    <listitem>
	      <simpara>
449
	      <command>dns-servers</command> -
450 451 452 453 454 455 456 457 458 459 460 461
	      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:
462
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
463
"DhcpDdns": {
464 465
    "forward-ddns": {
	"ddns-domains": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
466
	    <userinput>{
467
		"name": "other.example.com.",
468 469
		"key-name": "",
		"dns-servers": [
470 471 472
		]
	    }</userinput>
	]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
473 474
    }
}
475 476
</screen>

477 478 479 480 481 482 483 484 485
	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>

	<section id="add-forward-dns-servers">
	  <title>Adding Forward DNS Servers</title>
	  <para>
486
	  This section describes how to add DNS servers to a Forward DDNS Domain.
487 488 489 490 491 492 493 494 495
	  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>
496
	      <command>hostname</command> -
497 498 499 500 501 502
	      The resolvable host name of the DNS server. This value is not
	      yet implemented.
	      </simpara>
	    </listitem>
	    <listitem>
	      <simpara>
503
	      <command>ip-address</command> -
504 505 506 507 508 509
	      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>
510
	      <command>port</command> -
511 512 513 514 515 516
	      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
517
	  element to the domain and fill in its parameters.  If for
518 519
	example the service is running at "172.88.99.10", then set it as
	follows:
520
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
521
"DhcpDdns": {
522 523
    "forward-ddns": {
	"ddns-domains": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
524
	    {
525
		"name": "other.example.com.",
526 527
		"key-name": "",
		"dns-servers": [
528 529
		    <userinput>{
			"hostname": "",
530
			"ip-address": "172.88.99.10",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
531
			"port": 53
532 533 534 535
		    }</userinput>
		]
	    }
	]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
536 537
    }
}
538
</screen>
539
	  </para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
540

541
    <note><simpara>
542
	As stated earlier, "hostname" is not yet supported so, the parameter
543
	"ip-address" must be set to the address of the DNS server.
544 545
    </simpara></note>

546
	</section> <!-- "add-forward-dns-servers" -->
547 548 549 550 551 552

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

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

      <section id="d2-reverse-ddns-config">
553 554 555 556 557 558
	<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.
559
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
560
"DhcpDdns": {
561 562
    <userinput>"reverse-ddns": {
	"ddns-domains": [ ]
563 564
    }</userinput>
    ...
Tomek Mrugalski's avatar
Tomek Mrugalski committed
565
}
566
</screen>
567 568 569 570 571 572
	By default, this list is empty, which will cause the server to ignore
	the reverse update portions of requests.
	</para>
	<section id="add-reverse-ddns-domain">
	  <title>Adding Reverse DDNS Domains</title>
	  <para>
573 574 575 576 577 578 579 580 581
	  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.
582 583
	  </para>
	  <para>
584
	  This section describes how to add Reverse DDNS Domains. Repeat these
585 586 587 588 589
	  steps for each Reverse DDNS Domain desired.  Each Reverse DDNS Domain
	  has the following parameters:
	  <itemizedlist>
	    <listitem>
	      <simpara>
590
	      <command>name</command> -
591 592 593 594 595 596
	      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,
597
	      to support an IPv6 subnet of 2001:db8:1, the name should be
598 599 600 601 602 603
	      "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>
604
	      <command>key-name</command> -
605 606 607 608 609 610 611 612 613
	      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>
614
	      <command>dns-servers</command> -
615 616 617 618 619 620 621 622 623 624 625 626
	      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::,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
627
	the following configuration could be used:
628
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
629
"DhcpDdns": {
630 631
    "reverse-ddns": {
	"ddns-domains": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
632
	    <userinput>{
633
		"name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
634 635
		"key-name": "",
		"dns-servers": [
636 637 638
		]
	    }</userinput>
	]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
639 640
    }
}
641
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
642

643 644 645 646 647
	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>
648

649 650 651
	<section id="add-reverse-dns-servers">
	  <title>Adding Reverse DNS Servers</title>
	  <para>
652 653
	  This section describes how to add DNS servers to a Reverse DDNS Domain.
	  Repeat them for as many servers as desired for each domain.
654 655 656 657 658 659 660 661
	  </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>
662
	      <command>hostname</command> -
663 664 665 666 667 668
	      The resolvable host name of the DNS server. This value is
	      currently ignored.
	      </simpara>
	    </listitem>
	    <listitem>
	      <simpara>
669
	      <command>ip-address</command> -
670 671 672 673 674
	      The IP address at which the server listens for DDNS requests.
	      </simpara>
	    </listitem>
	    <listitem>
	      <simpara>
675
	      <command>port</command> -
676 677 678 679 680 681
	      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
682
	  element to the domain and fill in its parameters.  If for
683 684
	example the service is running at "172.88.99.10", then set it as
	follows:
685
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
686
"DhcpDdns": {
687 688
    "reverse-ddns": {
	"ddns-domains": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
689
	    {
690
		"name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
691 692
		"key-name": "",
		"dns-servers": [
693 694
		    <userinput>{
			"hostname": "",
695
			"ip-address": "172.88.99.10",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
696
			"port": 53
697 698 699 700
		    }</userinput>
		]
	    }
	]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
701 702
    }
}
703
</screen>
704 705 706 707 708
</para>

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

713
	</section> <!-- "add-reverse-dns-servers" -->
714 715 716 717 718

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

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

Andrei Pavel's avatar
Andrei Pavel committed
719
      <section id="d2-example-config">
720 721 722 723 724
	<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.
725

726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805
	<table>
	  <title>Our example network</title>
	  <tgroup cols='4' align='left'>
	  <colspec colname='domain'/>
	  <colspec colname='subnet'/>
	  <colspec colname='fservers'/>
	  <colspec colname='rservers'/>
	  <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>
	  <tgroup cols='3' align='left'>
	  <colspec colname='num'/>
	  <colspec colname='name'/>
	  <colspec colname='servers'/>
	  <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>
806
	The following example configuration specified the Forward DDNS Domains.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
807 808
<screen><userinput>
"DhcpDdns": {
809 810
    "forward-ddns": {
	"ddns-domains": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
811
	    {
812
		"name": "four.example.com.",
813 814 815 816
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "172.16.1.5" },
		    { "ip-address": "172.16.2.5" }
817 818
		]
	    },
Tomek Mrugalski's avatar
Tomek Mrugalski committed
819
	    {
820
		"name": "six.example.com.",
821 822 823
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "2001:db8::1" }
824 825
		]
	    },
Tomek Mrugalski's avatar
Tomek Mrugalski committed
826
	    {
827
		"name": "example.com.",
828 829 830
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "172.16.2.5" }
831 832 833 834
		]
	    },

	]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
835 836
    }
}</userinput>
837
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
838

839 840 841 842 843 844 845 846 847 848 849 850 851 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
	</para>
	<para>
	Similarly, we need to construct the three reverse DDNS Domains:
	<table>
	  <title>Reverse DDNS Domains Needed</title>
	  <tgroup cols='3' align='left'>
	  <colspec colname='num'/>
	  <colspec colname='DDNS Domain name'/>
	  <colspec colname='DDNS Domain DNS Servers'/>
	  <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>
879
	These Reverse DDNS Domains are specified as follows:
Tomek Mrugalski's avatar
Tomek Mrugalski committed
880 881 882

<screen><userinput>
"DhcpDdns": {
883 884
    "reverse-ddns": {
	"ddns-domains": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
885
	    {
886
		"name": "2.0.192.in-addr.arpa.",
887 888 889 890
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "172.16.1.5" },
		    { "ip-address": "172.16.2.5" }
891 892
		]
	    }
Tomek Mrugalski's avatar
Tomek Mrugalski committed
893
	    {
894
		"name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
895 896 897
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "2001:db8::1" }
898 899
		]
	    }
Tomek Mrugalski's avatar
Tomek Mrugalski committed
900
	    {
901
		"name": "0.192.in-addr.arpa.",
902 903 904
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "172.16.2.5" }
905 906 907
		]
	    }
	]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
908 909
    }
}</userinput>
910
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
911

912 913
	</para>
	</section> <!-- end of "d2-example" -->
914 915 916 917 918
    </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>
919 920 921 922 923 924 925
	<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>
926 927 928
      </itemizedlist>
    </section>
  </chapter> <!-- DHCP-DDNS Server -->