From fe841603f57c47aa69bc337ab1bbc9051c804927 Mon Sep 17 00:00:00 2001 From: Francis Dupont Date: Fri, 28 Dec 2018 00:09:53 +0100 Subject: [PATCH] [30-implement-control-socket-for-ddns-2] Reported doc updates --- doc/examples/agent/simple.json | 4 +-- doc/examples/ddns/comments.json | 7 +++++ doc/examples/ddns/sample1.json | 9 ++++++ doc/examples/ddns/template.json | 10 ++++++ doc/guide/agent.xml | 13 +++++--- doc/guide/ctrl-channel.xml | 34 ++++++++++++++++++-- doc/guide/ddns.xml | 56 +++++++++++++++++++++++++++++++++ 7 files changed, 124 insertions(+), 9 deletions(-) diff --git a/doc/examples/agent/simple.json b/doc/examples/agent/simple.json index 15be619f69..b64a647a62 100644 --- a/doc/examples/agent/simple.json +++ b/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 - // command channel yet, but we hope this will change in the - // future. + // Location of the D2 command channel socket. "d2": { "socket-type": "unix", diff --git a/doc/examples/ddns/comments.json b/doc/examples/ddns/comments.json index 44a28b8364..f97005b098 100644 --- a/doc/examples/ddns/comments.json +++ b/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": diff --git a/doc/examples/ddns/sample1.json b/doc/examples/ddns/sample1.json index a413dc6e1b..890fc08adf 100644 --- a/doc/examples/ddns/sample1.json +++ b/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 ------------------ diff --git a/doc/examples/ddns/template.json b/doc/examples/ddns/template.json index c11f5b38e4..a3024bf364 100644 --- a/doc/examples/ddns/template.json +++ b/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 ------------------ // diff --git a/doc/guide/agent.xml b/doc/guide/agent.xml index 6a45c84353..e11b8a42ec 100644 --- a/doc/guide/agent.xml +++ b/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 and the - to learn how the socket - configuration is specified for the DHCPv4 and DHCPv6 services. + must match. Consult the , the + and + to learn how the socket + configuration is specified for the DHCPv4, DHCPv6 and D2 services. diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index 0fdf8e8340..213d80db97 100644 --- a/doc/guide/ctrl-channel.xml +++ b/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. - To avoid such problems, both the DHCPv4 and DHCPv6 servers + 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. - The DHCPv4 and DHCPv6 servers receive commands over the + The DHCPv4, DHCPv6 and D2 servers receive commands over the unix domain sockets. The details how to configure these sockets, see and . 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" +
+ Commands Supported by D2 Server + The D2 server supports only a subset of DHCPv4 / DHCPv6 server + commands: + + + build-report + + + config-get + + + config-test + + + config-write + + + list-commands + + + shutdown + + + version-get + + + +
+
Commands Supported by Control Agent The following commands listed in diff --git a/doc/guide/ddns.xml b/doc/guide/ddns.xml index 2bde0a43b5..fd2e5bc721 100644 --- a/doc/guide/ddns.xml +++ b/doc/guide/ddns.xml @@ -238,6 +238,11 @@ strings path/kea-dhcp-ddns | sed -n 's/;;;; //p' Global Server Parameters - values which control connectivity and global server behavior + + + Control Socket - defines the Control Socket type and name. + + TSIG Key Info - 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.
+
+ Management API for the D2 Server + + The management API allows the issuing of specific management + commands, such as configuration retrieval or shutdown. + For more details, see . + 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: + +"DhcpDdns": { + "control-socket": { + "socket-type": "unix", + "socket-name": "/path/to/the/unix/socket" + }, + ... +} + + + + + The length of the path specified by + the socket-name parameter is restricted by + the maximum length for the unix socket name on your operating + system, i.e. the size of the sun_path field + in the sockaddr_un 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. + + + + Communication over control channel is conducted using JSON + structures. See the Control Channel section in the Kea + Developer's Guide for more details. + + + The D2 server supports the following operational commands: + + build-report + config-get + config-test + config-write + list-commands + shutdown + version-get + + +
+
TSIG Key List -- 2.18.1