Self-hosted service
vishvananda/netlink avatar
vishvananda/netlink

vishvananda/netlink: an API named after iproute2, and a queue-length trap in the constructor

Simple netlink library for go.

3,331 stars851 forksGoApache-2.0

At a glance

What is it?
A Go library for the interface Linux user-space programs use to talk to the kernel, whose function names mirror the command line tool. The most useful line in its README is a warning about a transmit queue field, and its Makefile re-executes tests under sudo.
Who is it for?
Use vishvananda/netlink if you are writing Go that has to create interfaces, bridges, addresses, routes or IPsec state on a Linux host, and you would rather not hand-assemble netlink messages. The API shape is the reason: functions are named after the command line you would have typed anyway, so the mapping is guessable.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 16, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • vishvananda/netlink3,331 ★ · +22
Star history
Repository2026-09-242026-11-16
vishvananda/netlink3.3k3.3k

22 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The API is named after iproute2, on purpose

Netlink is the interface a user-space program on Linux uses to talk to the kernel. This library wraps it, and the wrapping philosophy is stated in the first paragraph.

Raw netlink messages are described as inscrutable at best, so the library aims to give you an API loosely modelled on the command line tool that ships with Linux. The consequence is concrete and checkable: an action you would perform with a link add command in a shell is performed here by a function with the same name in camel case.

The smallest complete example builds a bridge and enslaves an interface to it:

go
la := netlink.NewLinkAttrs()
la.Name = "foo"
mybridge := &netlink.Bridge{LinkAttrs: la}
err := netlink.LinkAdd(mybridge)

eth1, _ := netlink.LinkByName("eth1")
netlink.LinkSetMaster(eth1, mybridge)

Four lines of setup, three of them naming something you would type into a shell. That is the whole bet. It is not the only way to wrap a binary protocol, and it means the library's surface changes when the command line tool does. But it means somebody who knows the shell already knows roughly half the API, and it means documentation for the tool is documentation for the library.

The other thing the first paragraph tells you is about privileges. Netlink communication requires elevated privileges, so in most cases the code has to run as root. That shapes how you deploy anything built on it, and it is also why the test setup does what it does.

It started as a fork of a container runtime's netlink code

The provenance is stated plainly, which is rarer than it should be.

The library began its life as a fork of the netlink functionality inside a well known container runtime library, and it was then heavily rewritten for three named reasons: testability, performance, and the addition of functionality the original did not have, with IPsec transform handling given as the example.

Those three reasons map onto the shape of the repository. Testability is why there is a test file beside almost every source file, and why the build has a target whose only job is to re-run the test binary under elevated privileges. Performance explains the direct use of the system call layer rather than a wrapper. The IPsec addition explains why the dependency tree includes transform handling rather than stopping at links and addresses.

So when you read a function and find it handles a case the shell tool would not, the fork's history is usually the answer. It also means the API inherited some of the original's assumptions, which is a fair thing to keep in mind when something behaves unexpectedly.

The constructor exists for one field, and the note explains why

The clearest piece of documentation in the repository is a note about a constructor, and it is worth reproducing because the failure it prevents is silent.

Link attributes are normally built with a constructor that fills in defaults. At the moment it sets one field: the transmit queue length, to a negative value, so that the kernel applies its own default instead of the library choosing one.

Now the trap. If you build the struct directly with just a name, that field will be zero unless you set it yourself. Zero is a real value, not a sentinel, so the kernel will accept it and give you a device with a transmit queue length of zero rather than an error.

The note shows the two forms side by side: the constructor, and a literal that sets the field to a specific number.

This is the kind of documentation that only exists when somebody has been bitten. It is also a good illustration of the general hazard with this library, which is that most mistakes are not reported back to you as failures.

One file per subsystem, plus a stub for other platforms

The repository is a long flat list of files, and the naming pattern is the whole architecture.

Each subsystem gets a platform-neutral file, a Linux implementation, and a stub for builds on other platforms. Addresses, links, handles, connection tracking, device link, the chain and filter families, traffic control classes and queues all appear three times over, with a test file beside each.

The stubs are what let the package compile on a non-Linux machine even though none of the functionality exists there. That matters for two audiences: developers on a Mac or a Windows machine can build and run tests for the parts that are platform neutral, and continuous integration can run a matrix without excluding those platforms.

The breadth of the file list is also the honest measure of scope. Beyond the familiar link and address operations there is bridge handling, traffic control classes, queues, filters and chains, a small subset of the device offload configuration across several files, generic netlink, connection tracking, load balancing and distribution kernel socket options, socket diagnostics, firewall rule sets and offload acceleration. That is a library that covers a lot of surface area thinly rather than a few things well.

The tests re-execute themselves under sudo

