luigirizzo/netmap: High-Speed Packet I/O on Linux and FreeBSD

Why luigirizzo/netmap Exists Beyond Ordinary Sockets

luigirizzo/netmap targets applications that process raw network packets at high throughput. Its documented users include traffic generators, traffic sinks, monitors, loggers, software switches, software routers, generic middleboxes, and systems connecting virtual machines. These workloads differ from conventional server applications because they may need to move many packets per second while keeping protocol processing and per-packet overhead under direct control.

The repository includes VALE, an in-kernel Layer 2 software switch that uses the same API. It also contains example programs for common packet-processing tasks. `apps/pkt-gen.c` generates or receives traffic, `apps/bridge.c` connects interfaces, and `apps/vale-ctl.c` configures VALE ports. The kernel module includes a learning Ethernet bridge.

Netmap does not accelerate TCP by itself. The README is explicit that applications needing TCP acceleration must implement their own TCP/IP processing, possibly applying low-cost processing techniques. It is therefore a packet-processing foundation, not a transparent replacement for the normal networking stack. This boundary matters when evaluating it for an application whose performance depends mostly on TCP state management rather than raw frame throughput.

The Netmap API Data Path and Its Performance Trade-Offs

A netmap client receives a file descriptor that can be synchronized through `select()`. Through that descriptor, the application exchanges multiple packets per system call using device-independent memory-mapped buffers and descriptors. Drivers remain inside the kernel, but the data path is designed around I/O batching, efficient drivers, preallocated transmit and receive buffers, and memory-mapped buffers.

The README specifically rejects memory mapping as the sole reason for netmap's speed. It says a system does not obtain the same packet throughput and efficiency unless the other techniques are also present. That distinction rules out a simplistic description of netmap as merely `mmap` for network interfaces. The design depends on controlling the complete packet path.

Physical Ethernet performance requires netmap-aware drivers. Unmodified drivers can still provide access through the core module, but the README says this comes at much lower performance than using netmap-aware drivers. The documented driver list includes Intel ixgbe, ixl, i40e, e1000, e1000e, and igb, Realtek 8169, and Nvidia drivers. FreeBSD also documents native support for Chelsio 10G and 40G cards.

For virtual networking, QEMU has native netmap support through netmap ports, VALE ports, and netmap pipes. The repository also documents passing a netmap port into a QEMU VM. FreeBSD's `bhyve` hypervisor has native netmap support. These integration paths fit packet-heavy network functions better than a request for faster TCP connections on an otherwise conventional application.

Linux Build and First Traffic Test with pkt-gen

For Linux, the README directs users to the `./configure && make` build system in the `LINUX/` directory. The build must use headers matching the installed kernel. Some configurations also require full kernel sources, and the Linux driver build downloads Intel driver sources from SourceForge.

Change to the documented `LINUX/` build directory. To compile Netmap, VALE, and the supported Intel drivers, run the configuration command exactly as shown in the README. This also initiates the Intel driver source download:

./configure

A user who only needs Netmap and VALE can omit driver builds and rely on unmodified network drivers:

./configure --no-drivers

Build the kernel modules and sample applications after configuration:

make

Installation requires administrative privileges:

sudo make install

The Linux example applications are documented under `apps/`. The simplest first use is to replace `ix0` with an applicable netmap interface or VALE port and receive packets while printing statistics:

pkt-gen -i ix0 -f rx

To send a stream of 60-byte packets, run:

pkt-gen -i ix0 -f tx -l 60

A successful setup still depends on having a correctly built or loaded netmap module, a compatible driver path, and a valid interface name. If that prerequisite is absent, the examples cannot provide the documented packet path. The README does not give a generic verification command that can be copied across every supported kernel and driver combination.

Kernel-Specific Setup Boundaries for FreeBSD, Linux, and Windows

FreeBSD has a different adoption path. Netmap has been included since FreeBSD 10.x, and the README says FreeBSD users should use the FreeBSD source tree because it is mostly aligned with this repository. FreeBSD 11 includes netmap kernel support by default. If the running kernel configuration omits it, the documented change is to add `dev netmap` and rebuild the kernel:

