Kea: isc::ha::QueryFilter Class Reference

| Kea 3.0.0

isc::ha::QueryFilter Class Reference

DHCP query filtering class. More...

`#include <query_filter.h>`

## Public Member Functions
| QueryFilter (const HAConfigPtr &config)
| Constructor.
bool | amServingScope (const std::string &scope_name) const
| Checks if this server instance is configured to process traffic belonging to a particular scope.
std::set< std::string > | getServedScopes () const
| Returns served scopes.
bool | inScope (const dhcp::Lease4Ptr &lease4) const
| Checks if this server should reclaim the DHCPv4 lease.
bool | inScope (const dhcp::Lease6Ptr &lease6) const
| Checks if this server should process the DHCPv6 query.
bool | inScope (const dhcp::Pkt4Ptr &query4, std::string &scope_class) const
| Checks if this server should process the DHCPv4 query.
bool | inScope (const dhcp::Pkt6Ptr &query6, std::string &scope_class) const
| Checks if this server should process the DHCPv6 query.
void | serveDefaultScopes ()
| Serve default scopes for the given HA mode.
void | serveFailoverScopes ()
| Enable scopes required in failover case.
void | serveNoScopes ()
| Disables all scopes.
void | serveScope (const std::string &scope_name)
| Enable scope.
void | serveScopeOnly (const std::string &scope_name)
| Enable scope and disable all other scopes.
void | serveScopes (const std::vector< std::string > &scopes)
| Enables selected scopes.

## Static Public Member Functions
static bool | isHaType (const dhcp::Pkt4Ptr &query4)
| Determines if a DHCPv4 query is a message type HA should process.
static bool | isHaType (const dhcp::Pkt6Ptr &query6)
| Determines if a DHCPv6 query is a message type HA should process.

## Protected Member Functions
int | loadBalance (const dhcp::Lease4Ptr &lease4) const
| Performs load balancing of the DHCPv4 leases.
int | loadBalance (const dhcp::Lease6Ptr &lease6) const
| Performs load balancing of the DHCPv6 leases.
int | loadBalance (const dhcp::Pkt4Ptr &query4) const
| Performs load balancing of the DHCPv4 queries.
int | loadBalance (const dhcp::Pkt6Ptr &query6) const
| Performs load balancing of the DHCPv6 queries.
uint8_t | loadBalanceHash (const uint8_t *key, const size_t key_len) const
| Compute load balancing hash.
std::string | makeScopeClass (const std::string &scope_name) const
| Returns scope class name for the specified scope name.
void | validateScopeName (const std::string &scope_name) const
| Checks if the scope name matches a name of any of the configured servers.

## Protected Attributes
int | active_servers_
| Number of the active servers in the given HA mode.
HAConfigPtr | config_
| Pointer to the HA configuration.
boost::scoped_ptr< std::mutex > | mutex_
| Mutex to protect the internal state.
std::vector< HAConfig::PeerConfigPtr > | peers_
| Vector of HA peers configurations.
std::map< std::string, bool > | scopes_
| Holds mapping of the scope names to the flag which indicates if the scopes are enabled or disabled.

## 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 balancing 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 61 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 121 of file query_filter.cc.

References active_servers_, config_, mutex_, peers_, isc::ha::HAConfig::PeerConfig::PRIMARY, scopes_, 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 313 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ getServedScopes()

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

Returns served scopes.

This method is mostly useful for testing purposes.

Definition at line 329 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ inScope() [1/4]

bool isc::ha::QueryFilter::inScope | ( | const dhcp::Lease4Ptr & | lease4 | ) | const

Checks if this server should reclaim the DHCPv4 lease.

This method is used to select DHCPv4 leases that are allocated by this server during the normal operation. It is used when the servers in the terminated state must reclaim expired leases. In this case each server can only reclaim the leases it is responsible for to avoid the situation that one of the servers reclaims a lease that another server allocates, as it would cause conflicts of the DNS updates between the servers.

Parameters

  lease4 | pointer to the DHCPv4 lease instance.

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

Definition at line 416 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ inScope() [2/4]

bool isc::ha::QueryFilter::inScope | ( | const dhcp::Lease6Ptr & | lease6 | ) | const

Checks if this server should process the DHCPv6 query.

This method is used to select DHCPv4 leases that are allocated by this server during the normal operation. It is used when the servers in the terminated state must reclaim expired leases. In this case each server can only reclaim the leases it is responsible for to avoid the situation that one of the servers reclaims a lease that another server allocates, as it would cause conflicts of the DNS updates between the servers.

Parameters

  lease6 | pointer to the DHCPv6 lease instance.

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

Definition at line 426 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ inScope() [3/4]

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 uses a table of DHCPv4 message types to determine whether or not a query needs further analysis to determine which HA server should handle it or if it should simply be processed by this server.

For message types that qualify (e.g. DHCPDISCOVER, DHCPREQUEST, etc), it then 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.

Non-qualifying message types (e.g. DHCPLEASEQUERY) are passed through for handling by this server.

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 363 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ inScope() [4/4]

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 uses a table of DHCPv6 message types to determine whether or not a query needs further analysis to determine which HA server should handle it or if it should simply be processed by this server.

For message types that qualify (e.g. DHCPV6_SOLICIT, DHCPV6_REQUEST, etc), it then 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.

Non-qualifying message types (e.g. DHCPV6_LEASEQUERY) are passed through for handling by this server.

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 373 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ isHaType() [1/2]

