From a080ae22d6f9c8f5879c866d7f85269fc0ebeb3c Mon Sep 17 00:00:00 2001 From: Shawn Routhier Date: Thu, 18 Jun 2015 23:36:13 -0700 Subject: [PATCH] [3800] Fix some typo level items in the documentation. --- doc/guide/ctrl-channel.xml | 34 +++++------ doc/guide/stats.xml | 97 ++++++++++++++++--------------- src/lib/config/command-socket.dox | 4 +- 3 files changed, 68 insertions(+), 67 deletions(-) diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index 638a55643d..eaba538005 100644 --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@ -9,17 +9,17 @@ Management API - A classic approach to the daemon configuration assumes that + A classic approach to 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 + This approach has the significant disadvantage of introducing periods + of downtime, when 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 + 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 @@ -36,7 +36,7 @@
Data syntax - Communication over Control Channel is conducted using JSON + 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: @@ -71,13 +71,13 @@ } 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 + means 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. + non-zero and contains a description of the error encountered, but it may + also appear for successful 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 + the server, specific to the command issued. The map is always present, even if it contains no data values.
@@ -87,24 +87,24 @@ 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 + may have quite varied expectations regarding the client and is 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 + homepage, but it 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 +where /path/to/the/kea/socket is the path specified in the +Dhcp4/control-socket/socket-name parameter in the 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 + such a simplistic client written in C is available in the Kea Developer's Guide, chapter Control Channel Overview, section Using Control Channel. @@ -117,7 +117,7 @@ configuration file. list-commands command retrieves a list of all - supported commands by the server. It does not take any arguments. + commands supported by the server. It does not take any arguments. An example command may look like this: { @@ -128,7 +128,7 @@ configuration file. The server will respond with a list of all supported commands. The - arguments element will be a list strings. Each string will convey + arguments element will be a list of strings. Each string will convey one supported command. @@ -138,7 +138,7 @@ configuration file. shutdown command instructs the server to initiate - its shutdown procedure. It is an equivalent of sending SIGTERM singal + its shutdown procedure. It is the equivalent of sending a SIGTERM singal to the process. This command does not take any arguments. An example command may look like this: diff --git a/doc/guide/stats.xml b/doc/guide/stats.xml index 9d59f861e2..241466d8d5 100644 --- a/doc/guide/stats.xml +++ b/doc/guide/stats.xml @@ -11,16 +11,16 @@ Statistics Overview Both Kea DHCP servers support statistics gathering since - 0.9.2-beta version. Working DHCP server encounters various events - that can influence certain statistics to be collected. For + 0.9.2-beta version. A working DHCP server encounters various events + that can cause certain statistics to be collected. For example, a DHCPv4 server may receive a packet (pkt4-received - statistic increased by one) that after parsing was identifier as - DHCPDISCOVER (pkt4-discover-received). Server processed it and + statistic increases by one) that after parsing was identifier as + DHCPDISCOVER (pkt4-discover-received). The Server processed it and decided to send DHCPOFFER representing its answer (pkt4-offer-sent - and pkt4-sent statistics increased by one). Such events happen + and pkt4-sent statistics increase by one). Such events happen frequently, so it is not uncommon for the statistics to have values in high thousands. They can serve as an easy and powerful - tool for observing server's and network's health. For example, + tool for observing a server's and network's health. For example, if pkt4-received statistic stops growing, it means that the clients' packets are not reaching the server. @@ -38,12 +38,12 @@ duration - this type is intended for - recoding time periods. It uses boost::posix_time::time_duration type, + recording time periods. It uses boost::posix_time::time_duration type, which stores hours, minutes, seconds and microseconds. string - this type is intended for - recoding statistics in textual forma. It uses std::string C++ type. + recording statistics in textual forma. It uses std::string C++ type. @@ -51,14 +51,14 @@ During normal operation, DHCPv4 and DHCPv6 servers gather statistics. - For a DHCPv4 and DHCPv6 list of statistics, see and , respectively. To extract data from the statistics module, the control channel can be used. See for details. It is possible to - retrieve a single statistic, all statistics, reset (i.e. set to neutral + retrieve a single or all statistics, reset statistics (i.e. set to neutral value, typically zero) or even remove completely a single or all statistics. See section for a list of statistic oriented commands. @@ -68,14 +68,14 @@
Statistics Lifecycle - It is useful to understand how Statistics Manager module is working. When + It is useful to understand how the Statistics Manager module works. When the server starts operation, the manager is empty and does not have any statistics. When statistic-get-all is executed, an empty list is returned. Once the server performs an operation that causes - statistic change, related statistic will be created. In a general case - once a statistic is recorded even once, it is kept in the manager, until + a statistic to change, the related statistic will be created. In the general + case once a statistic is recorded even once, it is kept in the manager, until explicitly removed, by statistic-remove or - statistic-remove-all is called or the server is shut + statistic-remove-all being called or the server is shut down. Per subnet statistics are explicitly removed when reconfiguration takes place. @@ -85,28 +85,29 @@ Removing a statistic that is updated frequently makes little sense as it - will be re-added when the server code records a given statistic the next - time. statistic-remove and + will be re-added when the server code next records that statistic. + The statistic-remove and statistic-remove-all commands are intended to remove - statistics that is not expected to be observed in the near future. For + statistics that are not expected to be observed in the near future. For example, a misconfigured device in a network may cause clients to report duplicate addresses, so the server will report increasing values of pkt4-decline-received. Once the problem is found and the device is - removed, system administrator may want to remove pkt4-decline-received - statistic, so it won't be reported anymore. If duplicate address is - detected ever again, the server will add this statistic back. + removed, the system administrator may want to remove the + pkt4-decline-received statistic, so it won't be reported anymore. If a + duplicate address is detected ever again, the server will add this + statistic back.
- Commands for manipulating statistics + Commands for Manipulating Statistics There are several commands defined that can be used for accessing (-get), resetting to zero or neutral value (-reset) or even removing a statistic completely (-remove). The difference between reset and remove is somewhat - subtle. Reset command sets value of the statistic to zero or neutral - value. After this operation, statistic will have value of 0 (integer), 0.0 - (float), 0h0m0s0us (duration) or "" (string). When asked for, statistic + subtle. The reset command sets the value of the statistic to zero or neutral + value. After this operation, the statistic will have a value of 0 (integer), + 0.0 (float), 0h0m0s0us (duration) or "" (string). When asked for, a statistic with the values metioned will be returned. Remove removes a statistic completely, so the statistic will not be reported anymore. Please note that @@ -130,9 +131,9 @@ - The server will respond with details of requested statistic, with result - set to 0 indicates success and specified statistic as the value of - "arguments" parameter. If requested statistic is not found, the response + The server will respond with details of the requested statistic, with result + set to 0 indicating success and the specified statistic as the value of + "arguments" parameter. If the requested statistic is not found, the response will contain an empty map, i.e. only { } as argument, but the status code will still be set to success (0). @@ -142,8 +143,8 @@ statistic-reset command - statistic-reset command sets specified statistic to - its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time + statistic-reset command sets the specified statistic + to its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time duration and "" for string type. It takes a single string parameter called name that specifies the statistic name. An example command may look like this: @@ -157,11 +158,11 @@ - If specific statistic is found and reset was successful, - the server will respond with status of 0, indicating success and empty - parameters field. If error is encountered (e.g. requested statistic - was not found), the server will return status code of 1 (error) - and text field will contain the error description. + If the specific statistic is found and reset was successful, the + server will respond with a status of 0, indicating success and an empty + parameters field. If an error is encountered (e.g. requested statistic + was not found), the server will return a status code of 1 (error) + and the text field will contain the error description.
@@ -169,7 +170,7 @@ statistic-remove command - statistic-remove command attempt to delete a single + statistic-remove command attempts to delete a single statistic. It takes a single string parameter called name that specifies the statistic name. An example command may look like this: @@ -183,11 +184,11 @@ - If specific statistic is found and its removal was successful, - the server will respond with status of 0, indicating success and empty - parameters field. If error is encountered (e.g. requested statistic - was not found), the server will return status code of 1 (error) - and text field will contain the error description. + If the specific statistic is found and its removal was successful, the + server will respond with a status of 0, indicating success and an empty + parameters field. If an error is encountered (e.g. requested statistic + was not found), the server will return a status code of 1 (error) + and the text field will contain the error description. @@ -227,9 +228,9 @@ - If the operation is successful, the server will respond with status of - 0, indicating success and empty parameters field. If error is - encountered, the server will return status code of 1 (error) and text + If the operation is successful, the server will respond with a status of + 0, indicating success and an empty parameters field. If an error is + encountered, the server will return a status code of 1 (error) and the text field will contain the error description. @@ -238,7 +239,7 @@ statistic-remove-all command - statistic-remove-all command attempt to delete all + statistic-remove-all command attempts to delete all statistics. An example command may look like this: { @@ -248,10 +249,10 @@ - If removal of all statistics was successful, the server will respond - with status of 0, indicating success and empty parameters field. If - error is encountered, the server will return status code of 1 (error) - and text field will contain the error description. + If the removal of all statistics was successful, the server will respond + with a status of 0, indicating success and an empty parameters field. If + an error is encountered, the server will return a status code of 1 (error) + and the text field will contain the error description. diff --git a/src/lib/config/command-socket.dox b/src/lib/config/command-socket.dox index 869c3de4c0..c7169b854d 100644 --- a/src/lib/config/command-socket.dox +++ b/src/lib/config/command-socket.dox @@ -20,9 +20,9 @@ In many cases it is useful to manage certain aspects of the DHCP servers while they are running. In Kea, this may be done via the Control Channel. Control Channel allows an external entity (e.g. a tool run by a sysadmin -or a script) to issue commands to the server which can influence the its +or a script) to issue commands to the server which can influence its behavior or retreive information from it. Several notable examples -envisioned are: reconfiguration, statistics retrival and manipulation, +envisioned are: reconfiguration, statistics retrieval and manipulation, and shutdown. Communication over Control Channel is conducted using JSON structures.