docker-tailscale-network-fix/README.md

ddev-tailscale-docker-fix

Note: these scripts were written by an LLM (Claude Code), diagnosing and fixing an issue live on one specific machine (Fedora + NetworkManager

• Tailscale + Docker). They worked there, but review them yourself before running as root on another machine — network/firewall behavior varies across distros, Tailscale versions, and configurations.

Fixes Docker containers (e.g. ddev) losing internet access when Tailscale is running with an exit node ("route all traffic") enabled.

The problem

With an exit node and "route all traffic" enabled, Tailscale installs a catch-all ip rule that captures every packet not explicitly exempted and routes it out via the tailscale0 interface. Tailscale exempts its own daemon traffic from that capture with a firewall mark, but has no way to exempt traffic that only passes through the host (forwarded) rather than originating from it.

Docker containers' outbound traffic is exactly that: forwarded, not locally-originated. It gets no exemption, so it's swept into Tailscale's catch-all route, sent out via tailscale0, and dropped by Tailscale's own anti-spoofing firewall rule (ts-forward) because it isn't a recognized Tailscale-tunneled flow.

Symptom: every DNS lookup / outbound HTTP request from inside a container hangs until timeout whenever Tailscale is connected — WP core update checks, plugin license pings, composer/npm installs, anything. The host's own applications aren't affected, since their traffic is locally-originated and gets Tailscale's exemption mark.

The fix

A higher-priority ip rule that routes Docker's private bridge subnet (default: 172.16.0.0/12, covering Docker's default address pool) through the normal routing table instead of Tailscale's catch-all. This doesn't weaken the VPN for anything else on the host — it only affects packets forwarded from Docker's own bridge networks.

The rule is kept in place by a systemd timer that re-checks/re-adds it every 15s (and 5s after boot), rather than hooked to a network event: tailscale0 is a tun device created directly by tailscaled, not through a NetworkManager connection profile, so NetworkManager never fires dispatcher/udev events we could reliably hook into for it (confirmed by testing — don't waste time re-trying that route).

Install

sudo ./install.sh

Optional overrides if Docker's default address pool doesn't apply on your machine (e.g. you have 15+ concurrent Docker networks and Docker has fallen back to a different private range):

sudo ./install.sh --subnet 172.16.0.0/12 --priority 5200 --table main

Verify

ip rule list | grep 172.16.0.0/12
ddev exec curl -sS -o /dev/null -w '%{time_total}\n' https://api.wordpress.org

Uninstall

sudo ./uninstall.sh

Caveats

• Only covers Docker networks within 172.16.0.0/12. If you have more than ~15 concurrent Docker networks on one machine, Docker falls back to 192.168.0.0/20 blocks and then 10.0.0.0/8 — those aren't covered by default. Don't just widen the subnet to 192.168.0.0/16 or 10.0.0.0/8 to compensate: those ranges are also real LAN/VPN subnet-route space, and blanket-exempting them could route traffic around the tunnel that's actually supposed to go through it. If you hit this, either raise --subnet to the specific overflow range Docker actually assigned, or extend the script to enumerate live docker network inspect subnets instead of using a fixed range.
• Assumes tailscaled's own ip rules stay in the 5210+ priority range observed on the machine this was built on; if a future Tailscale version changes that, priority 5200 should still safely sit above it as long as it's below whatever Tailscale uses for its catch-all rule.