Published ports and the userland proxy · Docker & Containers

When you publish a port with -p 8080:80, Docker sets up two mechanisms, not one. A DNAT rule in the kernel, and a small userspace forwarder called docker-proxy. Both are present in a default installation, and which one carries a given connection depends on where the connection came from — not on anything you configured.

Getting this split right is what separates “why does my access log show 172.17.0.1 for every request” from a five-minute fix.

What is actually running

Read-only / Safeboth mechanisms, one port— One proxy process and one DNAT rule for the same published port.

$ docker run -d --name web -p 8080:80 nginx:1.27-alpine

ps -o pid,args -C docker-proxy
echo '---'
sudo iptables -t nat -S DOCKER

  PID COMMAND
2841 /usr/bin/docker-proxy -proto tcp -host-ip 0.0.0.0 -host-port 8080 -container-ip 172.17.0.2 -container-port 80
---
-N DOCKER
-A DOCKER -i docker0 -j RETURN
-A DOCKER ! -i docker0 -p tcp -m tcp --dport 8080 -j DNAT --to-destination 172.17.0.2:80

Illustrative output

One process and one rule, for one port. They are not alternatives that Docker picks between at publish time; they cover different paths.

Which path uses which

The dockerd reference describes --userland-proxy (default true) in five words: “Use userland proxy for loopback traffic”. That is the whole division of labour.

Connection	Netfilter path	Carried by
From another host, arriving on `eth0`	`PREROUTING` → routing → `FORWARD`	Kernel DNAT
From the host itself to `127.0.0.1:8080`	`OUTPUT` on loopback	`docker-proxy`
From the host to its own LAN address `203.0.113.10:8080`	`OUTPUT` → `nat OUTPUT` → `DOCKER`	Kernel DNAT
From a container back to a published port on the host (hairpin)	`PREROUTING` → DNAT → `POSTROUTING` masquerade	Kernel DNAT, with SNAT

External traffic never touches docker-proxy, even though the process is listening. The DNAT in PREROUTING rewrites the destination before the routing decision, so the packet is forwarded to the container and the proxy’s socket is simply never reached. The proxy exists for the case DNAT cannot cover: locally generated traffic to 127.0.0.1, which the kernel will not route off the loopback interface.

Why loopback needs a process at all

The nat OUTPUT jump into Docker’s DOCKER chain is qualified with ! -d 127.0.0.0/8. Loopback destinations are excluded deliberately, because the kernel refuses to route a packet whose destination is in 127.0.0.0/8 out of a non-loopback interface. DNAT would rewrite the destination and the packet would then be dropped as a martian.

docker-proxy sidesteps the routing layer entirely. It holds an ordinary listening socket on the host, accepts the connection in userspace, opens a second connection to 172.17.0.2:80, and copies bytes between the two. Two TCP connections, one process, no routing question to answer.

That is also why it changes the source address: the container’s peer is the proxy, and the proxy’s outbound connection is sourced from the bridge gateway.

The source address the container sees

This is the observable consequence, and the reason most people end up reading about docker-proxy at all.

Read-only / Safetwo clients, two source addresses— The external client keeps its address. The local one is rewritten to the bridge gateway.

$ # From another host on the LAN
# (run on 198.51.100.7)  curl http://203.0.113.10:8080/

# From the Docker host itself
curl -s http://127.0.0.1:8080/ > /dev/null

docker logs web --tail 2

198.51.100.7 - - [12/Aug/2026:09:14:02 +0000] "GET / HTTP/1.1" 200 615 "-" "curl/8.5.0"
172.17.0.1 - - [12/Aug/2026:09:14:11 +0000] "GET / HTTP/1.1" 200 615 "-" "curl/8.5.0"

Illustrative output

DNAT rewrites only the destination, so an externally originated request arrives at the container with the client’s real address intact. Anything that went through docker-proxy arrives from 172.17.0.1 — the docker0 gateway — because that is the proxy’s own source address for its second connection.

Rate limits and allow-lists that key on client IP

An application that rate-limits by source address, or that has an admin allow-list, behaves differently depending on which path the request took. Every locally originated request and every hairpinned request shares the single source address 172.17.0.1.

