[5008] Editing changes to chapters 9 through 18 of the Kea guide

doc/guide/classify.xml

@@ -58,7 +58,7 @@
       When determining which options to include in the response the server will examine
       the union of options from all of the assigned classes. In the case two or more
       classes include the same option, the value from the first class examined will
-      be used.  When choosing a subnet the server will iterate over all of the
+      be used.  When choosing a subnet, the server will iterate over all of the
       subnets that are feasible given the information found in the packet (client address,
       relay address etc). It will use the first subnet it finds that either doesn't
       have a class associated with it or that has a class which matches one of
@@ -68,7 +68,8 @@
       </para>
 
       <para>
-      As an example, imagine two classes.  Class "foo" defines values for an NTP server
+      As an example, imagine that an incoming packet matches two classes.
+      Class "foo" defines values for an NTP server
       (option 42 in DHCPv4) and an SMTP server (option 69 in DHCPv4) while class
       "bar" defines values for an NTP server and a POP3 server (option 70 in DHCPv4).
       The server will examine the three options NTP, SMTP and POP3 and return any
@@ -131,9 +132,9 @@
       Expressions are pre-processed during the parsing of the configuration file
       and converted to an internal representation. This allows certain types of
       errors to be caught and logged during parsing.  Examples of these errors
-      include incorrect number or types of arguments to an operator.  The
+      include an incorrect number or types of arguments to an operator.  The
       evaluation code will also check for this class of error and generally
-      throw an exception, though they should not occur in a normally functioning
+      throw an exception, though this should not occur in a normally functioning
       system.
       </para>
 
@@ -146,7 +147,7 @@
       <para>
       Expressions are a work in progress and the supported operators and
       values are limited. The expectation is that additional operators and values
-      will be added over time, however it is expected the basic mechanisms will
+      will be added over time, however the basic mechanisms will
       remain the same.
       </para>
 
@@ -360,7 +361,7 @@
               <entry>4491</entry>
               <entry>If the vendor option is present, it returns the
               value of the enterprise-id field padded to 4
-              bytes. Returns '' otherwise.</entry>
+              bytes. Returns "" otherwise.</entry>
             </row>
             <row>
               <entry>Vendor sub-option existence</entry>
@@ -401,7 +402,7 @@
               <entry>4491</entry>
               <entry>If the vendor option is present, it returns the
               value of the enterprise-id field padded to 4
-              bytes. Returns '' otherwise.</entry>
+              bytes. Returns "" otherwise.</entry>
             </row>
             <row>
               <entry>First data chunk from vendor class option</entry>
@@ -409,7 +410,7 @@
               <entry>docsis3.0</entry>
               <entry>Returns content of the first data chunk from
               the vendor class option with specified enterprise-id.
-              Returns '' if missing.</entry>
+              Returns "" if missing.</entry>
             </row>
             <row>
               <entry>Specific data chunk from vendor class option</entry>
@@ -423,20 +424,26 @@
           </tbody>
           </tgroup>
         </table>
-      Hex Strings are converted into a string as expected.  The starting &quot;0X&quot; or
+        Notes:
+      </para>
+
+      <itemizedlist>
+
+      <listitem><para>
+      Hexadecimal strings are converted into a string as expected.  The starting &quot;0X&quot; or
       &quot;0x&quot; is removed and if the string is an odd number of characters a
       &quot;0&quot; is prepended to it.
-      </para>
+      </para></listitem>
 
-      <para>
+      <listitem><para>
       IP addresses are converted into strings of length 4 or 16. IPv4, IPv6,
       and IPv4 embedded IPv6 (e.g., IPv4 mapped IPv6) addresses are supported.
-      </para>
+      </para></listitem>
 
-      <para>
+      <listitem><para>
       Integers in an expression are converted to 32 bit unsigned integers and
-      are represented as four byte strings. For example 123 is represented as
-      0x0000007b. All expressions that return numeric values use 32 bit
+      are represented as four-byte strings. For example 123 is represented as
+      0x0000007b. All expressions that return numeric values use 32-bit
       unsigned integers, even if the field in the packet is smaller.  In general
       it is easier to use decimal notation to represent integers, but it is also
       possible to use hex notation. When using hex notation to represent an
@@ -444,88 +451,101 @@
       bits, e.g. use 0x00000001 instead of 0x1 or 0x01. Also, make
       sure the value is specified in network order, e.g. 1 is
       represented as 0x00000001.
-      </para>
+      </para></listitem>
 
-      <para>
+      <listitem><para>
       "option[code].hex" extracts the value of the option with the code "code"
       from the incoming packet. If the packet doesn't contain the option, it
       returns the empty string. The string is presented as a byte string of
       the option payload without the type code or length fields.
-      </para>
+      </para></listitem>
 
