// Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC") // // Permission to use, copy, modify, and/or distribute this software for any // purpose with or without fee is hereby granted, provided that the above // copyright notice and this permission notice appear in all copies. // // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR // PERFORMANCE OF THIS SOFTWARE. /** @page dhcpDatabaseBackends DHCP Database Back-Ends All DHCP lease data is stored in some form of database, the interface to this being through the Lease Manager. All backend classes such as isc::dhcp::MySqlLeaseMgr are derived from the abstract isc::dhcp::LeaseMgr class. This provides methods to create, retrieve, modify and delete leases in the database. There are currently three available Lease Managers, Memfile, MySQL and PostgreSQL: - Memfile is an in-memory lease database which can be configured to persist its content to disk in a flat-file. Support for the Memfile database backend is built into Kea DHCP. - The MySQL lease manager uses the freely available MySQL as its backend database. This is not included in Kea DHCP by default: the \--with-dhcp-mysql switch must be supplied to "configure" for support to be compiled into the software. - The PostgreSQL lease manager uses the freely available PostgreSQL as its backend database. This is not included in Kea DHCP by default: the \--with-dhcp-pgsql switch must be supplied to "configure" for support to be compiled into the software. @section dhcpdb-instantiation Instantiation of Lease Managers A lease manager is instantiated through the LeaseMgrFactory class. This has three methods: - isc::dhcp::LeaseMgrFactory::create - Creates a singleton Lease Manager of the appropriate type. - isc::dhcp::LeaseMgrFactory::instance - Returns a reference to the the instance of the Lease Manager. - isc::dhcp::LeaseMgrFactory::destroy - Destroys the singleton lease manager. The selection of the Lease Manager (and thus the backend database) is controlled by the connection string passed to isc::dhcp::LeaseMgrFactory::create. This is a set of "keyword=value" pairs (no embedded spaces), each pair separated by a space from the others, e.g. \code type=mysql user=keatest password=keatest name=keatest host=localhost \endcode The following keywords are used for all backends: - type - specifies the type of database backend. The following values for the type keyword are supported: - memfile - In-memory database. Nothing is written to any external storage, so this should not be used in production. - mysql - Use MySQL as the database The following sections list the database-specific keywords: @subsection dhcpdb-keywords-mysql MySQL connection string keywords - host - host on which the selected database is running. If not supplied, "localhost" is assumed. - name - name of the MySQL database to access. There is no default - this must always be supplied. - password - password for the selected user ID (see below). If not specified, no password is used. - user - database user ID under which the database is accessed. If not specified, no user ID is used - the database is assumed to be open. @subsection dhcpdb-keywords-pgsql PostgreSQL connection string keywords - host - host on which the selected database is running. If not supplied, "localhost" is assumed. - name - name of the PostgreSQL database to access. There is no default - this must always be supplied. - password - password for the selected user ID (see below). If not specified, no password is used. - user - database user ID under which the database is accessed. If not specified, no user ID is used - the database is assumed to be open. @section dhcp-backend-unittest Running Unit Tests With the use of databases requiring separate authorisation, there are certain database-specific pre-requisites for successfully running the unit tests. These are listed in the following sections. @subsection dhcp-mysql-unittest MySQL Unit Tests A database called keatest must be created. A database user, also called keatest (and with a password keatest) must also be created and be given full privileges in that database. The unit tests create the schema in the database before each test and delete it afterwards. In detail, the steps to create the database and user are: -# Log into MySQL as root: @verbatim % mysql -u root -p Enter password: : mysql>@endverbatim\n -# Create the test database. This must be called "keatest": @verbatim mysql> CREATE DATABASE keatest; mysql>@endverbatim\n -# Create the user under which the test client will connect to the database (the apostrophes around the words keatest and localhost are required): @verbatim mysql> CREATE USER 'keatest'@'localhost' IDENTIFIED BY 'keatest'; mysql>@endverbatim\n -# Grant the created user permissions to access the keatest database (again, the apostrophes around the words keatest and localhost are required): @verbatim mysql> GRANT ALL ON keatest.* TO 'keatest'@'localhost'; mysql>@endverbatim\n -# Exit MySQL: @verbatim mysql> quit Bye %@endverbatim The unit tests are run automatically when "make check" is executed (providing that Kea has been build with the \--with-dhcp-mysql switch (see the installation section in the Kea Administrator Reference Manual). @subsection dhcp-pgsql-unittest PostgreSQL Unit Tests Conceptually, the steps required to run PostgreSQL unit-tests are the same as in MySQL. First, a database called keatest must be created. A database user, also called keatest (that will be allowed to log in using password keatest) must be created and given full privileges in that database. The unit tests create the schema in the database before each test and delete it afterwards. PostgreSQL set up differs from system to system. Please consult your OS-specific PostgreSQL documentation. The remainder of that section uses Ubuntu 13.10 x64 as example. On Ubuntu, after installing PostgreSQL (with sudo apt-get install postgresql), it is installed as user postgres. To create new databases or add new users, initial commands must be issued as user postgres: @verbatim $ sudo -u postgres psql postgres [sudo] password for thomson: psql (9.1.12) Type "help" for help. postgres=# CREATE USER keatest WITH PASSWORD 'keatest'; CREATE ROLE postgres=# CREATE DATABASE keatest; CREATE DATABASE postgres=# GRANT ALL PRIVILEGES ON DATABASE keatest TO keatest; GRANT postgres=# \q @endverbatim Now we are back to our regular, unprivileged user. Try to log into the newly created database using keatest credentials: @verbatim $ psql -d keatest -U keatest Password for user keatest: psql (9.1.12) Type "help" for help. keatest=> @endverbatim If instead of seeing keatest=> prompt, your login will be refused with error code about failed peer or indent authentication, it means that PostgreSQL is configured to check unix username and reject login attepts if PostgreSQL names are different. To alter that, PostgreSQL configuration must be changed. Alternatively, you may set up your environment, so the tests would be run from unix account keatest. /etc/postgresql/9.1/main/pg_hba.conf config file had to betweaked. It may be in a different location in your system. The following lines: @verbatim local all all peer host all all 127.0.0.1/32 md5 host all all ::1/128 md5 @endverbatim were replaced with: @verbatim local all all password host all all 127.0.0.1/32 password host all all ::1/128 password @endverbatim Please consult your PostgreSQL user manual before applying those changes as those changes may expose your other databases that you run on the same system. In general case, it is a poor idea to run anything of value on a system that runs tests. Use caution! The unit tests are run automatically when "make check" is executed (providing that Kea has been build with the \--with-dhcp-pgsql switch (see the installation section in the Kea Administrator Reference Manual). */