The failure is not that the control stops working. It is that all of that traffic is treated as one client. A per-IP rate limit of 100 req/min becomes a shared 100 req/min bucket for the host, your health checker, your backup job and the reverse proxy on the same host. Under load the health check is the request that gets rate-limited, so the container is marked unhealthy and restarted, which is a restart loop with no application fault in it anywhere.

The inverse is worse: an allow-list containing 172.17.0.1 grants admin access to every container that can reach the published port, because they all arrive with that address.

If the application needs the real client address, terminate at a reverse proxy that sets X-Forwarded-For and have the application trust it — not the transport address. docker-nginx-reverse-proxy covers the header handling.

Hairpin NAT

A container connecting to 203.0.113.10:8080 — the host’s own address, for a port published to a container on the same host — is a hairpin. The packet leaves the bridge, gets DNATed back to a container on that same bridge, and would arrive with a source address on the same subnet as the destination. The container would then reply directly, and the client would drop the reply as coming from the wrong peer.

Docker fixes this with a masquerade rule so the reply is forced back through the host:

Read-only / Safethe hairpin rule— Source and destination are the same container. This rule is what makes the return path work.

sudo iptables -t nat -S POSTROUTING | grep -- '-s 172.17'
# -A POSTROUTING -s 172.17.0.2/32 -d 172.17.0.2/32 -p tcp -m tcp --dport 80 -j MASQUERADE

The cost is the same one as above: the container sees the gateway address rather than the calling container’s. Two services on the same host talking to each other through the host’s public address is a pattern worth removing on its own merits — put both on a user-defined network and use the service name.

Disabling the proxy

Service impact possibledaemon.json— Requires a daemon restart. Containers without a restart policy will not come back on their own.

# /etc/docker/daemon.json
{
"userland-proxy": false
}

Service impact possibleapply and verify— Validate the config before restarting; a malformed daemon.json leaves the daemon down.

sudo dockerd --validate --config-file /etc/docker/daemon.json
sudo systemctl restart docker

# No proxy processes should remain
pgrep -a docker-proxy || echo "no docker-proxy processes"

# The DNAT rules are still there
sudo iptables -t nat -S DOCKER

What you gain:

One fewer process per published port. A 50-port stack loses 50 processes. Each is small, but they are real RSS and real PIDs.
One fewer failure domain. A wedged proxy process breaks that port; a DNAT rule has no runtime to wedge.
Slightly lower latency on the loopback path, which is the only path the proxy was carrying anyway. External throughput does not change, because external traffic was already pure DNAT.

What disabling it actually costs

The claim that the proxy is pure overhead is only true for external traffic, which never used it. What changes is the loopback path.

With userland-proxy: false, Docker makes 127.0.0.1:8080 work by enabling net.ipv4.conf.<bridge>.route_localnet=1 on its bridge interfaces, which tells the kernel to route packets from 127.0.0.0/8 rather than discard them. Two things follow:

route_localnet is IPv4-only. There is no equivalent for ::1. Connecting to a published port over IPv6 loopback does not work the same way. If your health checks or local clients use localhost and the resolver returns ::1 first, they break, and the failure looks like an application problem rather than a daemon setting.
route_localnet loosens a kernel-level sanity check on those interfaces. It is a documented, widely used configuration, not a hole in itself, but it is a change to the host’s network posture that is worth recording in the change you make, not discovering later.

Setting the option back to true does not undo route_localnet on the existing bridges. The networks have to be recreated, or the host rebooted, before the sysctl returns to its default.

When you cannot disable it

Docker Desktop on macOS and Windows. The daemon runs in a VM; the mechanism that gets traffic from the host OS into the VM is not the Linux DNAT path at all.
A host whose local clients depend on IPv6 loopback to reach published ports, per the note above.
Swarm mode, where the ingress routing mesh has its own expectations about the proxy. If you run Swarm, test the change on one node before applying it to the cluster.

For a plain Linux host running Compose stacks, disabling it is a reasonable default — provided you have checked what connects to localhost: on that host first.

Sanity check

ps -C docker-proxy and iptables -t nat -S DOCKER both show entries for the same published port on a default host.
A request from another machine appears in the container log with the real client address.
A request from the host to 127.0.0.1 appears with the bridge gateway address.
If you disabled the proxy, curl 127.0.0.1:<port> still works, and you checked it over IPv4 and whatever localhost resolves to on that host.