Update admin.xml

doc/guide/admin.xml

@@ -3,7 +3,7 @@
  -
  - This Source Code Form is subject to the terms of the Mozilla Public
  - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ - file, you can obtain one at http://mozilla.org/MPL/2.0/.
 -->
 
 <!-- Converted by db4-upgrade version 1.1 -->
@@ -15,12 +15,12 @@
 
     <para>
       Kea supports storing leases and host reservations (i.e. static
-      assignments of addresses, prefixes and options) in one of
+      assignments of addresses, prefixes, and options) in one of
       the several supported databases. As future versions of Kea
       are released, the structure of those databases will change.
       For example, Kea currently only stores lease information
       and host reservations. Future versions of Kea will store
-      additional data such as subnet definitions: the database
+      additional data such as subnet definitions, so the database
       structure will need to be updated to accommodate the extra
       information.
     </para>
@@ -28,12 +28,12 @@
     <para>
       A given version of Kea expects a particular structure in
       the database and checks for this by examining the version of
-      database it is using.  Separate version numbers are maintained for
+      database it is using. Separate version numbers are maintained for
       backend databases, independent of the version of Kea itself. It
       is possible that the backend database version will stay the same
-      through several Kea revisions: similarly, it is possible that the
+      through several Kea revisions; similarly, it is possible that the
-      version of backend database may go up several revisions during a
+      version of the backend database may go up several revisions during a
-      Kea upgrade.  Versions for each database are independent, so an
+      Kea upgrade. Versions for each database are independent, so an
       increment in the MySQL database version does not imply an increment
       in that of PostgreSQL.
     </para>
@@ -41,16 +41,16 @@
     <para>
       Backend versions are specified in
       a <replaceable>major.minor</replaceable> format. The minor
-      number is increased when there are backward compatible changes
+      number is increased when there are backward-compatible changes
-      introduced.  For example, the addition of a new index. It is
+      introduced: for example, the addition of a new index. It is
-      desirable, but not mandatory to apply such a change; you
+      desirable but not mandatory to apply such a change; you
-      can run on older database version if you want to. (Although, in
+      can run an older database version if you want to. (Although, in
       the example given, running without the new index may be at the
       expense of a performance penalty.) On the other hand, the major
-      number is increased when an incompatible change is introduced,
+      number is increased when an incompatible change is introduced:
-      for example an extra column is added to a table. If you try to
+      for example, an extra column is added to a table. If you try to
       run Kea software on a database that is too old (as signified by
-      mismatched backend major version number), Kea will refuse to run:
+      a mismatched backend major version number), Kea will refuse to run;
       administrative action will be required to upgrade the database.
     </para>
   </section>
@@ -69,7 +69,7 @@
       <command>kea-admin</command> takes two mandatory
       parameters: <command>command</command> and
       <command>backend</command>. Additional, non-mandatory options
-      may be specified. Currently supported commands are:
+      may be specified. The currently supported commands are:
 
       <itemizedlist>
         <listitem>
@@ -102,16 +102,16 @@
         <listitem>
           <simpara>
             <command>lease-dump</command> —
-            Dumps the contents of the lease database (for MySQL, PostgreSQL or
+            Dumps the contents of the lease database (for MySQL, PostgreSQL, or
-            CQL backends) to a CSV (comma separated values) text file. The first
+            CQL backends) to a CSV (comma-separated values) text file. The first
-            line of the file contains the column names.  This is meant to be
+            line of the file contains the column names. This is meant to be
             used as a diagnostic tool, so it provides a portable, human-readable
             form of the lease data.
           </simpara>
         </listitem>
       </itemizedlist>
 
-      <command>backend</command> specifies the backend type. Currently
+      <command>backend</command> specifies the backend type. The currently
       supported types are:
 
       <itemizedlist>
@@ -146,7 +146,7 @@
       </itemizedlist>
 
       Additional parameters may be needed, depending on your setup
