Katran: Meta's XDP Layer 4 Load Balancer for DSR Forwarding Planes

The problem Katran solves: scaling L7 load balancers without DNS or anycast

Katran sits in front of layer 7 load balancers, the ones that terminate TCP sessions. The README frames the motivation directly: an L4 load balancer is a way to scale out L7 capacity, and it compares that approach against two alternatives. Against DNS, an L4 balancer does not have to wait for a TTL to expire before redirecting traffic away from a failed L7 node. Against anycast, the README argues L4 balancers are more resilient to network problems that trigger mass ECMP reshuffles, handle adding and removing L7 nodes from the pool better, and support unequal load balancing more cleanly.

The audience is infrastructure engineers who already operate a routed network and want packet steering to happen in the kernel, before the normal network stack runs. The project is a library and a BPF program rather than a packaged appliance, so it assumes you are comfortable building from source, loading XDP programs, and wiring up your own control plane through the provided examples.

How the forwarding plane works: VIP lookup, session table, ipip encapsulation

The README lays out the packet path in seven steps. Katran receives a packet and checks whether the destination is configured as a VIP, the virtual IP address of a service. For a packet headed to a VIP, it first checks whether it has seen a packet from the same session before. If it has, the packet goes to the same real server, meaning the actual server or L7 load balancer that terminates the TCP session.

For a new session, Katran computes a hash from the packet's 5-tuple, uses that hash to pick a real server, and writes the lookup result into the session table so subsequent packets in the session can skip the hash computation. The packet is then encapsulated in another IP packet and sent to the real server.

Two design consequences follow from that description. First, because the hash depends only on packet headers, different L4 balancers select the same real server without explicit state sharing. The README uses this to argue that a single L4 balancer can be restarted or drained without affecting the TCP sessions running through it. Second, the data plane is lockless and uses per-CPU versions of BPF maps, which is the stated reason performance scales linearly with the number of NIC RX queues: XDP invokes the BPF program per received packet, and each queue runs it independently.

The encapsulation is ipip, and the README notes a detail that matters for the receive side: instead of using the same source address for every ipip packet, Katran crafts a source that keeps different flows spread across RX queues on the L7 balancer, which the README calls RSS friendly encapsulation.

Installing Katran on Ubuntu and running a first example

The README states the current tested distribution is Ubuntu 20.04, with two requirements: a recent Linux kernel (5.6 or newer) and a recent clang compiler (6.0 or newer). On Ubuntu, if you are unsure whether the build tools are present, the README suggests installing build-essential first.

sudo apt install build-essential

Building the library and the thrift and gRPC examples is handled by a single script at the repository root. The README says it takes care of all required dependencies.

./build_katran.sh

If you build on a distribution other than Ubuntu, the README lists what you must provide yourself: folly, clang 6.0 or newer, and the glog, gtest, gflags and elf libraries. Building the examples additionally requires fbthrift and gRPC. The README notes that Meta runs its CI on CentOS while the project tries to support OSS builds on recent Ubuntu versions.

For a first real use, the repository ships example programs rather than a single binary. The README points to EXAMPLE.md for the output of running the provided thrift and gRPC services that use the Katran library. Two shell scripts at the root start those services.

./start_katran_simple_server.sh
./start_katran_grpc_server.sh

The README does not document the flags, ports or configuration keys these scripts accept, so read EXAMPLE.md and the scripts themselves before running them. There is also an install_xdproot.sh script for the XDP program and a collect_debug_lb.sh script for gathering debug output, both visible in the repository layout but not described in the README.

Environment requirements that decide whether Katran fits at all

Katran is unusually explicit about what it will not do, and these constraints are the most useful part of the README for an adoption decision. It works only in DSR (direct service response) mode. The network topology must be L3 based, with everything above the top-of-rack switch routed, because Katran offloads the routing decision for the return path by unconditionally sending all packets to the first routing device.

