Commit f9cad784 authored by Andrei Pavel's avatar Andrei Pavel

Upgraded Docbook from v4.2 to v5.0

Used script http://docbook.org/xml/5.0/tools/db4-upgrade.xsl as
specified in the installation documentation at
http://tdg.docbook.org/tdg/5.0/appa.html.
parent 039622a4
<?xml version="1.0" encoding="UTF-8"?> <!-- Converted by db4-upgrade version 1.0 -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="admin"><info><title>Kea Database Administration</title></info>
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash "&#x2014;" >
]>
<chapter id="admin"> <section xml:id="kea-database-version"><info><title>Databases and Database Version Numbers</title></info>
<title>Kea Database Administration</title>
<section id="kea-database-version">
<title>Databases and Database Version Numbers</title>
<para> <para>
Kea supports storing leases and host reservations (i.e. static Kea supports storing leases and host reservations (i.e. static
...@@ -52,8 +47,8 @@ ...@@ -52,8 +47,8 @@
</para> </para>
</section> </section>
<section id="kea-admin"> <section xml:id="kea-admin"><info><title>The kea-admin Tool</title></info>
<title>The kea-admin Tool</title>
<para> <para>
To manage the databases, Kea provides the To manage the databases, Kea provides the
...@@ -71,7 +66,7 @@ ...@@ -71,7 +66,7 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<simpara> <simpara>
<command>lease-init</command> &mdash; <command>lease-init</command>
Initializes a new lease database. This is useful during a new Initializes a new lease database. This is useful during a new
Kea installation. The database is initialized to the Kea installation. The database is initialized to the
latest version supported by the version of the software being latest version supported by the version of the software being
...@@ -81,7 +76,7 @@ ...@@ -81,7 +76,7 @@
<listitem> <listitem>
<simpara> <simpara>
<command>lease-version</command> &mdash; <command>lease-version</command>
Reports the lease database version number. This is Reports the lease database version number. This is
not necessarily equal to the Kea version number as not necessarily equal to the Kea version number as
each backend has its own versioning scheme. each backend has its own versioning scheme.
...@@ -90,7 +85,7 @@ ...@@ -90,7 +85,7 @@
<listitem> <listitem>
<simpara> <simpara>
<command>lease-upgrade</command> &mdash; <command>lease-upgrade</command>
Conducts a lease database upgrade. This is useful when Conducts a lease database upgrade. This is useful when
upgrading Kea. upgrading Kea.
</simpara> </simpara>
...@@ -98,7 +93,7 @@ ...@@ -98,7 +93,7 @@
<listitem> <listitem>
<simpara> <simpara>
<command>lease-dump</command> &mdash; <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
...@@ -114,28 +109,28 @@ ...@@ -114,28 +109,28 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<simpara> <simpara>
<command>memfile</command> &mdash; Lease information is <command>memfile</command> Lease information is
stored on disk in a text file. stored on disk in a text file.
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<command>mysql</command> &mdash; <command>mysql</command>
Lease information is stored in a MySQL relational database. Lease information is stored in a MySQL relational database.
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<command>pgsql</command> &mdash; <command>pgsql</command>
Lease information is stored in a PostgreSQL relational database. Lease information is stored in a PostgreSQL relational database.
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<command>cql</command> &mdash; <command>cql</command>
Lease information is stored in a CQL database. Lease information is stored in a CQL database.
</simpara> </simpara>
</listitem> </listitem>
...@@ -149,8 +144,8 @@ ...@@ -149,8 +144,8 @@
</para> </para>
</section> </section>
<section id="supported-databases"> <section xml:id="supported-databases"><info><title>Supported Databases</title></info>
<title>Supported Databases</title>
<para>The following table presents the capabilities of available <para>The following table presents the capabilities of available
backends. Please refer to the specific sections dedicated to each backend to backends. Please refer to the specific sections dedicated to each backend to
...@@ -158,14 +153,14 @@ ...@@ -158,14 +153,14 @@
backend may be essential for success or failure of your deployment.</para> backend may be essential for success or failure of your deployment.</para>
<para> <para>
<table frame="all" id="backends"> <table frame="all" xml:id="backends"><info><title>List of available backends</title></info>
<title>List of available backends</title>
<tgroup cols='2'> <tgroup cols="2">
<colspec colname='feature'/> <colspec colname="feature"/>
<colspec colname='memfile'/> <colspec colname="memfile"/>
<colspec colname='mysql'/> <colspec colname="mysql"/>
<colspec colname='pgsql'/> <colspec colname="pgsql"/>
<colspec colname='cql'/> <colspec colname="cql"/>
<thead> <thead>
<row> <row>
<entry>Feature</entry> <entry>Feature</entry>
...@@ -222,8 +217,8 @@ ...@@ -222,8 +217,8 @@
</table> </table>
</para> </para>
<section> <section><info><title>memfile</title></info>
<title>memfile</title>
<para> <para>
The memfile backend is able to store lease information, but is not able to The memfile backend is able to store lease information, but is not able to
...@@ -240,8 +235,8 @@ ...@@ -240,8 +235,8 @@
present. Necessary disk write permission is required. present. Necessary disk write permission is required.
</para> </para>
<section id="memfile-upgrade"> <section xml:id="memfile-upgrade"><info><title>Upgrading Memfile Lease Files from an Earlier Version of Kea</title></info>
<title>Upgrading Memfile Lease Files from an Earlier Version of Kea</title>
<para> <para>
There are no special steps required to upgrade memfile lease files There are no special steps required to upgrade memfile lease files
from an earlier version of Kea to a new version of Kea. from an earlier version of Kea to a new version of Kea.
...@@ -264,8 +259,8 @@ ...@@ -264,8 +259,8 @@
<!-- @todo: document lease file upgrades once they are implemented in kea-admin --> <!-- @todo: document lease file upgrades once they are implemented in kea-admin -->
</section> </section>
<section> <section><info><title>MySQL</title></info>
<title>MySQL</title>
<para> <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
...@@ -273,8 +268,8 @@ ...@@ -273,8 +268,8 @@
if you chose to store the data in other backends. if you chose to store the data in other backends.
</para> </para>
<section id="mysql-database-create"> <section xml:id="mysql-database-create"><info><title>First Time Creation of the MySQL Database</title></info>
<title>First Time Creation of the MySQL Database</title>
<para> <para>
If you are setting the MySQL database for the first time, If you are setting the MySQL database for the first time,
...@@ -287,14 +282,14 @@ ...@@ -287,14 +282,14 @@
<para> <para>
To create the database: To create the database:
<orderedlist> <orderedlist inheritnum="ignore" continuation="restarts">
<listitem> <listitem>
<para> <para>
Log into MySQL as "root": Log into MySQL as "root":
<screen> <screen>
$ <userinput>mysql -u root -p</userinput> $ <userinput>mysql -u root -p</userinput>
Enter password: Enter password:
mysql> mysql&gt;
</screen> </screen>
</para> </para>
</listitem> </listitem>
...@@ -303,7 +298,7 @@ mysql> ...@@ -303,7 +298,7 @@ mysql>
<para> <para>
Create the MySQL database: Create the MySQL database:
<screen> <screen>
mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput> mysql&gt; <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
</screen> </screen>
(<replaceable>database-name</replaceable> is the name (<replaceable>database-name</replaceable> is the name
you have chosen for the database.) you have chosen for the database.)
...@@ -316,8 +311,8 @@ mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</use ...@@ -316,8 +311,8 @@ mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</use
(and give it a password), then grant it access to the (and give it a password), then grant it access to the
database tables: database tables:
<screen> <screen>
mysql> <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput> mysql&gt; <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> mysql&gt; <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput>
</screen> </screen>
(<replaceable>user-name</replaceable> and (<replaceable>user-name</replaceable> and
<replaceable>password</replaceable> are the user ID <replaceable>password</replaceable> are the user ID
...@@ -334,8 +329,8 @@ mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<r ...@@ -334,8 +329,8 @@ mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<r
the tables using the <command>kea-admin</command> tool, the tables using the <command>kea-admin</command> tool,
as explained below.) To do this: as explained below.) To do this:
<screen> <screen>
mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput> mysql&gt; <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
mysql> <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/scripts/mysql/dhcpdb_create.mysql</userinput> mysql&gt; <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/scripts/mysql/dhcpdb_create.mysql</userinput>
</screen> </screen>
(<replaceable>path-to-kea</replaceable> is the (<replaceable>path-to-kea</replaceable> is the
location where you installed Kea.) location where you installed Kea.)
...@@ -346,7 +341,7 @@ mysql> <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/script ...@@ -346,7 +341,7 @@ mysql> <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/script
<para> <para>
Exit MySQL: Exit MySQL:
<screen> <screen>
mysql> <userinput>quit</userinput> mysql&gt; <userinput>quit</userinput>
Bye Bye
$ $
</screen> </screen>
...@@ -371,8 +366,8 @@ $ <userinput>kea-admin lease-init mysql -u <replaceable>database-user</replaceab ...@@ -371,8 +366,8 @@ $ <userinput>kea-admin lease-init mysql -u <replaceable>database-user</replaceab
</para> </para>
</section> </section>
<section id="mysql-upgrade"> <section xml:id="mysql-upgrade"><info><title>Upgrading a MySQL Database from an Earlier Version of Kea</title></info>
<title>Upgrading a MySQL Database from an Earlier Version of Kea</title>
<para> <para>
Sometimes a new Kea version may use newer database schema, so Sometimes a new Kea version may use newer database schema, so
...@@ -405,8 +400,8 @@ $ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replac ...@@ -405,8 +400,8 @@ $ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replac
</section> </section>
</section> <!-- end of MySQL sections --> </section> <!-- end of MySQL sections -->
<section> <section><info><title>PostgreSQL</title></info>
<title>PostgreSQL</title>
<para> <para>
A PostgreSQL database must be set up if you want Kea to store A PostgreSQL database must be set up if you want Kea to store
...@@ -414,15 +409,15 @@ $ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replac ...@@ -414,15 +409,15 @@ $ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replac
safely ignored if you are using other database backends. safely ignored if you are using other database backends.
</para> </para>
<section id="pgsql-database-create"> <section xml:id="pgsql-database-create"><info><title>First Time Creation of the PostgreSQL Database</title></info>
<title>First Time Creation of the PostgreSQL Database</title>
<para> <para>
The first task is to create both the lease database and the The first task is to create both the lease database and the
user under which the servers will access it. A number of steps user under which the servers will access it. A number of steps
are required: are required:
<orderedlist> <orderedlist inheritnum="ignore" continuation="restarts">
<listitem> <listitem>
<para> <para>
Log into PostgreSQL as "root": Log into PostgreSQL as "root":
...@@ -546,8 +541,8 @@ host <replaceable>database-name</replaceable> <replaceable>user-name</repl ...@@ -546,8 +541,8 @@ host <replaceable>database-name</replaceable> <replaceable>user-name</repl
</para> </para>
</section> </section>
<section> <section><info><title>Initialize the PostgreSQL Database Using kea-admin</title></info>
<title>Initialize the PostgreSQL Database Using kea-admin</title>
<para> <para>
If you elected not to create the tables manually, you can do If you elected not to create the tables manually, you can do
so now by running the <command>kea-admin</command> tool: so now by running the <command>kea-admin</command> tool:
...@@ -563,8 +558,8 @@ $ <userinput>kea-admin lease-init pgsql -u <replaceable>database-user</replaceab ...@@ -563,8 +558,8 @@ $ <userinput>kea-admin lease-init pgsql -u <replaceable>database-user</replaceab
by <command>kea-admin</command>.) by <command>kea-admin</command>.)
</para> </para>
</section> </section>
<section id="pgsql-upgrade"> <section xml:id="pgsql-upgrade"><info><title>Upgrading a PostgreSQL Database from an Earlier Version of Kea</title></info>
<title>Upgrading a PostgreSQL Database from an Earlier Version of Kea</title>
<para> <para>
The PostgreSQL database schema can be upgraded using the same tool and The PostgreSQL database schema can be upgraded using the same tool and
commands as described in <xref linkend="mysql-upgrade"/>, with the commands as described in <xref linkend="mysql-upgrade"/>, with the
...@@ -584,8 +579,8 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac ...@@ -584,8 +579,8 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
</section> </section>
</section> <!-- end of PostgreSQL sections --> </section> <!-- end of PostgreSQL sections -->
<section> <section><info><title>CQL (Cassandra)</title></info>
<title>CQL (Cassandra)</title>
<para> <para>
Cassandra, or Cassandra Query Language (CQL), is the newest backend Cassandra, or Cassandra Query Language (CQL), is the newest backend
...@@ -602,8 +597,8 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac ...@@ -602,8 +597,8 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
store the data in other backends. store the data in other backends.
</para> </para>
<section id="cql-database-create"> <section xml:id="cql-database-create"><info><title>First Time Creation of the Cassandra Database</title></info>
<title>First Time Creation of the Cassandra Database</title>
<para> <para>
If you are setting up the CQL database for the first time, you need to If you are setting up the CQL database for the first time, you need to
...@@ -613,7 +608,7 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac ...@@ -613,7 +608,7 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
<para> <para>
To create the database: To create the database:
<orderedlist> <orderedlist inheritnum="ignore" continuation="restarts">
<listitem> <listitem>
<para> <para>
Export CQLSH_HOST environemnt variable: Export CQLSH_HOST environemnt variable:
...@@ -627,7 +622,7 @@ $ <userinput>export CQLSH_HOST=localhost</userinput> ...@@ -627,7 +622,7 @@ $ <userinput>export CQLSH_HOST=localhost</userinput>
Log into CQL: Log into CQL:
<screen> <screen>
$ <userinput>cqlsh</userinput> $ <userinput>cqlsh</userinput>
cql> cql&gt;
</screen> </screen>
</para> </para>
</listitem> </listitem>
...@@ -636,7 +631,7 @@ cql> ...@@ -636,7 +631,7 @@ cql>
<para> <para>
Create the CQL keyspace: Create the CQL keyspace:
<screen> <screen>
cql> <userinput>CREATE KEYSPACE keyspace-name WITH replication = {'class' : 'SimpleStrategy','replication_factor' : 1};</userinput> cql&gt; <userinput>CREATE KEYSPACE keyspace-name WITH replication = {'class' : 'SimpleStrategy','replication_factor' : 1};</userinput>
</screen> </screen>
(<replaceable>keyspace-name</replaceable> is the name you have (<replaceable>keyspace-name</replaceable> is the name you have
chosen for the keyspace) chosen for the keyspace)
...@@ -674,8 +669,8 @@ $ <userinput>kea-admin lease-init cql -n <replaceable>database-name</replaceable ...@@ -674,8 +669,8 @@ $ <userinput>kea-admin lease-init cql -n <replaceable>database-name</replaceable
</para> </para>
</section> </section>
<section id="cql-upgrade"> <section xml:id="cql-upgrade"><info><title>Upgrading a CQL Database from an Earlier Version of Kea</title></info>
<title>Upgrading a CQL Database from an Earlier Version of Kea</title>
<para> <para>
Sometimes a new Kea version may use newer database schema, so Sometimes a new Kea version may use newer database schema, so
...@@ -708,8 +703,8 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea ...@@ -708,8 +703,8 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
</section> </section>
</section> <!-- end of CQL sections --> </section> <!-- end of CQL sections -->
<section> <section><info><title>Using Read-Only Databases with Host Reservations</title></info>
<title>Using Read-Only Databases with Host Reservations</title>
<para>If a read-only database is used for storing host reservations, <para>If a read-only database is used for storing host reservations,
Kea must be explicitly configured to operate on the database in Kea must be explicitly configured to operate on the database in
read-only mode. read-only mode.
...@@ -720,8 +715,8 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea ...@@ -720,8 +715,8 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
</para> </para>
</section> </section>
<section> <section><info><title>Limitations Related to the use of SQL Databases</title></info>
<title>Limitations Related to the use of SQL Databases</title>
<para> <para>
The lease expiration time is stored in the SQL database for each lease The lease expiration time is stored in the SQL database for each lease
...@@ -741,4 +736,4 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea ...@@ -741,4 +736,4 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
</section> <!-- End of Database sections --> </section> <!-- End of Database sections -->
</chapter> </chapter>
\ No newline at end of file
<?xml version="1.0" encoding="UTF-8"?> <!-- Converted by db4-upgrade version 1.0 -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="classify"><info><title>Client Classification</title></info>
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash "&#x2014;" >
]>
<chapter id="classify"> <section><info><title>Client Classification Overview</title></info>
<title>Client Classification</title>
<section>
<title>Client Classification Overview</title>
<para> <para>
In certain cases it is useful to differentiate between different In certain cases it is useful to differentiate between different
types of clients and treat them accordingly. Common reasons include: types of clients and treat them accordingly. Common reasons include:
...@@ -41,7 +36,7 @@ ...@@ -41,7 +36,7 @@
<para> <para>
The process of doing classification is conducted in three steps: The process of doing classification is conducted in three steps:
<orderedlist> <orderedlist inheritnum="ignore" continuation="restarts">
<listitem><para> <listitem><para>
Assess an incoming packet and assign it to zero or more classes. Assess an incoming packet and assign it to zero or more classes.
</para></listitem> </para></listitem>
...@@ -95,37 +90,37 @@ ...@@ -95,37 +90,37 @@
</note> </note>
</section> </section>
<section id="classification-using-host-reservations"> <section xml:id="classification-using-host-reservations"><info><title>Using Static Host Reservations In Classification</title></info>
<title>Using Static Host Reservations In Classification</title>
<para>Classes can be statically assigned to the clients using techniques described <para>Classes can be statically assigned to the clients using techniques described
in <xref linkend="reservation4-client-classes"/> and in <xref linkend="reservation4-client-classes"/> and
<xref linkend="reservation6-client-classes"/>. <xref linkend="reservation6-client-classes"/>.
</para> </para>
</section> </section>
<section id="classification-using-vendor"> <section xml:id="classification-using-vendor"><info><title>Using Vendor Class Information In Classification</title></info>
<title>Using Vendor Class Information In Classification</title>
<para> <para>
The server checks whether an incoming DHCPv4 packet includes The server checks whether an incoming DHCPv4 packet includes
the vendor class identifier option (60) or an incoming DHCPv6 packet the vendor class identifier option (60) or an incoming DHCPv6 packet
includes the vendor class option (16). If it does, the content of that includes the vendor class option (16). If it does, the content of that
option is prepended with &quot;VENDOR_CLASS_&quot; and the result is interpreted option is prepended with "VENDOR_CLASS_" and the result is interpreted
as a class. For example, modern cable modems will send this option with as a class. For example, modern cable modems will send this option with
value &quot;docsis3.0&quot; and so the packet will belong to value "docsis3.0" and so the packet will belong to
class &quot;VENDOR_CLASS_docsis3.0&quot;. class "VENDOR_CLASS_docsis3.0".
</para> </para>
</section> </section>
<section id="classification-using-expressions"> <section xml:id="classification-using-expressions"><info><title>Using Expressions In Classification</title></info>
<title>Using Expressions In Classification</title>
<para> <para>
The expression portion of classification contains operators and values. The expression portion of classification contains operators and values.
All values are currently strings and operators take a string or strings and All values are currently strings and operators take a string or strings and
return another string. When all the operations have completed return another string. When all the operations have completed
the result should be a value of &quot;true&quot; or &quot;false&quot;. the result should be a value of "true" or "false".
The packet belongs to The packet belongs to
the class (and the class name is added to the list of classes) if the result the class (and the class name is added to the list of classes) if the result
is &quot;true&quot;. Expressions are written in standard format and can be nested. is "true". Expressions are written in standard format and can be nested.
</para> </para>
<para> <para>
...@@ -152,12 +147,12 @@ ...@@ -152,12 +147,12 @@
</para> </para>
<para> <para>
<table frame="all" id="classification-values-list"> <table frame="all" xml:id="classification-values-list"><info><title>List of Classification Values</title></info>
<title>List of Classification Values</title>
<tgroup cols='3'> <tgroup cols="3">
<colspec colname='name' /> <colspec colname="name"/>
<colspec colname='example' /> <colspec colname="example"/>
<colspec colname='description' /> <colspec colname="description"/>
<thead> <thead>
<row> <row>
<entry>Name</entry> <entry>Name</entry>
...@@ -192,7 +187,7 @@ ...@@ -192,7 +187,7 @@
<entry>'123'</entry> <entry>'123'</entry>
<entry>A 32 bit unsigned integer value</entry> <entry>A 32 bit unsigned integer value</entry>
</row> </row>
<row></row> <row/>
<row> <row>