Implementation:ClickHouse ClickHouse Poco NetworkInterface

Knowledge Sources	ClickHouse Poco Documentation
Domains	Networking, System
Last Updated	2026-02-08 00:00 GMT

Overview

System network interface enumeration and configuration query for discovering and inspecting network adapters.

Description

The Poco `NetworkInterface` class provides a platform-independent API for querying system network interfaces. It enables enumeration of all network adapters, retrieval of interface properties (name, display name, MAC address, MTU), and inspection of bound IP addresses with their subnet masks and broadcast addresses.

The class supports querying interface capabilities (IP, IPv4, IPv6, broadcast, multicast), interface state (up, running, loopback, point-to-point), and can filter interfaces by various criteria. It's particularly useful for multicast operations and discovering local network configuration.

Usage

ClickHouse uses this vendored component to discover available network interfaces for binding servers to specific addresses, configuring multicast groups, and implementing network-aware functionality that adapts to the system's network configuration.

Code Reference

Source Location

• Repository: ClickHouse
• File: base/poco/Net/include/Poco/Net/NetworkInterface.h
• Lines: 1-367

Signature

class NetworkInterface {
public:
    typedef std::vector<NetworkInterface> List;
    typedef std::map<unsigned, NetworkInterface> Map;
    typedef Poco::Tuple<IPAddress, IPAddress, IPAddress> AddressTuple;
    typedef std::vector<AddressTuple> AddressList;
    typedef std::vector<unsigned char> MACAddress;

    enum AddressType {
        IP_ADDRESS,
        SUBNET_MASK,
        BROADCAST_ADDRESS
    };

    enum Type {
        NI_TYPE_ETHERNET_CSMACD,
        NI_TYPE_ISO88025_TOKENRING,
        NI_TYPE_PPP,
        NI_TYPE_SOFTWARE_LOOPBACK,
        NI_TYPE_ATM,
        NI_TYPE_IEEE80211,
        NI_TYPE_TUNNEL,
        NI_TYPE_OTHER
    };

    enum IPVersion {
        IPv4_ONLY,
        IPv6_ONLY,
        IPv4_OR_IPv6
    };

    NetworkInterface(unsigned index = NO_INDEX);
    NetworkInterface(const NetworkInterface& interfc);

    unsigned index() const;
    const std::string& name() const;
    const std::string& displayName() const;
    const std::string& adapterName() const;

    const IPAddress& firstAddress(IPAddress::Family family) const;
    const IPAddress& address(unsigned index = 0) const;
    void addAddress(const IPAddress& address);
    void addAddress(const IPAddress& address, const IPAddress& subnetMask,
                    const IPAddress& broadcastAddress);
    const AddressList& addressList() const;

    const IPAddress& subnetMask(unsigned index = 0) const;
    const IPAddress& broadcastAddress(unsigned index = 0) const;
    const IPAddress& destAddress(unsigned index = 0) const;

    const MACAddress& macAddress() const;
    unsigned mtu() const;
    Type type() const;

    bool supportsIP() const;
    bool supportsIPv4() const;
    bool supportsIPv6() const;
    bool supportsBroadcast() const;
    bool supportsMulticast() const;
    bool isLoopback() const;
    bool isPointToPoint() const;
    bool isRunning() const;
    bool isUp() const;

    static NetworkInterface forName(const std::string& name, bool requireIPv6 = false);
    static NetworkInterface forName(const std::string& name, IPVersion ipVersion);
    static NetworkInterface forAddress(const IPAddress& address);
    static NetworkInterface forIndex(unsigned index);
    static List list(bool ipOnly = true, bool upOnly = true);
    static Map map(bool ipOnly = true, bool upOnly = true);
};

Import

#include <Poco/Net/NetworkInterface.h>

I/O Contract

Input	Output
Interface name, index, or IP address	`NetworkInterface` object
Query filters (IP-only, up-only)	List or map of network interfaces
Interface query methods	Interface properties and capabilities

Interface Query Methods

Method	Description
`forName`	Find interface by name (e.g., "eth0")
`forAddress`	Find interface with specific IP address
`forIndex`	Find interface by system index
`list`	Get all interfaces as vector
`map`	Get all interfaces as map keyed by index

Usage Examples

// List all network interfaces
NetworkInterface::List interfaces = NetworkInterface::list();
for (const auto& iface : interfaces) {
    std::cout << "Interface: " << iface.name() << std::endl;
    std::cout << "  Display Name: " << iface.displayName() << std::endl;
    std::cout << "  Index: " << iface.index() << std::endl;
    std::cout << "  MTU: " << iface.mtu() << std::endl;

    // Print MAC address
    const auto& mac = iface.macAddress();
    std::cout << "  MAC: ";
    for (size_t i = 0; i < mac.size(); ++i) {
        if (i > 0) std::cout << ":";
        std::cout << std::hex << std::setw(2) << std::setfill('0')
                  << (int)mac[i];
    }
    std::cout << std::dec << std::endl;

    // Print IP addresses
    const auto& addrs = iface.addressList();
    for (const auto& addrTuple : addrs) {
        std::cout << "  IP: " << addrTuple.get<0>().toString() << std::endl;
        std::cout << "  Mask: " << addrTuple.get<1>().toString() << std::endl;
        std::cout << "  Broadcast: " << addrTuple.get<2>().toString() << std::endl;
    }
}

// Find specific interface by name
try {
    NetworkInterface eth0 = NetworkInterface::forName("eth0");
    if (eth0.supportsIPv4()) {
        IPAddress addr = eth0.firstAddress(IPAddress::IPv4);
        std::cout << "eth0 IPv4: " << addr.toString() << std::endl;
    }
} catch (NotFoundException& ex) {
    std::cerr << "Interface not found" << std::endl;
}

// Find interface for specific address
IPAddress myAddr("192.168.1.100");
try {
    NetworkInterface iface = NetworkInterface::forAddress(myAddr);
    std::cout << "Address " << myAddr.toString()
              << " is on interface " << iface.name() << std::endl;
} catch (NotFoundException& ex) {
    std::cerr << "No interface has this address" << std::endl;
}

// Get only running interfaces with IP
NetworkInterface::List activeInterfaces =
    NetworkInterface::list(true, true);

// Check interface capabilities
NetworkInterface iface = NetworkInterface::forName("eth0");
if (iface.supportsMulticast()) {
    std::cout << "Interface supports multicast" << std::endl;
}

if (iface.isLoopback()) {
    std::cout << "Loopback interface" << std::endl;
}

if (iface.isUp() && iface.isRunning()) {
    std::cout << "Interface is active" << std::endl;
}

// Map interfaces by index
NetworkInterface::Map ifaceMap = NetworkInterface::map();
for (const auto& pair : ifaceMap) {
    std::cout << "Index " << pair.first << ": "
              << pair.second.name() << std::endl;
}

Related Pages

• Principle:ClickHouse_ClickHouse_Network_Interface_Enumeration