dev netmap

Alternative standalone modules include netmap and several drivers, while example applications are located in the FreeBSD source tree under `src/tools/tools/netmap/`. This makes repository installation largely unnecessary for a supported FreeBSD setup.

Linux has the most involved documented build procedure in the README. `--kernel-dir` identifies a specific full source tree, while distribution packages can place headers and sources in separate directories. For that case, the documented invocation is:

./configure --kernel-sources=/a/b/c/linux-sources-A.B/ --kernel-dir=/a/b/c/linux-headers-A.B/

Additional Linux builds for e1000, veth, forcedeth, virtio-net, and r8169 require full kernel sources. The `--driver-suffix=-netmap` option changes generated module names, such as `e1000e-netmap` and `ixgbe-netmap`, allowing them to sit alongside original modules. This reduces naming collisions but adds kernel module selection and upgrade coordination.

The Windows port has a separate `WINDOWS/README.txt`. The README describes it as a port completed in summer 2015, left behind for years, and currently unmaintained. It should not be treated as equivalent to the documented Linux and FreeBSD paths.

Maintenance, Releases, and BSD-2-Clause Upgrade Cost

The repository is not archived, and its last push was on 2026-08-08. That indicates source activity, but it does not by itself establish compatibility with every kernel or NIC named in the README. The only listed release is v11.3, dated 2017-01-23, which is much older than the last push. The release record and repository activity therefore point to two different questions: whether code has changed, and whether a packaged release has been issued for the target environment.

Netmap is not a conventional userspace package with a small dependency update. Its Linux upgrade path can involve rebuilding kernel modules, matching kernel headers, obtaining full kernel sources, and possibly downloading or patching NIC drivers. Replacing a loaded networking module also affects the system-level path rather than one application library. The README's optional driver suffix offers module coexistence, but operators still need to select the intended driver and ensure that applications target the resulting netmap interface.

The repository license is BSD-2-Clause. That is favorable for source redistribution and integration under the license terms, but this review does not interpret the license as legal advice. Applications must still include the required copyright and license notices when redistributing covered code. Windows support carries a separate operational concern because the README labels that port unmaintained.

Compared with a standard socket application, adopting netmap means accepting responsibility for a kernel-facing framework and its hardware compatibility. Compared with ordinary Linux bridges and `libpcap`, the gain is a purpose-built packet path, while the cost is driver, kernel, and API integration work.

Where Netmap Is the Wrong Tool or VALE Is the Better Choice

Netmap is the wrong choice when the application only needs ordinary TCP or UDP networking and gains nothing from direct packet handling. The README states that netmap alone does not accelerate TCP. Adding netmap to a workload that still relies on a complete protocol stack can introduce installation and driver complexity without solving the stated protocol-processing cost.

It is also unsuitable when only unmodified drivers are available and the workload requires the high-throughput physical-port behavior described in the README. Access may exist, but performance will be substantially lower than with netmap-aware drivers. That distinction should be treated as an architectural constraint, not a minor configuration difference.

VALE addresses a narrower and more specific problem: an in-kernel Layer 2 software switch. It is relevant when traffic must be connected through configurable VALE ports, learning bridge behavior, pipes, or host and VM interconnection. It does not replace netmap for an application that needs to generate, inspect, or modify packets through the userspace API.

The README also points to `netmap-libpcap` for running existing libpcap clients over netmap and `netmap-ipfw` for userspace `ipfw` and `dummynet`. Those projects represent different adoption strategies. Existing libpcap applications can retain their application code through the netmap-enabled library, while a direct netmap client requires more work against the native API. The correct choice depends on whether performance requires native access or whether existing libpcap compatibility is more valuable.

Editorial conclusion

Developers should adopt luigirizzo/netmap when their application genuinely needs a direct raw-packet data path and can support its kernel and driver requirements. They should not adopt it merely to accelerate ordinary TCP traffic. Before adoption, verify compatibility between the target kernel, selected NIC driver, build sources, loaded netmap module, and the required packet interface.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-2-Clause
3. luigirizzo/netmap on GitHub
4. README
5. Releases