-      and specific operation: username, password and database name or
+      and specific operation: username, password, and database name or
       the directory where specific files are located. See the appropriate
       manual page for details (<command>man 8 kea-admin</command>).
     </para>
@@ -158,7 +158,7 @@
     <para>The following table presents the capabilities of available
     backends. Please refer to the specific sections dedicated to each backend to
     better understand their capabilities and limitations. Choosing the right
-    backend may be essential for success or failure of your deployment.</para>
+    backend may be essential for the success of your deployment.</para>
 
     <para>
       <table frame="all" xml:id="backends">
@@ -230,17 +230,17 @@
 
       <para>
         The memfile backend is able to store lease information, but is not able to
-        store host reservation details: these must be stored in the configuration
+        store host reservation details; these must be stored in the configuration
         file. (There are no plans to add a host reservations storage capability to
         this backend.)
       </para>
 
       <para>
         No special initialization steps are necessary
-        for the memfile backend.  During the first run, both
+        for the memfile backend. During the first run, both
         <command>kea-dhcp4</command> and <command>kea-dhcp6</command>
         will create an empty lease file if one is not
-        present. Necessary disk write permission is required.
+        present. Necessary disk-write permission is required.
       </para>
 
       <section xml:id="memfile-upgrade">
@@ -250,17 +250,17 @@
         from an earlier version of Kea to a new version of Kea.
 
         During startup the servers will check the schema version of the lease
-        files against their own.  If there is a mismatch, the servers will
+        files against their own. If there is a mismatch, the servers will
         automatically launch the LFC process to convert the files to the
-        server's schema version.  While this mechanism is primarily meant to
+        server's schema version. While this mechanism is primarily meant to
         ease the process of upgrading to newer versions of Kea, it can also
-        be used for downgrading should the need arise.  When upgrading, any
+        be used for downgrading should the need arise. When upgrading, any
         values not present in the original lease files will be assigned
-        appropriate default values.  When downgrading, any data present in
+        appropriate default values. When downgrading, any data present in
         the files but not in the server's schema will be dropped.
 
-        If you wish to convert the files manually, prior to starting the
+        If you wish to convert the files manually prior to starting the
-        servers you may do so by running the LFC process yourself.
+        servers, you may do so by running the LFC process yourself.
         See <xref linkend="kea-lfc"/> for more information.
         </para>
       </section>
@@ -271,19 +271,19 @@
       <title>MySQL</title>
 
       <para>
-        MySQL is able to store leases, host reservations and options defined on
+        MySQL is able to store leases, host reservations, and options defined on
-        a per host basis. This section can be safely ignored
+        a per-host basis. This section can be safely ignored
-        if you chose to store the data in other backends.
+        if you choose to store the data in other backends.
       </para>
 
       <section xml:id="mysql-database-create">
-        <title>First Time Creation of the MySQL Database</title>
+        <title>First-Time Creation of the MySQL Database</title>
 
         <para>
           If you are setting the MySQL database for the first time,
           you need to create the database area within MySQL and set up
           the MySQL user ID under which Kea will access the database.
-          This needs to be done manually: <command>kea-admin</command>
+          This needs to be done manually; <command>kea-admin</command>
           is not able to do this for you.
         </para>
 
@@ -324,7 +324,7 @@ mysql&gt; <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO
 </screen>
                 (<replaceable>user-name</replaceable> and
                 <replaceable>password</replaceable> are the user ID
-                and password you are using to allow Keas access to the
+                and password you are using to allow Kea's access to the
                 MySQL instance. All apostrophes in the command lines
                 above are required.)
               </para>
@@ -335,7 +335,7 @@ mysql&gt; <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO
                 At this point, you may elect to create the database
                 tables. (Alternatively, you can exit MySQL and create
                 the tables using the <command>kea-admin</command> tool,
-                as explained below.)  To do this:
+                as explained below.) To do this:
 <screen>
 mysql&gt; <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
 mysql&gt; <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/scripts/mysql/dhcpdb_create.mysql</userinput>
