Represents a single network interface. More...

#include <iface_mgr.h>

Inheritance diagram for isc::dhcp::Iface:

Public Types
typedef util::Optional< asiolink::IOAddress >	Address
	Address type.

typedef std::list< Address >	AddressCollection
	Type that defines list of addresses.

using	ErrorBuffer = std::vector<std::string>
	Type definition for a list of error messages.

typedef std::list< SocketInfo >	SocketCollection
	Type that holds a list of socket information.

Public Member Functions
	Iface (const std::string &name, unsigned int ifindex)
	Iface constructor.

	~Iface ()
	Destructor.

void	addAddress (const isc::asiolink::IOAddress &addr)
	Adds an address to an interface.

void	addError (std::string const &message)
	Add an error to the list of messages.

void	addSocket (const SocketInfo &sock)
	Adds socket descriptor to an interface.

void	addUnicast (const isc::asiolink::IOAddress &addr)
	Adds unicast the server should listen on.

void	clearErrors ()
	Clears all errors.

void	clearUnicasts ()
	Removes any unicast addresses.

void	closeSockets ()
	Closes all open sockets on interface.

void	closeSockets (const uint16_t family)
	Closes all IPv4 or IPv6 sockets.

unsigned int	countActive4 () const
	Returns a number of activated IPv4 addresses on the interface.

bool	delAddress (const isc::asiolink::IOAddress &addr)
	Deletes an address from an interface.

bool	delSocket (uint16_t sockfd)
	Closes socket.

bool	getAddress4 (isc::asiolink::IOAddress &address) const
	Returns IPv4 address assigned to the interface.

const AddressCollection &	getAddresses () const
	Returns all addresses available on an interface.

ErrorBuffer const &	getErrors () const
	Get the consistent list of error messages.

std::string	getFullName () const
	Returns full interface name as "ifname/ifindex" string.

uint16_t	getHWType () const
	Returns hardware type of the interface.

unsigned int	getIndex () const
	Returns interface index.

const uint8_t *	getMac () const
	Returns pointer to MAC address.

size_t	getMacLen () const
	Returns MAC length.

std::string	getName () const
	Returns interface name.

std::string	getPlainMac () const
	Returns link-layer address a plain text.

uint8_t *	getReadBuffer ()
	Returns the pointer to the buffer used for data reading.

size_t	getReadBufferSize () const
	Returns the current size of the socket read buffer.

const SocketCollection &	getSockets () const
	Returns collection of all sockets added to interface.

const AddressCollection &	getUnicasts () const
	Returns a container of addresses the server should listen on.

bool	hasAddress (const isc::asiolink::IOAddress &address) const
	Check if the interface has the specified address assigned.

void	resizeReadBuffer (const size_t new_size)
	Reallocates the socket read buffer.

void	setActive (const bool active)
	Activates or deactivates all addresses for the interface.

void	setActive (const isc::asiolink::IOAddress &address, const bool active)
	Activates or deactivates address for the interface.

void	setFlags (uint64_t flags)
	Sets flag_*_ fields based on bitmask value returned by OS.

void	setHWType (uint16_t type)
	Sets up hardware type of the interface.

void	setMac (const uint8_t *mac, size_t macLen)
	Sets MAC address of the interface.

Public Attributes
bool	flag_broadcast_
	Flag specifies if selected interface is broadcast capable.

bool	flag_loopback_
	Specifies if selected interface is loopback.

bool	flag_multicast_
	Flag specifies if selected interface is multicast capable.