The build file contains one trick worth understanding, and it explains why the test dependencies exist at all.

Each package's tests are run through a flag that tells the test binary to re-execute itself under elevated privileges, rather than running the whole suite as root. That is a meaningfully better arrangement: the test process still starts as your user, and only the inner invocation is privileged.

The rest of the recipe is equally considered. Four-way parallelism and a sixty second timeout are applied per package rather than globally, so one slow package cannot consume the whole budget. Formatting is part of the test target rather than a separate target, and it fails if any file in the package differs from the formatter's output. The default goal is the test target, so a bare invocation of the build tool runs everything.

And the dependencies are fetched by the build itself rather than assumed present, with a small recursive deduplication helper in the make file so a shared dependency is fetched once.

There is also a second directory in the build's list besides the root, so the suite covers more than the root package.

Three dependencies, one of them only for tests

The dependency list is short enough to read in one breath, and each entry has a job.

One is the system call layer, which is how the library reaches the kernel without an intermediate binding. One is a testing assertion library. And one is the author's own small library for creating network namespaces, which is a test dependency: it lets a test build an isolated network environment to make its changes in rather than touching the machine's real configuration.

Three indirect dependencies come along with the assertion library.

So the total surface is one syscall wrapper plus two testing tools. For a library that talks to a kernel interface, that is a good sign, and it is also what makes the library easy to vendor into a build that already has a policy about what it will pull in.

One detail is worth a second look. The system call layer is pinned to a version from years ago while the module itself declares a much newer language version. That does not break anything on its own, since the pinned release still supports the declared version, but it does tell you the dependency floor was set once and not revisited, which is the kind of thing a security audit will notice.

The high-level interface is explicitly incomplete

The last section of the readme is titled future work, and it is the most honest thing in the documentation.

It says many pieces of netlink are not yet fully supported in the high-level interface, and that aspects of virtually all the high-level objects do not exist. So the API you see in the examples, links and addresses, is the finished part of a much larger protocol.

What follows is the useful part. The underlying primitives are largely there, so the remaining work is putting the right fields into the high-level objects and making sure they are serialised and deserialised correctly in the add and list methods. That is a mapping and correctness problem, not a protocol problem, which is why the project expects it to be tractable.

Two specific gaps are named: routing rules are not in place, and some of the more advanced link types are missing. So if your use case is policy routing or an exotic device type, you should find out now whether you will be writing netlink messages yourself.

The section closes on a note of confidence in the existing structure and tests, which is the argument that new contributors will have somewhere to start.

Editorial conclusion

Use vishvananda/netlink if you are writing Go that has to create interfaces, bridges, addresses, routes or IPsec state on a Linux host, and you would rather not hand-assemble netlink messages. The API shape is the reason: functions are named after the command line you would have typed anyway, so the mapping is guessable. Skip it if you only read network state, since that is a smaller problem, and do not expect the high-level interface to be complete, because the project says plainly that large parts of it do not exist yet and that you will sometimes need the low-level path. Before you write code against it, read the constructor note about transmit queue lengths, because getting that wrong produces a device with a zero length queue rather than an error, and expect every call to need elevated privileges.

Frequently asked questions

What is the vishvananda/netlink Go library?

A library for the netlink interface that Linux user-space programs use to communicate with the kernel, covering interfaces, addresses, routes and IPsec configuration. It provides an API loosely modelled on the iproute2 command line, and netlink communication needs elevated privileges, so the code usually runs as root.

Why do netlink link examples use a constructor instead of a struct literal?

Because the constructor sets the transmit queue length field to a negative value so the kernel applies its own default. A plain struct literal with just a name leaves that field at zero, which the kernel accepts as a real value, so the queue length is wrong rather than reported as an error.

Where did the vishvananda/netlink library come from?

It began as a fork of the netlink functionality in a container runtime library and was heavily rewritten for testability, for performance, and to add functionality the original lacked, with IPsec transform handling named as an example.

How are the netlink tests run?

Through the build file's test target, which checks formatting first and then runs each package's tests with the test binary re-executed under sudo, four tests in parallel and a sixty second timeout per package. Dependencies are fetched by the build itself, and a testing library for network namespaces is required.

Is the netlink high-level interface complete?

No, and the README says so directly: many pieces are not fully supported and aspects of virtually all the high-level objects do not exist yet, although the low-level primitives are largely in place. Routing rules and some advanced link types are named as missing.

Official sources

  1. Issues
  2. License: Apache-2.0
  3. README
  4. Releases
  5. vishvananda/netlink on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/vishvananda-netlink.svg)](https://hysenlabs.com/projects/vishvananda-netlink)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/vishvananda-netlink.svg)](https://hysenlabs.com/projects/vishvananda-netlink)

Was this useful?