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 two available Lease Managers, MySQL and Memfile:

  - The MySQL lease manager uses the freely available MySQL as its backend
  database.  This is not included in BIND 10 DHCP by default:
  the --with-dhcp-mysql switch must be supplied to "configure" for support
  to be compiled into the software.
  - Memfile is an in-memory lease database, with (currently) nothing being
  written to persistent storage.  The long-term plans for the backend do
  include the ability to store this on disk, but it is currently a
  low-priority item.

  @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.


  @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

  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>).
  */