-      <para>
+      <listitem><para>
       "option[code].exists" checks if an option with the code "code" is present
       in the incoming packet. It can be used with empty options.
-      </para>
+      </para></listitem>
 
-      <para>
-        "relay4[code].hex" attempts to extract the value of the sub-option
-        "code" from the option inserted as the DHCPv4 Relay Agent Information
-        (82) option. If the packet doesn't contain a RAI option, or the RAI
-        option doesn't contain the requested sub-option, the expression returns
-        an empty string. The string is presented as a byte string of the
-        option payload without the type code or length fields. This
-        expression is allowed in DHCPv4 only.
-      </para>
+      <listitem><para>
+      "relay4[code].hex" attempts to extract the value of the sub-option
+      "code" from the option inserted as the DHCPv4 Relay Agent Information
+      (82) option. If the packet doesn't contain a RAI option, or the RAI
+      option doesn't contain the requested sub-option, the expression returns
+      an empty string. The string is presented as a byte string of the
+      option payload without the type code or length fields. This
+      expression is allowed in DHCPv4 only.
+      </para></listitem>
 
-      <para>
-       "relay4" shares the same representation types as "option", for
-       instance "relay4[code].exists" is supported.
-      </para>
+      <listitem><para>
+      "relay4" shares the same representation types as "option", for
+      instance "relay4[code].exists" is supported.
+      </para></listitem>
 
-      <para>
-       "relay6[nest]" allows access to the encapsulations used by any DHCPv6
-       relays that forwarded the packet.  The "nest" level specifies the relay
-       from which to extract the information, with a value of 0 indicating
-       the relay closest to the DHCPv6 server.  If the requested encapsulation
-       doesn't exist an empty string "" is returned.  This expression is
-       allowed in DHCPv6 only.
-      </para>
+      <listitem><para>
+      "relay6[nest]" allows access to the encapsulations used by any DHCPv6
+      relays that forwarded the packet.  The "nest" level specifies the relay
+      from which to extract the information, with a value of 0 indicating
+      the relay closest to the DHCPv6 server.  If the requested encapsulation
+      doesn't exist an empty string "" is returned.  This expression is
+      allowed in DHCPv6 only.
+      </para></listitem>
 
-      <para>
-       "relay6[nest].option[code]" shares the same representation types as
-       "option", for instance "relay6[nest].option[code].exists" is supported.
-      </para>
+      <listitem><para>
+      "relay6[nest].option[code]" shares the same representation types as
+      "option", for instance "relay6[nest].option[code].exists" is supported.
+      </para></listitem>
 
-      <para>
-        Expressions starting with "pkt4" can be used only in DHCPv4.
-        They allows access to DHCPv4 message fields.
-      </para>
+      <listitem><para>
+       Expressions starting with "pkt4" can be used only in DHCPv4.
+       They allows access to DHCPv4 message fields.
+      </para></listitem>
 
-      <para>
-       "pkt6" refers to information from the client request.  To access any
-       information from an intermediate relay use "relay6".  "pkt6.msgtype"
-       and "pkt6.transid" output a 4 byte binary string for the message type
-       or transaction id.  For example the message type SOLICIT will be
-       "0x00000001" or simply 1 as in "pkt6.msgtype == 1".
-      </para>
+      <listitem><para>
+      "pkt6" refers to information from the client request.  To access any
+      information from an intermediate relay use "relay6".  "pkt6.msgtype"
+      and "pkt6.transid" output a 4 byte binary string for the message type
+      or transaction id.  For example the message type SOLICIT will be
+      "0x00000001" or simply 1 as in "pkt6.msgtype == 1".
+      </para></listitem>
 
-      <para>
-        Vendor option means Vendor-Identifying Vendor-specific Information
-        option (code 125, see Section 4 of RFC3925) in DHCPv4 and
-        Vendor-specific Information Option (code 17, defined in Section 22.17 of
-        RFC3315) in DHCPv6. Vendor class option means Vendor-Identifying Vendor
-        Class Option (code 124, see Section 3 of RFC3925) in DHCPv4 and Vendor
-        Class Option (code 16, see Section 22.16 of RFC3315). Vendor options may
-        have sub-options that are referenced by their codes. Vendor class
-        options do not have sub-options, but rather data chunks, which are
-        referenced by index value. Index 0 means the first data chunk, Index 1
-        is for the second data chunk (if present), etc.
-      </para>
+      <listitem><para>
+      Vendor option means Vendor-Identifying Vendor-specific Information
+      option (code 125, see
+      <ulink url="http://tools.ietf.org/html/rfc3925#section-4">Section 4 of RFC 3925</ulink>) in DHCPv4 and
+      Vendor-specific Information Option (code 17, defined in
+      <ulink url="https://tools.ietf.org/html/rfc3315#section-22.17">Section 22.17 of
+      RFC 3315</ulink>) in DHCPv6. Vendor class option means Vendor-Identifying Vendor
+      Class Option (code 124, see
+      <ulink url="http://tools.ietf.org/html/rfc3925#section-3">Section 3 of RFC 3925</ulink>) in DHCPv4 and
+      Class Option (code 16, see
+      <ulink url="https://tools.ietf.org/html/rfc3315#section-22.16">Section 22.16 of RFC 3315</ulink>).
+      Vendor options may
+      have sub-options that are referenced by their codes. Vendor class
+      options do not have sub-options, but rather data chunks, which are
+      referenced by index value. Index 0 means the first data chunk, Index 1
+      is for the second data chunk (if present), etc.
+      </para></listitem>
 