@@ -359,17 +359,17 @@ $
         </para>
 
         <para>
-          If you elected not to create the tables in step 4, you can do
+          If you elected not to create the tables in Step 4, you can do
           so now by running the <command>kea-admin</command> tool:
 <screen>
 $ <userinput>kea-admin lease-init mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
 </screen>
-          (Do not do this if you did create the tables in step 4.)
+          (Do not do this if you did create the tables in Step 4.)
-          <command>kea-admin</command> implements rudimentary checks:
+          <command>kea-admin</command> implements rudimentary checks;
           it will refuse to initialize a database that contains any
           existing tables. If you want to start from scratch, you
           must remove all data manually. (This process is a manual
-          operation on purpose to avoid possibly irretrievable mistakes
+          operation on purpose, to avoid possibly irretrievable mistakes
           by <command>kea-admin</command>.)
         </para>
       </section>
@@ -378,8 +378,8 @@ $ <userinput>kea-admin lease-init mysql -u <replaceable>database-user</replaceab
         <title>Upgrading a MySQL Database from an Earlier Version of Kea</title>
 
         <para>
-          Sometimes a new Kea version may use newer database schema, so
+          Sometimes a new Kea version may use a newer database schema, so
-          there will be a need to upgrade the existing database. This can
+          the existing database will need to be upgraded. This can
           be done using the <command>kea-admin lease-upgrade</command>
           command.
         </para>
@@ -390,16 +390,16 @@ $ <userinput>kea-admin lease-init mysql -u <replaceable>database-user</replaceab
 $ <userinput>kea-admin lease-version mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
 </screen>
           (See <xref linkend="kea-database-version"/> for a discussion
-          about versioning.)  If the version does not match the minimum
+          about versioning.) If the version does not match the minimum
           required for the new version of Kea (as described in the
           release notes), the database needs to be upgraded.
         </para>
 
         <para>
           Before upgrading, please make sure that the database is
-          backed up.  The upgrade process does not discard any data but,
+          backed up. The upgrade process does not discard any data, but
           depending on the nature of the changes, it may be impossible
-          to subsequently downgrade to an earlier version.  To perform
+          to subsequently downgrade to an earlier version. To perform
           an upgrade, issue the following command:
 <screen>
 $ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
@@ -412,15 +412,15 @@ $ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replac
       <title>PostgreSQL</title>
 
       <para>
-        PostgreSQL is able to store leases, host reservations and options
+        PostgreSQL is able to store leases, host reservations, and options
-        defined on a per host basis.
+        defined on a per-host basis.
         A PostgreSQL database must be set up if you want Kea to store
         lease and other information in PostgreSQL. This step can be
         safely ignored if you are using other database backends.
       </para>
 
       <section xml:id="pgsql-database-create">
-        <title>First Time Creation of the PostgreSQL Database</title>
+        <title>First-Time Creation of the PostgreSQL Database</title>
 
         <para>
           The first task is to create both the lease database and the
@@ -483,11 +483,11 @@ $
                 At this point you are ready to create the database tables.
                 This can be done using the <command>kea-admin</command> tool
                 as explained in the next section (recommended), or manually.
-                To create the tables manually enter the following command.
+                To create the tables manually, enter the following command.
                 Note that PostgreSQL will prompt you to enter the new user's
-                password you specified in Step 3. When the command completes
+                password you specified in Step 3. When the command completes,
                 you will be returned to the shell prompt. You should see output
-                similar to following:
+                similar to the following:
 <screen>
 $ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/scripts/pgsql/dhcpdb_create.pgsql</userinput>
 Password for user <replaceable>user-name</replaceable>:
@@ -520,16 +520,16 @@ psql: FATAL:  no pg_hba.conf entry for host "[local]", user "<replaceable>user-n
                 ... you will need to alter the PostgreSQL configuration.
                 Kea uses password authentication when connecting to
                 the database and must have the appropriate entries
