F-Stack: a user space TCP/IP stack on DPDK for services that outgrow the Linux kernel

The problem F-Stack is aimed at

The README opens with a specific claim: as network interface cards got faster, packet processing inside the Linux kernel became the bottleneck. Its list of causes is concrete: packet copying between kernel and user space, thread scheduling, system calls, and interrupts. F-Stack's answer is kernel bypass, where Linux handles only control flow and all data streams are processed in user space.

The audience follows from that. F-Stack is for engineers running services whose throughput is limited by the kernel's network path rather than by their own application logic, and who control the machine enough to hand a network card over to a user space process. The project's history describes exactly that situation: Tencent Cloud DNSPod's authoritative DNS server moved from Gigabit to 10-Gigabit Ethernet at the end of 2012, and the team chose DPDK over staying on the Linux stack. The README also states that HttpDNS, a COS access module and a CDN access module in Tencent Cloud use F-Stack. Those are high-connection-count, latency-sensitive services, not general web applications.

FreeBSD's TCP/IP stack, lifted into user space

The mechanism has three layers. DPDK takes packets directly from the NIC, bypassing the kernel driver. On top of that sits the FreeBSD TCP/IP stack, which the README says was ported from FreeBSD 13.0 stable, with "a great amount of irrelevant features" cut. The team's stated reason for porting rather than writing their own is cost: maintaining a complete high performance stack in house would have been too expensive, and a port lets them inherit future FreeBSD improvements. The README credits libplebnet and libuinet for making that work easier.

Above the stack, F-Stack offers two interfaces. One is a micro thread (coroutine) API, described as a way for stateful applications to get high performance "without processing complex asynchronous logic". The other is an Epoll/Kqueue interface, which is the migration path for software that already speaks epoll. The repository layout reflects the split: example/main_epoll.c, example/echo_client_fstack_epoll.c and example/epoll_test_fstack.c sit alongside example/main.c and example/main_zc.c, and there is an adapter/ directory holding integrations for mature applications. The README names Nginx and Redis as supported, and says the multi-process architecture is meant to be easy to extend.

The performance figures in the README are the project's own: 10 million concurrent connections, 5 million RPS, 1 million CPS, and 0.6 million RPS with a single 10GE port for the original user space stack. Treat those as vendor numbers measured on the vendor's hardware, not as a baseline you should expect on yours.

Installing F-Stack and running the example server

The README's Quick Start is a shell sequence, and it is not short. It clones the repository into /data/f-stack, installs numactl-devel or libnuma-dev, installs pyelftools for DPDK's Python scripts, then builds DPDK with meson and ninja. On FreeBSD the dependency line is different (meson, pkgconf, py38-pyelftools), so the platform you build on changes the commands you run.

mkdir -p /data/f-stack
git clone https://github.com/F-Stack/f-stack.git /data/f-stack
cd f-stack
cd dpdk/
meson setup -Denable_kmods=true build
ninja -C build
ninja -C build install

After the build, the kernel-side preparation begins. Hugepages are allocated through sysfs, a hugetlbfs mount is created at /mnt/huge, and ASLR is turned off because the README states it is necessary in multiple process mode. Then the NIC is unbound from its kernel driver and bound to igb_uio.

echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
mkdir /mnt/huge
mount -t hugetlbfs nodev /mnt/huge
echo 0 > /proc/sys/kernel/randomize_va_space
modprobe uio
insmod /data/f-stack/dpdk/build/kernel/linux/igb_uio/igb_uio.ko
python dpdk-devbind.py --status
ifconfig eth0 down
python dpdk-devbind.py --bind=igb_uio eth0

The README notes that igb_uio is about 5 percent more efficient than vfio-pci, which is why the example keeps using it. That line is worth reading twice, because it is also the reason the setup needs a custom kernel module and a driver unbind rather than a safer device passthrough configuration. On Ubuntu the README warns to install gawk instead of the default mawk, and to upgrade pkg-config if the version is below 0.28. F-Stack's own dependencies are gcc, make and libssl-dev on Ubuntu. The repository ships a config.ini at the top level and a start.sh, which is where the runtime configuration and launch path live; the README excerpt does not document their keys, so read those files directly before running anything. The example/ directory is the first real target: it contains main.c, main_epoll.c, echo_server.py and echo_client_fstack.c, so a working echo test is the natural first use.

