DHCP query filtering class. More...

#include <query_filter.h>

Public Member Functions
	QueryFilter (const HAConfigPtr &config)
	Constructor. More...

bool	amServingScope (const std::string &scope_name) const
	Checks if this server instance is configured to process traffic belonging to a particular scope. More...

std::set< std::string >	getServedScopes () const
	Returns served scopes. More...

bool	inScope (const dhcp::Pkt4Ptr &query4, std::string &scope_class) const
	Checks if this server should process the DHCPv4 query. More...

bool	inScope (const dhcp::Pkt6Ptr &query6, std::string &scope_class) const
	Checks if this server should process the DHCPv6 query. More...

void	serveDefaultScopes ()
	Serve default scopes for the given HA mode. More...

void	serveFailoverScopes ()
	Enable scopes required in failover case. More...

void	serveNoScopes ()
	Disables all scopes. More...

void	serveScope (const std::string &scope_name)
	Enable scope. More...

void	serveScopeOnly (const std::string &scope_name)
	Enable scope and disable all other scopes. More...

void	serveScopes (const std::vector< std::string > &scopes)
	Enables selected scopes. More...

Protected Member Functions
int	loadBalance (const dhcp::Pkt4Ptr &query4) const
	Performs load balancing of the DHCPv4 queries. More...

int	loadBalance (const dhcp::Pkt6Ptr &query6) const
	Performs load balancing of the DHCPv6 queries. More...

uint8_t	loadBalanceHash (const uint8_t *key, const size_t key_len) const
	Compute load balancing hash. More...

std::string	makeScopeClass (const std::string &scope_name) const
	Returns scope class name for the specified scope name. More...

void	validateScopeName (const std::string &scope_name) const
	Checks if the scope name matches a name of any of the configured servers. More...

Protected Attributes
int	active_servers_
	Number of the active servers in the given HA mode. More...

HAConfigPtr	config_
	Pointer to the HA configuration. More...

std::vector< HAConfig::PeerConfigPtr >	peers_
	Vector of HA peers configurations. More...

std::map< std::string, bool >	scopes_
	Holds mapping of the scope names to the flag which indicates if the scopes are enabled or disabled. More...

Detailed Description

DHCP query filtering class.

This class is a central point of information about distribution of the DHCP queries processed by the servers within HA setup. It also implements load balancing of the DHCP queries, when configured to do so.

The query filter uses a term "scope" to identify group of DHCP queries processed by a given server. Currently, we support load balanacing between two servers. Therefore, in this mode of operation, there are two scopes named after servers responsible for processing packets belonging to those scopes, e.g. "server1" and "server2".

In the hot-standby mode, there is only one server processing incoming DHCP queries. Thus, there is only one scope named after the primary server, e.g. "server1".

This class allows for assigning the server to process queries belonging to various scopes. For example: when a failure of the partner server is detected, the QueryFilter::serveFailoverScopes is called to indicate that this server instance should start handling queries belonging to the scope(s) of the server which have died. Converesly, a call to QueryFilter::serveDefaultScopes reverts to the default state.

When DHCP query is received, the QueryFilter class is used to determine whether this query should be processed by this server. The QueryFilter::inScope methods return boolean value indicating whether the query should be processed or not. If not, the query is dropped.

The server administrator may force the server to start processing queries from the selected scopes, e.g. the administrator may manually instruct the backup server to take over the traffic of the primary and secondary servers. The 'ha-scopes' command is sent in such case, which enables/disables scopes within this class instance.

Definition at line 57 of file query_filter.h.

Constructor & Destructor Documentation

◆ QueryFilter()

isc::ha::QueryFilter::QueryFilter ( const HAConfigPtr & config )

explicit

Constructor.

This constructor puts HA peers configurations in the following order:

primary server configuration,
secondary or standby server configuration,
backup servers configurations

It also sets the active_servers_ value to the number of active servers (responding to DHCP queries) for a given HA mode. In our case, this is 2 for the load balancing case and 1 for the hot-standby. Such organization of the configurations makes it easier for the load balancing algorithm to distribute queries between active servers. In our simple case, the load balancing algorithm can produce a value of 0 or 1, which points to a primary or secondary server in the configuration vector.

Parameters

config pointer to the HA configuration.

Exceptions

HAConfigValidationError if provided configuration is invalid.

Definition at line 52 of file query_filter.cc.

References active_servers_, config_, peers_, isc::ha::HAConfig::PeerConfig::PRIMARY, isc::ha::HAConfig::PeerConfig::SECONDARY, serveDefaultScopes(), and isc::ha::HAConfig::PeerConfig::STANDBY.

Here is the call graph for this function:

Member Function Documentation

◆ amServingScope()

bool isc::ha::QueryFilter::amServingScope ( const std::string & scope_name ) const

Checks if this server instance is configured to process traffic belonging to a particular scope.

Parameters

scope_name name of the scope/server.

Returns: true if the scope is enabled.

Definition at line 183 of file query_filter.cc.

References scopes_.

◆ getServedScopes()

std::set< std::string > isc::ha::QueryFilter::getServedScopes ( ) const

Returns served scopes.

This method is mostly useful for testing purposes.

Definition at line 189 of file query_filter.cc.

References scopes_.

◆ inScope() [1/2]

bool isc::ha::QueryFilter::inScope	(	const dhcp::Pkt4Ptr &	query4,
		std::string &	scope_class
	)		const

