Publishing ports and the embedded DNS: DNAT, bind addresses, and 127.0.0.11

Publishing a port is DNAT

-p 8080:8080 does not “open” a port the way a firewall rule does — it installs a DNAT (destination NAT) rule in iptables that rewrites the destination of packets arriving at the host’s port 8080 to the container’s IP and port. The rule lands in the nat table’s DOCKER chain, reached from PREROUTING (for traffic arriving from outside) and OUTPUT (for traffic originating on the host):

-A DOCKER ! -i docker0 -p tcp --dport 8080 -j DNAT --to-destination 172.17.0.2:8080

The published-port spec has three parts: [bind-address:]host-port:container-port. The bind address is the part that bites: omit it (or use 0.0.0.0) and the port is reachable on every host interface; set 127.0.0.1:8080:8080 and the DNAT only matches traffic arriving on loopback — reachable from the host itself, invisible to every other machine. That is the Hook bug: the rule existed, docker ps proudly listed it, but its interface scope excluded the health checker. A second subtlety: by default Docker’s DNAT rule is inserted ahead of the host firewall’s INPUT rules, so a published port can be reachable from the outside even if ufw/firewalld thinks it blocked that port — Docker and the host firewall are editing different chains, and people are surprised which one wins.

The userland-proxy

There are actually two paths for published-port traffic. The fast path is the iptables DNAT above, handled entirely in-kernel. But Docker also runs a small docker-proxy userland process per published port as a fallback — for hairpin cases and same-host loopback connections the DNAT rule alone doesn’t cover. The kernel path costs essentially nothing; the userland-proxy path copies bytes through a userspace process, adding single-digit microseconds of latency per packet plus a process and a held socket per published port. On a host publishing hundreds of ports this is real overhead, which is why high-throughput setups often disable it ("userland-proxy": false) and rely on DNAT plus a kernel hairpin route alone.

The embedded DNS at 127.0.0.11

Have you ever wondered why http://api:8080 just works inside a Compose project but breaks the moment you reference a container from a different project? That is DNS scope in action — and it is the second failure class to master.

On the default bridge, containers can only reach each other by IP — there is no name resolution. On a user-defined bridge network (the kind docker network create or any Compose service network makes), Docker runs an embedded DNS server that every container reaches at the fixed address 127.0.0.11:53. Docker rewrites each container’s /etc/resolv.conf to point at it, and it resolves container names and network aliases to current container IPs, forwarding everything else to the host’s configured resolvers. This is why on a Compose network you connect to http://api:8080 and it just works — api is a container name the embedded DNS knows, and the IP it returns is always current even after a restart gives the container a new address.

The numbers and failure modes that matter:

• The resolver lives at 127.0.0.11 inside every container’s netns — a loopback address, so it never collides with the host’s DNS and is unreachable from outside the container. iptables NAT rules inside the netns redirect that loopback traffic to the daemon’s DNS listener.
• Name resolution is per-network: a container only resolves names of containers attached to a network it shares. Two containers on different user-defined networks cannot resolve each other by name even on the same host — the classic “works in one compose file, not across two” bug.
• A short DNS TTL plus resolution-on-every-connect is what makes restarts transparent, but a client that caches a resolved IP forever (some JVM defaults, naive HTTP clients) keeps hitting the old IP after the target container restarts — a stale-connection bug that looks like the network but is the client’s resolver cache.