-                added to PostgreSQL's pg_hba.conf file.  This file is
+                added to PostgreSQL's pg_hba.conf file. This file is
                 normally located in the primary data directory for your
-                PostgreSQL server. The precise path may vary but the
+                PostgreSQL server. The precise path may vary, but the
                 default location for PostgreSQL 9.3 on Centos 6.5 is:
                 <filename>/var/lib/pgsql/9.3/data/pg_hba.conf</filename>.
               </para>
 
               <para>
                 Assuming Kea is running on the same host as PostgreSQL,
-                adding lines similar to following should be sufficient to
+                adding lines similar to the following should be sufficient to
                 provide password-authenticated access to Kea's database:
 <screen>
 local   <replaceable>database-name</replaceable>    <replaceable>user-name</replaceable>                                 password
@@ -539,11 +539,11 @@ host    <replaceable>database-name</replaceable>    <replaceable>user-name</repl
               </para>
 
               <para>
-                These edits are primarily intended as a starting point
+                These edits are primarily intended as a starting point, and are
                 not a definitive reference on PostgreSQL administration or
-                database security.  Please consult your PostgreSQL user
+                database security. Please consult your PostgreSQL user
-                manual before making these changes as they may expose
+                manual before making these changes, as they may expose
-                other databases that you run.  It may be necessary to
+                other databases that you run. It may be necessary to
                 restart PostgreSQL in order for these changes to take effect.
               </para>
             </listitem>
@@ -559,12 +559,12 @@ host    <replaceable>database-name</replaceable>    <replaceable>user-name</repl
 <screen>
 $ <userinput>kea-admin lease-init pgsql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
 </screen>
-          Do not do this if you already created the tables in manually.
+          Do not do this if you already created the tables manually.
-          <command>kea-admin</command> implements rudimentary checks:
+          <command>kea-admin</command> implements rudimentary checks;
           it will refuse to initialize a database that contains any
           existing tables. If you want to start from scratch, you
           must remove all data manually. (This process is a manual
-          operation on purpose to avoid possibly irretrievable mistakes
+          operation on purpose, to avoid possibly irretrievable mistakes
           by <command>kea-admin</command>.)
         </para>
       </section>
@@ -594,25 +594,24 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
 
       <para>
         Cassandra, or Cassandra Query Language (CQL), is the newest backend
-        added to Kea. Since it was added recently and has not undergone as much
+        added to Kea; initial development was contributed by Deutsche Telekom. 
-        testing as other backends, it is considered experimental. Please use
+        The Cassandra backend is able to store leases,
-        with caution. The Cassandra backend is able to store leases,
+        host reservations, and options defined on a per-host basis.
-        host reservations and options defined on a per host basis.
       </para>
 
       <para>
         The CQL database must be properly set up if you want Kea to store
-        information in CQL. This section can be safely ignored if you chose to
+        information in CQL. This section can be safely ignored if you choose to
         store the data in other backends.
       </para>
 
     <section xml:id="cql-database-create">
-      <title>First Time Creation of the Cassandra Database</title>
+      <title>First-Time Creation of the Cassandra Database</title>
 
       <para>
         If you are setting up the CQL database for the first time, you need to
-        create the keyspace area within CQL. This needs to be done manually:
+        create the keyspace area within CQL. This needs to be done manually;
-        <command>kea-admin</command> is not able to do this for you.
+        <command>kea-admin</command> cannot do this for you.
       </para>
 
       <para>
@@ -651,7 +650,7 @@ cql&gt; <userinput>CREATE KEYSPACE keyspace-name WITH replication = {'class' : '
             <para>
               At this point, you may elect to create the database tables.
               (Alternatively, you can exit CQL and create the tables using the
-              <command>kea-admin</command> tool, as explained below)  To do this:
+              <command>kea-admin</command> tool, as explained below.) To do this:
 <screen>
 <userinput>cqslh -k <replaceable>keyspace-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/scripts/cql/dhcpdb_create.cql</userinput>
 </screen>