The NIC you give up, and the debugging you lose

The cost of kernel bypass is stated plainly by the setup itself. You run ifconfig eth0 down and bind the port to igb_uio. From that moment the kernel no longer owns that NIC. If your service also needs to talk to the host over the same interface, or if you want tcpdump, iptables, or the kernel's routing table on that port, F-Stack is the wrong tool. The README's own instructions assume a dedicated port on a dedicated machine.

Other constraints follow. Hugepages must be reserved before the process starts, and ASLR must be off for the multi-process mode. That is a host-level setting, not an application setting, so it affects everything else running on the box. The build is multi-stage: DPDK first, then F-Stack, with a kernel module in between, which means a kernel upgrade can invalidate the module you just built. The README does not document rollback, and it does not describe how to return a port to the kernel driver after a failed run; you are expected to know that dpdk-devbind.py can bind it back. Finally, the interface choice matters. If your application is built on an asynchronous framework, the Epoll/Kqueue layer is the path of least resistance. If it is a stateful service, the coroutine API is the reason to pick F-Stack over a bare DPDK packet pipeline, because it keeps the blocking-style code you already have.

F-Stack against raw DPDK and against Seastar

The closest comparison is raw DPDK. DPDK gives you packet queues, memory pools and poll-mode drivers, but no TCP. On bare DPDK you write your own transport, or you use a higher-level framework. F-Stack's difference is that it brings a complete, mature TCP/IP stack (FreeBSD 13.0 stable, per the README) plus an epoll-compatible surface, so a program that already uses epoll can be moved over with far less rewriting than a from-scratch DPDK design would require. That is the trade: you accept the porting work of a FreeBSD stack and its configuration, and in return you do not implement congestion control, timers or socket semantics yourself.

Seastar takes the opposite approach. It is a C++ framework built around its own futures and share-nothing per-core model, and applications are written against its programming model from the start. F-Stack tries to meet existing applications where they are, through Epoll/Kqueue and coroutines, and the adapter/ directory for Nginx and Redis is the clearest expression of that intent. If you are writing a new service from scratch in C++ and are willing to adopt a new concurrency model, Seastar's model is more coherent. If you have a working C service on epoll and want it to stop being kernel-bound, F-Stack's compatibility layer is the shorter path.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-23. Releases are not frequent: v1.25 and 1.21.6 were both published on 2025-11-04, after v.1.21.5 on 2024-10-18. That cadence matters for planning, because F-Stack tracks two upstreams at once. Its TCP/IP stack is a port of FreeBSD 13.0 stable, and its packet layer is DPDK. An upgrade means re-syncing against both, plus rebuilding the kernel module against your current kernel. Budget for that as a periodic project, not a background task.

The licence field is NOASSERTION, which means GitHub could not map the repository's LICENSE file to a standard identifier. Read that file yourself before you ship anything built on F-Stack, and check how it interacts with DPDK's own licence and with the FreeBSD stack's BSD terms, since those are separate components. Nothing here is legal advice; the point is that the metadata does not answer the question for you, and the answer depends on which parts of the tree you actually distribute.

Editorial conclusion

F-Stack is for teams that own their hardware, can dedicate a NIC to a single process, and have already measured a kernel bottleneck in packet processing or connection count. It is not for anyone who needs the host's normal networking to keep working alongside the application, and not for a first attempt at a network-bound service. Before adopting it, verify which NIC drivers your vendor supports under DPDK, confirm you can spare a whole port and pin its queues, and decide whether you will run the bundled Nginx or Redis adapter or write your own main loop against the Epoll/Kqueue interface. The project's own framing is a kernel bypass framework, and every one of those costs follows from that choice.

Frequently asked questions

Official sources

1. F-Stack/f-stack on GitHub
2. Issues
3. Project website
4. README
5. Releases