From 433bf38a0f7fa16f33209b15b574ec23ec005643 Mon Sep 17 00:00:00 2001 From: Tomek Mrugalski Date: Wed, 11 Jun 2014 14:03:16 +0200 Subject: [PATCH] [3418] Installation and Configuration moved to separate files. --- doc/guide/Makefile.am | 2 +- doc/guide/config.xml | 103 ++++++ doc/guide/install.xml | 588 ++++++++++++++++++++++++++++++++++ doc/guide/kea-guide.xml | 682 +--------------------------------------- 4 files changed, 696 insertions(+), 679 deletions(-) create mode 100644 doc/guide/config.xml create mode 100644 doc/guide/install.xml diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index b8f271448e..840f88ab9b 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 logging.xml +DOCBOOK = kea-guide.xml logging.xml config.xml install.xml EXTRA_DIST = $(DOCBOOK) DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml diff --git a/doc/guide/config.xml b/doc/guide/config.xml new file mode 100644 index 0000000000..e354c2cda5 --- /dev/null +++ b/doc/guide/config.xml @@ -0,0 +1,103 @@ + + +]> + + Kea configuration + + Depending on configuration backend chosen (see ), configuration mechanisms are + different. The following sections describe details of specific configuration + backends. Note that only one configuration backend can be used and its + selection is determined during compilation time. + +
+ Bundy configuration backend + This legacy configuration backend allows Kea to use former BIND10 + framework. That framework and this Kea configuration backend is no longer + supported by ISC. It is currently developed as part of Bundy project (see + Bundy homepage). See Bundy + project documentation regarding configuration. +
+ +
+ JSON configuration backend + JSON is the default configuration backend and the only one supported + as of 0.9 release. It assumes that the servers are started from command + line (either directly or using a script, see TODO for details). JSON + backend uses certain signals to influence certain behaviors. The + configuration file is specified upon startup using -c parameter. + +
+ JSON syntax + Configuration files for DHCPv4, DHCPv6 and DDNS modules are + defined in extended JSON format. The basic JSON is defined in RFC 4627. Kea + components use extended JSON, which extends basic format by allowing + bash-style comments in the file. Comment lines must have hash (#) in the + first column. + + Configuration file consists of a single object (often colloquially + called a map) started with a curly bracket. It consists "Dhcp4", + "Dhcp6", "DhcpDdns" and/or "Logging" objects. It is possible to define + additional elements, but they will be ignored. That principle was chosen + to ease configuration management. For example, it is possible to define + Dhcp4, Dhcp6 and Logging elements in one configuration file that can be + used to start both DHCPv4 and DHCPv6 components. When starting, DHCPv4 + component will use Dhcp4 object to configure itself and Logging to + configure logging parameters, while ignoring Dhcp6 object. + + For example, a very simple configuration for Dhcp6 could look + like this: + +{ + +# DHCPv6 specific configuration starts here. +"Dhcp6": { + +# These are DHCPv6-specific parameters. They will be explained in later sections. + "interfaces": [ "eth0" ], + + "preferred-lifetime": 3000, + "valid-lifetime": 4000, + "renew-timer": 1000, + "rebind-timer": 2000, + +# The following list defines subnets. Each subnet consists of at +# least subnet and pool entries. + "subnet6": [{ + "pool": [ "2001:db8:1::/80" ], + "subnet": "2001:db8:1::/64" + }] +}, +# DHCPv6 specific configuration ends here. + +# Logger parameters (that could be shared among several components) start here. +"Logging": { + +# These are Logger-specific parameters. They will be explained in later sections. + "loggers": [{ + "name": "*", + "severity": "DEBUG" + }] +} +# Logger parameters end here. + +} + + + + + More examples are available in the Kea source code in the + doc/examples directory. + + +
+ + + +
+ + + diff --git a/doc/guide/install.xml b/doc/guide/install.xml new file mode 100644 index 0000000000..217e1174d7 --- /dev/null +++ b/doc/guide/install.xml @@ -0,0 +1,588 @@ + + +]> + + + Installation + +
+ Packages + + + Some operating systems or software package vendors may provide + ready-to-use, pre-built software packages for Kea. Installing a + pre-built package means you do not need to install build-only + prerequisites and do not need to make the software. + + + + FreeBSD ports, NetBSD pkgsrc, and Debian testing + package collections provide all the prerequisite packages. + +
+ +
+ Install Hierarchy + + The following is the standard, common layout of the + complete Kea installation: + + + + bin/ — + general tools and diagnostic clients. + + + + + + etc/bind10/ — + configuration files. + + + + + lib/ — + libraries and python modules. + + + + + + libexec/bind10/ — + executables that a user wouldn't normally run directly and + are not run independently. + These are the BIND 10 and Kea modules which are daemons started by + the b10-init master process. + + + + + sbin/ — + commands used by the system administrator. + + + + + + share/bind10/ — + configuration specifications. + + + + + + share/doc/bind10/ — + this guide and other supplementary documentation. + + + + + share/man/ — + manual pages (online documentation). + + + + + + var/bind10/ — + data source and configuration databases. + + + + +
+ +
+ Building Requirements + + + In addition to the run-time requirements (listed in ), building Kea from source code requires + various development include headers and program development tools. + + + + + Some operating systems have split their distribution packages into + a run-time and a development package. You will need to install + the development package versions, which include header files and + libraries, to build Kea from source code. + + + + + Building from source code requires the Boost + build-time headers + (). + At least Boost version 1.35 is required. + + + + + + To build Kea, also install the Botan (at least version + 1.8) and the log4cplus (at least version 1.0.3) + development include headers. + + + + + + + + + Building Kea also requires a C++ compiler and + standard development headers, make, and pkg-config. + Kea builds have been tested with GCC g++ 3.4.3, 4.1.2, + 4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10. + + + + + Visit the user-contributed wiki at + for system-specific installation tips. + + +
+ +
+ Installation from source + + Kea is open source software written in C++ (some components of the + BIND 10 framework are written in Python). + It is freely available in source code form from ISC as a + downloadable tar file or via Kea Git code revision control + service. (It may also be available in pre-compiled ready-to-use + packages from operating system vendors.) + + +
+ + Download Tar File + + Kea 0.8 is available as a part of BIND10 1.2 release, which is a final + release of BIND10 from ISC. This release can be downloaded from: + . Upcoming Kea 0.9 and all + following releases will be shipped as a stand-alone tarball. + +
+ +
+ Retrieve from Git + + Downloading this "bleeding edge" code is recommended only for + developers or advanced users. Using development code in a production + environment is not recommended. + + + + + When using source code retrieved via Git, additional + software will be required: automake (v1.11 or newer), + libtoolize, and autoconf (2.59 or newer). + These may need to be installed. + + + + + The latest development code (and temporary experiments + and un-reviewed code) is available via the Kea code revision + control system. This is powered by Git and all the Kea + development is public. + The leading development is done in the master + branch. + + + The code can be checked out from + git://git.kea.isc.org/kea; + for example: + + $ git clone git://git.kea.isc.org/kea + + + + When checking out the code from + the code version control system, it doesn't include the + generated configure script, Makefile.in files, nor their + related build files. + They can be created by running autoreconf + with the switch. + This will run autoconf, + aclocal, + libtoolize, + autoheader, + automake, + and related commands. + + +
+ + +
+ Configure before the build + + Kea uses the GNU Build System to discover build environment + details. + To generate the makefiles using the defaults, simply run: + $ ./configure + + + Run ./configure with the + switch to view the different options. Some commonly-used options are: + + + + + --prefix + + Define the installation location (the + default is /usr/local/). + + + + + + --with-boost-include + + Define the path to find the Boost headers. + + + + + + --with-pythonpath + + Define the path to Python 3.x if it is not in the + standard execution path. Python 3.x is mandatory for Kea 0.8, + but is no longer required for upcoming Kea 0.9. + + + + + + --with-gtest + + Enable building the C++ Unit Tests using the + Google Tests framework. Optionally this can define the + path to the gtest header files and library. + + + + + + --without-werror + + Disable the default use of the + compiler flag so that + compiler warnings aren't build failures. + + + + + + + + For additional instructions concerning the building and installation of + Kea for various databases, see . + For additional instructions concerning configuration backends, see + . + + + + + + + For example, the following configures it to + find the Boost headers, find the + Python interpreter, and sets the installation location: + + $ ./configure \ + --with-boost-include=/usr/pkg/include \ + --with-dhcp-pgsql=/usr/local/bin/pg_config \ + --prefix=/opt/kea + + + + If the configure fails, it may be due to missing or old + dependencies. + + + +
+ +
+ Build + + After the configure step is complete, to build the executables + from the C++ code and prepare the Python scripts, run: + + $ make + +
+ +
+ Install + + To install the Kea executables, support files, + and documentation, run: + $ make install + + + Please don't use any form of parallel or job server options + (such as GNU make's -j option) when + performing this step. Doing so may cause errors. + + + The install step may require superuser privileges. + + + If required, run ldconfig as root with + /usr/local/lib (or with ${prefix}/lib if + configured with --prefix) in + /etc/ld.so.conf (or the relevant linker + cache configuration file for your OS): + $ ldconfig + + + + If you do not run ldconfig where it is + required, you may see errors like the following: + + program: error while loading shared libraries: libkea-something.so.1: + cannot open shared object file: No such file or directory + + + +
+ + + +
+ +
+ Selecting configuration backend + Kea 0.9 introduces configuration backends that are switchable during + compilation phase. There is a new parameter for configure script: + --with-kea-config. It currently supports two values: BIND10 and + JSON. This is currently only supported by DHCPv6 component. + + + + + BIND10 + + BIND10 (which is the default value as of April 2014) means + that Kea6 is linked with the BIND10 configuration backend that + connects to the BIND10 framework and in general works exactly the + same as Kea 0.8 and earlier versions. The benefits of that backend + are uniform integration with BIND10 framework, easy on-line + reconfiguration using bindctl, available RESTful API. On the other + hand, it requires the whole heavy BIND10 framework that requires + Python3 to be present. That backend is likely to go away with the + release of Kea 0.9. + + + + + JSON + + JSON is a new configuration backend that causes Kea to read + JSON configuration file from disk. It does not require any framework + and thus is considered more lightweight. It will allow dynamic + on-line reconfiguration, but will lack remote capabilities (i.e. no + RESTful API). This configuration backend is expected to be the + default for upcoming Kea 0.9. + + + + +
+ +
+ DHCP Database Installation and Configuration + + Kea stores its leases in a lease database. The software has been written in + a way that makes it possible to choose which database product should be used to + store the lease information. At present, Kea supports 3 database backends: MySQL, + PostgreSQL and Memfile. To limit external dependencies, both MySQL and PostgreSQL + support are disabled by default and only Memfile (which is implemented in pure C++) + is available. Support for a given database backend must be explicitly included when + Kea is built. This section covers the building of Kea with MySQL and/or PostgreSQL + and the creation of the lease database. + +
+ Building with MySQL support + + Install MySQL according to the instructions for your system. The client development + libraries must be installed. + + + Build and install Kea as described in , with + the following modification: to enable the MySQL database code, at the + "configure" step (see ), specify the location of the + MySQL configuration program "mysql_config" with the "--with-dhcp-mysql" switch, + i.e. + ./configure [other-options] --with-dhcp-mysql + ...if MySQL was installed in the default location, or: + ./configure [other-options] --with-dhcp-mysql=path-to-mysql_config + ...if not. + +
+
+ Create MySQL 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 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: + mysql> CONNECT database-name; +mysql> SOURCE path-to-bind10/share/bind10/dhcpdb_create.mysql + + + 4. Create the user under which BIND 10 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 + + Install PostgreSQL according to the instructions for your system. The client development + libraries must be installed. Client development libraries are often packaged as "libpq". + + + Build and install Kea as described in , with + the following modification: to enable the PostgreSQL database code, at the + "configure" step (see ), specify the location of the + PostgreSQL configuration program "pg_config" with the "--with-dhcp-pgsql" switch, + i.e. + ./configure [other-options] --with-dhcp-pgsql + ...if PostgreSQL was installed in the default location, or: + ./configure [other-options] --with-dhcp-pgsql=path-to-pg_config + ...if not. + +
+
+ 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. + 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-bind10/share/bind10/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 such as shown below: + + +psql: FATAL: no pg_hba.conf entry for host "[local]", user "user-name", database "database-name", SSL off + + + This indicates that the PostgreSQL configuration needs to be modified. + 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/kea-guide.xml b/doc/guide/kea-guide.xml index 8d96080109..cabb9d569f 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -385,7 +385,7 @@ $ ./configure [your extra parameters] Edit your configuration file for DHCPv4. See doc/examples/kea4 - for set of examples. + for a set of examples. @@ -406,7 +406,7 @@ $ ./configure [your extra parameters] Edit your configuration file for DHCPv6. See doc/examples/kea6 - for set of examples. + for a set of examples. @@ -432,683 +432,9 @@ $ ./configure [your extra parameters] - - Installation - -
- Packages - - - Some operating systems or software package vendors may provide - ready-to-use, pre-built software packages for Kea. Installing a - pre-built package means you do not need to install build-only - prerequisites and do not need to make the software. - - - - FreeBSD ports, NetBSD pkgsrc, and Debian testing - package collections provide all the prerequisite packages. - -
- -
- Install Hierarchy - - The following is the standard, common layout of the - complete Kea installation: - - - - bin/ — - general tools and diagnostic clients. - - - - - - etc/bind10/ — - configuration files. - - - - - lib/ — - libraries and python modules. - - - - - - libexec/bind10/ — - executables that a user wouldn't normally run directly and - are not run independently. - These are the BIND 10 and Kea modules which are daemons started by - the b10-init master process. - - - - - sbin/ — - commands used by the system administrator. - - - - - - share/bind10/ — - configuration specifications. - - - - - - share/doc/bind10/ — - this guide and other supplementary documentation. - - - - - share/man/ — - manual pages (online documentation). - - - - - - var/bind10/ — - data source and configuration databases. - - - - -
- -
- Building Requirements - - - In addition to the run-time requirements (listed in ), building Kea from source code requires - various development include headers and program development tools. - - - - - Some operating systems have split their distribution packages into - a run-time and a development package. You will need to install - the development package versions, which include header files and - libraries, to build Kea from source code. - - - - - Building from source code requires the Boost - build-time headers - (). - At least Boost version 1.35 is required. - - - - - - To build Kea, also install the Botan (at least version - 1.8) and the log4cplus (at least version 1.0.3) - development include headers. - - - - - - - - - Building Kea also requires a C++ compiler and - standard development headers, make, and pkg-config. - Kea builds have been tested with GCC g++ 3.4.3, 4.1.2, - 4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10. - - - - - Visit the user-contributed wiki at - for system-specific installation tips. - - -
- -
- Installation from source - - Kea is open source software written in C++ (some components of the - BIND 10 framework are written in Python). - It is freely available in source code form from ISC as a - downloadable tar file or via Kea Git code revision control - service. (It may also be available in pre-compiled ready-to-use - packages from operating system vendors.) - - -
- - Download Tar File - - Kea 0.8 is available as a part of BIND10 1.2 release, which is a final - release of BIND10 from ISC. This release can be downloaded from: - . Upcoming Kea 0.9 and all - following releases will be shipped as a stand-alone tarball. - -
- -
- Retrieve from Git - - Downloading this "bleeding edge" code is recommended only for - developers or advanced users. Using development code in a production - environment is not recommended. - - - - - When using source code retrieved via Git, additional - software will be required: automake (v1.11 or newer), - libtoolize, and autoconf (2.59 or newer). - These may need to be installed. - - - - - The latest development code (and temporary experiments - and un-reviewed code) is available via the Kea code revision - control system. This is powered by Git and all the Kea - development is public. - The leading development is done in the master - branch. - - - The code can be checked out from - git://git.kea.isc.org/kea; - for example: - - $ git clone git://git.kea.isc.org/kea - - - - When checking out the code from - the code version control system, it doesn't include the - generated configure script, Makefile.in files, nor their - related build files. - They can be created by running autoreconf - with the switch. - This will run autoconf, - aclocal, - libtoolize, - autoheader, - automake, - and related commands. - - -
- - -
- Configure before the build - - Kea uses the GNU Build System to discover build environment - details. - To generate the makefiles using the defaults, simply run: - $ ./configure - - - Run ./configure with the - switch to view the different options. Some commonly-used options are: - - - - - --prefix - - Define the installation location (the - default is /usr/local/). - - - - - - --with-boost-include - - Define the path to find the Boost headers. - - - - - - --with-pythonpath - - Define the path to Python 3.x if it is not in the - standard execution path. Python 3.x is mandatory for Kea 0.8, - but is no longer required for upcoming Kea 0.9. - - - - - - --with-gtest - - Enable building the C++ Unit Tests using the - Google Tests framework. Optionally this can define the - path to the gtest header files and library. - - - - - - --without-werror - - Disable the default use of the - compiler flag so that - compiler warnings aren't build failures. - - - - - - - - For additional instructions concerning the building and installation of - Kea for various databases, see . - For additional instructions concerning configuration backends, see - . - - - - - - - For example, the following configures it to - find the Boost headers, find the - Python interpreter, and sets the installation location: - - $ ./configure \ - --with-boost-include=/usr/pkg/include \ - --with-dhcp-pgsql=/usr/local/bin/pg_config \ - --prefix=/opt/kea - - - - If the configure fails, it may be due to missing or old - dependencies. - - - -
- -
- Build - - After the configure step is complete, to build the executables - from the C++ code and prepare the Python scripts, run: - - $ make - -
- -
- Install - - To install the Kea executables, support files, - and documentation, run: - $ make install - - - Please don't use any form of parallel or job server options - (such as GNU make's -j option) when - performing this step. Doing so may cause errors. - - - The install step may require superuser privileges. - - - If required, run ldconfig as root with - /usr/local/lib (or with ${prefix}/lib if - configured with --prefix) in - /etc/ld.so.conf (or the relevant linker - cache configuration file for your OS): - $ ldconfig - - - - If you do not run ldconfig where it is - required, you may see errors like the following: - - program: error while loading shared libraries: libkea-something.so.1: - cannot open shared object file: No such file or directory - - - -
- - - -
- -
- Selecting configuration backend - Kea 0.9 introduces configuration backends that are switchable during - compilation phase. There is a new parameter for configure script: - --with-kea-config. It currently supports two values: BIND10 and - JSON. This is currently only supported by DHCPv6 component. - - - - - BIND10 - - BIND10 (which is the default value as of April 2014) means - that Kea6 is linked with the BIND10 configuration backend that - connects to the BIND10 framework and in general works exactly the - same as Kea 0.8 and earlier versions. The benefits of that backend - are uniform integration with BIND10 framework, easy on-line - reconfiguration using bindctl, available RESTful API. On the other - hand, it requires the whole heavy BIND10 framework that requires - Python3 to be present. That backend is likely to go away with the - release of Kea 0.9. - - - - - JSON - - JSON is a new configuration backend that causes Kea to read - JSON configuration file from disk. It does not require any framework - and thus is considered more lightweight. It will allow dynamic - on-line reconfiguration, but will lack remote capabilities (i.e. no - RESTful API). This configuration backend is expected to be the - default for upcoming Kea 0.9. - - - - -
- -
- DHCP Database Installation and Configuration - - Kea stores its leases in a lease database. The software has been written in - a way that makes it possible to choose which database product should be used to - store the lease information. At present, Kea supports 3 database backends: MySQL, - PostgreSQL and Memfile. To limit external dependencies, both MySQL and PostgreSQL - support are disabled by default and only Memfile (which is implemented in pure C++) - is available. Support for a given database backend must be explicitly included when - Kea is built. This section covers the building of Kea with MySQL and/or PostgreSQL - and the creation of the lease database. - -
- Building with MySQL support - - Install MySQL according to the instructions for your system. The client development - libraries must be installed. - - - Build and install Kea as described in , with - the following modification: to enable the MySQL database code, at the - "configure" step (see ), specify the location of the - MySQL configuration program "mysql_config" with the "--with-dhcp-mysql" switch, - i.e. - ./configure [other-options] --with-dhcp-mysql - ...if MySQL was installed in the default location, or: - ./configure [other-options] --with-dhcp-mysql=path-to-mysql_config - ...if not. - -
-
- Create MySQL 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 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: - mysql> CONNECT database-name; -mysql> SOURCE path-to-bind10/share/bind10/dhcpdb_create.mysql - - - 4. Create the user under which BIND 10 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 - - Install PostgreSQL according to the instructions for your system. The client development - libraries must be installed. Client development libraries are often packaged as "libpq". - - - Build and install Kea as described in , with - the following modification: to enable the PostgreSQL database code, at the - "configure" step (see ), specify the location of the - PostgreSQL configuration program "pg_config" with the "--with-dhcp-pgsql" switch, - i.e. - ./configure [other-options] --with-dhcp-pgsql - ...if PostgreSQL was installed in the default location, or: - ./configure [other-options] --with-dhcp-pgsql=path-to-pg_config - ...if not. - -
-
- 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. - 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-bind10/share/bind10/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 such as shown below: - - -psql: FATAL: no pg_hba.conf entry for host "[local]", user "user-name", database "database-name", SSL off - - - This indicates that the PostgreSQL configuration needs to be modified. - 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. - -
-
- - - - - Kea configuration - - Depending on configuration backend chosen (see ), configuration mechanisms are - different. The following sections describe details of specific configuration - backends. Note that only one configuration backend can be used and its - selection is determined during compilation time. - -
- Bundy configuration backend - This legacy configuration backend allows Kea to use former BIND10 - framework. That framework and this Kea configuration backend is no longer - supported by ISC. It is currently developed as part of Bundy project (see - Bundy homepage). See Bundy - project documentation regarding configuration. -
- -
- JSON configuration backend - JSON is the default configuration backend and the only one supported - as of 0.9 release. It assumes that the servers are started from command - line (either directly or using a script, see TODO for details). JSON - backend uses certain signals to influence certain behaviors. The - configuration file is specified upon startup using -c parameter. - -
- JSON syntax - Configuration files for DHCPv4, DHCPv6 and DDNS modules are - defined in extended JSON format. The basic JSON is defined in RFC 4627. Kea - components use extended JSON, which extends basic format by allowing - bash-style comments in the file. Comment lines must have hash (#) in the - first column. - - Configuration file consists of a single object (often colloquially - called a map) started with a curly bracket. It consists "Dhcp4", - "Dhcp6", "DhcpDdns" and/or "Logging" objects. It is possible to define - additional elements, but they will be ignored. That principle was chosen - to ease configuration management. For example, it is possible to define - Dhcp4, Dhcp6 and Logging elements in one configuration file that can be - used to start both DHCPv4 and DHCPv6 components. When starting, DHCPv4 - component will use Dhcp4 object to configure itself and Logging to - configure logging parameters, while ignoring Dhcp6 object. - - For example, a very simple configuration for Dhcp6 could look - like this: - -{ - -# DHCPv6 specific configuration starts here. -"Dhcp6": { - -# These are DHCPv6-specific parameters. They will be explained in later sections. - "interfaces": [ "eth0" ], - - "preferred-lifetime": 3000, - "valid-lifetime": 4000, - "renew-timer": 1000, - "rebind-timer": 2000, - -# The following list defines subnets. Each subnet consists of at -# least subnet and pool entries. - "subnet6": [{ - "pool": [ "2001:db8:1::/80" ], - "subnet": "2001:db8:1::/64" - }] -}, -# DHCPv6 specific configuration ends here. - -# Logger parameters (that could be shared among several components) start here. -"Logging": { - -# These are Logger-specific parameters. They will be explained in later sections. - "loggers": [{ - "name": "*", - "severity": "DEBUG" - }] -} -# Logger parameters end here. - -} - - - -
- - - -
- - - + + The DHCPv4 Server