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

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 ... -->
@@ -197,6 +197,16 @@
 
           <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;
               Message bus daemon.
               This process coordinates communication between all of the other
@@ -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>