From: Tomek Mrugalski Date: Wed, 14 Jan 2015 14:41:36 +0000 (+0100) Subject: [3644] kea-admin is now documented in the User's Guide. X-Git-Tag: trac3712_base~36^2~2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=97a03ea1c490913ac18f449d2e224b6ed7c424fd;p=thirdparty%2Fkea.git [3644] kea-admin is now documented in the User's Guide. --- diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index 67be2065c2..6878535845 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -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 diff --git a/doc/guide/admin.xml b/doc/guide/admin.xml new file mode 100644 index 0000000000..fd0f46f757 --- /dev/null +++ b/doc/guide/admin.xml @@ -0,0 +1,327 @@ + + +]> + + + Database administration + +
+ kea-admin tool + + + 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 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. + + + + 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: + + + + + + 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 lease database version. This is not necessarily + equal to Kea version as each backend has its own versioning + scheme. + + + + + + lease-upgrade — + Conducts lease database upgrade. This is useful when + migrating between old and new Kea versions. + + + + + + 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). + + +
+ +
+ 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. + + + + + +
+ +
+ 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. + + +
+ 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. + + + + 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 . + + + + 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 + + + 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 + + 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 + + + +
+ +
+ Manually create the MySQL Database and the Kea User + + + + 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: + + + 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 +$ + +
+ +
+ +
+ 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. + + +
+ Initialize the PostgreSQL Database using kea-admin + + + Support for PostgreSQL in kea-admin is currently not implemented. + + + +
+ + +
+ Create PostgreSQL Database and 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: + +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'; +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 +Password for user user-name: +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 +$ + + + + 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: + + +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. + +
+ +
+ + diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index dee22e5b6b..51ae8811ba 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -302,8 +302,8 @@ url="http://jsonviewer.stack.hu/"/>. "Dhcp4": { "lease-database": { "type": "mysql", ... }, ... } 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 - or ). + name used when the lease database was created (see + or ). "Dhcp4": { "lease-database": { "name": "database-name" , ... }, ... } diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index be3097613b..75a5619657 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -306,8 +306,8 @@ JSON validator is available at . "Dhcp6": { "lease-database": { "type": "mysql", ... }, ... } 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 - or ). + name used when the lease database was created (see + or ). "Dhcp6": { "lease-database": { "name": "database-name" , ... }, ... } diff --git a/doc/guide/install.xml b/doc/guide/install.xml index 80038e6f57..e36f1584c7 100644 --- a/doc/guide/install.xml +++ b/doc/guide/install.xml @@ -454,44 +454,11 @@ Debian and Ubuntu: "mysql_config" if MySQL was not installed in the default location: ./configure [other-options] --with-dhcp-mysql=path-to-mysql_config - -
- Create the MySQL 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 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 + See for details regarding + MySQL database configuration. - - 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 -$ - -
- +
Building with PostgreSQL support @@ -509,98 +476,10 @@ $ the default location: ./configure [other-options] --with-dhcp-pgsql=path-to-pg_config -
-
- Create PostgreSQL Database and 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: - -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'; -CREATE ROLE -postgres=# -postgres=# GRANT ALL PRIVILEGES ON DATABASE database-name TO user-name; -GRANT -postgres=# - + See for details regarding + MySQL database configuration. - - 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 -Password for user user-name: -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 -$ - - - - 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: - - -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. -
diff --git a/doc/guide/intro.xml b/doc/guide/intro.xml index cfde8b6ba6..c5a17d7e47 100644 --- a/doc/guide/intro.xml +++ b/doc/guide/intro.xml @@ -138,6 +138,14 @@ + + + kea-admin — + A tool useful for database backend maintenance (creating new + database, checking versions, upgrading etc.) + + + perfdhcp — diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index cdfa86e12f..76545aff73 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -57,6 +57,8 @@ + +