From 5d1bc8d88df2c411460f78fd9f93b36b984ff3f7 Mon Sep 17 00:00:00 2001 From: Stephen Morris Date: Mon, 26 Jan 2015 13:45:22 +0000 Subject: [PATCH] [3644] Review and edit of kea-admin part of the guide The edit also included a reorganisation of the sections. --- doc/guide/admin.xml | 576 +++++++++++++++++++++++++----------------- doc/guide/install.xml | 2 +- 2 files changed, 344 insertions(+), 234 deletions(-) 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.