-      <para>In the vendor and vendor-class constructs Asterisk (*) or 0 can be
+      <listitem><para>
+      In the vendor and vendor-class constructs Asterisk (*) or 0 can be
       used to specify a wildcard enterprise-id value, i.e. it will match any
-      enterprise-id value.</para>
+      enterprise-id value.
+      </para></listitem>
 
-      <para>Vendor Class Identifier (option 60 in DHCPv4) can be
-      accessed using option[60] expression.</para>
+      <listitem><para>Vendor Class Identifier (option 60 in DHCPv4) can be
+      accessed using option[60] expression.</para></listitem>
 
-      <para>RFC3925 and RFC3315 allow for multiple instances of vendor options
+      <listitem><para>
+      <ulink url="http://tools.ietf.org/html/rfc3925">RFC3925</ulink> and
+      <ulink url="http://tools.ietf.org/html/rfc3315">RFC3315</ulink>
+      allow for multiple instances of vendor options
       to appear in a single message. The client classification code currently
       examines the first instance if more than one appear. For vendor.enterprise
       and vendor-class.enterprise expressions, the value from the first instance
       is returned. Please submit a feature request on Kea website if you need
-      support for multiple instances.</para>
+      support for multiple instances.
+      </para></listitem>
+
+      </itemizedlist>
 
       <para>
         <table frame="all" id="classification-expressions-list">
@@ -557,7 +577,7 @@ concatenation of the strings</entry></row>
       <section>
         <title>Logical operators</title>
         The Not, And and Or logical operators are the common operators. Not
-        has the highest precedence, Or the lowest. And and Or are (left)
+        has the highest precedence and Or the lowest. And and Or are (left)
         associative, parentheses around a logical expression can be used
         to enforce a specific grouping, for instance in "A and (B or C)"
         (without parentheses "A and B or C" means "(A and B) or C").
@@ -626,7 +646,7 @@ concatenation of the strings</entry></row>
 
       <para>
       In the following example the class named &quot;Client_foo&quot; is defined.
-      It is comprised of all clients who's client ids (option 61) start with the
+      It is comprised of all clients whose client ids (option 61) start with the
       string &quot;foo&quot;. Members of this class will be given 192.0.2.1 and
       192.0.2.2 as their domain name servers.
 
@@ -685,7 +705,7 @@ concatenation of the strings</entry></row>
     <title>Configuring Subnets With Class Information</title>
       <para>
         In certain cases it beneficial to restrict access to certain subnets
-        only to clients that belong to a given class using the "client-class"
+        only to clients that belong to a given class, using the "client-class"
         keyword when defining the subnet.
       </para>
 
@@ -784,9 +804,9 @@ concatenation of the strings</entry></row>
       expression would either be complex or time consuming and be easier or
       better to write as code.  Once the hook has added the proper class name
       to the packet the rest of the classification system will work as normal
-      in choosing a subnet and selecting options.  For a description of the
+      in choosing a subnet and selecting options.  For a description of
       hooks see <xref linkend="hooks-libraries"/>, for a description on
-      configuring he classes see <xref linkend="classification-configuring"/>
+      configuring classes see <xref linkend="classification-configuring"/>
       and <xref linkend="classification-subnets"/>.
       </para>
   </section>
@@ -817,7 +837,7 @@ concatenation of the strings</entry></row>
      <para>
      The list of tokens is created when the configuration file is processed with
      most expressions and values being converted to a token.  The list is organized
-     in reverse Polish notation.  During execution the list will be traversed
+     in reverse Polish notation.  During execution, the list will be traversed
      in order.  As each token is executed it will be able to pop values
      from the top of the stack and eventually push its result on the top of the
      stack.  Imagine the following expression:
@@ -836,17 +856,17 @@ concatenation of the strings</entry></row>
      </para>
 
      <para>