Checks if this server should process the DHCPv4 query.

This method takes into account enabled scopes for this server and HA mode to determine whether this query should be processed. It triggers load balancing when load balancing mode is enabled.

Parameters

	query4	pointer to the DHCPv4 query instance.
[out]	scope_class	name of the class which corresponds to the name of the server which owns the packet. Those class names are used in subnets, pools and network configurations to associate them with different servers.

Returns: true if the specified query should be processed by this server, false otherwise.

Definition at line 200 of file query_filter.cc.

◆ inScope() [2/2]

bool isc::ha::QueryFilter::inScope	(	const dhcp::Pkt6Ptr &	query6,
		std::string &	scope_class
	)		const

Checks if this server should process the DHCPv6 query.

This method takes into account enabled scopes for this server and HA mode to determine whether this query should be processed. It triggers load balancing when load balancing mode is enabled.

Parameters

	query6	pointer to the DHCPv6 query instance.
[out]	scope_class	name of the class which corresponds to the name of the server which owns the packet. Those class names are used in subnets, pools and network configurations to associate them with different servers.

Returns: true if the specified query should be processed by this server, false otherwise.

Definition at line 205 of file query_filter.cc.

◆ loadBalance() [1/2]

int isc::ha::QueryFilter::loadBalance ( const dhcp::Pkt4Ptr & query4 ) const

protected

Performs load balancing of the DHCPv4 queries.

This method returns an index of the server configuration held within peers_ vector. This points to a server which should process the given query. Currently, we only support load balancing between two servers, therefore this value should be 0 or 1.

Parameters

query4 pointer to the DHCPv4 query instance.

Returns: Index of the server which should process the query. It returns negative value if the query is malformed, i.e. contains no HW address and no client identifier.

Definition at line 236 of file query_filter.cc.

References active_servers_, isc::log::DBGLVL_TRACE_BASIC, isc::dhcp::DHO_DHCP_CLIENT_IDENTIFIER, isc::ha::ha_logger, loadBalanceHash(), and LOG_DEBUG.

Here is the call graph for this function:

◆ loadBalance() [2/2]

int isc::ha::QueryFilter::loadBalance ( const dhcp::Pkt6Ptr & query6 ) const

protected

Performs load balancing of the DHCPv6 queries.

This method returns an index of the server configuration held within peers_ vector. This points to a server which should process the given query. Currently, we only support load balancing between two servers, therefore this value should be 0 or 1.

Parameters

query6 pointer to the DHCPv6 query instance.

Returns: Index of the server which should process the query. It returns negative value if the query is malformed, i.e. contains no DUID.

Definition at line 268 of file query_filter.cc.

References active_servers_, D6O_CLIENTID, isc::log::DBGLVL_TRACE_BASIC, isc::ha::ha_logger, loadBalanceHash(), and LOG_DEBUG.

Here is the call graph for this function:

◆ loadBalanceHash()

uint8_t isc::ha::QueryFilter::loadBalanceHash	(	const uint8_t *	key,
		const size_t	key_len
	)		const

protected

Compute load balancing hash.

The load balancing hash is computed according to section 6 if RFC3074.

Parameters

key	identifier used to compute a hash, i.e. HW address or client identifier.
key_len	length of the key.

Returns: Computed hash value.

Definition at line 291 of file query_filter.cc.

Referenced by loadBalance().

◆ makeScopeClass()

std::string isc::ha::QueryFilter::makeScopeClass ( const std::string & scope_name ) const

protected

Returns scope class name for the specified scope name.

When the server is designated to process a received DHCP query, it is often required to assign a class to this query which corresponds to the particular server. This class name is associated with the pools, subnets and/or networks which this server should hand out leases from.

This function converts scope name to the class name by prefixing the scope name with "ha_" string.

Parameters

scope_name scope name to be converted to class name.

Returns: Scope class name.

Definition at line 314 of file query_filter.cc.

◆ serveDefaultScopes()

void isc::ha::QueryFilter::serveDefaultScopes ( )

Serve default scopes for the given HA mode.

If this server is primary or secondary (load balancing), the scope of this server is enabled. All other scopes are disabled.

Definition at line 135 of file query_filter.cc.

References config_, isc::ha::HAConfig::PeerConfig::PRIMARY, isc::ha::HAConfig::PeerConfig::SECONDARY, serveNoScopes(), and serveScope().

Referenced by isc::ha::HAService::normalStateHandler(), isc::ha::HAService::partnerDownStateHandler(), QueryFilter(), isc::ha::HAService::serveDefaultScopes(), and isc::ha::HAService::terminatedStateHandler().

Here is the call graph for this function:

◆ serveFailoverScopes()

void isc::ha::QueryFilter::serveFailoverScopes ( )

Enable scopes required in failover case.

In the load balancing case, the scopes of the primary and secondary servers are enabled (this server will handle the entire traffic). In the hot standby case, the primary server's scope is enabled (this server will handle the entire traffic normally processed by the primary server).

Definition at line 152 of file query_filter.cc.

References peers_, isc::ha::HAConfig::PeerConfig::PRIMARY, isc::ha::HAConfig::PeerConfig::SECONDARY, serveNoScopes(), and serveScope().

Referenced by isc::ha::HAService::partnerDownStateHandler().

Here is the call graph for this function: