Represents option data configuration for the DHCP server. More...

#include <cfg_option.h>

Inheritance diagram for isc::dhcp::CfgOption:

Public Member Functions
	CfgOption ()
	default constructor

bool	empty () const
	Indicates the object is empty.

Public Member Functions inherited from isc::data::CfgToElement
virtual	~CfgToElement ()
	Destructor.

virtual isc::data::ElementPtr	toElement () const =0
	Unparse a configuration object.

Methods and operators used for comparing objects.
bool	equals (const CfgOption &other) const
	Check if configuration is equal to other configuration.

bool	operator== (const CfgOption &other) const
	Equality operator.

bool	operator!= (const CfgOption &other) const
	Inequality operator.

void	add (const OptionPtr &option, const bool persistent, const bool cancelled, const std::string &option_space, const uint64_t id=0)
	Adds instance of the option to the configuration.

void	add (const OptionDescriptor &desc, const std::string &option_space)
	A variant of the CfgOption::add method which takes option descriptor as an argument.

void	replace (const OptionDescriptor &desc, const std::string &option_space)
	Replaces the instance of an option within this collection.

void	merge (CfgOptionDefPtr cfg_def, CfgOption &other)
	Merges another option configuration into this one.

void	createOptions (CfgOptionDefPtr cfg_def)
	Re-create the option in each descriptor based on given definitions.

void	mergeTo (CfgOption &other) const
	Merges this configuration to another configuration.

void	copyTo (CfgOption &other) const
	Copies this configuration to another configuration.

void	encapsulate ()
	Appends encapsulated options to top-level options.

bool	isEncapsulated () const
	Checks if options have been encapsulated.

OptionContainerPtr	getAll (const std::string &option_space) const
	Returns all options for the specified option space.

OptionContainerPtr	getAll (const uint32_t vendor_id) const
	Returns vendor options for the specified vendor id.

OptionContainerPtr	getAllCombined (const std::string &option_space) const
	Returns all non-vendor or vendor options for the specified option space.

template<typename Selector >
OptionDescriptor	get (const Selector &key, const uint16_t option_code) const
	Returns option for the specified key and option code.

template<typename Selector >
OptionDescriptorList	getList (const Selector &key, const uint16_t option_code) const
	Returns options for the specified key and option code.

size_t	del (const std::string &option_space, const uint16_t option_code)
	Deletes option for the specified option space and option code.

size_t	del (const uint32_t vendor_id, const uint16_t option_code)
	Deletes vendor option for the specified vendor id.

size_t	del (const uint64_t id)
	Deletes all options having a given database id.

std::list< std::string >	getOptionSpaceNames () const
	Returns a list of configured option space names.

std::list< uint32_t >	getVendorIds () const
	Returns a list of all configured vendor identifiers.

std::list< std::string >	getVendorIdsSpaceNames () const
	Returns a list of option space names for configured vendor ids.

virtual isc::data::ElementPtr	toElement () const
	Unparse a configuration object.

isc::data::ElementPtr	toElementWithMetadata (const bool include_metadata) const
	Unparse a configuration object with optionally including the metadata.

static bool	createDescriptorOption (CfgOptionDefPtr cfg_def, const std::string &space, OptionDescriptor &opt_desc)
	Creates an option descriptor's option based on a set of option defs.

Detailed Description

Represents option data configuration for the DHCP server.

This class holds a collection of options to be sent to a DHCP client. Options are grouped by the option space or vendor identifier (for vendor options).

The server configuration allows for specifying two distinct collections of options: global options and per-subnet options in which some options may overlap.

The collection of global options specify options being sent to the client belonging to any subnets, i.e. global options are "inherited" by all subnets.

The per-subnet options are configured for a particular subnet and are sent to clients which belong to this subnet. The values of the options specified for a particular subnet override the values of the global options.

This class represents a single collection of options (either global or per-subnet). Each subnet holds its own object of the CfgOption type. The CfgMgr holds a CfgOption object representing global options.

Note that having a separate copy of the CfgOption to represent global options is useful when the client requests stateless configuration from the DHCP server and no subnet is selected for this client. This client will only receive global options.

Definition at line 352 of file cfg_option.h.

Constructor & Destructor Documentation

◆ CfgOption()

isc::dhcp::CfgOption::CfgOption ( )

default constructor

Definition at line 54 of file cfg_option.cc.

Member Function Documentation

◆ add() [1/2]

