PostgreSQL Host Data Source. More...

#include <pgsql_host_data_source.h>

Inheritance diagram for isc::dhcp::PgSqlHostDataSource:

Public Member Functions
	PgSqlHostDataSource (const db::DatabaseConnection::ParameterMap &parameters)
	Constructor. More...

virtual	~PgSqlHostDataSource ()
	Virtual destructor. More...

virtual void	add (const HostPtr &host)
	Adds a new host to the collection. More...

virtual void	commit ()
	Commit Transactions. More...

virtual bool	del (const SubnetID &subnet_id, const asiolink::IOAddress &addr)
	Attempts to delete a host by (subnet-id, address) More...

virtual bool	del4 (const SubnetID &subnet_id, const Host::IdentifierType &identifier_type, const uint8_t *identifier_begin, const size_t identifier_len)
	Attempts to delete a host by (subnet4-id, identifier type, identifier) More...

virtual bool	del6 (const SubnetID &subnet_id, const Host::IdentifierType &identifier_type, const uint8_t *identifier_begin, const size_t identifier_len)
	Attempts to delete a host by (subnet6-id, identifier type, identifier) More...

virtual ConstHostPtr	get4 (const SubnetID &subnet_id, const Host::IdentifierType &identifier_type, const uint8_t *identifier_begin, const size_t identifier_len) const
	Returns a host connected to the IPv4 subnet. More...

virtual ConstHostPtr	get4 (const SubnetID &subnet_id, const asiolink::IOAddress &address) const
	Returns a host connected to the IPv4 subnet and having a reservation for a specified IPv4 address. More...

virtual ConstHostPtr	get6 (const SubnetID &subnet_id, const Host::IdentifierType &identifier_type, const uint8_t *identifier_begin, const size_t identifier_len) const
	Returns a host connected to the IPv6 subnet. More...

virtual ConstHostPtr	get6 (const asiolink::IOAddress &prefix, const uint8_t prefix_len) const
	Returns a host using the specified IPv6 prefix. More...

virtual ConstHostPtr	get6 (const SubnetID &subnet_id, const asiolink::IOAddress &address) const
	Returns a host connected to the IPv6 subnet and having a reservation for a specified IPv6 address or prefix. More...

virtual ConstHostCollection	getAll (const Host::IdentifierType &identifier_type, const uint8_t *identifier_begin, const size_t identifier_len) const
	Return all hosts connected to any subnet for which reservations have been made using a specified identifier. More...

virtual ConstHostCollection	getAll4 (const asiolink::IOAddress &address) const
	Returns a collection of hosts using the specified IPv4 address. More...

virtual std::string	getDescription () const
	Returns description of the backend. More...

virtual std::string	getName () const
	Returns the name of the open database. More...

virtual std::string	getType () const
	Return backend type. More...

virtual std::pair< uint32_t, uint32_t >	getVersion () const
	Returns backend version. More...

virtual void	rollback ()
	Rollback Transactions. More...

Public Member Functions inherited from isc::dhcp::BaseHostDataSource
virtual	~BaseHostDataSource ()
	Default destructor implementation. More...

Additional Inherited Members
Public Types inherited from isc::dhcp::BaseHostDataSource
enum	IdType { ID_HWADDR = 0, ID_DUID = 1 }
	Specifies the type of an identifier. More...

Detailed Description

PostgreSQL Host Data Source.

This class implements the isc::dhcp::BaseHostDataSource interface to the PostgreSQL database. Use of this backend presupposes that a PostgreSQL database is available and that the Kea schema has been created within it.

Reservations are uniquely identified by identifier type and value. The currently supported values are defined in Host::IdentifierType as well as in host_identifier_table:

IDENT_HWADDR
IDENT_DUID
IDENT_CIRCUIT_ID
IDENT_CLIENT_ID

Definition at line 35 of file pgsql_host_data_source.h.

Constructor & Destructor Documentation

◆ PgSqlHostDataSource()

isc::dhcp::PgSqlHostDataSource::PgSqlHostDataSource ( const db::DatabaseConnection::ParameterMap & parameters )

Constructor.

Uses the following keywords in the parameters passed to it to connect to the database:

name - Name of the database to which to connect (mandatory)
host - Host to which to connect (optional, defaults to "localhost")
user - Username under which to connect (optional)
password - Password for "user" on the database (optional)