-     When debug logging is enabled each time a token is evaluated it will
-     emit a log line indicating the values of any objects that were popped
+     When debug logging is enabled, each time a token is evaluated it will
+     emit a log message indicating the values of any objects that were popped
      off of the value stack and any objects that were pushed onto the value
      stack.
      </para>
 
      <para>
      The values will be displayed as either text if the command is known
-     to use text values or hex if the command either uses binary values or
+     to use text values or hexadecimal if the command either uses binary values or
      can manipulate either text or binary values.  For expressions that
-     pop multiple values off the stack the values will be displayed in
+     pop multiple values off the stack, the values will be displayed in
      the order they were popped.  For most expressions this won't matter
      but for the concat expression the values are displayed in reverse
      order from how they are written in the expression.
@@ -863,8 +883,7 @@ concatenation of the strings</entry></row>
        2016-05-19 13:35:04.163 DEBUG [kea.eval/44478] EVAL_DEBUG_OPTION Pushing option 61 with value 0x666F6F626172
        2016-05-19 13:35:04.164 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '0'
        2016-05-19 13:35:04.165 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '3'
-       2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0,
-       string 0x666F6F626172 pushing result 0x666F6F
+       2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0, string 0x666F6F626172 pushing result 0x666F6F
        2016-05-19 13:35:04.167 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string 'foo'
        2016-05-19 13:35:04.168 DEBUG [kea.eval/44478] EVAL_DEBUG_EQUAL Popping 0x666F6F and 0x666F6F pushing result 'true'
        </screen>
@@ -872,7 +891,7 @@ concatenation of the strings</entry></row>
 
      <note><para>
      The debug logging may be quite verbose if you have a number of expressions
-     to evaluate.  It is intended as an aide in helping you create and debug
+     to evaluate.  It is intended as an aid in helping you create and debug
      your expressions.  You should plan to disable debug logging when you have your
      expressions working correctly.  You also may wish to include only one set of
      expressions at a time in the configuration file while debugging them in order

doc/guide/ctrl-channel.xml

@@ -10,21 +10,21 @@
     <title>Management API</title>
 
     <para>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.
+    the server's configuration is stored in configuration files
+    and, when the configuration is changed, the daemon is restarted.
     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.</para>
+    downtime period until the issue is resolved.</para>
 
-    <para>To avoid such problems, both DHCPv4 and DHCPv6 servers
-    introduced support for a mechanism that will allow
-    on-line reconfiguration, without requiring server shutdown.
+    <para>To avoid such problems, both the DHCPv4 and DHCPv6 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.
-    While the set of commands supported in Kea 0.9.2 is limited,
+    While the set of commands in Kea 1.1.0 is limited,
     the number is expected to grow over time.</para>
 
     <para>Currently the only supported type of control channel
@@ -35,10 +35,10 @@
     </para>
 
     <section id="ctrl-channel-syntax">
-    <title>Data syntax</title>
-    <para>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
+    <title>Data Syntax</title>
+    <para>Communication over the control channel is conducted using JSON
+    structures. If configured, Kea will open a socket and listen
+    for incoming connections. A process connecting to this socket
     is expected to send JSON commands structured as follows:
 
 <screen>
@@ -55,7 +55,7 @@
     <command>command</command> is the name of command to execute and
     is mandatory. <command>arguments</command> is a map of parameters
     required to carry out the given command.  The exact content and
-    format is command specific.</para>
+    format of the map is command specific.</para>
 
     <para>The server will process the incoming command and then send a
     response of the form:
@@ -73,23 +73,23 @@
     <command>result</command> indicates the outcome of the command. A value of 0
     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. <command>text</command> field typically appears when result is
+    future. The <command>text</command> field typically appears when result is
     non-zero and contains a description of the error encountered, but it may
-    also appear for successful results. That's command specific.
+    also appear for successful results (that is command specific).
     <command>arguments</command> is a map of additional data values returned by
-    the server, specific to the command issued. The map is always present, even
+    the server which is specific to the command issued. The map is always present, even
     if it contains no data values.</para>
     </section>
 
     <section id="ctrl-channel-client">
-    <title>Using control channel</title>
+    <title>Using the Control Channel</title>
 
-    <para>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
+    <para>Kea does not currently provide a client for using the control channel.  The primary
+    reason for this is the expectation is that the entity using the control channel
     is typically an IPAM or similar network management/monitoring software which
     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.</para>
+    be written in languages different than C or C++. Therefore only examples are provided to show
+    how one can take advantage of the API.</para>
 
     <para>The easiest way is to use a tool called <command>socat</command>,
     a tool available from <ulink url="http://www.dest-unreach.org/socat/">socat
@@ -101,7 +101,8 @@ $ socat UNIX:/path/to/the/kea/socket -
 </screen>
 where <command>/path/to/the/kea/socket</command> is the path specified in the
 <command>Dhcp4/control-socket/socket-name</command> parameter in the Kea