void isc::dhcp::CfgOption::add	(	const OptionDescriptor &	desc,
		const std::string &	option_space
	)

A variant of the CfgOption::add method which takes option descriptor as an argument.

Parameters

desc	Option descriptor holding option instance and other parameters pertaining to the option.
option_space	Option space name.

Exceptions

isc::BadValue if the option space is invalid.

Definition at line 83 of file cfg_option.cc.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::addItem(), isc_throw, isc::dhcp::OptionDescriptor::option_, isc::dhcp::LibDHCP::optionSpaceToVendorId(), and isc::dhcp::OptionSpace::validateName().

Here is the call graph for this function:

◆ add() [2/2]

void isc::dhcp::CfgOption::add	(	const OptionPtr &	option,
		const bool	persistent,
		const bool	cancelled,
		const std::string &	option_space,
		const uint64_t	id = `0`
	)

Adds instance of the option to the configuration.

There are two types of options which may be passed to this method:

vendor options
non-vendor options

The non-vendor options are grouped by the name of the option space (specified in textual format). The vendor options are grouped by the vendor identifier, which is a 32-bit unsigned integer value.

In order to add new vendor option to the list the option space name (last argument of this method) should be specified as "vendor-X" where "X" is a 32-bit unsigned integer, e.g. "vendor-1234". Options for which the option_space argument doesn't follow this format are added as non-vendor options.

Parameters

option	Pointer to the option being added.
persistent	Boolean value which specifies if the option should be sent to the client regardless if requested (true), or nor (false)
cancelled	Boolean value which specifies if the option must never be sent to the client.
option_space	Option space name.
id	Optional database id to be associated with the option.

Exceptions

isc::BadValue if the option space is invalid.

Definition at line 70 of file cfg_option.cc.

References add(), and isc::data::BaseStampedElement::setId().

Referenced by add().

Here is the call graph for this function:

◆ copyTo()

void isc::dhcp::CfgOption::copyTo ( CfgOption & other ) const

Copies this configuration to another configuration.

This method copies options configuration to another object.

Parameters

[out] other An object to copy the configuration to.

Definition at line 254 of file cfg_option.cc.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::clearItems(), and mergeTo().

Referenced by merge().

Here is the call graph for this function:

◆ createDescriptorOption()

bool isc::dhcp::CfgOption::createDescriptorOption	(	CfgOptionDefPtr	cfg_def,
		const std::string &	space,
		OptionDescriptor &	opt_desc
	)

static

Creates an option descriptor's option based on a set of option defs.

This function's primary use is to create definition specific options for option descriptors fetched from a configuration backend, as part of a configuration merge.

Given an OptionDescriptor whose option_ member contains a generic option (i.e has a code and/or data), this function will attempt to find a matching definition and then use that definition's factory to create an option instance specific to that definition. It will then replace the descriptor's generic option with the specific option.

Three sources of definitions are searched, in the following order:

Standard option definitions (LIBDHCP::getOptionDef))
Vendor option definitions (LIBDHCP::getVendorOptionDef))
User specified definitions passed in via cfg_def parameter.

The code will use the first matching definition found. It then applies the following rules:

If no definition is found but the descriptor conveys a non-empty formatted value, throw an error.
If not definition is found and there is no formatted value, return This leaves intact the generic option in the descriptor.
If a definition is found and there is no formatted value, pass the descriptor's generic option's data into the definition's factory. Replace the descriptor's option with the newly created option.
If a definition is found and there is a formatted value, split the value into vector of values and pass that into the definition's factory. Replace the descriptor's option with the newly created option.

Parameters

cfg_def	the user specified definitions to use
space	the option space name of the option
opt_desc	OptionDescriptor describing the option.

Returns: True if the descriptor's option instance was replaced.

Exceptions

InvalidOperation if the descriptor conveys a formatted value and there is no definition matching the option code in the given space, or if the definition factory invocation fails.

Definition at line 176 of file cfg_option.cc.

References DHCP4_OPTION_SPACE, DHCP6_OPTION_SPACE, isc::dhcp::OptionDescriptor::formatted_value_, isc::dhcp::LibDHCP::getLastResortOptionDef(), isc::dhcp::LibDHCP::getOptionDef(), isc::dhcp::LibDHCP::getVendorOptionDef(), isc_throw, isc::dhcp::OptionDescriptor::option_, isc::dhcp::LibDHCP::optionSpaceToVendorId(), and isc::Exception::what().