bool	flag_running_
	Flag specifies if selected interface is running (e.g.

bool	flag_up_
	Specifies if selected interface is up.

uint64_t	flags_
	Interface flags (this value is as is returned by OS, it may mean different things on different OSes).

bool	inactive4_
	Indicates that IPv4 sockets should (true) or should not (false) be opened on this interface.

bool	inactive6_
	Indicates that IPv6 sockets should (true) or should not (false) be opened on this interface.

Static Public Attributes
static const unsigned int	MAX_MAC_LEN = 20
	Maximum MAC address length (Infiniband uses 20 bytes)

Protected Attributes
AddressCollection	addrs_
	List of assigned addresses.

uint16_t	hardware_type_
	Hardware type.

unsigned int	ifindex_
	Interface index (a value that uniquely identifies an interface).

uint8_t	mac_ [MAX_MAC_LEN]
	Link-layer address.

size_t	mac_len_
	Length of link-layer address (usually 6).

std::string	name_
	Network interface name.

SocketCollection	sockets_
	Socket used to send data.

AddressCollection	unicasts_
	List of unicast addresses the server should listen on.

Detailed Description

Represents a single network interface.

Iface structure represents network interface with all useful information, like name, interface index, MAC address and list of assigned addresses

This class also holds the pointer to the socket read buffer. Functions reading from the socket may utilize this buffer to store the data being read from the socket. The advantage of using the pre-allocated buffer is that the buffer is allocated only once, rather than on every read. In addition, some OS specific code (e.g. BPF) may require use of fixed-size buffers. The size of such a buffer is returned by the OS kernel when the socket is opened. Hence, it is convenient to allocate the buffer when the socket is being opened and utilize it throughout the lifetime of the socket.

In order to avoid potentially expensive copies of the Iface objects holding pre-allocated buffers and multiple containers, this class is noncopyable.

Definition at line 118 of file iface_mgr.h.

Member Typedef Documentation

◆ Address

typedef util::Optional<asiolink::IOAddress> isc::dhcp::Iface::Address

Address type.

Definition at line 125 of file iface_mgr.h.

◆ AddressCollection

typedef std::list<Address> isc::dhcp::Iface::AddressCollection

Type that defines list of addresses.

Definition at line 128 of file iface_mgr.h.

◆ ErrorBuffer

using isc::dhcp::Iface::ErrorBuffer = std::vector<std::string>

Type definition for a list of error messages.

Definition at line 142 of file iface_mgr.h.

◆ SocketCollection

typedef std::list<SocketInfo> isc::dhcp::Iface::SocketCollection

Type that holds a list of socket information.

Warning: The type of the container used here must guarantee that the iterators do not invalidate when erase() is called. This is because, the closeSockets function removes elements selectively by calling erase on the element to be removed and further iterates through remaining elements.

Todo: : Add SocketCollectionConstIter type

Definition at line 139 of file iface_mgr.h.

Constructor & Destructor Documentation

◆ Iface()

isc::dhcp::Iface::Iface	(	const std::string &	name,
		unsigned int	ifindex )

Iface constructor.

Creates Iface object that represents network interface.

Parameters

name	name of the interface
ifindex	interface index (unique integer identifier)

Exceptions

BadValue when name is empty.

Definition at line 64 of file iface_mgr.cc.

References isc_throw, and mac_.

◆ ~Iface()

isc::dhcp::Iface::~Iface ( )

inline

Destructor.

Definition at line 154 of file iface_mgr.h.

Member Function Documentation

◆ addAddress()

void isc::dhcp::Iface::addAddress ( const isc::asiolink::IOAddress & addr )

Adds an address to an interface.

This only adds an address to collection, it does not physically configure address on actual network interface.

Parameters

addr	address to be added

Definition at line 250 of file iface_mgr.cc.

References addrs_, and hasAddress().

Here is the call graph for this function:

◆ addError()

void isc::dhcp::Iface::addError ( std::string const & message )

Add an error to the list of messages.

Parameters

message the error message

Definition at line 1979 of file iface_mgr.cc.

◆ addSocket()

void isc::dhcp::Iface::addSocket ( const SocketInfo & sock )

inline

Adds socket descriptor to an interface.

Parameters

sock	SocketInfo structure that describes socket.

Definition at line 321 of file iface_mgr.h.

References sockets_.

◆ addUnicast()

void isc::dhcp::Iface::addUnicast ( const isc::asiolink::IOAddress & addr )

Adds unicast the server should listen on.

Exceptions

BadValue if specified address is already defined on interface

Parameters

addr	unicast address to listen on

Definition at line 213 of file iface_mgr.cc.

References isc_throw, name_, and unicasts_.

◆ clearErrors()

void isc::dhcp::Iface::clearErrors ( )

Clears all errors.

Definition at line 1984 of file iface_mgr.cc.

◆ clearUnicasts()

void isc::dhcp::Iface::clearUnicasts ( )

inline

Removes any unicast addresses.

Removes any unicast addresses that the server was configured to listen on

Definition at line 353 of file iface_mgr.h.

References unicasts_.

◆ closeSockets() [1/2]

void isc::dhcp::Iface::closeSockets ( )

Closes all open sockets on interface.

Definition at line 77 of file iface_mgr.cc.

References closeSockets().

Referenced by closeSockets().

Here is the call graph for this function:

◆ closeSockets() [2/2]

void isc::dhcp::Iface::closeSockets ( const uint16_t family )

Closes all IPv4 or IPv6 sockets.

This function closes sockets of the specific 'type' and closes them. The 'type' of the socket indicates whether it is used to send IPv4 or IPv6 packets. The allowed values of the parameter are AF_INET and AF_INET6 for IPv4 and IPv6 packets respectively. It is important to realize that the actual types of sockets may be different than AF_INET for IPv4 packets. This is because, historically the IfaceMgr always used AF_INET sockets for IPv4 traffic. This is no longer the case when the Direct IPv4 traffic must be supported. In order to support direct traffic, the IfaceMgr operates on raw sockets, e.g. AF_PACKET family sockets on Linux.

Todo: Replace the AF_INET and AF_INET6 values with an enum which will not be confused with the actual socket type.

Parameters

family type of the sockets to be closed (AF_INET or AF_INET6)

Exceptions

BadValue if family value is different than AF_INET or AF_INET6.

Definition at line 85 of file iface_mgr.cc.

References isc_throw, and sockets_.

◆ countActive4()

unsigned int isc::dhcp::Iface::countActive4 ( ) const

Returns a number of activated IPv4 addresses on the interface.

Definition at line 276 of file iface_mgr.cc.

References addrs_.

◆ delAddress()

bool isc::dhcp::Iface::delAddress ( const isc::asiolink::IOAddress & addr )

Deletes an address from an interface.

This only deletes address from collection, it does not physically remove address configuration from actual network interface.

Parameters

addr	address to be removed.

Returns: true if removal was successful (address was in collection), false otherwise

Definition at line 158 of file iface_mgr.cc.

References addrs_.

◆ delSocket()

bool isc::dhcp::Iface::delSocket ( uint16_t sockfd )

Closes socket.

Closes socket and removes corresponding SocketInfo structure from an interface.

Parameters

sockfd socket descriptor to be closed/removed.

Returns: true if there was such socket, false otherwise

Definition at line 168 of file iface_mgr.cc.

References sockets_.

◆ getAddress4()

bool isc::dhcp::Iface::getAddress4 ( isc::asiolink::IOAddress & address ) const

Returns IPv4 address assigned to the interface.

This function looks for an IPv4 address assigned to the interface and returns it through the argument.

Parameters

[out] address IPv4 address assigned to the interface.

Returns: Boolean value which informs whether IPv4 address has been found for the interface (if true), or not (false).

Definition at line 224 of file iface_mgr.cc.

References getAddresses().

Here is the call graph for this function:

◆ getAddresses()

const AddressCollection & isc::dhcp::Iface::getAddresses ( ) const

inline

Returns all addresses available on an interface.

The returned addresses are encapsulated in the util::Optional class to be able to selectively flag some of the addresses as active (when optional value is specified) or inactive (when optional value is specified). If the address is marked as active, the IfaceMgr::openSockets4 method will open socket and bind to this address. Otherwise, it will not bind any socket to this address. This is useful when an interface has multiple IPv4 addresses assigned.

Care should be taken to not use this collection after Iface object ceases to exist. That is easy in most cases as Iface objects are created by IfaceMgr that is a singleton an is expected to be available at all time. We may revisit this if we ever decide to implement dynamic interface detection, but such fancy feature would mostly be useful for clients with wifi/vpn/virtual interfaces.

Returns: collection of addresses

Definition at line 254 of file iface_mgr.h.

References addrs_.

Referenced by getAddress4(), and hasAddress().

◆ getErrors()

Iface::ErrorBuffer const & isc::dhcp::Iface::getErrors ( ) const

Get the consistent list of error messages.

Returns: the list of messages

Definition at line 1989 of file iface_mgr.cc.

◆ getFullName()

std::string isc::dhcp::Iface::getFullName ( ) const

Returns full interface name as "ifname/ifindex" string.

Returns: string with interface name

Definition at line 124 of file iface_mgr.cc.

References ifindex_, and name_.

Referenced by setMac().

◆ getHWType()

uint16_t isc::dhcp::Iface::getHWType ( ) const

inline

Returns hardware type of the interface.

Returns: hardware type

Definition at line 234 of file iface_mgr.h.

References hardware_type_.

◆ getIndex()

unsigned int isc::dhcp::Iface::getIndex ( ) const

inline

Returns interface index.

Returns: interface index

Definition at line 219 of file iface_mgr.h.

References ifindex_.

◆ getMac()

const uint8_t * isc::dhcp::Iface::getMac ( ) const

inline

Returns pointer to MAC address.

Note: Returned pointer is only valid as long as the interface object that returned it.

Definition at line 205 of file iface_mgr.h.

References mac_.

◆ getMacLen()

size_t isc::dhcp::Iface::getMacLen ( ) const

inline

Returns MAC length.

Returns: length of MAC address

Definition at line 199 of file iface_mgr.h.

References mac_len_.

◆ getName()

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

inline

Returns interface name.

Returns: interface name

Definition at line 224 of file iface_mgr.h.

References name_.

Referenced by setActive().

◆ getPlainMac()

std::string isc::dhcp::Iface::getPlainMac ( ) const

Returns link-layer address a plain text.

Returns: MAC address as a plain text (string)

Definition at line 131 of file iface_mgr.cc.

References mac_, and mac_len_.

◆ getReadBuffer()

uint8_t * isc::dhcp::Iface::getReadBuffer ( )

inline

Returns the pointer to the buffer used for data reading.

The returned pointer is only valid during the lifetime of the object which returns it or until the buffer is resized. This function is meant to be used with socket API to gather data from the socket.

Returns: Pointer to the first element of the read buffer or NULL if the buffer is empty.

Definition at line 379 of file iface_mgr.h.

◆ getReadBufferSize()

size_t isc::dhcp::Iface::getReadBufferSize ( ) const

inline

Returns the current size of the socket read buffer.

Definition at line 387 of file iface_mgr.h.

◆ getSockets()

const SocketCollection & isc::dhcp::Iface::getSockets ( ) const

inline

Returns collection of all sockets added to interface.

When new socket is created with IfaceMgr::openSocket it is added to sockets collection on particular interface. If socket is opened by other means (e.g. function that does not use IfaceMgr::openSocket) it will not be available in this collection. Note that functions like IfaceMgr::openSocketFromIface use IfaceMgr::openSocket internally. The returned reference is only valid during the lifetime of the IfaceMgr object that returned it.

Returns: collection of sockets added to interface

Definition at line 347 of file iface_mgr.h.

References sockets_.

◆ getUnicasts()

const AddressCollection & isc::dhcp::Iface::getUnicasts ( ) const

inline

Returns a container of addresses the server should listen on.

Returns: address collection (may be empty)

Definition at line 366 of file iface_mgr.h.

References unicasts_.

◆ hasAddress()

bool isc::dhcp::Iface::hasAddress ( const isc::asiolink::IOAddress & address ) const

Check if the interface has the specified address assigned.

Parameters

address Address to be checked.

Returns: true if address is assigned to the interface, false otherwise.

Definition at line 240 of file iface_mgr.cc.

References getAddresses().

Referenced by addAddress().

Here is the call graph for this function:

◆ resizeReadBuffer()

void isc::dhcp::Iface::resizeReadBuffer ( const size_t new_size )

inline

Reallocates the socket read buffer.

Parameters

new_size New size of the buffer.

Definition at line 394 of file iface_mgr.h.

◆ setActive() [1/2]

void isc::dhcp::Iface::setActive ( const bool active )

Activates or deactivates all addresses for the interface.

This method marks all addresses on the interface active or inactive. If the address is marked inactive, the IfaceMgr::openSockets4 method will NOT open socket for this address.

Parameters

active A boolean flag which indicates that the addresses should be active (if true) or inactive (if false).

Definition at line 269 of file iface_mgr.cc.

References addrs_.

◆ setActive() [2/2]

void isc::dhcp::Iface::setActive	(	const isc::asiolink::IOAddress &	address,
		const bool	active )

Activates or deactivates address for the interface.

This method marks a specified address on the interface active or inactive. If the address is marked inactive, the IfaceMgr::openSockets4 method will NOT open socket for this address.

Parameters

address	An address which should be activated, deactivated.
active	A boolean flag which indicates that the specified address should be active (if true) or inactive (if false).

Exceptions

BadValue if specified address doesn't exist for the interface.

Definition at line 257 of file iface_mgr.cc.

References addrs_, getName(), and isc_throw.

Here is the call graph for this function:

◆ setFlags()

void isc::dhcp::Iface::setFlags ( uint64_t flags )

Sets flag_*_ fields based on bitmask value returned by OS.

Note: Implementation of this method is OS-dependent as bits have different meaning on each OS. We need to make it 64 bits, because Solaris uses 64, not 32 bits.

Parameters

flags bitmask value returned by OS in interface detection

◆ setHWType()

void isc::dhcp::Iface::setHWType ( uint16_t type )

inline

Sets up hardware type of the interface.

Parameters

type	hardware type

Definition at line 229 of file iface_mgr.h.

References hardware_type_.

◆ setMac()

void isc::dhcp::Iface::setMac	(	const uint8_t *	mac,
		size_t	macLen )

Sets MAC address of the interface.

Parameters

mac	pointer to MAC address buffer
macLen	length of mac address

Definition at line 145 of file iface_mgr.cc.

References getFullName(), isc_throw, mac_, mac_len_, and MAX_MAC_LEN.

Here is the call graph for this function:

Member Data Documentation

◆ addrs_

AddressCollection isc::dhcp::Iface::addrs_

protected

List of assigned addresses.

Definition at line 422 of file iface_mgr.h.

Referenced by addAddress(), countActive4(), delAddress(), getAddresses(), setActive(), and setActive().

◆ flag_broadcast_

bool isc::dhcp::Iface::flag_broadcast_

Flag specifies if selected interface is broadcast capable.

Definition at line 454 of file iface_mgr.h.

◆ flag_loopback_

bool isc::dhcp::Iface::flag_loopback_

Specifies if selected interface is loopback.

Todo: : Make those fields protected once we start supporting more than just Linux

Definition at line 441 of file iface_mgr.h.

◆ flag_multicast_

bool isc::dhcp::Iface::flag_multicast_

Flag specifies if selected interface is multicast capable.

Definition at line 451 of file iface_mgr.h.

◆ flag_running_

bool isc::dhcp::Iface::flag_running_

Flag specifies if selected interface is running (e.g.

cable plugged in, wifi associated).

Definition at line 448 of file iface_mgr.h.

◆ flag_up_

bool isc::dhcp::Iface::flag_up_

Specifies if selected interface is up.

Definition at line 444 of file iface_mgr.h.

◆ flags_

uint64_t isc::dhcp::Iface::flags_

Interface flags (this value is as is returned by OS, it may mean different things on different OSes).

Solaris based os have unsigned long flags field (64 bits). It is usually 32 bits, though.

Definition at line 460 of file iface_mgr.h.

◆ hardware_type_

uint16_t isc::dhcp::Iface::hardware_type_

protected

Hardware type.

Definition at line 434 of file iface_mgr.h.

Referenced by getHWType(), and setHWType().

◆ ifindex_

unsigned int isc::dhcp::Iface::ifindex_

protected

Interface index (a value that uniquely identifies an interface).

Definition at line 419 of file iface_mgr.h.

Referenced by getFullName(), and getIndex().

◆ inactive4_

bool isc::dhcp::Iface::inactive4_

Indicates that IPv4 sockets should (true) or should not (false) be opened on this interface.

Definition at line 464 of file iface_mgr.h.

◆ inactive6_

bool isc::dhcp::Iface::inactive6_

Indicates that IPv6 sockets should (true) or should not (false) be opened on this interface.

Definition at line 468 of file iface_mgr.h.

◆ mac_

uint8_t isc::dhcp::Iface::mac_[MAX_MAC_LEN]

protected

Link-layer address.

Definition at line 428 of file iface_mgr.h.

Referenced by Iface(), getMac(), getPlainMac(), and setMac().

◆ mac_len_

size_t isc::dhcp::Iface::mac_len_

protected

Length of link-layer address (usually 6).

Definition at line 431 of file iface_mgr.h.

Referenced by getMacLen(), getPlainMac(), and setMac().

◆ MAX_MAC_LEN

const unsigned int isc::dhcp::Iface::MAX_MAC_LEN = 20

static

Maximum MAC address length (Infiniband uses 20 bytes)

Definition at line 122 of file iface_mgr.h.

Referenced by setMac().

◆ name_

std::string isc::dhcp::Iface::name_

protected

Network interface name.

Definition at line 416 of file iface_mgr.h.

Referenced by addUnicast(), getFullName(), and getName().

◆ sockets_

SocketCollection isc::dhcp::Iface::sockets_

protected

Socket used to send data.

Definition at line 413 of file iface_mgr.h.

Referenced by addSocket(), closeSockets(), delSocket(), and getSockets().

◆ unicasts_

AddressCollection isc::dhcp::Iface::unicasts_

protected

List of unicast addresses the server should listen on.

Definition at line 425 of file iface_mgr.h.

Referenced by addUnicast(), clearUnicasts(), and getUnicasts().

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

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Address

◆ AddressCollection

◆ ErrorBuffer

◆ SocketCollection

Constructor & Destructor Documentation

◆ Iface()

◆ ~Iface()

Member Function Documentation

◆ addAddress()

◆ addError()

◆ addSocket()

◆ addUnicast()

◆ clearErrors()

◆ clearUnicasts()

◆ closeSockets() [1/2]

◆ closeSockets() [2/2]

◆ countActive4()

◆ delAddress()

◆ delSocket()

◆ getAddress4()

◆ getAddresses()

◆ getErrors()

◆ getFullName()

◆ getHWType()

◆ getIndex()

◆ getMac()

◆ getMacLen()

◆ getName()

◆ getPlainMac()

◆ getReadBuffer()

◆ getReadBufferSize()

◆ getSockets()

◆ getUnicasts()

◆ hasAddress()

◆ resizeReadBuffer()

◆ setActive() [1/2]

◆ setActive() [2/2]

◆ setFlags()

◆ setHWType()

◆ setMac()

Member Data Documentation

◆ addrs_

◆ flag_broadcast_

◆ flag_loopback_

◆ flag_multicast_

◆ flag_running_

◆ flag_up_

◆ flags_

◆ hardware_type_

◆ ifindex_

◆ inactive4_

◆ inactive6_

◆ mac_

◆ mac_len_

◆ MAX_MAC_LEN

◆ name_

◆ sockets_

◆ unicasts_