[2005] added a chapter for DDNS to BIND 10 guide.

diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index 7f7d0206f2e92494c63ec70c3ce9bf0531d33ad4..20914af9b8fe9dc04a8f8c3755a90a2da608ecdb 100644 (file)
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -128,10 +128,10 @@
       </para>
 
       <para>
-        The <command>b10-xfrin</command>, <command>b10-xfrout</command>,
-        and <command>b10-zonemgr</command> components require the
-        libpython3 library and the Python _sqlite3.so module
-        (which is included with Python).
+        The <command>b10-ddns</command>, <command>b10-xfrin</command>,
+        <command>b10-xfrout</command>, and <command>b10-zonemgr</command>
+        components require the libpython3 library and the Python
+        _sqlite3.so module (which is included with Python).
         The Python module needs to be built for the corresponding Python 3.
       </para>
 <!-- TODO: this will change ... -->
@@ -195,6 +195,16 @@
             </simpara>
           </listitem>
 
+          <listitem>
+            <simpara>
+              <command>b10-ddns</command> &mdash;
+              Dynamic DNS update service.
+              This process is used to handle incoming DNS update
+              requests to allow granted clients to update zones
+             for which BIND 10 is serving as a primary server.
+            </simpara>
+          </listitem>
+
           <listitem>
             <simpara>
               <command>b10-msgq</command> &mdash;
@@ -1832,7 +1842,6 @@ what if a NOTIFY is sent?
 
   <chapter id="xfrout">
     <title>Outbound Zone Transfers</title>
-
     <para>
       The <command>b10-xfrout</command> process is started by
       <command>bind10</command>.
@@ -1908,6 +1917,251 @@ what is XfroutClient xfr_client??
 
   </chapter>
 
