Skip to content

GitLab

Commit 97a03ea1 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[3644] kea-admin is now documented in the User's Guide.

parent f8b8d39b
Hide whitespace changes
Inline Side-by-side
doc/guide/Makefile.am
View file @ 97a03ea1
......@@ -5,7 +5,7 @@ DOCS = kea-guide.txt
dist_doc_DATA = $(DOCS)
dist_html_DATA = $(HTMLDOCS) kea-guide.css
DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml config.xml
DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml
DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml logging.xml ddns.xml
DOCBOOK += libdhcp.xml
......
doc/guide/admin.xml 0 → 100644
View file @ 97a03ea1
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash "&#x2014;" >
]>
<chapter id="admin">
<title>Database administration</title>
<section id="kea-admin">
<title>kea-admin tool</title>
<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>
<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>
<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>
</section>
<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>
<!-- @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.
</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>
<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>
</section>
<section id="mysql-upgrade">
<title>Upgrading MySQL database from earlier Kea versions</title>
<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>
</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>
</screen>
</para>
</section>
<section id="mysql-database-create-manual">
<title>Manually create the MySQL Database and the Kea User</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:
</para>
<para>
1. Log into MySQL as "root":
<screen>$ <userinput>mysql -u root -p</userinput>
Enter password:<userinput/>
:<userinput/>
mysql></screen>
</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>
</para>
<para>
5. Exit MySQL:
<screen>mysql> <userinput>quit</userinput>
Bye<userinput/>
$</screen>
</para>
</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.
</para>
<section>
<title>Initialize the PostgreSQL Database using kea-admin</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>
<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:
<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>
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>
Password for user <replaceable>user-name</replaceable>:
CREATE TABLE
CREATE INDEX
CREATE INDEX
CREATE TABLE
CREATE INDEX
CREATE TABLE
START TRANSACTION
INSERT 0 1
INSERT 0 1
INSERT 0 1
COMMIT
CREATE TABLE
START TRANSACTION
INSERT 0 1
COMMIT
$
</screen>
</para>
<para>
If instead you encounter an error like:
</para>
<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>
<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>
</section>
</section> <!-- end of postgres sections -->
</chapter>
doc/guide/dhcp4-srv.xml
View file @ 97a03ea1
......@@ -302,8 +302,8 @@ url="http://jsonviewer.stack.hu/"/>.
"Dhcp4": { "lease-database": { <userinput>"type": "mysql"</userinput>, ... }, ... }
</screen>
Next, the name of the database to hold the leases must be set: this is the
name used when the lease database was created (see <xref linkend="dhcp-mysql-database-create"/>
or <xref linkend="dhcp-pgsql-database-create"/>).
name used when the lease database was created (see <xref linkend="mysql-database-create"/>
or <xref linkend="pgsql-database-create"/>).
<screen>
"Dhcp4": { "lease-database": { <userinput>"name": "<replaceable>database-name</replaceable>" </userinput>, ... }, ... }
</screen>
......
doc/guide/dhcp6-srv.xml
View file @ 97a03ea1
......@@ -306,8 +306,8 @@ JSON validator is available at <ulink url="http://jsonviewer.stack.hu/"/>.
"Dhcp6": { "lease-database": { <userinput>"type": "mysql"</userinput>, ... }, ... }
</screen>
Next, the name of the database is to hold the leases must be set: this is the
name used when the lease database was created (see <xref linkend="dhcp-mysql-database-create"/>
or <xref linkend="dhcp-pgsql-database-create"/>).
name used when the lease database was created (see <xref linkend="mysql-database-create"/>
or <xref linkend="pgsql-database-create"/>).
<screen>
"Dhcp6": { "lease-database": { <userinput>"name": "<replaceable>database-name</replaceable>" </userinput>, ... }, ... }
</screen>
......
doc/guide/install.xml
View file @ 97a03ea1
......@@ -454,44 +454,11 @@ Debian and Ubuntu:
"mysql_config" if MySQL was not installed in the default location:
<screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
</para>
</section>
<section id="dhcp-mysql-database-create">
<title>Create the MySQL Database and the 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 MySQL as "root":
<screen>$ <userinput>mysql -u root -p</userinput>
Enter password:<userinput/>
:<userinput/>
mysql></screen>
</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>
See <xref linkend="mysql-database-create"/> for details regarding
MySQL database configuration.
</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>
</para>
<para>
5. Exit MySQL:
<screen>mysql> <userinput>quit</userinput>
Bye<userinput/>
$</screen>
</para>
</section>
</section>
<section>
<title>Building with PostgreSQL support</title>
......@@ -509,98 +476,10 @@ $</screen>
the default location:
<screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
</para>
</section>
<section id="dhcp-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:
<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>
CREATE ROLE
postgres=#
postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
GRANT
postgres=#
</screen>
See <xref linkend="pgsql-database-create"/> for details regarding
MySQL database configuration.
</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>
Password for user <replaceable>user-name</replaceable>:
CREATE TABLE
CREATE INDEX
CREATE INDEX
CREATE TABLE
CREATE INDEX
CREATE TABLE
START TRANSACTION
INSERT 0 1
INSERT 0 1
INSERT 0 1
COMMIT
CREATE TABLE
START TRANSACTION
INSERT 0 1
COMMIT
$
</screen>
</para>
<para>
If instead you encounter an error like:
</para>
<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>
<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>
</section>
</section>
......
doc/guide/intro.xml
View file @ 97a03ea1
......@@ -138,6 +138,14 @@
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-admin</command> &mdash;
A tool useful for database backend maintenance (creating new
database, checking versions, upgrading etc.)
</simpara>
</listitem>
<listitem>
<simpara>
<command>perfdhcp</command> &mdash;
......
doc/guide/kea-guide.xml
View file @ 97a03ea1
......@@ -57,6 +57,8 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="admin.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="keactrl.xml" />
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment