netlink

netlink provides a Go-native interface to the Linux kernel’s netlink communication protocol, the mechanism user-space programs use to configure networking state such as interfaces, IP addresses, routes, and IPsec transforms. Rather than exposing raw netlink message encoding, it mirrors the command structure of the iproute2 CLI: operations like ip link add map to functions such as AddLink(), making the API approachable for anyone already familiar with Linux network administration.

The project began as a fork of the netlink code inside docker/libcontainer and was substantially rewritten for testability, performance, and broader coverage, including IPsec xfrm handling, traffic control (qdisc/class/filter), network namespaces, and device-link management. Because netlink communication requires elevated kernel privileges, most operations must run as root, and the library is used extensively by container runtimes, CNI plugins, and other low-level Linux networking tooling that needs precise, programmatic control over kernel network state.

What You Get

• High-level functions for link management (LinkAdd, LinkSetMaster, LinkByName) covering bridges, VLANs, VXLAN, bonds, and other virtual device types
• Address and route manipulation (AddrAdd, RouteAdd, RuleAdd) modeled directly on iproute2 semantics
• IPsec xfrm policy and state management for configuring kernel-level IPsec tunnels and transforms
• Traffic control primitives for qdiscs, classes, and filters to implement shaping and prioritization
• Network namespace support for creating and manipulating netns-scoped network configuration
• A lower-level nl subpackage exposing raw netlink message construction for cases the high-level API doesn’t yet cover

Common Use Cases

• Container runtimes and CNI plugins programmatically wiring up veth pairs, bridges, and namespace networking for containers
• Building custom network orchestration or SDN control-plane agents that need to reconcile kernel networking state
• Implementing VPN or IPsec tooling that configures xfrm policies and states directly from Go
• Writing infrastructure agents that inspect or modify routing tables and traffic-control queues at runtime

Under The Hood

Architecture The library is organized as a flat package exposing per-domain files (link.go, route.go, addr.go, rule.go, qdisc.go, xfrm_.go, conntrack_.go) that each define Go structs mirroring kernel networking objects and a matching set of Add/Del/List functions; a Handle type wraps a netlink socket so callers can either use package-level convenience functions against an implicit default handle or manage explicit handles for namespace-scoped or concurrent use. The real protocol work is isolated in the nl subpackage, which builds and parses raw netlink attribute (nl.RtAttr) and message structures, so the top-level package can stay focused on translating idiomatic Go calls into those low-level messages and decoding kernel responses back into typed structs. Platform variance is handled through Go build tags: _linux.go files contain the real syscall-backed implementation, while _unspecified.go counterparts provide non-Linux stubs, which is what lets the module still go build cleanly on macOS despite being fundamentally a Linux-only library.

Tech Stack Written in Go 1.23 with a deliberately small dependency surface: golang.org/x/sys for raw syscall and unix constants, the companion github.com/vishvananda/netns module for namespace handling, and stretchr/testify for test assertions. There is no external build tooling beyond the standard Go toolchain and a Makefile; CI (GitHub Actions) runs privileged tests against real kernel modules on Ubuntu runners in addition to a macOS build-only job that guards against missing build tags.

Code Quality The project has extensive test coverage — dozens of _test.go files at both the top level and inside nl, generally exercising real kernel behavior (tests run under sudo since netlink operations require root) rather than mocks, which is a meaningful commitment to integration-style correctness for a kernel-facing library. Error handling is explicit and idiomatic Go (returned errors, no panics in the primary API surface), naming follows standard Go conventions, and the CI pipeline enforces that tests pass with real privileged syscalls rather than just compiling. There’s no linter/formatter enforcement visible in CI beyond go vet-style implicit checks and no CONTRIBUTING guide, and comment density on individual files is moderate rather than exhaustive.

What Makes It Unique Most Go netlink implementations either stay at the raw-message level or cover only a narrow slice of kernel functionality; this library’s breadth — link types, routing, rules, qdiscs, xfrm/IPsec, conntrack, devlink, RDMA links, and network namespaces all under one cohesive iproute2-modeled API — combined with its adoption as a foundational dependency inside Docker and countless CNI/container-networking projects, is what distinguishes it. The design choice to keep the high-level API’s shape mirroring iproute2 command names specifically lowers the learning curve for engineers who already think in terms of ip link/ip route commands.