Linux Transparent Proxy Internals

Linux transparent proxy internals - by AllHailTheTopology

SubscribeSign in

Linux transparent proxy internals Learn how Linux's transparent proxying works by building a toy proxy server in C.

AllHailTheTopology Jul 13, 2026

I've always thought the transparent proxying functionality in the Linux kernel is one of the coolest but hardest to understand. This may have to do with the sheer lack of documentation on the subject or maybe the fact that configuring it requires quite a few moving pieces like IP rules, socket options, and routing. Let's explore how transparent proxying works and build a toy transparent proxy server to drive the concepts home. What is transparent proxying?

Most people will have colloquial familiarity with the term "proxy" as a networking infrastructure. A proxy sits between a client, the source, and a server, the destination, and manages the connections and data between them. If this is a TCP proxy, it will terminate the client's connection, holding a socket to it, and will connect to the server, holding a socket for this "leg" as well. With both sockets in-hand the proxy will pipe the data between them, performing whatever actions on the data is required. Proxies can do all sorts of things, but we just need to understand the fundamentals right now.

The above is what, I think, most people imagine when they think 'proxy', though technically, this is a reverse proxy where the proxy sits in front of the server. To understand what a transparent proxy is they must think about what IP addresses the client will use to connect to the server, and the client IPs seen by the server.

┌─────────────┐ │ 66.66.66.66 │ ┌────────┐ conn A │ proxy │ conn B ┌────────┐ │10.0.5.1├────────────► ├────────────►10.0.6.1│ │ client ◄────────────┤ terminates ◄────────────┤ server │ └────────┘ │ and │ └────────┘ ┌───────────────────────┐ │ forwards │ ┌───────────────────────┐ │ Conn A │ └─────────────┘ │ Conn B │ │10.0.5.1 -> 66.66.66.66│ │66.66.66.66 -> 10.0.6.1│ └───────────────────────┘ └───────────────────────┘

Let's use the non-transparent proxy example above, both the client connection and the server's connections are well aware a proxy server sits between them. A transparent proxy is fundamentally different. ┌─────────────┐ │ 66.66.66.66 │ ┌────────┐ conn A │ proxy │ conn B ┌────────┐ │10.0.5.1├────────────► ├────────────►10.0.6.1│ │ client ◄────────────┤ terminates ◄────────────┤ server │ └────────┘ │ and │ └────────┘ ┌───────────────────────┐ │ forwards │ ┌───────────────────────┐ │ Conn A │ └─────────────┘ │ Conn B │ │ 10.0.5.1 -> 10.0.6.1 │ │ 10.0.5.1 -> 10.0.6.1 │ └───────────────────────┘ └───────────────────────┘

Notice, in the transparent case the client perceives itself connected directly to the server and the server perceives itself connected directly to the client. Both client and server maintain their IP addresses, across both "legs" of the proxy. The example above is sometimes called a "fully transparent proxy" since the source IP of the client is maintained from the server's perspective. It's not uncommon for the server to see the proxy's original IP when, for example, routing the client's IP back to the proxy is difficult, among other reasons. While the explanation is simple, like a lot of things with networking, the devil's in the details. Let's start building a proxy server which we will modify into a transparent socket as we explain how we can accomplish the above. The topology

We need a small testing environment which creates separate layer 3 networks for the client, proxy, and server. We can do this with just Linux network namespaces, the ip tool, and veths.

┌───────────┐ ┌──────────────┐ ┌──────────────┐ │ client ns │ │ proxy ns │ │ server ns │ │ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │ │ │ ┼────────┼ │ │ ┼────────┼ │ │ └──────┴────┘ └────┘────└────┘ └────┘─────────┘ 10.0.5.1 10.0.5.10 10.0.6.10 10.0.6.1

The above diagram illustrates the topology, three network namespaces connected by veths. Makefile

LINK = ip link NETNS = ip netns NETNS_EXEC = ip netns exec NETNS_CLIENT = client NETNS_PROXY = proxy NETNS_SERVER = server

topology: # create network namespaces $(NETNS) add $(NETNS_CLIENT) $(NETNS) add $(NETNS_PROXY) $(NETNS) add $(NETNS_SERVER)

# wire them together with veths $(LINK) add name client-a type veth peer name proxy-a $(LINK) set dev client-a netns $(NETNS_CLIENT) $(LINK) set dev proxy-a netns $(NETNS_PROXY)

$(LINK) add name proxy-b type veth peer name server-a $(LINK) set dev proxy-b netns $(NETNS_PROXY) $(LINK) set dev server-a netns $(NETNS_SERVER)

# configure IP networking $(NETNS_EXEC) $(NETNS_CLIENT) ip addr add 10.0.5.1/24 dev client-a $(NETNS_EXEC) $(NETNS_CLIENT) ip link set dev client-a up $(NETNS_EXEC)...

Linux Transparent Proxy Internals

Related Articles

(no title)

Scientists reverse brain aging, with a nasal spray

AI has torched the market for junior programmers

Al Vigier: Canada's AI strategy shouldn't include secret Palantir bills

The Anatomy of an AI-Native Org