Browse Source

[3644] Review and edit of kea-admin part of the guide

The edit also included a reorganisation of the sections.
Stephen Morris 10 years ago
parent
commit
5d1bc8d88d
2 changed files with 346 additions and 236 deletions
  1. 345 235
      doc/guide/admin.xml
  2. 1 1
      doc/guide/install.xml

+ 345 - 235
doc/guide/admin.xml

@@ -4,276 +4,366 @@
 <!ENTITY mdash  "&#x2014;" >
 ]>
 
-  <chapter id="admin">
-    <title>Database administration</title>
+<chapter id="admin">
+  <title>Kea Database Administration</title>
+
+  <section id="kea-database-version">
+    <title>Databases and Database Version Numbers</title>
+
+    <para>
+      Kea stores leases in one of 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: in the future, additional data - such as host
+      reservation details - will also be stored.
+    </para>
+
+    <para>
+      A given version of Kea expects a particular structure in
+      the database.  It ensures this by checking the version of the
+      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. Likewise, it is possible that the
+      version of backend database may go up several revisions during a
+      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>
+
+    <para>
+      Backend versions are specified in
+      a <replaceable>major.minor</replaceable> format. The minor
+      number is increased when there are backward compatibile changes
+      introduced.  For example, ithe addition of a new index. It is
+      desirable, but not mandatory to to apply such a change; you
+      can run on 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,
+      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:
+      administrative action will be required to upgrade the database.
+    </para>
+  </section>
+
+  <section id="kea-admin">
+    <title>The kea-admin Tool</title>
+
+    <para>
+      To manage the databases, Kea provides the
+      <command>kea-admin</command> tool. It is able to initialize
+      a new database, check its version number, and perform a
+      database upgrade.
+    </para>
+
+    <para>
+      <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:
+
+      <itemizedlist>
+        <listitem>
+          <simpara>
+            <command>lease-init</command> &mdash;
+            Initializes a new lease database. Useful during first
+            Kea installation. The database is initialized to the
+            latest version supported by the version of the software.
+          </simpara>
+        </listitem>
 
-    <section id="kea-admin">
-      <title>kea-admin tool</title>
+        <listitem>
+          <simpara>
+            <command>lease-version</command> &mdash;
+            Reports the lease database version number. This is
+            not necessarily equal to the Kea version number as
+            each backend has its own versioning scheme.
+          </simpara>
+        </listitem>
 
-      <para>
-        Kea is able to store leases in one of several supported databases.
-        Additional types of data, like host reservation details, will
-        be supported in the near future. To manage those databases, a
-        tool called <command>kea-admin</command> was introduced. Currently
-        it is able to initialize new database, check its version
-        and perform database upgrade, if needed.
-      </para>
+        <listitem>
+          <simpara>
+            <command>lease-upgrade</command> &mdash;
+            Conducts a lease database upgrade. This is useful when
+            upgrading Kea.
+          </simpara>
+        </listitem>
+      </itemizedlist>
 
-      <para>
-        Kea mantains separate version numbering for its database backends. These
-        are independent of the Kea version. It is possible that the backend
-        revision will stay the same through several Kea revisions. Likewise, it
-        is possible that a backend may go up several times between two Kea
-        revisions, if there were several changes introduced that required database
-        schema change. Versions for each backend are independent, so a bump
-        in MySQL version does not imply bump in the Postgres version.
-      </para>
+      <command>backend</command> specifies the backend type. Currently
+      supported types are:
 
-      <para>
-        Backend versions are specified in major.minor format. Minor number is
-        increased when there are backward compatibile changes introduced.  For
-        example, a new index is added. It is desirable, but not mandatory to
-        have it. You can run on older database version if you want to. On
-        the other hand, major number is increased when there's an incompatible
-        change introduced, for example an extra column is added. If you try
-        to run Kea software on a database that is too old (which is signified
-        by mismatched major backend version number), Kea will refuse to run
-        and an administrative action will be required to upgrade the database.
-      </para>
-      
-      <para>
-        <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:
-
-        <itemizedlist>
-
-          <listitem>
-            <simpara>
-              <command>lease-init</command> &mdash;
-              Initializes a new lease database. Useful during first Kea
-              installation. The database is initialized to the latest version
-              supported by the version of the software.
-            </simpara>
-          </listitem>
-
-          <listitem>
-            <simpara>
-              <command>lease-version</command> &mdash;
-              Reports lease database version. This is not necessarily
-              equal to Kea version as each backend has its own versioning
-              scheme.
-            </simpara>
-          </listitem>
-
-          <listitem>
-            <simpara>
-              <command>lease-upgrade</command> &mdash;
-              Conducts lease database upgrade. This is useful when
-              migrating between old and new Kea versions.
-            </simpara>
-          </listitem>
-
-        </itemizedlist>
-
-        The <command>backend</command> specified backend type. Currently
-        allowed backends are: memfile, mysql and pgsql. There are additional
-        parameters that may be needed, depending on your setup and specific
-        operation: specify username, password and database name or the directory
-        where specific files are located. See appropriate manual page for
-        details (<command>man 8 kea-admin</command>).
-      </para>
+      <itemizedlist>
+        <listitem>
+          <simpara>
+            <command>memfile</command> &mdash; Lease information is
+            stored on disk in a text file.
+          </simpara>
+        </listitem>
 