-configuration file.</para>
+configuration file. Text passed to <command>socat</command>
+will be sent to Kea and the responses received from Kea printed to standard output.</para>
 
     <para>It is also easy to open UNIX socket programmatically. An example of
     such a simplistic client written in C is available in the Kea Developer's
@@ -110,10 +111,10 @@ configuration file.</para>
     </section>
 
     <section id="commands-common">
-      <title>Commands supported by both DHCPv4 and DHCPv6 servers</title>
+      <title>Commands Supported by Both the DHCPv4 and DHCPv6 Servers</title>
 
       <section id="command-leases-reclaim">
-        <title>leases-reclaim command</title>
+        <title>leases-reclaim</title>
         <para>
           <emphasis>leases-reclaim</emphasis> command instructs the server to
           reclaim all expired leases immediately. The command has the following
@@ -140,10 +141,10 @@ configuration file.</para>
       </section>
 
       <section id="command-list-commands">
-      <title>list-commands command</title>
+      <title>list-commands</title>
 
       <para>
-	<emphasis>list-commands</emphasis> command retrieves a list of all
+	The <emphasis>list-commands</emphasis> command retrieves a list of all
 	commands supported by the server. It does not take any arguments.
 	An example command may look like this:
 <screen>
@@ -161,10 +162,10 @@ configuration file.</para>
     </section> <!-- end of command-list-commands -->
 
     <section id="command-shutdown">
-      <title>shutdown command</title>
+      <title>shutdown</title>
 
       <para>
-	<emphasis>shutdown</emphasis> command instructs the server to initiate
+	The <emphasis>shutdown</emphasis> command instructs the server to initiate
 	its shutdown procedure. It is the equivalent of sending a SIGTERM signal
 	to the process. This command does not take any arguments.  An example
 	command may look like this:

doc/guide/ddns.xml

@@ -8,7 +8,8 @@
     <title>The DHCP-DDNS Server</title>
     <para>
     The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts the client side of
-    the DDNS protocol (defined in RFC 2136) on behalf of the DHCPv4 and DHCPv6
+    the DDNS protocol (defined in <ulink url="http://tools.ietf.org/html/rfc2136">RFC 2136</ulink>)
+    on behalf of the DHCPv4 and DHCPv6
     servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP servers construct
     DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP
     lease change events and then post these to D2. D2 attempts to match
@@ -87,8 +88,11 @@
           </listitem>
           <listitem>
             <simpara>
-              <command>-V</command> - prints out Kea extended version with
-              additional parameters and exits.
+              <command>-W</command> - prints out the Kea configuration report
+              and exits. The report is a copy of the
+              <filename>config.report</filename> file produced by
+              <userinput>./configure</userinput>: it is embedded in the
+              executable binary.
             </simpara>
           </listitem>
           <listitem>
@@ -100,19 +104,6 @@
       </itemizedlist>
 
       <para>
-            The <command>-V</command> command returns the versions of the
-            external libraries dynamically linked.
-      </para>
-
-      <para>
-            The <command>-W</command> command describes the environment used
-            to build Kea.  This command displays a copy of the
-            <filename>config.report</filename> file produced by
-            <userinput>./configure</userinput> that is embedded in the
-            executable binary.
-      </para>
-
-      <para>
             The <filename>config.report</filename> may also be accessed more
             directly.  The following command may be used to extract this
             information.  The binary <userinput>path</userinput> may be found
@@ -188,26 +179,22 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
 	<itemizedlist>
 	  <listitem>
 	    <simpara>
-	      <command>Global Server Parameters</command> -
-	      values which control connectivity and global server behavior
+        <emphasis>Global Server Parameters</emphasis> - values which control connectivity and global server behavior
 	    </simpara>
 	  </listitem>
 	  <listitem>
 	    <simpara>
-	      <command>TSIG Key Info</command> -
-	      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
 	    </simpara>
 	  </listitem>
 	  <listitem>
 	    <simpara>
-	      <command>Forward DDNS</command> -
-	      defines the catalog of Forward DDNS Domains
+	      <emphasis>Forward DDNS</emphasis> - defines the catalog of Forward DDNS Domains
 	    </simpara>
 	  </listitem>
 	  <listitem>
 	    <simpara>
-	      <command>Reverse DDNS</command> -
-	      defines the catalog of Forward DDNS Domains
+	      <emphasis>Reverse DDNS</emphasis> - defines the catalog of Forward DDNS Domains
 	    </simpara>
 	  </listitem>
 	</itemizedlist>
@@ -234,8 +221,7 @@ strings <userinput>path</userinput>/kea-dhcp-ddns | sed -n 's/;;;; //p'
 
       <listitem><simpara>
       <command>ncr-protocol</command> - Socket protocol to use when sending requests to D2.