@@ -663,18 +662,18 @@ cql&gt; <userinput>CREATE KEYSPACE keyspace-name WITH replication = {'class' : '
       </para>
 
       <para>
-        If you elected not to create the tables in step 4, you can do
+        If you elected not to create the tables in Step 4, you can do
         so now by running the <command>kea-admin</command> tool:
 <screen>
 $ <userinput>kea-admin lease-init cql -n <replaceable>database-name</replaceable></userinput>
 </screen>
-        (Do not do this if you did create the tables in step 4.)
+        (Do not do this if you did create the tables in Step 4.)
-        <command>kea-admin</command> implements rudimentary checks:
+        <command>kea-admin</command> implements rudimentary checks;
         it will refuse to initialize a database that contains any
         existing tables. If you want to start from scratch, you
         must remove all data manually. (This process is a manual
-        operation on purpose to avoid possibly irretrievable mistakes
+        operation on purpose, to avoid possibly irretrievable mistakes
-        by <command>kea-admin</command>)
+        by <command>kea-admin</command>.)
       </para>
     </section>
 
@@ -682,8 +681,8 @@ $ <userinput>kea-admin lease-init cql -n <replaceable>database-name</replaceable
       <title>Upgrading a CQL Database from an Earlier Version of Kea</title>
 
       <para>
-        Sometimes a new Kea version may use newer database schema, so
+        Sometimes a new Kea version may use a newer database schema, so
-        there will be a need to upgrade the existing database. This can
+        the existing database will need to be upgraded. This can
         be done using the <command>kea-admin lease-upgrade</command>
         command.
       </para>
@@ -694,16 +693,16 @@ $ <userinput>kea-admin lease-init cql -n <replaceable>database-name</replaceable
 $ <userinput>kea-admin lease-version cql -n <replaceable>database-name</replaceable></userinput>
 </screen>
         (See <xref linkend="kea-database-version"/> for a discussion
-        about versioning)  If the version does not match the minimum
+        about versioning.) If the version does not match the minimum
         required for the new version of Kea (as described in the
         release notes), the database needs to be upgraded.
       </para>
 
       <para>
         Before upgrading, please make sure that the database is
-        backed up.  The upgrade process does not discard any data but,
+        backed up. The upgrade process does not discard any data, but
         depending on the nature of the changes, it may be impossible
-        to subsequently downgrade to an earlier version.  To perform
+        to subsequently downgrade to an earlier version. To perform
         an upgrade, issue the following command:
 <screen>
 $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replaceable></userinput>
@@ -725,21 +724,21 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
     </section>
 
     <section>
-      <title>Limitations Related to the use of SQL Databases</title>
+      <title>Limitations Related to the Use of SQL Databases</title>
 
 
       <section>
-        <title>Year 2038 issue</title>
+        <title>Year 2038 Issue</title>
         <para>
           The lease expiration time is stored in the SQL database for each lease
-          as a timestamp value. Kea developers observed that MySQL database doesn't
+          as a timestamp value. Kea developers observed that the MySQL database doesn't
           accept timestamps beyond 2147483647 seconds (maximum signed 32-bit number)
-          from the beginning of the epoch. At the same time, some versions of PostgreSQL
+          from the beginning of the epoch. Some versions of PostgreSQL
-          do accept greater values but the value is altered when it is read back.
+          do accept greater values, but the value is altered when it is read back.
-          For this reason the lease database backends put the restriction for the
+          For this reason, the lease database backends put a restriction on the
           maximum timestamp to be stored in the database, which is equal to the
           maximum signed 32-bit number. This effectively means that the current
-          Kea version can't store the leases which expiration time is later than
+          Kea version cannot store leases whose expiration time is later than
           2147483647 seconds since the beginning of the epoch (around year 2038).
           This will be fixed when the database support for longer timestamps
           is available.