Kea: isc::dhcp::Iface Class Reference

| Kea 3.0.0

isc::dhcp::Iface Class Reference

Represents a single network interface. More...

`#include <iface_mgr.h>`

Inheritance diagram for isc::dhcp::Iface:
[legend]

## 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 flag_broadcast_, flag_loopback_, flag_multicast_, flag_running_, flag_up_, flags_, hardware_type_, ifindex_, inactive4_, inactive6_, mac_, mac_len_, and name_.

## ◆ ~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_.

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

  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_.

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

## ◆ 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_.

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

## ◆ 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_.

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

## ◆ 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_.

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

## ◆ 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 isc::dhcp::PktFilterBPF::openSocket(), isc::dhcp::PktFilterInet6::openSocket(), isc::dhcp::PktFilterInet::openSocket(), isc::dhcp::PktFilterLPF::openSocket(), isc::dhcp::PktFilterBPF::receive(), isc::dhcp::PktFilterInet::receive(), isc::dhcp::PktFilterLPF::receive(), and 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.

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 387 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 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.

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

## ◆ 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.

Referenced by Iface(), and 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 441 of file iface_mgr.h.

Referenced by Iface(), 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 451 of file iface_mgr.h.

Referenced by Iface().

## ◆ 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.

Referenced by Iface().

## ◆ flag_up_

bool isc::dhcp::Iface::flag_up_

Specifies if selected interface is up.

Definition at line 444 of file iface_mgr.h.

Referenced by Iface().

## ◆ 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.

Referenced by Iface().

## ◆ hardware_type_

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

Hardware type.

Definition at line 434 of file iface_mgr.h.

Referenced by Iface(), 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 Iface(), 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.

Referenced by Iface().

## ◆ 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.

Referenced by Iface().

## ◆ 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 Iface(), 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 Iface(), 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:

- iface_mgr.h
- iface_mgr.cc