Kea  2.1.2-git
isc::dhcp::Iface Class Reference

Represents a single network interface. More...

#include <iface_mgr.h>

+ Inheritance diagram for isc::dhcp::Iface:

Public Types

typedef util::Optional< asiolink::IOAddressAddress
 Address type. More...
 
typedef std::list< AddressAddressCollection
 Type that defines list of addresses. More...
 
typedef std::list< SocketInfoSocketCollection
 Type that holds a list of socket information. More...
 

Public Member Functions

 Iface (const std::string &name, unsigned int ifindex)
 Iface constructor. More...
 
 ~Iface ()
 Destructor. More...
 
void addAddress (const isc::asiolink::IOAddress &addr)
 Adds an address to an interface. More...
 
void addSocket (const SocketInfo &sock)
 Adds socket descriptor to an interface. More...
 
void addUnicast (const isc::asiolink::IOAddress &addr)
 Adds unicast the server should listen on. More...
 
void clearUnicasts ()
 Removes any unicast addresses. More...
 
void closeSockets ()
 Closes all open sockets on interface. More...
 
void closeSockets (const uint16_t family)
 Closes all IPv4 or IPv6 sockets. More...
 
unsigned int countActive4 () const
 Returns a number of activated IPv4 addresses on the interface. More...
 
bool delAddress (const isc::asiolink::IOAddress &addr)
 Deletes an address from an interface. More...
 
bool delSocket (uint16_t sockfd)
 Closes socket. More...
 
bool getAddress4 (isc::asiolink::IOAddress &address) const
 Returns IPv4 address assigned to the interface. More...
 
const AddressCollectiongetAddresses () const
 Returns all addresses available on an interface. More...
 
std::string getFullName () const
 Returns full interface name as "ifname/ifindex" string. More...
 
uint16_t getHWType () const
 Returns hardware type of the interface. More...
 
int getIndex () const
 Returns interface index. More...
 
const uint8_t * getMac () const
 Returns pointer to MAC address. More...
 
size_t getMacLen () const
 Returns MAC length. More...
 
std::string getName () const
 Returns interface name. More...
 
std::string getPlainMac () const
 Returns link-layer address a plain text. More...
 
uint8_t * getReadBuffer ()
 Returns the pointer to the buffer used for data reading. More...
 
size_t getReadBufferSize () const
 Returns the current size of the socket read buffer. More...
 
const SocketCollectiongetSockets () const
 Returns collection of all sockets added to interface. More...
 
const AddressCollectiongetUnicasts () const
 Returns a container of addresses the server should listen on. More...
 
bool hasAddress (const isc::asiolink::IOAddress &address) const
 Check if the interface has the specified address assigned. More...
 
void resizeReadBuffer (const size_t new_size)
 Reallocates the socket read buffer. More...
 
void setActive (const isc::asiolink::IOAddress &address, const bool active)
 Activates or deactivates address for the interface. More...
 
void setActive (const bool active)
 Activates or deactivates all addresses for the interface. More...
 
void setFlags (uint64_t flags)
 Sets flag_*_ fields based on bitmask value returned by OS. More...
 
void setHWType (uint16_t type)
 Sets up hardware type of the interface. More...
 
void setMac (const uint8_t *mac, size_t macLen)
 Sets MAC address of the interface. More...
 

Public Attributes

bool flag_broadcast_
 Flag specifies if selected interface is broadcast capable. More...
 
bool flag_loopback_
 Specifies if selected interface is loopback. More...
 
bool flag_multicast_
 Flag specifies if selected interface is multicast capable. More...
 
bool flag_running_
 Flag specifies if selected interface is running (e.g. More...
 
bool flag_up_
 Specifies if selected interface is up. More...
 
uint64_t flags_
 Interface flags (this value is as is returned by OS, it may mean different things on different OSes). More...
 
bool inactive4_
 Indicates that IPv4 sockets should (true) or should not (false) be opened on this interface. More...
 
bool inactive6_
 Indicates that IPv6 sockets should (true) or should not (false) be opened on this interface. More...
 

Static Public Attributes

static const unsigned int MAX_MAC_LEN = 20
 Maximum MAC address length (Infiniband uses 20 bytes) More...
 

Protected Attributes

AddressCollection addrs_
 List of assigned addresses. More...
 
uint16_t hardware_type_
 Hardware type. More...
 
int ifindex_
 Interface index (a value that uniquely identifies an interface). More...
 
uint8_t mac_ [MAX_MAC_LEN]
 Link-layer address. More...
 
size_t mac_len_
 Length of link-layer address (usually 6). More...
 
std::string name_
 Network interface name. More...
 
SocketCollection sockets_
 Socket used to send data. More...
 
AddressCollection unicasts_
 List of unicast addresses the server should listen on. More...
 

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

Address type.

Definition at line 125 of file iface_mgr.h.

◆ AddressCollection

Type that defines list of addresses.

Definition at line 128 of file iface_mgr.h.

◆ 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
namename of the interface
ifindexinterface index (unique integer identifier)
Exceptions
BadValuewhen name is empty.

Definition at line 63 of file iface_mgr.cc.

References isc_throw, and mac_.

◆ ~Iface()

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

Destructor.

Definition at line 151 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
addraddress to be added

Definition at line 250 of file iface_mgr.cc.

◆ addSocket()

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

Adds socket descriptor to an interface.

Parameters
sockSocketInfo structure that describes socket.

Definition at line 318 of file iface_mgr.h.

Referenced by isc::dhcp::IfaceMgr::openSocket4().

◆ addUnicast()

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

Adds unicast the server should listen on.

Exceptions
BadValueif specified address is already defined on interface
Parameters
addrunicast address to listen on

Definition at line 213 of file iface_mgr.cc.

References isc_throw, and name_.

◆ 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 350 of file iface_mgr.h.

◆ closeSockets() [1/2]

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

Closes all open sockets on interface.

Definition at line 77 of file iface_mgr.cc.

◆ 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
familytype of the sockets to be closed (AF_INET or AF_INET6)
Exceptions
BadValueif 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.

◆ 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
addraddress 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
sockfdsocket descriptor to be closed/removed.
Returns
true if there was such socket, false otherwise

Definition at line 169 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]addressIPv4 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.

◆ 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 251 of file iface_mgr.h.

Referenced by isc::dhcp::CfgIface::reset().

◆ 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 231 of file iface_mgr.h.

Referenced by isc::dhcp::PktFilterLPF::send(), and isc::dhcp::PktFilterBPF::send().

◆ getIndex()

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

◆ 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 202 of file iface_mgr.h.

Referenced by isc::dhcp::PktFilterLPF::send(), and isc::dhcp::PktFilterBPF::send().

◆ getMacLen()

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

Returns MAC length.

Returns
length of MAC address

Definition at line 196 of file iface_mgr.h.

Referenced by isc::dhcp::PktFilterLPF::send(), and isc::dhcp::PktFilterBPF::send().

◆ getName()

◆ 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 376 of file iface_mgr.h.

Referenced by isc::dhcp::PktFilterBPF::receive().

◆ getReadBufferSize()

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

Returns the current size of the socket read buffer.

Definition at line 384 of file iface_mgr.h.

Referenced by isc::dhcp::PktFilterBPF::receive().

◆ 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 344 of file iface_mgr.h.

◆ 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 363 of file iface_mgr.h.

◆ hasAddress()

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

Check if the interface has the specified address assigned.

Parameters
addressAddress to be checked.
Returns
true if address is assigned to the interface, false otherwise.

Definition at line 240 of file iface_mgr.cc.

◆ resizeReadBuffer()

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

Reallocates the socket read buffer.

Parameters
new_sizeNew size of the buffer.

Definition at line 391 of file iface_mgr.h.

Referenced by isc::dhcp::PktFilterBPF::openSocket().

◆ setActive() [1/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
addressAn address which should be activated, deactivated.
activeA boolean flag which indicates that the specified address should be active (if true) or inactive (if false).
Exceptions
BadValueif specified address doesn't exist for the interface.

Definition at line 255 of file iface_mgr.cc.

References isc_throw.

Referenced by isc::dhcp::CfgIface::reset().

◆ setActive() [2/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
activeA boolean flag which indicates that the addresses should be active (if true) or inactive (if false).

Definition at line 268 of file iface_mgr.cc.

◆ 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
flagsbitmask 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
typehardware type

Definition at line 226 of file iface_mgr.h.

◆ setMac()

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

Sets MAC address of the interface.

Parameters
macpointer to MAC address buffer
macLenlength 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 406 of file iface_mgr.h.

Referenced by delAddress().

◆ flag_broadcast_

bool isc::dhcp::Iface::flag_broadcast_

Flag specifies if selected interface is broadcast capable.

Definition at line 438 of file iface_mgr.h.

Referenced by isc::dhcp::PktFilterInet::openSocket().

◆ 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 425 of file iface_mgr.h.

Referenced by isc::dhcp::PktFilterBPF::openSocket(), isc::dhcp::PktFilterBPF::receive(), and isc::dhcp::PktFilterBPF::send().

◆ flag_multicast_

bool isc::dhcp::Iface::flag_multicast_

Flag specifies if selected interface is multicast capable.

Definition at line 435 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 432 of file iface_mgr.h.

◆ flag_up_

bool isc::dhcp::Iface::flag_up_

Specifies if selected interface is up.

Definition at line 428 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 444 of file iface_mgr.h.

◆ hardware_type_

uint16_t isc::dhcp::Iface::hardware_type_
protected

Hardware type.

Definition at line 418 of file iface_mgr.h.

◆ ifindex_

int isc::dhcp::Iface::ifindex_
protected

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

Definition at line 403 of file iface_mgr.h.

Referenced by getFullName().

◆ inactive4_

bool isc::dhcp::Iface::inactive4_

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

Definition at line 448 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 452 of file iface_mgr.h.

◆ mac_

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

Link-layer address.

Definition at line 412 of file iface_mgr.h.

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

◆ mac_len_

size_t isc::dhcp::Iface::mac_len_
protected

Length of link-layer address (usually 6).

Definition at line 415 of file iface_mgr.h.

Referenced by 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 400 of file iface_mgr.h.

Referenced by getFullName().

◆ sockets_

SocketCollection isc::dhcp::Iface::sockets_
protected

Socket used to send data.

Definition at line 397 of file iface_mgr.h.

Referenced by closeSockets(), and delSocket().

◆ unicasts_

AddressCollection isc::dhcp::Iface::unicasts_
protected

List of unicast addresses the server should listen on.

Definition at line 409 of file iface_mgr.h.


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