ddns.xml 30.9 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
    the DDNS protocol (defined in RFC 2136) on behalf of the DHCPv4 and DHCPv6
12
    servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP servers construct
13
14
15
16
17
18
    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>
19
    In order to match a request to the appropriate DNS servers, D2 must have a
20
21
22
    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
23
    Domains. Further, each DDNS Domain has a list of one or more DNS
24
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
    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
53

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

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

102
      <para>
103
104
            The <command>-V</command> command returns the versions of the
            external libraries dynamically linked.
105
106
      </para>

107
      <para>
108
109
110
111
112
113
114
115
116
117
118
119
            The <command>-W</command> command describes the environment used
            to build Kea.  This command displays a copy of the
            <filename>config.report</filename> file produced by
            <userinput>./configure</userinput> that is embedded in the
            executable binary.
      </para>

      <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>
120
121
            subdirectory in the source treee. For example
            <filename>kea/src/bin/d2/.libs/kea-dhcp-ddns</filename>.
122
123
124
125
126
<screen>
strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
</screen>
      </para>

127
128
129
130
      <para>
      Upon start up the module will load its configuration and begin listening
      for NCRs based on that configuration.
      </para>
131
132
133
134
135
136
137
138

      <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
139
            build configure script. It defaults to "/usr/local/var".  Note
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
            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>
            <simpara><command>conf name</command>: The confguration file name
            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
155
        and the process to which the PID belongs is unrelated to Kea.  In such a
156
157
158
159
        case it would be necessary to manually delete the PID file.
      </para>


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

      <listitem><simpara>
219
      <command>ip-address</command> - IP address on which D2
220
221
222
223
224
225
      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
226
      is 53001.
227
228
229
      </simpara></listitem>

      <listitem><simpara>
230
      <command>dns-server-timeout</command> - The maximum amount
231
232
233
234
235
      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>
236
      <command>ncr-protocol</command> - Socket protocol to use when sending requests to D2.
237
238
      Currently only UDP is supported.  TCP may be available in an upcoming
      release.
239
240
241
      </simpara></listitem>

      <listitem><simpara>
242
      <command>ncr-format</command> - Packet format to use when sending requests to D2.
243
244
      Currently only JSON format is supported.  Other formats may be available
      in future releases.
245
246
247
      </simpara></listitem>

      </itemizedlist>
248
249
250
251
252
	<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:
253
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
254
"DhcpDdns": {
255
    <userinput>"ip-address": "192.168.1.10",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
256
257
258
259
    "port": 900,</userinput>
    ...
    }
}</screen>
260
261
262
	</para>
	<warning>
	  <simpara>
263
264
265
266
267
268
	    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
269
270
	    authentication to guard against such attacks.
	  </simpara>
271
<!-- see ticket #3514 -->
272
	</warning>
273
274
<note>
<simpara>
275
If the ip-address and port are changed, it will be necessary to change the
276
277
278
279
280
281
corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
</simpara>
</note>
      </section> <!-- "d2-server-parameter-config" -->

      <section id="d2-tsig-key-list-config">
282
283
284
285
286
287
288
	<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>
289

290
291
292
293
294
295
296
297
298
	<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>
299

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

388
	We must extend the list with a new key:
389
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
390
"DhcpDdns": {
391
    "tsig-keys": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
392
    <userinput>    {
393
	    "name": "key.four.example.com.",
Tomek Mrugalski's avatar
Tomek Mrugalski committed
394
395
	    "algorithm": "HMAC-SHA224",
	    "secret": "bZEG7Ow8OgAUPfLWV3aAUQ=="
396
	}</userinput>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
397
398
399
    ],
    ...
}
400
</screen>
401
	</para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
402

403
404
	<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
405
      </section>
406
	<!-- "d2-tsig-key-list-config" -->
407
408

      <section id="d2-forward-ddns-config">
409
410
411
412
413
	<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.
414
<screen>
415
"DhcpDdns": {
416
417
    <userinput>"forward-ddns": {
	"ddns-domains": [ ]
418
    }</userinput>,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
419
    ...
420
}
421
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
422

423
424
425
426
427
428
	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>
429
430
431
432
433
434
435
436
	  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.
437
438
	  </para>
	  <para>
439
	  This section describes how to add Forward DDNS Domains. Repeat these
440
441
442
443
444
	  steps for each Forward DDNS Domain desired.  Each Forward DDNS Domain
	  has the following parameters:
	  <itemizedlist>
	    <listitem>
	      <simpara>
445
	      <command>name</command> -
446
447
448
449
450
451
452
453
	      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>
454
	      <command>key-name</command> -
455
456
457
	      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
458
	      used in DDNS conversations with this domain's servers.
459
460
461
462
	      </simpara>
	    </listitem>
	    <listitem>
	      <simpara>