-      Currently only UDP is supported.  TCP may be available in an upcoming
-      release.
+      Currently only UDP is supported.  TCP may be available in a future release.
       </simpara></listitem>
 
       <listitem><simpara>
@@ -347,7 +333,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
 	    <simpara>
 	      <command>digest-bits</command> -
 	      is used to specify the minimum truncated length in bits.
-	      The default value 0 means truncation is forbidden, not 0
+	      The default value 0 means truncation is forbidden, non-zero
 	      values must be an integral number of octets, be greater
 	      than 80 and the half of the full length. Note in BIND9
 	      this parameter is appended after a dash to the algorithm

doc/guide/faq.xml

@@ -18,7 +18,7 @@
     it in the known issues list. -->
 
   <section id="faq-generic">
-    <title>Generic Frequently Asked Questions</title>
+    <title>General Frequently Asked Questions</title>
 
     <section id="q1-generic">
       <title>Where did the Kea name came from?</title>
@@ -61,7 +61,8 @@
       Accepted contributions range from minor documentation corrections to
       significant new features, like support for a new database type. Before
       considering writing and submitting a patch, make sure you read
-      the Contributor's Guide in <ulink url="http://git.kea.isc.org/~tester/kea/doxygen/">Kea Developer's Guide</ulink>.
+      the Contributor's Guide in the
+      <ulink url="http://git.kea.isc.org/~tester/kea/doxygen/">Kea Developer's Guide</ulink>.
       </para>
 
       <para>Kea is developed by ISC, which is a non-profit organization.

doc/guide/hooks.xml

@@ -75,14 +75,6 @@
 </screen>
       </para>
 
-      <note><para>
-        This is a change to the syntax used in Kea 0.9.2 and earlier, where
-        hooks-libraries was a list of strings, each string being the name of
-        a library.  The change has been made in Kea 1.0 to facilitate the
-        specification of library-specific parameters, a feature that will be
-        added to a future version of Kea.
-      </para></note>
-
         <note>
           <para>
           The library reloading behavior has changed in Kea 1.1. Libraries are
@@ -102,8 +94,8 @@
         parameter), floor (integer parameter), debug (boolean parameter) and
         even lists (list of strings) and maps (containing strings). Nested
         parameters could be used if the library supports it. This topic is
-        explained in detail in the Hooks Developer's Guide in Configuring Hooks
-        Libraries section.
+        explained in detail in the Hooks Developer's Guide in the "Configuring
+        Hooks Libraries" section.
       </para>
 
       <para>

doc/guide/lease-expiration.xml

@@ -8,8 +8,8 @@
 
   <para>The primary role of the DHCP server is to assign addresses and/or
   delegate prefixes to DHCP clients. These addresses and prefixes are
-  often referred to as 'leases'. Leases are typically assigned to clients
-  for a finite amount of time, known as 'valid lifetime'. DHCP clients who
+  often referred to as "leases". Leases are typically assigned to clients
+  for a finite amount of time, known as the "valid lifetime". DHCP clients who
   wish to continue using their assigned leases, will periodically renew them
   by sending the appropriate message to the DHCP server. The DHCP server records
   the time when these leases are renewed and calculates new expiration times
@@ -26,20 +26,20 @@
   available for reassignment is referred to as "lease reclamation" and expired
   leases returned to availability through this process are referred to as
   "reclaimed".
-
-  The DHCP server should reclaim an expired lease as soon as it detects
-  that it has expired. One way in which the server may detect expiration
-  is when it is trying to allocate a lease to a client and finds this
-  lease already present in the database but expired.  Another way the
-  server detects expired leases is by periodically querying the lease
+  The DHCP server attempts to reclaim an expired lease as soon as it detects
+  that it has expired. One way in which the server detects expiration occurs
+  when it is trying to allocate a lease to a client and finds this
+  lease already present in the database but expired.  Another way
+  is by periodically querying the lease
   database for them.  Regardless of how an expired lease is detected, before
-  it my assigned to a client, it must be reclaimed.
-
+  it may assigned to a client, it must be reclaimed.
+  </para>
+  <para>
   This chapter explains how to configure the server to periodically query
-  for the expired leases and how to minimize the impact of the periodic leases
-  reclamation process on the server's responsiveness. Finally, 'lease affinity',
-  which provides the means to assign the same lease to the returning client
-  after its lease has expired, is explained.
+  for the expired leases and how to minimize the impact of the periodic lease
+  reclamation process on the server's responsiveness. Finally, it explains
+  "lease affinity", which provides the means to assign the same lease to a
+  returning client after its lease has expired.
   </para>
 
   <para>Although, all configuration examples in this section are provided
@@ -50,14 +50,14 @@
   <section id="lease-reclamation">
     <title>Lease Reclamation</title>
     <para>Lease reclamation is the process through which an expired lease