If the database is successfully opened, the version number in the schema_version table will be checked against hard-coded value in the implementation file.

Finally, all the SQL commands are pre-compiled.

Parameters

parameters A data structure relating keywords and values concerned with the database.

Exceptions

isc::db::NoDatabaseName	Mandatory database name not given
isc::db::DbOpenError	Error opening the database
isc::db::DbOperationError	An operation on the open database has failed.

Definition at line 1964 of file pgsql_host_data_source.cc.

◆ ~PgSqlHostDataSource()

isc::dhcp::PgSqlHostDataSource::~PgSqlHostDataSource ( )

virtual

Virtual destructor.

Frees database resources and closes the database connection through the destruction of member impl_.

Definition at line 1968 of file pgsql_host_data_source.cc.

Member Function Documentation

◆ add()

void isc::dhcp::PgSqlHostDataSource::add ( const HostPtr & host )

virtual

Adds a new host to the collection.

The method will insert the given host and all of its children (v4 options, v6 options, and v6 reservations) into the database. It relies on constraints defined as part of the PostgreSQL schema to defend against duplicate entries and to ensure referential integrity.

Violation of any of these constraints for a host will result in a DuplicateEntry exception:

IPV4_ADDRESS and DHCP4_SUBNET_ID combination must be unique
IPV6 ADDRESS and PREFIX_LEN combination must be unique
DHCP ID, DHCP ID TYPE, and DHCP4_SUBNET_ID combination must be unique
DHCP ID, DHCP ID TYPE, and DHCP6_SUBNET_ID combination must be unique

In addition, violating the following referential constraints will a DbOperationError exception:

DHCP ID TYPE must be defined in the HOST_IDENTIFIER_TYPE table
For DHCP4 Options:
1. HOST_ID must exist with HOSTS
2. SCOPE_ID must be defined in DHCP_OPTION_SCOPE
For DHCP6 Options:
1. HOST_ID must exist with HOSTS
2. SCOPE_ID must be defined in DHCP_OPTION_SCOPE
For IPV6 Reservations:
1. HOST_ID must exist with HOSTS
2. Address and Prefix Length must be unique (DuplicateEntry)

Parameters

host	Pointer to the new `Host` object being added.

Exceptions

DuplicateEntry or DbOperationError dependent on the constraint violation

Implements isc::dhcp::BaseHostDataSource.

Definition at line 1973 of file pgsql_host_data_source.cc.

Here is the call graph for this function:

◆ commit()

void isc::dhcp::PgSqlHostDataSource::commit ( )

virtual

Commit Transactions.

Commits all pending database operations.

Reimplemented from isc::dhcp::BaseHostDataSource.

Definition at line 2247 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::checkReadOnly(), isc::db::PgSqlConnection::commit(), and isc::dhcp::PgSqlHostDataSourceImpl::conn_.

Here is the call graph for this function:

◆ del()

bool isc::dhcp::PgSqlHostDataSource::del	(	const SubnetID &	subnet_id,
		const asiolink::IOAddress &	addr
	)

virtual

Attempts to delete a host by (subnet-id, address)

This method supports both v4 and v6.

Parameters

subnet_id	subnet identifier.
addr	specified address.

Returns: true if deletion was successful, false if the host was not there.

Exceptions

various exceptions in case of errors

Implements isc::dhcp::BaseHostDataSource.

Definition at line 2018 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::checkReadOnly(), del6(), isc::dhcp::PgSqlHostDataSourceImpl::DEL_HOST_ADDR4, isc::dhcp::PgSqlHostDataSourceImpl::delStatement(), get6(), and isc::asiolink::IOAddress::isV4().

Here is the call graph for this function:

◆ del4()

bool isc::dhcp::PgSqlHostDataSource::del4	(	const SubnetID &	subnet_id,
		const Host::IdentifierType &	identifier_type,
		const uint8_t *	identifier_begin,
		const size_t	identifier_len
	)

virtual

Attempts to delete a host by (subnet4-id, identifier type, identifier)

This method supports v4 hosts only.

Parameters

subnet_id	subnet identifier.
identifier_type	Identifier type.
identifier_begin	Pointer to a beginning of a buffer containing an identifier.
identifier_len	Identifier length.

Returns: true if deletion was successful, false if the host was not there.

Exceptions

various exceptions in case of errors

Implements isc::dhcp::BaseHostDataSource.