-    </section>
+        <listitem>
+          <simpara>
+            <command>mysql</command> &mdash;
+            Lease information is stored in a MySQL relational
+            database.
+          </simpara>
+        </listitem>
+
+        <listitem>
+          <simpara>
+            <command>pgsql</command> &mdash;
+            Lease information is stored in a PostgreSQL relational
+            database.
+          </simpara>
+        </listitem>
+      </itemizedlist>
+
+      Additional parameters may be needed, depending on your setup
+      and specific operation: username, password and database name or
+      the directory where specific files are located. See appropriate
+      manual page for details (<command>man 8 kea-admin</command>).
+    </para>
+  </section>
+
+  <section>
+    <title>Supported Databases</title>
 
     <section>
       <title>memfile</title>
 
-      <para>There are no special initialization steps necessary for memfile
-      backend.  During the first run, both <command>kea-dhcp4</command> and
-      <command>kea-dhcp6</command> will create an empty lease file, if it is not
-      present. Necessary disk write permission is required.
+      <para>
+        There are no special initialization steps necessary
+        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.
       </para>
-
-
       <!-- @todo: document lease file upgrades once they are implemented in kea-admin -->
-
     </section>
 
     <section>
       <title>MySQL</title>
 
       <para>
-        MySQL database must be properly set up if you want Kea to store lease
-        and other information in MySQL. This step can be safely skipped if you
-        chose to store the data in other backends, like memfile or PosgreSQL.
+        The MySQL database must be properly set up if you want Kea to
+        store information in MySQL. This section can be safely ignored
+        if you chose to store the data in other backends.
       </para>
 
-    <section id="mysql-database-create">
-      <title>Initialize the MySQL Database using kea-admin</title>
 
-      <para>
-        There are two ways to initialize the database. The first one involves
-        running <command>kea-admin</command> tool, which attempts to automate
-        the process. It is convenient to use, but may not cover more complex
-        cases. The second alternative is to run all the commands
-        manually.
-      </para>
+      <section id="mysql-database-create">
+        <title>First Time Creation of Kea Database</title>
 
-      <para>
-        When <command>kea-admin</command> is told to initialize the database, it
-        assumes that the database and database user has been created. If not,
-        please follow the necessary instructions in <xref
-        linkend="mysql-database-create-manual" />.
-      </para>
-
-      <para>
-        To initialize new MySQL database using <command>kea-admin</command>, use the
-        following command:
-          <screen>$ <userinput>kea-admin lease-init mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <replaceable>database-name</replaceable></userinput>
-</screen>
-
-      <command>kea-admin</command> has rudimentary checks implemented. It will
-      refuse to initialize a database that has any existing tables. If you want
-      to start from scratch, you must remove existing data manually. This process
-      is left manual on purpose to avoid mistakes that could not be undone.
-      </para>
+        <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>
+          is not able to do this for you.
+        </para>
 
-    </section>
+        <para>
+          To create the database:
 
-    <section id="mysql-upgrade">
-      <title>Upgrading MySQL database from earlier Kea versions</title>
+          <orderedlist>
+            <listitem>
+              <para>
+                Log into MySQL as "root":
+<screen>
+$ <userinput>mysql -u root -p</userinput>
+Enter password:
+mysql>
+</screen>
+              </para>
+            </listitem>
 
-      <para>Sometime a new Kea version may use newer database schema and there may
-      be a need to upgrade existing database. This can be done using <command>kea-admin</command>.
-      It is possible to check existing database version:
-          <screen>$ <userinput>kea-admin lease-version mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <replaceable>database-name</replaceable></userinput>
+            <listitem>
+              <para>
+                Create the MySQL database:
+<screen>
+mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
 </screen>
-      See <xref linkend="kea-admin"/> for a discussion about versioning.</para>
-      <para>It may be required to run database upgrade. This process is designed
-      to not discard any data, but depending on the nature of the changes, it
-      may be impossible to downgrade to earlier Kea version. Please back up your
-      database if you consider reverting to an earlier Kea version. To conduct
-      an upgrade, the following command should be used:
-          <screen>$ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <replaceable>database-name</replaceable></userinput>
+                (<replaceable>database-name</replaceable> is the name
+                you have chosen for the database.)
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Create the user under which Kea will access the database
+                (and give it a password), then grant it access to the
+                database tables:
+<screen>
+mysql> <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput>
+mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput>
 </screen>
