From: Tomek Mrugalski Date: Thu, 18 Jun 2015 17:00:09 +0000 (+0200) Subject: [3800] Remaing documentation written. X-Git-Tag: trac3910_base~6^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f603a0dbceb475c7478e35c9caf99b7ffab12268;p=thirdparty%2Fkea.git [3800] Remaing documentation written. --- diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index 92bb314422..638a55643d 100644 --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@ -8,8 +8,152 @@ Management API - - @todo: To be implemented in ticket 3880. + + A classic approach to the daemon configuration assumes that + the server's configuration is stored in the configuration files + and when the configuration is changed, the daemon is restarted. + This approach has significant disadvantage of introducing periods + of downtime, where client traffic is not handled. Another risk + is that if the new configuration is invalid for whatever reason, + the server may refuse to start, which will further extend the + downtime period, until the issue is resolved. + + To avoid such problems, both DHCPv4 and DHCPv6 servers + support introduced support for a mechanism that will allow + 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. + While the set of commands supported in Kea 0.9.2 is limited, + the number is expected to grow over time. + + Currently the only supported type of control channel + is UNIX stream socket. For details how to configure it, see + and . It is likely that support + for other control channel types will be added in the future. +
+ Data syntax + Communication over Control Channel is conducted using JSON + structures. If configured, Kea will open a socket and will listen + for any incoming connections. A process connecting to this socket + is expected to send JSON commands structured as follows: + + +{ + "command": "foo", + "arguments": { + "param1": "value1", + "param2": "value2", + ... + } +} + + + command is the name of command to execute and + is mandatory. arguments is a map of parameters + required to carry out the given command. The exact content and + format is command specific. + + The server will process the incoming command and then send a + response of the form: + +{ + "result": 0|1, + "text": "textual description", + "arguments": { + "argument1": "value1", + "argument2": "value2", + ... + } +} + + result indicates the outcome of the command. A value of 0 + means a success while any non-zero value designates an error. Currently 1 is + used as a generic error, but additional error codes may be added in the + future.text field typically appears when result is + non-zero and contains description of the error encountered, but it may also + appear for success results. That's command specific. + arguments is a map of additional data values returned by + the server, specific to the command issue. The map is always present, even + if it contains no data values. +
+ +
+ Using control channel + + ISC does not provide a client for using control channel. The primary + reason for that is the expectation is that the entity using control channel + is typically an IPAM or similar network management/monitoring software which + may have quite varied expectations regarding the client and even likely to + be written in languages different than C or C++. Therefore we only provide + examples how one can take advantage of the API. + + The easiest way is to use a tool called socat, + a tool available from socat + homepage, but is also widely available in Linux and BSD + distributions. Once Kea is started, one could connect to the control + interface using the following command: + +$ socat UNIX:/path/to/the/kea/socket - + +where /path/to/the/kea/socket is the path specified in +Dhcp4/control-socket/socket-name parameter in Kea +configuration file. + + It is also easy to open UNIX socket programmatically. An example of + such simplistic client written in C is available in the Kea Developer's + Guide, chapter Control Channel Overview, section Using Control Channel. + +
+ +
+ Commands supported by both DHCPv4 and DHCPv6 servers + +
+ list-commands command + + + list-commands command retrieves a list of all + supported commands by the server. It does not take any arguments. + An example command may look like this: + +{ + "command": "list-commands", + "arguments": { } +} + + + + The server will respond with a list of all supported commands. The + arguments element will be a list strings. Each string will convey + one supported command. + +
+ +
+ shutdown command + + + shutdown command instructs the server to initiate + its shutdown procedure. It is an equivalent of sending SIGTERM singal + to the process. This command does not take any arguments. An example + command may look like this: + +{ + "command": "shutdown", + "arguments": { } +} + + + + The server will respond with a confirmation that the shutdown procedure + has been initiated. + +
+ +
+ diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index faf5976f44..e410a2fbeb 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -2888,6 +2888,15 @@ appropiately --> Communication over control channel is conducted using JSON structures. See the Control Channel section in the Kea Developer's Guide for more details. + + DHCPv4 server supports statistic-get, + statistic-reset, statistic-remove, + statistic-get-all, statistic-reset-all + and statistic-remove-all, specified in + . It also supports + list-commands and shutdown, + specified in and + , respectively.
diff --git a/src/lib/config/command-socket.dox b/src/lib/config/command-socket.dox index 0474ace212..869c3de4c0 100644 --- a/src/lib/config/command-socket.dox +++ b/src/lib/config/command-socket.dox @@ -24,12 +24,10 @@ or a script) to issue commands to the server which can influence the its behavior or retreive information from it. Several notable examples envisioned are: reconfiguration, statistics retrival and manipulation, and shutdown. -@note Currently, only the DHCPv4 component supports Control Channel. -@todo: Update this text once Control Channel support in DHCPv6 is added. Communication over Control Channel is conducted using JSON structures. -Currently (Kea 0.9.2) the only supported communication channel is UNIX stream -sockets, but additional types may be added in the future. +As of Kea 0.9.2, the only supported communication channel is UNIX stream +socket, but additional types may be added in the future. If configured, Kea will open a socket and will listen for any incoming connections. A process connecting to this socket is expected to send JSON @@ -47,7 +45,7 @@ commands structured as follows: @endcode - command - is the name of command to execute and is mandatory. -- arguments - it may be absent, contain a single parameter or a map or parameters +- arguments - contain a single parameter or a map or parameters required to carry out the given command. The exact content and format is command specific. The server will process the incoming command and then send a response of the form: