Netlink C++ Interface¶

Netlink Overview¶

Linux Netlink is a messaging system for intra-kernel as well as kernel and user-space processes to program the Linux network forwarding stack. Networking utilities like iproute2 and iptables use Netlink to program and gather networking information from the Linux Kernel. Introduced in RFC 3549, Netlink is a more flexible successor to ioctl. ioctl used system calls to program and poll the kernel for updates, however, Netlink is asynchronous and supports multicast communication: multiple user-space processes can listen to updates from the kernel. To program the kernel, a process can send a Netlink message(s) to the Linux socket and listen to responses.

Introduction¶

Each Netlink packet comprises of one or more Netlink messages. Each Netlink message has a header

struct nlmsghdr {
    __u32 nlmsg_len;    /* Length of message including header */
    __u16 nlmsg_type;   /* Type of message content */
    __u16 nlmsg_flags;  /* Additional flags */
    __u32 nlmsg_seq;    /* Sequence number */
    __u32 nlmsg_pid;    /* Sender port ID */
};

This library provides C++ APIs to interact with kernel for networking state via netlink protocol. The functionality is intentionally kept minimal to the needs of Open/R, but it can be extended. In Open/R, we primarily use the NETLINK_ROUTE family to manage the links, addresses, neighbor and route entries. nlmsghdr.nlmsg_type reflects the type of the Netlink operation. Based on the type of the message, each message has an ancillary netlink header whose fields on dependent on the type of the operation. Each message can also have a bunch of attributes and sub-attributes (mainly used for multiple next-hops for ECMP/UCMP). Below we describe the organization of code in this directory. Refer to inline code documentation in header files for more information.

Deep Dive¶

NetlinkTypes¶

Defines C++ classes to represent various routing information e.g. Address, Link, Route etc. This serves as data representation between application code and netlink C++ library.

NetlinkMessageBase¶

Defines base class that facilitates serialization and de-serialization of message exchange with linux kernel.

Reference: http://man7.org/linux/man-pages/man7/netlink.7.html

Addr/Link/Neighbor/Route¶

Specialization of netlink message for NETLINK_ROUTE (aka rtnetlink) family. It implements Addresses, Link, Neighbor and Route (IP, IPv6 & MPLS).

Reference: http://man7.org/linux/man-pages/man7/rtnetlink.7.html

For example, a sample message layout of RTM_NEWROUTE will be like:

Layout of sample RTM_NEWROUTE msg

NetlinkProtocolSocket¶

Implements send and receive netlink messages with the use of AF_NETLINK socket type. Also provides public APIs to get/add/del for Addresses, Link, Neighbor and Routes.

Unit Testing¶

Netlink code is exhaustively unit-tested. However to run unit-tests, you’ll need to run with sudo. Temporary route, link, address and neighbor entries will be created in the network. Hence it is best to run inside the container

For MPLS route unit-tests you’ll need to have MPLS enabled kernel with following sysctl configuration parameters.

Some unit-tests tries to add upto 100k routes and can consume significant amount of memory and time to run. So please be patient or disable those tests if you don’t want your system to scale to that number.

// Install kernel modules
sudo modprobe mpls_router
sudo modprobe mpls_iptunnel
sudo modprobe mpls_gso

// Configure sysctl
sysctl -w net.mpls.platform_labels=65536