+  <chapter id="ddns">
+    <title>Dynamic DNS Update</title>
+
+    <para>
+      BIND 10 supports the server side of the Dynamic DNS Update
+      (DDNS) protocol as defined in RFC 2136.
+      This service is provided by the <command>b10-ddns</command>
+      process, which is started by the <command>bind10</command>
+      process if configured so.
+    </para>
+
+    <para>
+      When the <command>b10-auth</command> authoritative DNS server
+      receives an UPDATE request, it internally forwards the request
+      to <command>b10-ddns</command>, which handles the rest of
+      request processing.
+      When the process is completed <command>b10-ddns</command>
+      will send a response to the client with the processing result.
+      If the zone has been changed as a result, it will internally
+      notify <command>b10-auth</command> and
+      <command>b10-xfrout</command> so the new version of zone will
+      be served, and other secondary servers will be notified via the
+      DNS notify protocol.
+    </para>
+
+    <para>
+      The <command>b10-ddns</command> process supports requests over
+      both UDP and TCP, and both IPv6 and IPv4; for TCP requests,
+      however, it terminates the TCP connection immediately after
+      each single request has been processed.  Clients cannot reuse the
+      same TCP connection for multiple requests.
+    </para>
+
+    <para>
+      As of this writing <command>b10-ddns</command> does not support
+      update forwarding for secondary zones.
+      If it receives an update request for a secondary zone, it will
+      immediately return a response with an RCODE of NOTIMP.
+    </para>
+
+    <section>
+      <title>Enabling Dynamic Update</title>
+      <para>
+       First off, it must be made sure that a few components on which
+       <command>b10-ddns</command> depends are configured to run,
+       which are <command>b10-auth</command>
+       and <command>b10-zonemgr</command>.
+       If BIND 10 is already configured to provide authoritative DNS
+       service they should normally be configured to run already.
+      </para>
+
+      <para>
+       Second, for the obvious reason dynamic update requires that the
+       underlying data source storing the zone data be writable.
+       In the current implementation this means the zone must be stored
+       in an SQLite3-based data source.
+       Also, right now, the <command>b10-ddns</command> process
+       configures itself with the data source referring to the
+       <quote>database_file</quote> configuration parameter of
+       <command>b10-auth</command>.
+       So this information must be configured correctly before starting
+       <command>b10-ddns</command>.
+
+       <note><simpara>
+           The way to configure data sources is now being revised.
+           Configuration on the data source for DDNS will be very
+           likely to be changed in a backward incompatible manner in
+           a near future version.
+       </simpara></note>
+      </para>
+
+      <para>
+       Next, to enable the DDNS service, <command>b10-ddns</command>
+       needs to be explicitly configured to run.
+       It can be done by using the <command>bindctl</command>
+       utility.  For example:
+      <screen>
+&gt; <userinput>config add Boss/components b10-ddns</userinput>
+&gt; <userinput>config set Boss/components/b10-ddns/address DDNS</userinput>
+&gt; <userinput>config set Boss/components/b10-ddns/kind dispensable</userinput>
+&gt; <userinput>config commit</userinput>
+</screen>
+      </para>
+    </section>
+
+    <section>
+      <title>Access Control</title>
+      <para>
+       By default <command>b10-ddns</command> rejects any update
+       requests from any clients by returning a response with an RCODE
+       of REFUSED.
+       To allow updates to take effect, an access control rule
+       (called update ACL) with that policy must explicitly be
+       configured.
+       Update ACL must be configured per zone basis in the
+       <quote>zones</quote> configuration parameter of
+       <command>b10-ddns</command>.
+       This is a list of per-zone configuration regarding DDNS.
+       Each list element consists of the following parameters:
+        <variablelist>
+          <varlistentry>
+            <term>origin</term>
+            <listitem>
+              <simpara>The zone's origin name</simpara>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>class</term>
+            <listitem>
+              <simpara>The RR class of the zone
+               (normally <quote>IN</quote>)</simpara>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>update_acl</term>
+            <listitem>
+              <simpara>List of access control rules (ACL) for the zone</simpara>
+            </listitem>
+          </varlistentry>
+       </variablelist>
+       The syntax of the ACL is the same as ACLs for other
+       components.
+       Specific examples are given below.
+      </para>
+
+      <para>
+       In general, an update ACL rule that allows an update request
+       should be configured with a TSIG key.
+       This is an example update ACL that allows updates to the zone
+       named <quote>example.org</quote> of RR class <quote>IN</quote>
+       from clients that send requests signed with a TSIG whose
+       key name is "key.example.org" (and refuses all others):
+      <screen>
+&gt; <userinput>config add DDNS/zones</userinput>
+&gt; <userinput>config set DDNS/zones[0]/origin example.org</userinput>
+&gt; <userinput>config set DDNS/zones[0]/class IN</userinput>
+&gt; <userinput>config set DDNS/zones[0]/update_acl [{"action": "ACCEPT", "key": "key.example.org"}]</userinput>
+&gt; <userinput>config commit</userinput>
+       </screen>
+      The TSIG key must be configured system wide
+      (see <xref linkend="xfrout"/>.)
+      </para>
+
+      <para>
+       Multiple rules can be specified in the ACL, and an ACL rule
+       can consist of multiple constraints, such as a combination of
+       IP address and TSIG.
+       The following ACL is to allow update requests that meet the
+       above condition, or requests sent from a client using TSIG key
+       name of "key.example" and has an IPv6 address of ::1.
+      <screen>
+&gt; <userinput>config set DDNS/zones[0]/update_acl [{"action": "ACCEPT", "key": "key.example.org"}, {"action": "ACCEPT", "from": "::1", "key": "key.example"}]</userinput>
+&gt; <userinput>config commit</userinput>
+</screen>
+      (Right now, ACL cannot be updated incrementally; you need to
+      specify the entire new list of rules at once.)
+      </para>
+
+      <note><simpara>
+         The <command>b10-ddns</command> process accepts an ACL
+         rule that just allows updates from a specific IP address
+         (i.e., without requiring TSIG), but this is highly
+         discouraged (remember that requests can be made over UDP and
+         spoofing the source address of a UDP packet is often pretty
+         easy).
+         Unless you know what you are doing and that you can accept
+         its consequence, any update ACL rule that allows updates
+         should have a TSIG key in its constraints.
+      </simpara></note>
+
+      <para>
+       Currently update ACL can only control updates per zone basis;
+       it's not possible to specify access control with higher
+       granularity such as for particular domain names or specific
+       types of RRs.
+      </para>
+
+      <note><simpara>
+       Contrary to what RFC 2136 (literally) specifies,
+       <command>b10-ddns</command> checks the update ACL before
+       checking the prerequisites of the update request.
+       This is a deliberate implementation decision.
+       This counter intuitive specification has been repeatedly
+       discussed among implementers and in the IETF, and it is now
+       widely agreed that it does not make sense to strictly follow
+       that part of RFC.
+       One known specific bad result of this is that it could leak
+       information about which name or record exists or does not
+       exist in the zone as a result of prerequisite checks even if a
+       zone is somehow configured to reject normal queries from
+       arbitrary clients.
+       There have been other troubles that could have been avoided if
+       the ACL could be checked before the prerequisite check.
+      </simpara></note>
+    </section>
+
+    <section>
+      <title>Miscellaneous Operational Issues</title>
+      <para>
+       Unlike BIND 9, BIND 10 currently does not support automatic
+       resigning of DNSSEC-signed zone when it's updated via DDNS.
+       It could be possible to resign the updated zone afterwards
+       or make sure the update request also updates related DNSSEC
+       records, but that will be pretty error-prone operation.
+       In general, it's not advisable to allow DDNS for a signed zone
+       at this moment.
+      </para>
+
+      <para>
+       Also unlike BIND 9, it's currently not possible
+       to <quote>freeze</quote> a zone temporarily in order to
+       suspend DDNS while you manually update the zone.
+       If you need to make manual updates to a dynamic zone,
+       you'll need to temporarily reject any updates to the zone via
+       the update ACLs.
+      </para>
+
+      <para>
+       Dynamic updates are only applicable to primary zones.
+       In order to avoid updating secondary zones via DDNS requests,
+       <command>b10-ddns</command> refers to the
+       <quote>secondary_zones</quote> configuration of
+       <command>b10-zonemgr</command>.  Zones listed in
+       <quote>secondary_zones</quote> will never be updated via DDNS
+       regardless of the update ACL configuration.
+       If you have a "conceptual" secondary zone whose content is a
+       copy of some external source but is not updated via the
+       standard zone transfers and therefore not listed in
+       <quote>secondary_zones</quote>, be careful not to allow DDNS
+       for the zone; it would be quite likely to lead to inconsistent
+       state between different servers.
+       Normally this should not be a problem because the default
+       update ACL rejects any update requests, but you may want to
+       take an extra care about the configuration if you have such
+       type of secondary zones.
+      </para>
+      <para>
+       The difference of two versions of a zone, before and after a
+       DDNS transaction is automatically recorded in the underlying
+       data source, and can be retrieved in the form of outbound IXFR.
+       There has to be no configuration to make this possible.
+      </para>
+    </section>
+  </chapter>
+
   <chapter id="resolverserver">
     <title>Recursive Name Server</title>