-      </para>
+                (<replaceable>user-name</replaceable> and
+                <replaceable>password</replaceable> are the user ID
+                and password you are using to allow Keas access to the
+                MySQL instance. All apostrophes in the command lines
+                above are required.)
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                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:
+<screen>
+mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
+mysql> <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/dhcpdb_create.mysql</userinput>
+</screen>
+                (<replaceable>path-to-kea</replaceable> is the
+                location where you installed Kea.)
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Exit MySQL:
+<screen>
+mysql> <userinput>quit</userinput>
+Bye
+$
+</screen>
+              </para>
+            </listitem>
+          </orderedlist>
+        </para>
 
-    </section>
+        <para>
+          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> -d <replaceable>database-name</replaceable></userinput>
+</screen>
+          (Do not do this if you did create the tables in step 4.)
+          <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
+          by <command>kea-admin</command>.)
+        </para>
+      </section>
 
-     <section id="mysql-database-create-manual">
-        <title>Manually create the MySQL Database and the Kea User</title>
+      <section id="mysql-upgrade">
+        <title>Upgrading a MySQL Database from an Earlier Version of Kea</title>
 
-        <note>
-          <simpara>
-          This paragraph explains how to create and initialize MySQL database
-          manually. See <xref linkend="mysql-database-create" /> for a kea-admin,
-          a tool that automates most of those steps.
-          </simpara>
-        </note>
         <para>
-          The first task is to create both the lease database and the user under
-          which the servers will access it. A number of steps are required:
+          Sometimes a new Kea version may use newer database schema, so
+          there will be a need to upgrade the existing database. This can
+          be done using the <command>kea-admin lease-upgrade</command>
+          command.
         </para>
+
         <para>
-          1. Log into MySQL as "root":
-          <screen>$ <userinput>mysql -u root -p</userinput>
-Enter password:<userinput/>
-   :<userinput/>
-mysql></screen>
+          To check the current version of the database, use the following command:
+<screen>
+$ <userinput>kea-admin lease-version mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <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
+          required for the new version of Kea (as described in the
+          release notes), the database needs to be upgraded.
         </para>
+
         <para>
-          2. Create the database:
-          <screen>mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput></screen>
-	  (<replaceable>database-name</replaceable> is the name you
-	  have chosen for the database.)
-        </para>
-         <para>
-          3. Create the database tables by running the dhcpdb_create.mysql script supplied as part of Kea:
-          <screen>mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
-mysql> <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/dhcpdb_create.mysql</userinput></screen>
-        </para>
-         <para>
-          4. Create the user under which Kea will access the database (and give it a password), then grant it access to the database tables:
-          <screen>mysql> <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput>
-mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput></screen>
+          Before upgrading, please make sure that the database is
+          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
+          an upgrade, issue the following command:
+<screen>
+$ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <replaceable>database-name</replaceable></userinput>
+</screen>
         </para>
-        <para>
-          5. Exit MySQL:
-          <screen>mysql> <userinput>quit</userinput>
-Bye<userinput/>
-$</screen>
-       </para>
-     </section>
-
+      </section>
     </section> <!-- end of MySQL sections -->
 
     <section>
       <title>PostgreSQL</title>
 
       <para>
-        PostgreSQL database must be properly set up if you want Kea to store lease
-        and other information in PostgreSQL. This step can be safely skipped if you
-        chose to store the data in other backends, like memfile or MySQL.
+        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>
-        <title>Initialize the PostgreSQL Database using kea-admin</title>
+      <section id="pgsql-database-create">
+        <title>Manually Create the PostgreSQL Database and the Kea User</title>
 
         <para>
-          Support for PostgreSQL in kea-admin is currently not implemented.
-        </para>
-      <!-- @todo: document PgSQL upgrade once they are implemented in kea-admin -->
-
-      </section>
-      
+          The first task is to create both the lease database and the
+          user under which the servers will access it. A number of steps
+          are required:
+
+          <orderedlist>
+            <listitem>
+              <para>
+                Log into PostgreSQL as "root":
+<screen>
+$ <userinput>sudo -u postgres psql postgres</userinput>
+Enter password:
+postgres=#
+</screen>
+              </para>
+            </listitem>
 
-      <section id="pgsql-database-create">
-        <title>Create PostgreSQL Database and Kea User</title>
-        <para>
-          The next task is to create both the lease database and the user under which the servers will
-          access it. A number of steps are required:
-        </para>
-        <para>
-          1. Log into PostgreSQL as "root":
-          <screen>$ <userinput>sudo -u postgres psql postgres</userinput>
-Enter password:<userinput/>
-   :<userinput/>
-postgres=#</screen>
-        </para>
-        <para>
-          2. Create the database:
+            <listitem>
+              <para>
+                Create the database:
 <screen>
 postgres=#<userinput> CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
 CREATE DATABASE
 postgres=#
 </screen>
-	  (<replaceable>database-name</replaceable> is the name you
-	  have chosen for the database.)
-        </para>
-         <para>
-          3. Create the user under which Kea will access the database (and give it a password), then grant it access to the database:
-<screen>postgres=#<userinput> CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD '<replaceable>password</replaceable>';</userinput>
+                (<replaceable>database-name</replaceable> is the name
+                you have chosen for the database.)
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Create the user under which Kea will access the database
+                (and give it a password), then grant it access to the
+                database:
+<screen>
+postgres=#<userinput> CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD '<replaceable>password</replaceable>';</userinput>
 CREATE ROLE
 postgres=#
 postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
 GRANT
 postgres=#
 </screen>
-        </para>
-         <para>
-          4. Exit PostgreSQL:
-          <screen>postgres=# <userinput>\q</userinput>
-Bye<userinput/>
-$</screen>
-       </para>
-       <para>
-        5. Create the database tables using the new user's credentials and the dhcpdb_create.pgsql script supplied with Kea.
-        After entering the following command, you will be prompted for the new
-        user's password. When the command completes you will be returned to
-        the shell prompt. You should see output similar to following:
-<screen>$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/dhcpdb_create.pgsql</userinput>
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Exit PostgreSQL:
+<screen>
+postgres=# <userinput>\q</userinput>
+Bye
+$
+</screen>
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Create the database tables using the new user's
+                credentials and the dhcpdb_create.pgsql script supplied
+                with Kea.  After entering the following command, you
+                will be prompted for the new user's password. When the
+                command completes you will be returned to the shell
+                prompt. You should see output similar to following:
+<screen>
+$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/dhcpdb_create.pgsql</userinput>
 Password for user <replaceable>user-name</replaceable>:
 CREATE TABLE
 CREATE INDEX
@@ -292,36 +382,56 @@ INSERT 0 1
 COMMIT
 $
 </screen>
-  </para>
-  <para>
-  If instead you encounter an error like:
-  </para>
+                (<replaceable>path-to-kea</replaceable> is the location
+                where you installed Kea.)
+              </para>
+
+              <para>
+                If instead you encounter an error like:
 <screen>
 psql: FATAL:  no pg_hba.conf entry for host "[local]", user "<replaceable>user-name</replaceable>", database "<replaceable>database-name</replaceable>", SSL off
 </screen>
-  <para>
-  ... 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 normally located in the primary data directory for your 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>.
-  Assuming Kea is running on the same host as PostgreSQL, adding lines similar
-  to following should be sufficient to provide password-authenticated access to
-  Kea's database:
-  </para>
+                ... 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
+                normally located in the primary data directory for your
+                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
+                provide password-authenticated access to Kea's database:
 <screen>
 local   <replaceable>database-name</replaceable>    <replaceable>user-name</replaceable>                                 password
 host    <replaceable>database-name</replaceable>    <replaceable>user-name</replaceable>          127.0.0.1/32           password
 host    <replaceable>database-name</replaceable>    <replaceable>user-name</replaceable>          ::1/128                password
 </screen>
-  <para>
-  Please consult your PostgreSQL user manual before making these changes as they
-  may expose your other databases that you run on the same system.
-  </para>
+              </para>
+
+              <para>
+                Please consult your PostgreSQL user manual before making
+                these changes as they may expose your other databases
+                that you run on the same system.
+              </para>
+            </listitem>
+          </orderedlist>
+        </para>
       </section>
 
-    </section> <!-- end of postgres sections -->
+      <section>
+        <title>Initialize the PostgreSQL Database Using kea-admin</title>
+
+        <para>
+          Support for PostgreSQL in <command>kea-admin</command> is
+          currently not implemented.
+        </para>
+        <!-- @todo: document PgSQL upgrade once they are implemented in kea-admin -->
+      </section>
+    </section> <!-- end of PostgreSQL sections -->
+  </section> <!-- End of Database sections -->
 
-  </chapter>
+</chapter>

+ 1 - 1
doc/guide/install.xml

@@ -478,7 +478,7 @@ Debian and Ubuntu:
         </para>
         <para>
           See <xref linkend="pgsql-database-create"/> for details regarding
-          MySQL database configuration.
+          PostgreSQL database configuration.
         </para>
       </section>
    </section>