bool isc::ha::QueryFilter::isHaType | ( | const dhcp::Pkt4Ptr & | query4 | ) |
| static

Determines if a DHCPv4 query is a message type HA should process.

Parameters

  query4 | DHCPv4 packet to test. Must not be null.

Returns

Definition at line 350 of file query_filter.cc.

## ◆ isHaType() [2/2]

bool isc::ha::QueryFilter::isHaType | ( | const dhcp::Pkt6Ptr & | query6 | ) |
| static

Determines if a DHCPv6 query is a message type HA should process.

Parameters

  query6 | DHCPv6 packet to test. Must not be null.

Returns

Definition at line 356 of file query_filter.cc.

## ◆ loadBalance() [1/4]

int isc::ha::QueryFilter::loadBalance | ( | const dhcp::Lease4Ptr & | lease4 | ) | const
| protected

Performs load balancing of the DHCPv4 leases.

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

Parameters

  lease4 | pointer to the DHCPv4 lease instance.

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

Definition at line 517 of file query_filter.cc.

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

Here is the call graph for this function:

## ◆ loadBalance() [2/4]

int isc::ha::QueryFilter::loadBalance | ( | const dhcp::Lease6Ptr & | lease6 | ) | const
| protected

Performs load balancing of the DHCPv6 leases.

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

Parameters

  lease6 | pointer to the DHCPv6 lease instance.

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

Definition at line 547 of file query_filter.cc.

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

Here is the call graph for this function:

## ◆ loadBalance() [3/4]

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 460 of file query_filter.cc.

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

Here is the call graph for this function:

## ◆ loadBalance() [4/4]

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 493 of file query_filter.cc.

References active_servers_, config_, D6O_CLIENTID, isc::log::DBGLVL_TRACE_BASIC, isc::ha::HA_LOAD_BALANCING_DUID_MISSING, 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 569 of file query_filter.cc.

Referenced by loadBalance(), loadBalance(), loadBalance(), and 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 592 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 235 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Referenced by QueryFilter().

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 262 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ serveNoScopes()

void isc::ha::QueryFilter::serveNoScopes | ( |  | ) |

Disables all scopes.

Definition at line 293 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ serveScope()

void isc::ha::QueryFilter::serveScope | ( | const std::string & | scope_name | ) |

Enable scope.

Starts serving queries from the specified scope. It doesn't affect other scopes.

Parameters

  scope_name | name of the scope/server to be enabled.

Exceptions

  BadValue | if scope name doesn't match any of the server names.

Definition at line 173 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ serveScopeOnly()

void isc::ha::QueryFilter::serveScopeOnly | ( | const std::string & | scope_name | ) |

Enable scope and disable all other scopes.

Starts serving queries from the specified scope. Disable all other scopes.

Parameters

  scope_name | name of the scope/server to be enabled.

Exceptions

  BadValue | if scope name doesn't match any of the server names.

Definition at line 189 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ serveScopes()

void isc::ha::QueryFilter::serveScopes | ( | const std::vector< std::string > & | scopes | ) |

Enables selected scopes.

All non listed scopes are disabled.

Parameters

  scopes | vector of scope names to be enabled.

Definition at line 206 of file query_filter.cc.

References isc::util::MultiThreadingMgr::instance(), and mutex_.

Here is the call graph for this function:

## ◆ validateScopeName()

void isc::ha::QueryFilter::validateScopeName | ( | const std::string & | scope_name | ) | const
| protected

Checks if the scope name matches a name of any of the configured servers.

Parameters

  scope_name | scope name to be tested.

Exceptions

  BadValue | if no server is found for a given scope name.

Definition at line 580 of file query_filter.cc.

References config_, and isc_throw.

## Member Data Documentation

## ◆ active_servers_

int isc::ha::QueryFilter::active_servers_
| protected

Number of the active servers in the given HA mode.

Definition at line 437 of file query_filter.h.

Referenced by QueryFilter(), loadBalance(), loadBalance(), loadBalance(), and loadBalance().

## ◆ config_

HAConfigPtr isc::ha::QueryFilter::config_
| protected

Pointer to the HA configuration.

Definition at line 427 of file query_filter.h.

Referenced by QueryFilter(), loadBalance(), loadBalance(), loadBalance(), loadBalance(), and validateScopeName().

## ◆ mutex_

boost::scoped_ptr<std::mutex> isc::ha::QueryFilter::mutex_
| protected

Mutex to protect the internal state.

Definition at line 440 of file query_filter.h.

Referenced by QueryFilter(), amServingScope(), getServedScopes(), inScope(), inScope(), inScope(), inScope(), serveDefaultScopes(), serveFailoverScopes(), serveNoScopes(), serveScope(), serveScopeOnly(), and serveScopes().

## ◆ peers_

std::vector<HAConfig::PeerConfigPtr> isc::ha::QueryFilter::peers_
| protected

Vector of HA peers configurations.

Definition at line 430 of file query_filter.h.

Referenced by QueryFilter().

## ◆ scopes_

std::map<std::string, bool> isc::ha::QueryFilter::scopes_
| protected

Holds mapping of the scope names to the flag which indicates if the scopes are enabled or disabled.

Definition at line 434 of file query_filter.h.

Referenced by QueryFilter().

The documentation for this class was generated from the following files:

- query_filter.h
- query_filter.cc