-    becomes available for assignment to the same or a different client.
+    becomes available for assignment to the same or different client.
     This process involves the following steps for each reclaimed lease:
     </para>
 
     <itemizedlist>
       <listitem>
         <simpara>Invoke callouts for the <command>lease4_expire</command> or
-        <command>lease6_expire</command> hook points, if hook libraries
+        <command>lease6_expire</command> hook points if hook libraries
         supporting those callouts are currently loaded.</simpara>
       </listitem>
       <listitem>
@@ -69,9 +69,9 @@
         indicate that the lease is now available for re-assignment.</simpara>
       </listitem>
       <listitem>
-        <simpara>Update statistics of the server, which includes
+        <simpara>Update counters on the server, which includes
         increasing the number of reclaimed leases and decreasing the
-        number of assigned addresses or delegated prefixes etc.</simpara>
+        number of assigned addresses or delegated prefixes.</simpara>
       </listitem>
     </itemizedlist>
 
@@ -82,13 +82,13 @@
   </section>
 
   <section id="lease-reclaim-config">
-    <title>Configuring Leases Reclamation</title>
+    <title>Configuring Lease Reclamation</title>
     <para>Kea can be configured to periodically detect and reclaim expired
     leases. During this process the lease entries in the database are
-    modified or removed. Therefore the server will not process incoming DHCP
+    modified or removed. While this is happening the server will not process incoming DHCP
     messages to avoid issues with concurrent access to database information.
     As a result, the server will be unresponsive while lease reclamation
-    is performed. DHCP queries will accumulate and responses will be
+    is performed and DHCP queries will accumulate; responses will be
     sent once the leases reclamation cycle is complete.</para>
 
     <para>In deployments where response time is critical, administrators may
@@ -117,7 +117,7 @@
 
     <para>The first parameter is expressed in seconds and specifies an
     interval between the two consecutive lease reclamation cycles. This
-    is explained on the following diagram.
+    is explained by the following diagram.
 
 <screen>
 
@@ -129,7 +129,7 @@
 </screen>
 
     </para>
-    <para>This diagram shows 4 leases reclamation cycles of variable duration.
+    <para>This diagram shows four lease reclamation cycles (c1 through c4) of variable duration.
     Note that the duration of the reclamation cycle depends on the number
     of expired leases detected and processed in the particular cycle. This
     duration is also usually significantly shorter than the interval between
@@ -137,19 +137,19 @@
     </para>
 
     <para>According to the <command>reclaim-timer-wait-time</command> the
-    server keeps fixed intervals of 5 seconds between the end of one cycle
+    server keeps fixed intervals of five seconds between the end of one cycle
     and the start of the next cycle. This guarantees the presence of
     5s long periods during which the server remains responsive to DHCP
-    queries and does not perform leases reclamation. The
+    queries and does not perform lease reclamation. The
     <command>max-reclaim-leases</command> and
-    <command>max-reclaim-time</command> are set to 0, which implies that
-    there is no restriction on the maximum number of leases reclaimed
-    in the particular cycle, or the maximum duration of each cycle.
+    <command>max-reclaim-time</command> are set to 0, which sets
+    no restriction on the maximum number of leases reclaimed
+    in the particular cycle, or on the maximum duration of each cycle.
     </para>
 
     <para>In deployments with high lease pool utilization, relatively
     short valid lifetimes, and frequently disconnecting clients which
-    allow leases to expire; the number of expired leases requiring reclamation
+    allow leases to expire, the number of expired leases requiring reclamation
     at any given time may rise significantly. In this case it is often
     desirable to apply restrictions on the maximum duration of a reclamation
     cycle or the maximum number of leases reclaimed in a cycle. The following
@@ -164,7 +164,6 @@
         "max-reclaim-leases": 100,
         "max-reclaim-time": 50,
         "unwarned-reclaim-cycles": 10,
-        "flush-reclaimed-timer-wait-time": 0,
     },
 
     ...
@@ -212,11 +211,11 @@
     is a risk that expired leases will accumulate faster than the server can
     reclaim them.  This should not be the problem if the server is dealing
     with a temporary burst of expirations, because it should be able to
-    eventually deal with them over time. However, if leases expire at the high
+    eventually deal with them over time. However, if leases expire at a high
     rate for a longer period of time, the unreclaimed leases will pile up in
     the database. In order to notify the administrator that the current
     configuration does not satisfy the needs for reclamation of expired
-    leases, the server issues a warning message in the log, if it was unable
+    leases, the server issues a warning message in the log if it was unable
     to reclaim all leases within the last couple of reclamation cycles. The
     number of cycles after which such warning is issued is specified with the
     <command>unwarned-reclaim-cycles</command> configuration parameter.