Referenced by createOptions().

Here is the call graph for this function:

◆ createOptions()

void isc::dhcp::CfgOption::createOptions ( CfgOptionDefPtr cfg_def )

Re-create the option in each descriptor based on given definitions.

Invokes createDescriptorOption() on each option descriptor in each option space, passing in the given dictionary of option definitions. If the descriptor's option is re-created, then the descriptor is updated by calling replace().

Parameters

cfg_def set of of user-defined option definitions to use when creating option instances.

Definition at line 161 of file cfg_option.cc.

References createDescriptorOption(), getAll(), getOptionSpaceNames(), and replace().

Referenced by merge().

Here is the call graph for this function:

◆ del() [1/3]

size_t isc::dhcp::CfgOption::del	(	const std::string &	option_space,
		const uint16_t	option_code
	)

Deletes option for the specified option space and option code.

If the option is encapsulated within some non top level option space, it is also deleted from all option instances encapsulating this option space.

Parameters

option_space	Option space name.
option_code	Code of the option to be returned.

Returns: Number of deleted options.

Definition at line 360 of file cfg_option.cc.

References DHCP4_OPTION_SPACE, DHCP6_OPTION_SPACE, getAll(), and getOptionSpaceNames().

Here is the call graph for this function:

◆ del() [2/3]

size_t isc::dhcp::CfgOption::del	(	const uint32_t	vendor_id,
		const uint16_t	option_code
	)

Deletes vendor option for the specified vendor id.

Parameters

vendor_id	Vendor identifier.
option_code	Option code.

Returns: Number of deleted options.

Definition at line 395 of file cfg_option.cc.

References getAll().

Here is the call graph for this function:

◆ del() [3/3]

size_t isc::dhcp::CfgOption::del ( const uint64_t id )

Deletes all options having a given database id.

Note that there are cases when there will be multiple options having the same id (typically id of 0). When configuration backend is in use it sets the unique ids from the database. In cases when the configuration backend is not used, the ids default to 0. Passing the id of 0 would result in deleting all options that were not added via the database.

Both regular and vendor specific options are deleted with this method.

This method internally calls encapsulate() after deleting options having the given id.

Parameters

id	Identifier of the options to be deleted.

Returns: Number of deleted options. Note that if a single option instance is encapsulated by multiple options it adds 1 to the number of deleted options even though the same instance is deleted from multiple higher level options.

Definition at line 408 of file cfg_option.cc.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::deleteItems(), encapsulate(), getAll(), and getOptionSpaceNames().

Here is the call graph for this function:

◆ empty()

bool isc::dhcp::CfgOption::empty ( ) const

Indicates the object is empty.

Returns: true when the object is empty

Definition at line 59 of file cfg_option.cc.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::empty().

Here is the call graph for this function:

◆ encapsulate()

void isc::dhcp::CfgOption::encapsulate ( )

Appends encapsulated options to top-level options.

This method iterates over the top-level options (from "dhcp4" and "dhcp6" option space) and checks which option spaces these options encapsulate. For each encapsulated option space, the options from this option space are appended to top-level options.

Definition at line 262 of file cfg_option.cc.

References DHCP4_OPTION_SPACE, and DHCP6_OPTION_SPACE.

Referenced by del(), and merge().

◆ equals()

bool isc::dhcp::CfgOption::equals ( const CfgOption & other ) const

Check if configuration is equal to other configuration.

Parameters

other An object holding configuration to compare to.

Returns: true if configurations are equal, false otherwise.

Definition at line 64 of file cfg_option.cc.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::equals().

Referenced by operator!=(), and operator==().

Here is the call graph for this function:

◆ get()

template<typename Selector >

OptionDescriptor isc::dhcp::CfgOption::get	(	const Selector &	key,
		const uint16_t	option_code
	)		const

inline

Returns option for the specified key and option code.

The key should be a string, in which case it specifies an option space name, or an uint32_t value, in which case it specifies a vendor identifier.

Note: If there are multiple options with the same key, only one will be returned. No indication will be given of the presence of others, and the instance returned is not determinable. So please use the next method when multiple instances of the option are expected.

Parameters

key	Option space name or vendor identifier.
option_code	Code of the option to be returned.

Template Parameters

Selector one of: std::string or uint32_t

Returns: Descriptor of the option. If option hasn't been found, the descriptor holds null option.

