diff --git a/doc/guide/admin.xml b/doc/guide/admin.xml
index fd0f46f757..d1bb165500 100644
--- a/doc/guide/admin.xml
+++ b/doc/guide/admin.xml
@@ -4,276 +4,366 @@
]>
-
- Database administration
+
+ Kea Database Administration
-
- kea-admin tool
+
+ Databases and Database Version Numbers
-
- 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 kea-admin was introduced. Currently
- it is able to initialize new database, check its version
- and perform database upgrade, if needed.
-
+
+ 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.
+
-
- 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.
-
+
+ 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.
+
-
- 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.
-
-
-
- kea-admin takes two mandatory parameters:
- command and backend. Additional,
- non-mandatory options may be specified. Currently supported commands
- are:
+
+ Backend versions are specified in
+ a major.minor 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.
+
+
-
+
+ The kea-admin Tool
-
-
- lease-init —
- 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.
-
-
+
+ To manage the databases, Kea provides the
+ kea-admin tool. It is able to initialize
+ a new database, check its version number, and perform a
+ database upgrade.
+
-
-
- lease-version —
- Reports lease database version. This is not necessarily
- equal to Kea version as each backend has its own versioning
- scheme.
-
-
+
+ kea-admin takes two mandatory
+ parameters: command and
+ backend. Additional, non-mandatory options
+ may be specified. Currently supported commands are:
-
-
- lease-upgrade —
- Conducts lease database upgrade. This is useful when
- migrating between old and new Kea versions.
-
-
+
+
+
+ lease-init —
+ 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.
+
+
-
+
+
+ lease-version —
+ Reports the lease database version number. This is
+ not necessarily equal to the Kea version number as
+ each backend has its own versioning scheme.
+
+
- The backend 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 (man 8 kea-admin).
-
+
+
+ lease-upgrade —
+ Conducts a lease database upgrade. This is useful when
+ upgrading Kea.
+
+
+
-
+ backend specifies the backend type. Currently
+ supported types are:
+
+
+
+
+ memfile — Lease information is
+ stored on disk in a text file.
+
+
+
+
+
+ mysql —
+ Lease information is stored in a MySQL relational
+ database.
+
+
+
+
+
+ pgsql —
+ Lease information is stored in a PostgreSQL relational
+ database.
+
+
+
+
+ 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 (man 8 kea-admin).
+
+
+
+
+ Supported Databases
memfile
- There are no special initialization steps necessary for memfile
- backend. During the first run, both kea-dhcp4 and
- kea-dhcp6 will create an empty lease file, if it is not
- present. Necessary disk write permission is required.
+
+ There are no special initialization steps necessary
+ for the memfile backend. During the first run, both
+ kea-dhcp4 and kea-dhcp6
+ will create an empty lease file if one is not
+ present. Necessary disk write permission is required.
-
-
-
MySQL
- 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.
-
- Initialize the MySQL Database using kea-admin
-
- There are two ways to initialize the database. The first one involves
- running kea-admin 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.
-
+
+ First Time Creation of Kea Database
-
- When kea-admin 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 .
-
+
+ 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: kea-admin
+ is not able to do this for you.
+
-
- To initialize new MySQL database using kea-admin, use the
- following command:
- $ kea-admin lease-init mysql -u database-user -p database-password -d database-name
+
+ To create the database:
+
+
+
+
+ Log into MySQL as "root":
+
+$ mysql -u root -p
+Enter password:
+mysql>
+
+
- kea-admin 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.
-
-
-
-
-
- Upgrading MySQL database from earlier Kea versions
-
- 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 kea-admin.
- It is possible to check existing database version:
- $ kea-admin lease-version mysql -u database-user -p database-password -d database-name
+
+
+ Create the MySQL database:
+
+mysql> CREATE DATABASE database-name;
- See for a discussion about versioning.
- 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:
- $ kea-admin lease-upgrade mysql -u database-user -p database-password -d database-name
+ (database-name is the name
+ you have chosen for the database.)
+
+
+
+
+
+ Create the user under which Kea will access the database
+ (and give it a password), then grant it access to the
+ database tables:
+
+mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password';
+mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost';
-
+ (user-name and
+ password 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.)
+
+
-
+
+
+ At this point, you may elect to create the database
+ tables. (Alternatively, you can exit MySQL and create
+ the tables using the kea-admin tool,
+ as explained below.) To do this:
+
+mysql> CONNECT database-name;
+mysql> SOURCE path-to-kea/share/kea/dhcpdb_create.mysql
+
+ (path-to-kea is the
+ location where you installed Kea.)
+
+
-
- Manually create the MySQL Database and the Kea User
+
+
+ Exit MySQL:
+
+mysql> quit
+Bye
+$
+
+
+
+
+
-
-
- This paragraph explains how to create and initialize MySQL database
- manually. See for a kea-admin,
- a tool that automates most of those steps.
-
-
- 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:
+ If you elected not to create the tables in step 4, you can do
+ so now by running the kea-admin tool:
+
+$ kea-admin lease-init mysql -u database-user -p database-password -d database-name
+
+ (Do not do this if you did create the tables in step 4.)
+ kea-admin 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 kea-admin.)
-
- 1. Log into MySQL as "root":
- $ mysql -u root -p
-Enter password:
- :
-mysql>
-
-
- 2. Create the database:
- mysql> CREATE DATABASE database-name;
- (database-name is the name you
- have chosen for the database.)
-
-
- 3. Create the database tables by running the dhcpdb_create.mysql script supplied as part of Kea:
- mysql> CONNECT database-name;
-mysql> SOURCE path-to-kea/share/kea/dhcpdb_create.mysql
-
-
- 4. Create the user under which Kea will access the database (and give it a password), then grant it access to the database tables:
- mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password';
-mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost';
-
-
- 5. Exit MySQL:
- mysql> quit
-Bye
-$
-
-
+
+
+ Upgrading a MySQL Database from an Earlier Version of Kea
+
+
+ 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 kea-admin lease-upgrade
+ command.
+
+
+
+ To check the current version of the database, use the following command:
+
+$ kea-admin lease-version mysql -u database-user -p database-password -d database-name
+
+ (See 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.
+
+
+
+ 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:
+
+$ kea-admin lease-upgrade mysql -u database-user -p database-password -d database-name
+
+
+
PostgreSQL
- 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.
-
- Initialize the PostgreSQL Database using kea-admin
-
-
- Support for PostgreSQL in kea-admin is currently not implemented.
-
-
-
-
-
-
- Create PostgreSQL Database and Kea User
+ Manually Create the PostgreSQL Database and the Kea User
+
- 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:
-
-
- 1. Log into PostgreSQL as "root":
- $ sudo -u postgres psql postgres
-Enter password:
- :
-postgres=#
-
-
- 2. Create the database:
+ 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:
+
+
+
+
+ Log into PostgreSQL as "root":
+
+$ sudo -u postgres psql postgres
+Enter password:
+postgres=#
+
+
+
+
+
+
+ Create the database:
postgres=# CREATE DATABASE database-name;
CREATE DATABASE
postgres=#
- (database-name is the name you
- have chosen for the database.)
-
-
- 3. Create the user under which Kea will access the database (and give it a password), then grant it access to the database:
-postgres=# CREATE USER user-name WITH PASSWORD 'password';
+ (database-name is the name
+ you have chosen for the database.)
+
+
+
+
+
+ Create the user under which Kea will access the database
+ (and give it a password), then grant it access to the
+ database:
+
+postgres=# CREATE USER user-name WITH PASSWORD 'password';
CREATE ROLE
postgres=#
postgres=# GRANT ALL PRIVILEGES ON DATABASE database-name TO user-name;
GRANT
postgres=#
-
-
- 4. Exit PostgreSQL:
- postgres=# \q
-Bye
-$
-
-
- 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:
-$ psql -d database-name -U user-name -f path-to-kea/share/kea/dhcpdb_create.pgsql
+
+
+
+
+
+ Exit PostgreSQL:
+
+postgres=# \q
+Bye
+$
+
+
+
+
+
+
+ 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:
+
+$ psql -d database-name -U user-name -f path-to-kea/share/kea/dhcpdb_create.pgsql
Password for user user-name:
CREATE TABLE
CREATE INDEX
@@ -292,36 +382,56 @@ INSERT 0 1
COMMIT
$
-
-
- If instead you encounter an error like:
-
+ (path-to-kea is the location
+ where you installed Kea.)
+
+
+
+ If instead you encounter an error like:
psql: FATAL: no pg_hba.conf entry for host "[local]", user "user-name", database "database-name", SSL off
-
- ... 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:
- /var/lib/pgsql/9.3/data/pg_hba.conf.
- 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:
-
+ ... 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:
+ /var/lib/pgsql/9.3/data/pg_hba.conf.
+
+
+
+ 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:
local database-name user-name password
host database-name user-name 127.0.0.1/32 password
host database-name user-name ::1/128 password
-
- Please consult your PostgreSQL user manual before making these changes as they
- may expose your other databases that you run on the same system.
-
+
+
+
+ Please consult your PostgreSQL user manual before making
+ these changes as they may expose your other databases
+ that you run on the same system.
+
+
+
+
-
+
+ Initialize the PostgreSQL Database Using kea-admin
-
+
+ Support for PostgreSQL in kea-admin is
+ currently not implemented.
+
+
+
+
+
+
+
diff --git a/doc/guide/install.xml b/doc/guide/install.xml
index e36f1584c7..8bc17fba37 100644
--- a/doc/guide/install.xml
+++ b/doc/guide/install.xml
@@ -478,7 +478,7 @@ Debian and Ubuntu:
See for details regarding
- MySQL database configuration.
+ PostgreSQL database configuration.