@@ -231,13 +230,13 @@
     <para>Suppose that a laptop goes to a sleep mode after a period of user
     inactivity.  While the laptop is in sleep mode, its DHCP client will not
     renew leases obtained from the server and these leases will eventually
-    expire.  When the laptop wakes up, it is often desired that it continue
+    expire.  When the laptop wakes up, it is often desirable for it to continue
     using its previous assigned IP addresses. In order to facilitate this,
     the server needs to correlate returning clients with their expired leases
     When the client returns, the server will first check for those leases and
-    re-assign them if they have not assigned to another client.  The ability
+    re-assign them if they have not been assigned to another client.  The ability
     of the server to re-assign the same lease to a returning client is
-    referred to as 'lease affinity'.
+    referred to as "lease affinity".
     </para>
 
     <para>When lease affinity is enabled, the server will still
@@ -250,10 +249,10 @@
     any reclaimed lease may be assigned to another client if that client
     specifically asks for it. Therefore, the lease affinity does not
     guarantee that the reclaimed lease will be available for the client
-    who used it before. It merely increases the chances for the client to
-    be assigned the same lease. If the lease pool is small (mostly applies
+    who used it before; it merely increases the chances for the client to
+    be assigned the same lease. If the lease pool is small (this mostly applies
     to DHCPv4 for which address space is small), there is an increased
-    likelihood that the expired lease will be hijacked by another client.
+    likelihood that the expired lease will be assigned to another client.
     </para>
 
     <para>Consider the following configuration:
@@ -290,7 +289,7 @@
     the previous removal attempt was completed. Setting this value to 0
     disables lease affinity, in which case leases will be removed from the
     lease database when they are reclaimed.  If lease affinity is enabled, it
-    is recommended that hold-reclaim-time be set to a value significantly
+    is recommended that <command>hold-reclaim-time</command> be set to a value significantly
     higher than the <command>reclaim-timer-wait-time</command>, as timely
     removal of expired-reclaimed leases is less critical while the removal
     process may impact server responsiveness.</para>

doc/guide/lfc.xml

@@ -22,7 +22,7 @@
       of the lease entries and to indicate where it is in the process in case of an
       interruption.  Currently the caller must supply names for all of the files, in
       the future this requirement may be relaxed with the process getting the names
-      from either the config file or from defaults.
+      from either the configuration file or from defaults.
       </para>
     </section>
 

doc/guide/libdhcp.xml

@@ -5,9 +5,9 @@
 ]>
 
   <chapter id="libdhcp">
-    <title>libdhcp++ library</title>
+    <title>The libdhcp++ Library</title>
     <para>
-      libdhcp++ is a common library written in C++ that handles
+      libdhcp++ is a library written in C++ that handles
       many DHCP-related tasks, including:
       <itemizedlist>
         <listitem>
@@ -40,7 +40,7 @@
       OpenBSD), Mac OS X and Solaris 11 systems.</para>
 
       <para>DHCPv4 requires special raw socket processing to send and receive
-      packets from hosts that do not have IPv4 address assigned yet. Support
+      packets from hosts that do not have IPv4 address assigned. Support
       for this operation is implemented on Linux, FreeBSD, NetBSD and OpenBSD.
       It is likely that DHCPv4 component will not work in certain cases on
       other systems.</para>

doc/guide/stats.xml

@@ -10,13 +10,13 @@
   <section>
     <title>Statistics Overview</title>
 
-    <para>Both Kea DHCP servers support statistics gathering since
-    0.9.2-beta version. A working DHCP server encounters various events
+    <para>Both Kea DHCP servers support statistics gathering.
+    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 increases by one) that after parsing was identifier as
+    statistic increases by one) that after parsing was identified as a
     DHCPDISCOVER (pkt4-discover-received). The Server processed it and
-    decided to send DHCPOFFER representing its answer (pkt4-offer-sent
+    decided to send a DHCPOFFER representing its answer (pkt4-offer-sent
     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
@@ -73,7 +73,7 @@
       statistics. When <command>statistic-get-all</command> is executed, an
       empty list is returned. Once the server performs an operation that causes
       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
+      case, once a statistic is recorded even once, it is kept in the manager, until
       explicitly removed, by <command>statistic-remove</command> or
        <command>statistic-remove-all</command> being called or the server is shut
       down. Per subnet statistics are explicitly removed when reconfiguration
@@ -114,6 +114,12 @@
       it.
     </para>
 
+    <note><para>
+    The following sections describe commands that can be sent to the server: the
+    examples are not fragments of a configuration file.  For more information on
+    sending commands to Kea, see <xref linkend="ctrl-channel"/>.
+    </para></note>
+
     <section id="command-statistic-get">
       <title>statistic-get command</title>