Definition at line 605 of file cfg_option.h.

References getAll().

Here is the call graph for this function:

◆ getAll() [1/2]

OptionContainerPtr isc::dhcp::CfgOption::getAll ( const std::string & option_space ) const

Returns all options for the specified option space.

This method will not return vendor options, i.e. having option space name in the format of "vendor-X" where X is 32-bit unsigned integer. See getAll(uint32_t) for vendor options.

Parameters

option_space Name of the option space.

Returns: Pointer to the container holding returned options. This container is empty if no options have been found.

Definition at line 341 of file cfg_option.cc.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::getItems().

Referenced by createOptions(), del(), get(), getAllCombined(), getList(), replace(), and toElementWithMetadata().

Here is the call graph for this function:

◆ getAll() [2/2]

OptionContainerPtr isc::dhcp::CfgOption::getAll ( const uint32_t vendor_id ) const

Returns vendor options for the specified vendor id.

Parameters

vendor_id Vendor id for which options are to be returned.

Returns: Pointer to the container holding returned options. This container is empty if no options have been found.

Definition at line 346 of file cfg_option.cc.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::getItems().

Here is the call graph for this function:

◆ getAllCombined()

OptionContainerPtr isc::dhcp::CfgOption::getAllCombined ( const std::string & option_space ) const

Returns all non-vendor or vendor options for the specified option space.

It combines the output of the getAll function variants. When option space has the format of "vendor-X", it retrieves the vendor options by vendor id, where X must be a 32-bit unsigned integer. Otherwise, it fetches non-vendor options.

Parameters

option_space Name of the option space.

Returns: Pointer to the container holding returned options. This container is empty if no options have been found.

Definition at line 351 of file cfg_option.cc.

References getAll(), and isc::dhcp::LibDHCP::optionSpaceToVendorId().

Here is the call graph for this function:

◆ getList()

template<typename Selector >

OptionDescriptorList isc::dhcp::CfgOption::getList	(	const Selector &	key,
		const uint16_t	option_code
	)		const

inline

Returns options for the specified key and option code.

The key should be a string, in which case it specifies an option space name, or an uint32_t value, in which case it specifies a vendor identifier.

Parameters

key	Option space name or vendor identifier.
option_code	Code of the option to be returned.

Template Parameters

Selector one of: std::string or uint32_t

Returns: List of Descriptors of the option.

Definition at line 636 of file cfg_option.h.

References getAll().

Here is the call graph for this function:

◆ getOptionSpaceNames()

std::list< std::string > isc::dhcp::CfgOption::getOptionSpaceNames ( ) const

inline

Returns a list of configured option space names.

The returned option space names exclude vendor option spaces, such as "vendor-1234". These are returned by the getVendorIdsSpaceNames.

Returns: List comprising option space names.

Definition at line 707 of file cfg_option.h.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::getOptionSpaceNames().

Referenced by createOptions(), and del().

Here is the call graph for this function:

◆ getVendorIds()

std::list< uint32_t > isc::dhcp::CfgOption::getVendorIds ( ) const

inline

Returns a list of all configured vendor identifiers.

Definition at line 712 of file cfg_option.h.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::getOptionSpaceNames().

Referenced by getVendorIdsSpaceNames().

Here is the call graph for this function:

◆ getVendorIdsSpaceNames()

std::list< std::string > isc::dhcp::CfgOption::getVendorIdsSpaceNames ( ) const

Returns a list of option space names for configured vendor ids.

For each vendor-id the option space name returned is constructed as "vendor-XYZ" where XYZ is a uint32_t value without leading zeros.

Returns: List comprising option space names for vendor options.

Definition at line 126 of file cfg_option.cc.

References getVendorIds().

Here is the call graph for this function:

◆ isEncapsulated()

bool isc::dhcp::CfgOption::isEncapsulated ( ) const

inline

Checks if options have been encapsulated.

Returns: true if options have been encapsulated, false otherwise.

Definition at line 550 of file cfg_option.h.

◆ merge()

void isc::dhcp::CfgOption::merge	(	CfgOptionDefPtr	cfg_def,
		CfgOption &	other
	)

Merges another option configuration into this one.

This method calls mergeTo() to add this configuration's options into other (skipping any duplicates). Next it calls createDescriptorOption() for each option descriptor in the merged set. This (re)-creates each descriptor's option based on the merged set of opt definitions. Finally, it calls copyTo() to overwrite this configuration's options with the merged set in other.

