kea/src/lib/dhcpsrv/database_backends.dox

// 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:

  - <b>type</b> - specifies the type of database backend.  The following values
  for the type keyword are supported:
     - <B>memfile</b> - In-memory database.  Nothing is written to any
       external storage, so this should not be used in production.
     - <b>mysql</b> - Use MySQL as the database

  The following sections list the database-specific keywords:

  @subsection dhcpdb-keywords-mysql MySQL connection string keywords

  - <b>host</b> - host on which the selected database is running.  If not
  supplied, "localhost" is assumed.
  - <b>name</b> - name of the MySQL database to access.  There is no default -
  this must always be supplied.
  - <b>password</b> - password for the selected user ID (see below).  If not
  specified, no password is used.
  - <b>user</b> - 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

  - <b>host</b> - host on which the selected database is running.  If not
  supplied, "localhost" is assumed.
  - <b>name</b> - name of the PostgreSQL database to access.  There is no
  default - this must always be supplied.
  - <b>password</b> - password for the selected user ID (see below).  If not
  specified, no password is used.
  - <b>user</b> - 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 <i>keatest</i> must be created. A database user, also called
  <i>keatest</i> (and with a password <i>keatest</i>) 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 <i>keatest</i> and <i>localhost</i> are
  required):
  @verbatim
  mysql> CREATE USER 'keatest'@'localhost' IDENTIFIED BY 'keatest';
  mysql>@endverbatim\n
  -# Grant the created user permissions to access the <i>keatest</i> database
  (again, the apostrophes around the words <i>keatest</i> and <i>localhost</i>
  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 BIND 10 has been build with the \--with-dhcp-mysql switch (see the installation
  section in the <a href="http://bind10.isc.org/docs/bind10-guide.html">BIND 10 Guide</a>).

 @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 <i>keatest</i> must be created. A database
  user, also called <i>keatest</i> (that will be allowed to log in using password
  <i>keatest</i>) 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 <tt>sudo apt-get install
  postgresql</tt>), it is installed as user <i>postgres</i>. 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. <tt>/etc/postgresql/9.1/main/pg_hba.conf</tt> 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 BIND 10 has been build with the \--with-dhcp-pgsql switch (see the installation
  section in the <a href="http://bind10.isc.org/docs/bind10-guide.html">BIND10 Guide</a>).

  */