463
	      <command>dns-servers</command> -
464
465
466
467
468
469
470
471
472
473
474
475
	      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:
476
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
477
"DhcpDdns": {
478
479
    "forward-ddns": {
	"ddns-domains": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
480
	    <userinput>{
481
		"name": "other.example.com.",
482
483
		"key-name": "",
		"dns-servers": [
484
485
486
		]
	    }</userinput>
	]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
487
488
    }
}
489
490
</screen>

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

555
    <note><simpara>
556
	As stated earlier, "hostname" is not yet supported so, the parameter
557
	"ip-address" must be set to the address of the DNS server.
558
559
    </simpara></note>

560
	</section> <!-- "add-forward-dns-servers" -->
561
562
563
564
565
566

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

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

      <section id="d2-reverse-ddns-config">
567
568
569
570
571
572
	<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.
573
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
574
"DhcpDdns": {
575
576
    <userinput>"reverse-ddns": {
	"ddns-domains": [ ]
577
578
    }</userinput>
    ...
Tomek Mrugalski's avatar
Tomek Mrugalski committed
579
}
580
</screen>
581
582
583
584
585
586
	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>
587
588
589
590
591
592
593
594
595
	  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.
596
597
	  </para>
	  <para>
598
	  This section describes how to add Reverse DDNS Domains. Repeat these
599
600
601
602
603
	  steps for each Reverse DDNS Domain desired.  Each Reverse DDNS Domain
	  has the following parameters:
	  <itemizedlist>
	    <listitem>
	      <simpara>
604
	      <command>name</command> -
605
606
607
608
609
610
611
612
613
614
615
616
617
	      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 subent 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>
618
	      <command>key-name</command> -
619
620
621
622
623
624
625
626
627
	      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>
628
	      <command>dns-servers</command> -
629
630
631
632
633
634
635
636
637
638
639
640
	      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
641
	the following configuration could be used:
642
<screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
643
"DhcpDdns": {
644
645
    "reverse-ddns": {
	"ddns-domains": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
646
	    <userinput>{
647
		"name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
648
649
		"key-name": "",
		"dns-servers": [
650
651
652
		]
	    }</userinput>
	]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
653
654
    }
}
655
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
656

657
658
659
660
661
	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>
662

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

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

727
	</section> <!-- "add-reverse-dns-servers" -->
728
729
730
731
732
733

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

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

      <section id="d2-exmaple-config">
734
735
736
737
738
	<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.
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
806
807
808
809
810
811
812
813
814
815
816
817
818
819
	<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>
820
	The following example configuration specified the Forward DDNS Domains.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
821
822
<screen><userinput>
"DhcpDdns": {
823
824
    "forward-ddns": {
	"ddns-domains": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
825
	    {
826
		"name": "four.example.com.",
827
828
829
830
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "172.16.1.5" },
		    { "ip-address": "172.16.2.5" }
831
832
		]
	    },
Tomek Mrugalski's avatar
Tomek Mrugalski committed
833
	    {
834
		"name": "six.example.com.",
835
836
837
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "2001:db8::1" }
838
839
		]
	    },
Tomek Mrugalski's avatar
Tomek Mrugalski committed
840
	    {
841
		"name": "example.com.",
842
843
844
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "172.16.2.5" }
845
846
847
848
		]
	    },

	]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
849
850
    }
}</userinput>
851
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
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
887
888
889
890
891
892
	</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>
893
	These Reverse DDNS Domains are specified as follows:
Tomek Mrugalski's avatar
Tomek Mrugalski committed
894
895
896

<screen><userinput>
"DhcpDdns": {
897
898
    "reverse-ddns": {
	"ddns-domains": [
Tomek Mrugalski's avatar
Tomek Mrugalski committed
899
	    {
900
		"name": "2.0.192.in-addr.arpa.",
901
902
903
904
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "172.16.1.5" },
		    { "ip-address": "172.16.2.5" }
905
906
		]
	    }
Tomek Mrugalski's avatar
Tomek Mrugalski committed
907
	    {
908
		"name": "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa.",
909
910
911
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "2001:db8::1" }
912
913
		]
	    }
Tomek Mrugalski's avatar
Tomek Mrugalski committed
914
	    {
915
		"name": "0.192.in-addr.arpa.",
916
917
918
		"key-name": "",
		"dns-servers": [
		    { "ip-address": "172.16.2.5" }
919
920
921
		]
	    }
	]
Tomek Mrugalski's avatar
Tomek Mrugalski committed
922
923
    }
}</userinput>
924
</screen>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
925

926
927
	</para>
	</section> <!-- end of "d2-example" -->
928
929
930
931
932
    </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>
933
934
935
936
937
938
939
	<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>
940
941
942
      </itemizedlist>
    </section>
  </chapter> <!-- DHCP-DDNS Server -->