Definition at line 2040 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::DEL_HOST_SUBID4_ID, and isc::dhcp::PgSqlHostDataSourceImpl::delStatement().

Here is the call graph for this function:

◆ del6()

bool isc::dhcp::PgSqlHostDataSource::del6	(	const SubnetID &	subnet_id,
		const Host::IdentifierType &	identifier_type,
		const uint8_t *	identifier_begin,
		const size_t	identifier_len
	)

virtual

Attempts to delete a host by (subnet6-id, identifier type, identifier)

This method supports v6 hosts only.

Parameters

subnet_id	subnet identifier.
identifier_type	Identifier type.
identifier_begin	Pointer to a beginning of a buffer containing an identifier.
identifier_len	Identifier length.

Returns: true if deletion was successful, false if the host was not there.

Exceptions

various exceptions in case of errors

Implements isc::dhcp::BaseHostDataSource.

Definition at line 2061 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::DEL_HOST_SUBID6_ID, and isc::dhcp::PgSqlHostDataSourceImpl::delStatement().

Referenced by del().

Here is the call graph for this function:

◆ get4() [1/2]

ConstHostPtr isc::dhcp::PgSqlHostDataSource::get4	(	const SubnetID &	subnet_id,
		const Host::IdentifierType &	identifier_type,
		const uint8_t *	identifier_begin,
		const size_t	identifier_len
	)		const

virtual

Returns a host connected to the IPv4 subnet.

Parameters

subnet_id	Subnet identifier.
identifier_type	Identifier type.
identifier_begin	Pointer to a beginning of a buffer containing an identifier.
identifier_len	Identifier length.

Returns: Const Host object for which reservation has been made using the specified identifier.

Implements isc::dhcp::BaseHostDataSource.

Definition at line 2117 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::GET_HOST_SUBID4_DHCPID, isc::dhcp::PgSqlHostDataSourceImpl::getHost(), and isc::dhcp::PgSqlHostDataSourceImpl::host_exchange_.

Here is the call graph for this function:

◆ get4() [2/2]

ConstHostPtr isc::dhcp::PgSqlHostDataSource::get4	(	const SubnetID &	subnet_id,
		const asiolink::IOAddress &	address
	)		const

virtual

Returns a host connected to the IPv4 subnet and having a reservation for a specified IPv4 address.

One of the use cases for this method is to detect collisions between dynamically allocated addresses and reserved addresses. When the new address is assigned to a client, the allocation mechanism should check if this address is not reserved for some other host and do not allocate this address if reservation is present.

Parameters

subnet_id	Subnet identifier.
address	reserved IPv4 address.

Returns: Const Host object using a specified IPv4 address.

Exceptions

BadValue is given an IPv6 address

Implements isc::dhcp::BaseHostDataSource.

Definition at line 2129 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::GET_HOST_SUBID_ADDR, isc::dhcp::PgSqlHostDataSourceImpl::getHostCollection(), isc::dhcp::PgSqlHostDataSourceImpl::host_exchange_, isc_throw, and isc::asiolink::IOAddress::isV4().

Here is the call graph for this function:

◆ get6() [1/3]

ConstHostPtr isc::dhcp::PgSqlHostDataSource::get6	(	const SubnetID &	subnet_id,
		const Host::IdentifierType &	identifier_type,
		const uint8_t *	identifier_begin,
		const size_t	identifier_len
	)		const

virtual

Returns a host connected to the IPv6 subnet.

Parameters

subnet_id	Subnet identifier.
identifier_type	Identifier type.
identifier_begin	Pointer to a beginning of a buffer containing an identifier.
identifier_len	Identifier length.

Returns: Const Host object for which reservation has been made using the specified identifier.

Implements isc::dhcp::BaseHostDataSource.

Definition at line 2159 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::GET_HOST_SUBID6_DHCPID, isc::dhcp::PgSqlHostDataSourceImpl::getHost(), and isc::dhcp::PgSqlHostDataSourceImpl::host_ipv6_exchange_.

Referenced by del().

Here is the call graph for this function:

◆ get6() [2/3]

ConstHostPtr isc::dhcp::PgSqlHostDataSource::get6	(	const asiolink::IOAddress &	prefix,
		const uint8_t	prefix_len
	)		const

virtual

Returns a host using the specified IPv6 prefix.

Parameters

prefix	IPv6 prefix for which the `Host` object is searched.
prefix_len	IPv6 prefix length.

