Docker’s Two Modes of Bridge Networking

by

Docker’s Two Modes of Bridge Networking

In v28.2.x Docker tightened up network security, effectively breaking things that were working.

TL;DR:

They are not mutually exclusive. In fact, they are complementary, but their relationship is subtle:

Accurate Truth:

FeaturePurposeWhen It’s Used
--opt com.docker.network.bridge.gateway_mode_ipv4=routedTells Docker to set up this specific network in “routed mode” instead of NAT.Per-network configuration
"allow-direct-routing": true in daemon.jsonAllows Docker daemon to honor IP routes between physical interfaces and containers.Global daemon setting

Key Insight:

If you use routed mode, you must also set "allow-direct-routing": true or packets from the outside world won’t be routed properly to containers.

These options are co-dependent in most real-world use.

Confusion:

Early Docker documents and blog posts described "allow-direct-routing": true as enabling manual routing without needing routed bridge mode — hence the illusion of exclusivity. But that’s only true if you manually manage all routing and don’t want Docker’s bridge automation at all.

Summary of the Current Reality (Docker ≥ 24.x):

ScenarioUse routed mode?Set allow-direct-routing?Effect
✅ Intended routed bridge✅ Yes✅ YesRouted packets flow from external IPs to containers
⚠️ NAT mode only❌ No❌ No or ✅ YesNAT will rewrite packets, outside world sees host IP
⚠️ Routed mode, but no allow-direct-routing✅ Yes❌ No❌ External systems can’t reach containers directly
✅ Manual routes (no routed mode)❌ No✅ YesAdvanced setups using custom iptables/ip route work

Best Practice:

If the goal is direct IP reachability, then:

// daemon.json
{
  "allow-direct-routing": true
}

And, for each plainly routed (i.e., not docker-managed NAT) network:

docker network create \
  --driver bridge \
  --opt com.docker.network.bridge.gateway_mode_ipv4=routed \
  --subnet=172.19.13.0/24 \
  net_yourname

These settings work together for routed networking to operate as needed.

Leave a Comment