[30-implement-control-socket-for-ddns-2] Reported doc updates

doc/examples/agent/simple.json

@@ -42,9 +42,7 @@
                 "socket-name": "/path/to/the/unix/socket-v6"
             },
 
-            // Currently DHCP-DDNS (nicknamed D2) does not support
+            // Location of the D2 command channel socket.
-            // command channel yet, but we hope this will change in the
-            // future.
             "d2":
             {
                 "socket-type": "unix",

doc/examples/ddns/comments.json

@@ -12,6 +12,13 @@
     "port": 53001,
     "dns-server-timeout" : 1000,
 
+    "control-socket":
+    {
+        "comment": "Control channel",
+        "socket-type": "unix",
+        "socket-name": "/tmp/d2-ctrl-socket"
+    },
+
     "forward-ddns":
     {
         "ddns-domains":

doc/examples/ddns/sample1.json

@@ -29,6 +29,15 @@
 
     "user-context": { "version": 1 },
 
+//
+// ----------------- Control Socket -----------------
+//
+
+    "control-socket":
+    {
+        "socket-type": "unix",
+        "socket-name": "/tmp/d2-ctrl-socket"
+    },
 
 //
 // ----------------- Forward DDNS  ------------------

doc/examples/ddns/template.json

@@ -20,6 +20,16 @@
 //    "ncr-protocol" : "UDP"
 //    "ncr-format" : "JSON"
 
+//
+// ----------------- Control Socket -----------------
+//
+
+//    "control-socket":
+//    {
+//        "socket-type": "unix",
+//        "socket-name": "/tmp/d2-ctrl-socket"
+//    },
+
 //
 // ----------------- Forward DDNS  ------------------
 //

doc/guide/agent.xml

@@ -77,7 +77,11 @@
                 "socket-type": "unix",
                 "socket-name": "/path/to/the/unix/socket-v6",
                 "user-context": { "version": 3 }
-            }
+            },
+            "d2": {
+                "socket-type": "unix",
+                "socket-name": "/path/to/the/unix/socket-d2"
+            },
         },
 
         "hooks-libraries": [
@@ -130,9 +134,10 @@
       commands to it. Obviously, the DHCPv4 server must be configured to
       listen to connections via this same socket. In other words, the command
       socket configuration for the DHCPv4 server and CA (for this server)
-      must match. Consult the <xref linkend="dhcp4-ctrl-channel"/> and the
+      must match. Consult the <xref linkend="dhcp4-ctrl-channel"/>, the
-      <xref linkend="dhcp6-ctrl-channel"/> to learn how the socket
+      <xref linkend="dhcp6-ctrl-channel"/> and
-      configuration is specified for the DHCPv4 and DHCPv6 services.
+      <xref linkend="d2-ctrl-channel"/> to learn how the socket
+      configuration is specified for the DHCPv4, DHCPv6 and D2 services.
     </para>
 
     <warning>

doc/guide/ctrl-channel.xml

@@ -19,14 +19,14 @@
     the server may refuse to start, which will further extend the
     downtime period until the issue is resolved.</para>
 
-    <para>To avoid such problems, both the DHCPv4 and DHCPv6 servers
+    <para>To avoid such problems, the DHCPv4, DHCPv6 and D2 servers
     include support for a mechanism that allows
     on-line reconfiguration without requiring server shutdown.
     Both servers can be instructed to open control sockets, which
     is a communication channel. The server is able to receive
     commands on that channel, act on them and report back status.</para>
 
-    <para>The DHCPv4 and DHCPv6 servers receive commands over the
+    <para>The DHCPv4, DHCPv6 and D2 servers receive commands over the
     unix domain sockets. The details how to configure these sockets,
     see <xref linkend="dhcp4-ctrl-channel"/> and <xref linkend="dhcp6-ctrl-channel"/>. While it is possible control
     the servers directly using unix domain sockets it requires that
@@ -613,6 +613,36 @@ $ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get"
 
     </section> <!-- end of commands supported by both servers -->
 
+    <section>
+      <title>Commands Supported by D2 Server</title>
+      <para>The D2 server supports only a subset of DHCPv4 / DHCPv6 server
+      commands:
+      <itemizedlist>
+        <listitem>
+          <simpara>build-report</simpara>
+        </listitem>
+        <listitem>
+          <simpara>config-get</simpara>
+        </listitem>
+        <listitem>
+          <simpara>config-test</simpara>
+        </listitem>
+        <listitem>
+          <simpara>config-write</simpara>
+        </listitem>
+        <listitem>
+          <simpara>list-commands</simpara>
+        </listitem>
+        <listitem>
+          <simpara>shutdown</simpara>
+        </listitem>
+        <listitem>
+          <simpara>version-get</simpara>
+        </listitem>
+      </itemizedlist>
+      </para>
+    </section>
+
     <section xml:id="agent-commands">
       <title>Commands Supported by Control Agent</title>
       <para>The following commands listed in <xref linkend="commands-common"/>

doc/guide/ddns.xml

@@ -238,6 +238,11 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
         <emphasis>Global Server Parameters</emphasis> - values which control connectivity and global server behavior
             </simpara>
           </listitem>
+          <listitem>
+            <simpara>
+              <emphasis>Control Socket</emphasis> - defines the Control Socket type and name.
+            </simpara>
+          </listitem>
           <listitem>
             <simpara>
               <emphasis>TSIG Key Info</emphasis> - defines the TSIG keys used for secure traffic with DNS servers
@@ -320,6 +325,57 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
 </note>
       </section> <!-- "d2-server-parameter-config" -->
 
+      <section xml:id="d2-ctrl-channel">
+        <title>Management API for the D2 Server</title>
+        <para>
+          The management API allows the issuing of specific management
+          commands, such as configuration retrieval or shutdown.
+          For more details, see <xref linkend="ctrl-channel"/>.
+          Currently the only supported communication channel type is UNIX
+          stream socket. By default there are no sockets open. To instruct
+          Kea to open a socket, the following entry in the configuration
+          file can be used:
+<screen>
+"DhcpDdns": {
+    "control-socket": {
+        "socket-type": "unix",
+        "socket-name": <userinput>"/path/to/the/unix/socket"</userinput>
+    },
+    ...
+}
+</screen>
+        </para>
+
+        <para>
+          The length of the path specified by
+          the <command>socket-name</command> parameter is restricted by
+          the maximum length for the unix socket name on your operating
+          system, i.e. the size of the <command>sun_path</command> field
+          in the <command>sockaddr_un</command> structure, decreased by 1.
+          This value varies on different operating systems between
+          91 and 107 characters. Typical values are 107 on Linux and 103
+          on FreeBSD.
+        </para>
+
+        <para>
+          Communication over control channel is conducted using JSON
+          structures.  See the Control Channel section in the Kea
+          Developer's Guide for more details.
+        </para>
+
+        <para>The D2 server supports the following operational commands:
+          <itemizedlist>
+              <listitem>build-report</listitem>
+              <listitem>config-get</listitem>
+              <listitem>config-test</listitem>
+              <listitem>config-write</listitem>
+              <listitem>list-commands</listitem>
+              <listitem>shutdown</listitem>
+              <listitem>version-get</listitem>
+          </itemizedlist>
+        </para>
+      </section> <!-- "d2-ctrl-channel" -->
+
       <section xml:id="d2-tsig-key-list-config">
         <title>TSIG Key List</title>
         <para>