Key takeaway
- Katran is Meta's open-source layer 4 load balancer. See how XDP, Maglev hashing and DSR work, what it needs to run, and when to use L7 proxies instead.
Katran is an open-source layer 4 load balancer from Meta. According to its Katran repository on GitHub, it is "a C++ library and BPF program to build high-performance layer 4 load balancing forwarding plane". It decides which backend receives each TCP or UDP flow by looking only at addresses, ports and protocol, and it does this inside the Linux kernel using XDP, so packets are handled before the normal network stack sees them.
This guide is for platform and network architects who need to decide whether a kernel-level L4 forwarding plane belongs in their stack. It explains how Katran works, what running it involves, where an L7 proxy is still needed, and how to govern changes to it. For the kernel technology underneath, see our guide to eBPF for secure managed services.
What is Katran and where does it fit?
Meta describes Katran in its Meta engineering post of 22 May 2018 as the forwarding plane behind its network load balancer, deployed on backend servers in its points of presence (PoPs). The project is published as facebookincubator/katran under the GPL-2.0 licence. It is a building block, not a packaged appliance: you embed the C++ library in your own control plane, or adapt the examples in the repository.
In a typical layered design, an L4 tier spreads flows across a fleet of L7 proxies or application servers, and the L7 tier handles TLS, HTTP routing and content rules. Katran occupies the first tier only.
How does Katran forward packets?
Katran combines a small set of well-defined techniques. The table below lists each one and what it does, as stated in the repository README and in Meta's engineering post.
| Technique | What it does | Why it matters |
|---|---|---|
| XDP | Runs a BPF program on every incoming packet, in driver mode as soon as the network card receives it; a slower generic mode also exists | Avoids the cost of the full kernel network stack |
| Modified Maglev hashing | Picks a backend by consistent hashing and supports unequal backend weights | Separate L4 nodes choose the same backend without sharing state |
| IP-in-IP encapsulation | Forwards packets to the next tier with an outer header whose source address varies by flow | Spreads flows across receive queues (RSS) while keeping each flow on one path |
| Direct service response (DSR) | Katran works only in DSR mode, so return traffic does not pass back through it | The load balancer handles the inbound direction only |
| Connection tracking | A fixed-size table with LRU eviction | Keeps existing flows on their backend when the backend set changes |
| Per-CPU, lockless design | Uses per-CPU BPF maps; Meta says throughput scales linearly with the number of NIC receive queues | Capacity grows with hardware queues rather than lock contention |
Layer 4 or layer 7: which do you need?
Layer 4 balancing is a routing decision made on the connection, so it cannot read HTTP headers, cookies or terminate TLS. Layer 7 proxies can, at a higher processing cost per request. Most large estates use both.
| Requirement | Layer 4 (Katran type) | Layer 7 proxy |
|---|---|---|
| Route on IP, port and protocol | Fits | Fits |
| Route on URL, header or cookie | Does not fit | Fits |
| TLS termination | Does not fit; Katran does not terminate TLS | Fits |
| Very high packet rates with simple rules | Fits well | Costs more CPU per request |
| UDP and non-HTTP services | Fits | Depends on the proxy |
| Operating effort | You own a kernel-level data plane and control plane | Mature products with ready management tools |
See also our guides to cloud versus edge placement and Kubernetes architecture components, where service load balancing is a separate concern from the node-level L4 tier discussed here.
What does running Katran involve?
The repository lists a recent Linux kernel (5.6 or later) and a recent clang (6.0 or later); builds were tested on Ubuntu 20.04, and other distributions need extra libraries such as folly, glog and gflags. The USAGE.md guide describes the control plane steps:
- Create and attach: populate a
KatranConfig, create aKatranLbinstance, then load and attach the BPF programs. The kernel verifier can reject a program, in which case the library throws. - Standalone or shared mode: attach directly to an interface, or register the program in a shared root XDP program.
- Define services: a virtual IP is identified by address, port and protocol, and backends ("reals") carry a weight. Setting a weight to 0 or removing a real drains it, although existing connections stay on it unless the VIP uses the LRU bypass flag.
- Size the tables: the consistent-hash ring size must be a prime number (default 65537), and the maximum VIPs and reals must match compile-time constants.
- Health checking: health-check traffic is marked with a socket mark that Katran maps to a chosen real.
What are the strengths and limits?
| Area | Strength | Limit or caution |
|---|---|---|
| Performance design | XDP, per-CPU maps and no busy loops on the receive path, per Meta | Meta gives no portable benchmark; measure on your own hardware and traffic |
| Statelessness across nodes | Consistent hashing lets several L4 nodes agree on a backend | Changing the backend set can still disturb flows that are not in the connection table |
| Licence and cost | Open source under GPL-2.0, no licence fee | Check the GPL-2.0 terms with your legal team before embedding it in a product you distribute |
| Scope | Does one job at layer 4 | DSR only; no TLS or HTTP-level routing; the QUIC VIP flag is described in USAGE.md as not fully stable |
| Operations | Library you can adapt to your own control plane | The repository shows no tagged release; you own build, upgrade and kernel compatibility |
How should an enterprise decide and adopt it?
- Confirm the need: measure whether your current load balancer is CPU-bound on packet rate. If it is not, a managed cloud load balancer is usually the lower-effort choice.
- Check the platform: confirm kernel version, NIC driver support for XDP driver mode, and your security review of loading BPF programs. Our guide to cloud-native security covers the surrounding controls.
- Prove it on a small VIP: run one low-risk service, compare against your baseline, and test backend drain and failure.
- Build the control plane: decide who changes VIPs, weights and health checks, and how changes are reviewed and rolled back.
- Keep the L7 tier: leave TLS and HTTP routing with proxies built for them.
How do you govern changes to a load balancer?
A load balancer change is a production decision: a wrong weight or a drained pool can take a service down. As teams let automation, and increasingly AI agents, propose these changes, the useful questions are who may change which VIP, what evidence supports the change, and how it is reversed. ElixirData Context OS keeps governed context, versioned policy and decision traces in one decision layer above AI agents, and ElixirClaw is an agentic OS platform to build, orchestrate and govern AI agents and automation workflows while keeping humans in control.
Our own view is that the data plane should stay simple and fast, while the decisions about it stay reviewable.
To map one traffic or load-balancer change your automation or agents should make, and the policy and context it depends on, book a Context Workshop. See what happens in the workshop.
Frequently asked questions
What is Katran?
Katran is an open-source layer 4 load balancer from Meta. Its GitHub README describes it as a C++ library and BPF program for building a high-performance layer 4 load balancing forwarding plane.
How does Katran differ from an L7 load balancer?
Katran decides on address, port and protocol only, so it cannot route on URLs, headers or cookies or terminate TLS. An L7 proxy can, at a higher processing cost per request.
Does Katran use XDP and eBPF?
Yes. Meta says it is built on XDP and the eBPF virtual machine, running a BPF program on every incoming packet, in driver mode as soon as the network card receives it.
What does Katran need to run?
The repository lists Linux kernel 5.6 or later and clang 6.0 or later, tested on Ubuntu 20.04. Confirm the current requirements on the GitHub page before you plan a deployment.
Does Katran work with return traffic?
Katran works only in direct service response (DSR) mode, so return traffic from backends does not pass back through it.
Is Katran the right choice for every team?
No. It is a library you integrate and operate yourself. If a managed cloud load balancer meets your packet rate and routing needs, it is usually the lower-effort option.
Katran – Advancing Layer 4 Operations
Connect with our experts to explore how Katran empowers industries and departments with Agentic Workflows and Decision Intelligence. Leverage Katran’s capabilities to optimize IT support and operations, driving automation, efficiency, and responsiveness for decision-centric organizations.
More Ways to Explore Us
cloud-native security
Cloud Native Storage Solutions
FOCUS vs Vantage: Managing Your Billing Data
Follow XenonStack on LinkedIn: XenonStack on LinkedIn for new guides on agentic AI, data and platform engineering.
Explore the XenonStack platform family: ElixirData · ElixirClaw · ElixirHub · NexaStack · MetaSecure · Neural AI · AgentGRC · AgentSRE · AgentAnalyst · AgentInstruct · AgentRAI · AgentScrum · AgentSearch · AgentForce · AI Aviator · SAIF Aviator · CohortIQ · XenonStack AI · XenonStack UAE