Fragmentation is not supported. Katran cannot forward a fragmented packet, and it cannot fragment a packet itself when encapsulation pushes the result past the MTU. The README suggests two mitigations: raising MTU inside your network, or changing the advertised TCP MSS from the L7 balancers. It recommends lowering MSS even when MTU is raised, giving the example of advertising 1450 instead of the IPv4 default of 1460 to help clients behind PPPoE connections.

Packets with IP options set are not supported. Maximum packet size cannot exceed 3.5k, and the default is 1.5k. Finally, Katran assumes a load balancer on a stick deployment, where a single interface carries both ingress traffic from users to the L4 balancer and egress traffic from the L4 balancer to the L7 balancers. If your design separates ingress and egress interfaces, this assumption is a direct conflict, not a tuning detail.

Consistency without state sharing, and where that breaks down

The consistency property is the strongest argument in the README and also the one easiest to misread. Because real-server selection comes from a hash over packet headers, two Katran instances that see the same 5-tuple pick the same real server even though they never exchange session state. That makes restarting or draining a single L4 balancer survivable for existing TCP sessions. It does not make the pool of real servers self-healing: if a real server is removed, the hash still points at it until the configuration changes, and the README does not describe health checking or automatic failover. Session affinity and backend health are separate problems that a control plane built on top of Katran has to solve.

The scaling claim deserves the same care. Lockless operation with per-CPU maps means queues do not contend, and the README describes linear scaling with RX queue count. It also states that generic XDP mode works but with performance degradation compared to driver mode, so the fast path depends on your NIC supporting XDP in driver mode. That is a hardware question you should answer before committing.

How Katran differs from IPVS and other L4 forwarding approaches

The obvious alternative in this space is IPVS, the layer 4 load balancer built into the Linux kernel. The difference in approach is where the forwarding decision happens. IPVS hooks into the kernel's netfilter path, so packets traverse more of the networking stack before a decision is made. Katran uses XDP, which the README describes as running packet handling routines right after the NIC receives the packet and before the kernel has a chance to run, when XDP is in driver mode.

That placement buys throughput but costs flexibility. IPVS integrates with the standard tooling and connection tracking that administrators already know, and it does not impose DSR-only operation or an L3-only topology. Katran gives up those conveniences in exchange for an in-kernel forwarding plane that is lockless and scales with RX queues. The README's own comparison is against DNS and anycast-based scaling rather than against IPVS, so treat the IPVS contrast as a topology argument: if you need NAT-mode load balancing or a mixed L2 environment, Katran's DSR and L3 requirements rule it out regardless of performance.

Licence, build cost and what maintaining a Katran deployment involves

Katran is licensed under GPL-2.0, and the repository carries both a LICENSE and a COPYING file at the top level. GPL-2.0 is a copyleft licence, so if you distribute a modified version of the library, the licence terms attach to that distribution. This article is not legal advice; check with your own counsel if you plan to ship a derivative.

Upgrade cost is dominated by the build, not by a package manager. There are no published releases, so there is no versioned artifact to pin. You build from the main branch with build_katran.sh, which means tracking upstream commits and rebuilding against folly, fbthrift and gRPC when those move. The README notes that Meta's CI runs on CentOS while OSS support targets recent Ubuntu, so distribution drift is a real maintenance line item. The last push to the repository was on 2026-09-22.

The operational surface is also larger than a single daemon: the repository contains build_bpf_modules_opensource.sh, install_xdproot.sh, os_run_tester.sh, and separate debug collection scripts for the load balancer and the real server. Budget for the control plane you write on top of the library, not just for the build.

Editorial conclusion

Adopt Katran if you run an L3 network, terminate TCP above the load balancer, and want a lockless XDP forwarding plane whose real-server selection stays consistent across instances without state sharing. Do not adopt it if your topology is L2, if you need fragmentation handling, or if you cannot commit to DSR. Before anything else, verify your kernel is 5.6 or newer, your NIC supports XDP in driver mode, and your MTU and TCP MSS settings leave room for ipip encapsulation.

Frequently asked questions

Official sources

1. facebookincubator/katran on GitHub
2. Issues
3. License: GPL-2.0
4. README