Commit fe841603 authored by Francis Dupont's avatar Francis Dupont

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

parent cc1b1168
...@@ -42,9 +42,7 @@ ...@@ -42,9 +42,7 @@
"socket-name": "/path/to/the/unix/socket-v6" "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": "d2":
{ {
"socket-type": "unix", "socket-type": "unix",
......
...@@ -12,6 +12,13 @@ ...@@ -12,6 +12,13 @@
"port": 53001, "port": 53001,
"dns-server-timeout" : 1000, "dns-server-timeout" : 1000,
"control-socket":
{
"comment": "Control channel",
"socket-type": "unix",
"socket-name": "/tmp/d2-ctrl-socket"
},
"forward-ddns": "forward-ddns":
{ {
"ddns-domains": "ddns-domains":
......
...@@ -29,6 +29,15 @@ ...@@ -29,6 +29,15 @@
"user-context": { "version": 1 }, "user-context": { "version": 1 },
//
// ----------------- Control Socket -----------------
//
"control-socket":
{
"socket-type": "unix",
"socket-name": "/tmp/d2-ctrl-socket"
},
// //
// ----------------- Forward DDNS ------------------ // ----------------- Forward DDNS ------------------
......
...@@ -20,6 +20,16 @@ ...@@ -20,6 +20,16 @@
// "ncr-protocol" : "UDP" // "ncr-protocol" : "UDP"
// "ncr-format" : "JSON" // "ncr-format" : "JSON"
//
// ----------------- Control Socket -----------------
//
// "control-socket":
// {
// "socket-type": "unix",
// "socket-name": "/tmp/d2-ctrl-socket"
// },
// //
// ----------------- Forward DDNS ------------------ // ----------------- Forward DDNS ------------------
// //
......
...@@ -77,7 +77,11 @@ ...@@ -77,7 +77,11 @@
"socket-type": "unix", "socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-v6", "socket-name": "/path/to/the/unix/socket-v6",
"user-context": { "version": 3 } "user-context": { "version": 3 }
} },
"d2": {
"socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-d2"
},
}, },
"hooks-libraries": [ "hooks-libraries": [
...@@ -130,9 +134,10 @@ ...@@ -130,9 +134,10 @@
commands to it. Obviously, the DHCPv4 server must be configured to commands to it. Obviously, the DHCPv4 server must be configured to
listen to connections via this same socket. In other words, the command listen to connections via this same socket. In other words, the command
socket configuration for the DHCPv4 server and CA (for this server) 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> </para>
<warning> <warning>
......
...@@ -19,14 +19,14 @@ ...@@ -19,14 +19,14 @@
the server may refuse to start, which will further extend the the server may refuse to start, which will further extend the
downtime period until the issue is resolved.</para> 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 include support for a mechanism that allows
on-line reconfiguration without requiring server shutdown. on-line reconfiguration without requiring server shutdown.
Both servers can be instructed to open control sockets, which Both servers can be instructed to open control sockets, which
is a communication channel. The server is able to receive is a communication channel. The server is able to receive
commands on that channel, act on them and report back status.</para> 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, 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 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 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" ...@@ -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> <!-- 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"> <section xml:id="agent-commands">
<title>Commands Supported by Control Agent</title> <title>Commands Supported by Control Agent</title>
<para>The following commands listed in <xref linkend="commands-common"/> <para>The following commands listed in <xref linkend="commands-common"/>
......
...@@ -238,6 +238,11 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p' ...@@ -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 <emphasis>Global Server Parameters</emphasis> - values which control connectivity and global server behavior
</simpara> </simpara>
</listitem> </listitem>
<listitem>
<simpara>
<emphasis>Control Socket</emphasis> - defines the Control Socket type and name.
</simpara>
</listitem>
<listitem> <listitem>
<simpara> <simpara>
<emphasis>TSIG Key Info</emphasis> - defines the TSIG keys used for secure traffic with DNS servers <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. ...@@ -320,6 +325,57 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
</note> </note>
</section> <!-- "d2-server-parameter-config" --> </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"> <section xml:id="d2-tsig-key-list-config">
<title>TSIG Key List</title> <title>TSIG Key List</title>
<para> <para>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment