nox-netlink#

Netlink and rtnetlink message codec (RFC 3549), built on the wire codec library.

Installation#

Install with opam:

$ opam install nox-netlink

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install nox-netlink

Overview#

nox-netlink encodes and decodes the netlink message framing (nlmsghdr) and the rtnetlink link and address payloads and attributes used to configure network interfaces. It is I/O-free: it turns messages to and from bytes and never opens a socket, leaving the AF_NETLINK transport to the caller (which needs a small C stub, since socket(AF_NETLINK, ...) is not exposed by the OCaml Unix module).

Netlink uses host byte order. Every Linux architecture in common use is little-endian, and this codec encodes little-endian.

The nox-netlink.eio sublibrary (module Rtnl) is the I/O layer over this codec: it opens the AF_NETLINK socket and runs typed link and address operations (link_add_bridge, link_set_master, addr_add, ...), replacing shell-outs to ip and nsenter. The core library here stays codec-only and has no eio dependency.

Features#

• nlmsghdr framing, with the length field derived on encode.
• rtnetlink payloads: ifinfomsg (links) and ifaddrmsg (addresses).
• rtattr attributes with 4-byte (RTA_ALIGN) framing, plus typed value helpers (u8/u16/u32/string).
• The nlmsgerr ACK/error payload, for confirming a request succeeded.
• Multipart dump parsing (list_of_string), advancing past each message's 4-byte-aligned length.
• Named constants for message types, flags, address families, interface flags and the common IFLA_*/IFA_* attribute codes.

Usage#

(* a "dump all links" request *)
let dump_links ~seq =
  Netlink.to_string
    {
      Netlink.header =
        {
          length = 0 (* filled in by to_string *);
          typ = Netlink.Type.getlink;
          flags = Netlink.Flags.(request lor dump);
          seq;
          pid = 0;
        };
      payload =
        Netlink.Ifinfomsg.to_string
          { family = Netlink.Af.unspec; typ = 0; index = 0; flags = 0; change = 0 };
    }

Related Work#

• netlink - OCaml bindings to the C libnl library. nox-netlink instead implements the wire format directly in OCaml, with no libnl dependency, and leaves the socket to the caller.
• mnl (C) - the minimalistic userspace netlink library this codec's framing mirrors.
• The Go vishvananda/netlink and Rust rtnetlink crates, which similarly build rtnetlink messages by hand rather than via libnl.

License#

ISC License. See LICENSE.md for details.