Adding upstream version 2.4.1.upstream/2.4.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 217 insertions, 0 deletions

diff --git a/src/lib/dhcpsrv/database_backends.dox b/src/lib/dhcpsrv/database_backends.dox
new file mode 100644
index 0000000..0cc54f0
--- /dev/null
+++ b/src/lib/dhcpsrv/database_backends.dox
@@ -0,0 +1,217 @@
+// Copyright (C) 2012-2022 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+  @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-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-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 @c 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.
+     - <b>mysql</b> - Use MySQL as the database. Must be enabled at compilation
+       time.
+     - <b>postgresql</b> - Use PostgreSQL as the database. Must be enabled
+       at compilation time.
+
+  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.
+
+  For details, see @ref isc::db::MySqlConnection::openDatabase().
+
+  @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.
+
+  For details, see @ref isc::db::PgSqlConnection::openDatabase().
+
+  @subsection infinite-valid-lifetime Infinite Valid Lifetime
+
+  The @c isc::dhcp::Lease class uses cltt (client last transmission time)
+  and valid lifetime, backend lease uses expire and valid lifetime.
+  These quantities are bound by the equation:
+  @code
+        expire = cltt + valid_lifetime
+  @endcode
+
+  But when expire is a 32 bit date and valid lifetime is the infinity
+  special value (0xffffffff) this overflows so for MySQL and PostgreSQL
+  backends this becomes:
+  @code
+        expire = cltt + valid_lifetime if valid_lifetime != 0xffffffff
+        expire = cltt if valid_lifetime == 0xffffffff
+  @endcode
+
+  @section dhcpdb-host Host Backends
+
+  Host backends (known also as host data sources) are similar to lease
+  backends with a few differences:
+
+  - host backends are optional (so it is allowed to have none) because
+    the first source of host reservations is the server configuration,
+    others are alternate backends.
+
+  - there may be more than one host backend. In such a case for lookups
+    returning a collection all results are appended, for lookups returning
+    at most one entry the first found is returned. Add operation is submitted
+    to all alternate backends which can ignore it, add the entry or throw
+    if the new entry conflicts with an already existing one. Delete
+    operations are submitted in sequence to all alternate backends until
+    one finds the entry, deletes it and returns true.
+
+  - the first alternate backend can be a cache (host cache hook library
+    is a premium feature) which avoids to lookup slow databases.
+    For subnet ID and identifier negative caching is optionally supported.
+
+  - host backends which do not support host collection (as host cache
+    and RADIUS) must return an empty collection (so not contributing
+    to the final result) from all methods returning collections.
+    Of course the core code must not use these methods with these backends
+    but there are some callers outside the server core code, e.g. the
+    host commands hook library.
+
+  @subsection dhcpdb-caching Caching
+
+  Some of these considerations apply to lease backends too but only
+  the host caching was analyzed and implemented.
+
+  Caching divides into two parts, positive and negative caching, and
+  its support is implemented at two places, a cache backend and inside
+  the host manager, i.e. the entity calling backends in sequence
+  providing the result of lookups to allocation engines.
+
+  The idea of positive caching is simple: when a value not in the
+  cache in returned by a database, this value is added to the cache
+  so the next time it will be available without calling and waiting
+  for the database.
+
+  This cannot be extended to lookups returning a collection because
+  they are supposed to collect and append results from all backends.
+  If you replace append by merge you avoid duplicate items in the
+  result but still get no benefit from caching. So in general a cache
+  backend should simply return nothing for these lookups.
+
+  Add (or any operation which can fail) has to wait that all backends
+  are called and possibly one fails before the new entry being cached.
+  Del is simpler: the cache backend processes it but always returns
+  false so the backend holding it if any is called.
+
+  Negative caching consists into adding fake entries indicating that
+  a particular host does not exists. As no host constructor allows
+  a host object without an identifier or with an empty identifier,
+  negative caching applies only to by identifier lookups. This is
+  no a problem because out-of-pools provides a clearer and simpler
+  to implement performance benefit than by address negative caching.
+  Note that by identifier negative caching can be critical for
+  performance because the non-existence is the worst case for lookups.
+
+  Negative cache entries should be easily identified (current
+  implementation uses the negative_ flag member in @c host class)
+  so all lookups returning at most one entry can (in fact have to)
+  return a null pointer when they get a negative cache entry.
+  Note this is for all such lookups, not only by identifier lookups,
+  to allow to negative cached entries with any value, for instance
+  with a IP address.
+
+  There is no direct and simple way to support negative caching
+  for collection lookups so again cache backends should return nothing
+  for these lookups which have not to filter out negative cached entries
+  from result.
+
+  Negative caching can be performed by the host manager: when a by
+  identifier lookup returns a null pointer, a fake entry with lookup
+  parameters and the negative cache mark is inserted into the cache.
+  Note this leads to negative cache entries without IP reservations,
+  this property should not be used because it limits negative cache
+  addition to only be performed by the host manager.
+
+@section dhcpDatabaseBackendsMTConsiderations Multi-Threading Consideration for DHCP Database Backends
+
+Lease and host database backends including the memfile for leases are Kea
+thread safe (i.e. are thread safe when the multi-threading mode is true).
+This extends to legal / forensic log backends but not to config
+backends which is used only for configuration by the main thread with
+packet processing threads stopped so has no thread safety
+requirements.
+
+There are exceptions:
+
+ - memfile constructor (including loading of leases from files) is not
+  thread safe.
+
+ - lfc handling in memfile is not thread safe: instead it is required
+  to be called from the main thread.
+
+ - wipe lease methods are either not thread safe or not implemented.
+
+Note for statistics queries it does not make sense to call them with
+running packet processing threads so they have no thread safety guarantees.
+
+Note too that the memfile backend is not inter-process safe so must be kept
+private to the Kea server using it.
+
+  */