Warning: The merge operation will affect the other configuration. Therefore, the caller must not rely on the data held in the other object after the call to merge. Also, the data held in other must not be modified after the call to merge because it may affect the merged configuration.

Parameters

cfg_def	set of of user-defined option definitions to use when merging.
other	option configuration to merge in.

Definition at line 140 of file cfg_option.cc.

References copyTo(), createOptions(), encapsulate(), and mergeTo().

Here is the call graph for this function:

◆ mergeTo()

void isc::dhcp::CfgOption::mergeTo ( CfgOption & other ) const

Merges this configuration to another configuration.

This method iterates over the configuration items held in this configuration and copies them to the configuration specified as a parameter. If an item exists in the destination it is not copied.

Parameters

[out] other Configuration object to merge to.

Definition at line 246 of file cfg_option.cc.

Referenced by copyTo(), and merge().

◆ operator!=()

bool isc::dhcp::CfgOption::operator!= ( const CfgOption & other ) const

inline

Inequality operator.

Parameters

other An object holding configuration to compare to.

Returns: true if configurations are unequal, false otherwise.

Definition at line 387 of file cfg_option.h.

References equals().

Here is the call graph for this function:

◆ operator==()

bool isc::dhcp::CfgOption::operator== ( const CfgOption & other ) const

inline

Equality operator.

Parameters

other An object holding configuration to compare to.

Returns: true if configurations are equal, false otherwise.

Definition at line 378 of file cfg_option.h.

References equals().

Here is the call graph for this function:

◆ replace()

void isc::dhcp::CfgOption::replace	(	const OptionDescriptor &	desc,
		const std::string &	option_space
	)

Replaces the instance of an option within this collection.

This method locates the option within the given space and replaces it with a copy of the given descriptor. This effectively updates the contents without altering the container indexing.

Parameters

desc	Option descriptor holding option instance and other parameters pertaining to the option.
option_space	Option space name.

Exceptions

isc::BadValue if the descriptor's option instance is null, if space is invalid, or if the option does not already exist in the given space.

Definition at line 101 of file cfg_option.cc.

References getAll(), isc_throw, and isc::dhcp::OptionDescriptor::option_.

Referenced by createOptions().

Here is the call graph for this function:

◆ toElement()

ElementPtr isc::dhcp::CfgOption::toElement ( ) const

virtual

Unparse a configuration object.

Returns: a pointer to unparsed configuration

Implements isc::data::CfgToElement.

Definition at line 442 of file cfg_option.cc.

References toElementWithMetadata().

Here is the call graph for this function:

◆ toElementWithMetadata()

ElementPtr isc::dhcp::CfgOption::toElementWithMetadata ( const bool include_metadata ) const

Unparse a configuration object with optionally including the metadata.

Parameters

include_metadata boolean value indicating if the metadata should be included (if true) or not (if false).

Returns: A pointer to the unparsed configuration.

Definition at line 447 of file cfg_option.cc.

References isc::data::Element::create(), isc::data::Element::createList(), isc::data::Element::createMap(), isc::util::encode::encodeHex(), getAll(), isc::dhcp::LibDHCP::getLastResortOptionDef(), isc::dhcp::LibDHCP::getOptionDef(), isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::getOptionSpaceNames(), isc::dhcp::LibDHCP::getRuntimeOptionDef(), isc::dhcp::LibDHCP::getVendorOptionDef(), and isc::dhcp::OPT_EMPTY_TYPE.

Referenced by toElement().

Here is the call graph for this function:

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

Public Member Functions

Methods and operators used for comparing objects.

Detailed Description

Constructor & Destructor Documentation

◆ CfgOption()

Member Function Documentation

◆ add() [1/2]

◆ add() [2/2]

◆ copyTo()

◆ createDescriptorOption()

◆ createOptions()

◆ del() [1/3]

◆ del() [2/3]

◆ del() [3/3]

◆ empty()

◆ encapsulate()

◆ equals()

◆ get()

◆ getAll() [1/2]

◆ getAll() [2/2]

◆ getAllCombined()

◆ getList()

◆ getOptionSpaceNames()

◆ getVendorIds()

◆ getVendorIdsSpaceNames()

◆ isEncapsulated()

◆ merge()

◆ mergeTo()

◆ operator!=()

◆ operator==()

◆ replace()

◆ toElement()

◆ toElementWithMetadata()