Returns: Const Host object using a specified IPv6 prefix.

Todo:: : Check that prefix is v6 address, not v4.

Implements isc::dhcp::BaseHostDataSource.

Definition at line 2170 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::GET_HOST_PREFIX, isc::dhcp::PgSqlHostDataSourceImpl::getHostCollection(), and isc::dhcp::PgSqlHostDataSourceImpl::host_ipv6_exchange_.

Here is the call graph for this function:

◆ get6() [3/3]

ConstHostPtr isc::dhcp::PgSqlHostDataSource::get6	(	const SubnetID &	subnet_id,
		const asiolink::IOAddress &	address
	)		const

virtual

Returns a host connected to the IPv6 subnet and having a reservation for a specified IPv6 address or prefix.

Parameters

subnet_id	Subnet identifier.
address	reserved IPv6 address/prefix.

Returns: Const Host object using a specified IPv6 address/prefix.

Todo:: : Check that prefix is v6 address, not v4.

Implements isc::dhcp::BaseHostDataSource.

Definition at line 2198 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::GET_HOST_SUBID6_ADDR, isc::dhcp::PgSqlHostDataSourceImpl::getHostCollection(), and isc::dhcp::PgSqlHostDataSourceImpl::host_ipv6_exchange_.

Here is the call graph for this function:

◆ getAll()

ConstHostCollection isc::dhcp::PgSqlHostDataSource::getAll	(	const Host::IdentifierType &	identifier_type,
		const uint8_t *	identifier_begin,
		const size_t	identifier_len
	)		const

virtual

Return all hosts connected to any subnet for which reservations have been made using a specified identifier.

This method returns all Host objects which represent reservations for a specified identifier. This method may return multiple hosts because a particular client may have reservations in multiple subnets.

Parameters

identifier_type	Identifier type.
identifier_begin	Pointer to a beginning of a buffer containing an identifier.
identifier_len	Identifier length.

Returns: Collection of const Host objects.

Implements isc::dhcp::BaseHostDataSource.

Definition at line 2081 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::GET_HOST_DHCPID, isc::dhcp::PgSqlHostDataSourceImpl::getHostCollection(), and isc::dhcp::PgSqlHostDataSourceImpl::host_ipv46_exchange_.

Here is the call graph for this function:

◆ getAll4()

ConstHostCollection isc::dhcp::PgSqlHostDataSource::getAll4 ( const asiolink::IOAddress & address ) const

virtual

Returns a collection of hosts using the specified IPv4 address.

This method may return multiple Host objects if they are connected to different subnets.

Parameters

address IPv4 address for which the Host object is searched.

Returns: Collection of const Host objects.

Implements isc::dhcp::BaseHostDataSource.

Definition at line 2101 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::GET_HOST_ADDR, isc::dhcp::PgSqlHostDataSourceImpl::getHostCollection(), and isc::dhcp::PgSqlHostDataSourceImpl::host_exchange_.

Here is the call graph for this function:

◆ getDescription()

std::string isc::dhcp::PgSqlHostDataSource::getDescription ( ) const

virtual

Returns description of the backend.

This description may be multiline text that describes the backend.

Returns: Description of the backend.

Definition at line 2237 of file pgsql_host_data_source.cc.

◆ getName()

std::string isc::dhcp::PgSqlHostDataSource::getName ( ) const

virtual

Returns the name of the open database.

Returns: String containing the name of the database

Definition at line 2227 of file pgsql_host_data_source.cc.

References isc::dhcp::PgSqlHostDataSourceImpl::conn_, and isc::db::DatabaseConnection::getParameter().

Here is the call graph for this function:

◆ getType()

virtual std::string isc::dhcp::PgSqlHostDataSource::getType ( ) const

inlinevirtual

Return backend type.

Returns the type of database as the string "postgresql". This is same value as used for configuration purposes.

Returns: Type of the backend.

Implements isc::dhcp::BaseHostDataSource.

Definition at line 242 of file pgsql_host_data_source.h.

◆ getVersion()

std::pair< uint32_t, uint32_t > isc::dhcp::PgSqlHostDataSource::getVersion ( ) const

virtual

Returns backend version.

The method is called by the constructor after opening the database but prior to preparing SQL statements, to verify that the schema version is correct. Thus it must not rely on a pre-prepared statement or formal statement execution error checking.