a73x

f8b94183

docs(faq): Docker on a host silently drops guest outbound traffic

a73x   2026-07-29 12:40

Commit message
docs(faq): Docker on a host silently drops guest outbound traffic

Docker sets the iptables FORWARD policy to drop, discarding the guests'
NAT'd traffic while the gate keeps working (tunnelled, not forwarded).
The entry names the symptom shape, the cause, the DOCKER-USER accept
rules for the eitri bridge, and the need to persist them.
docs/faq.md
Old New
@@ -11,3 +11,24 @@ To serve traffic from a VM, or to reach one directly from another network,
11 install [Tailscale](https://tailscale.com) (or WireGuard) inside it — it is 11 install [Tailscale](https://tailscale.com) (or WireGuard) inside it — it is
12 a normal Linux machine. A public gateway is on the 12 a normal Linux machine. A public gateway is on the
13 [roadmap](../ROADMAP.md). 13 [roadmap](../ROADMAP.md).
14
15 ## VMs boot and SSH works, but have no outbound network — why?
16
17 Docker. Installing (or starting) Docker on a host sets the kernel's iptables
18 `FORWARD` policy to drop, which silently discards the guests' NAT'd traffic —
19 the agent's own forwarding and masquerade rules are still in place, and a
20 drop in any chain wins. The symptoms are exactly this shape: the guest pings
21 its gateway, the jump gate still works (that path is tunnelled, not
22 forwarded), but DNS and everything outbound time out.
23
24 Docker reserves the `DOCKER-USER` chain for the host admin. Allow the eitri
25 bridge through it:
26
27 ```sh
28 sudo iptables -I DOCKER-USER -i eitri0 -j ACCEPT
29 sudo iptables -I DOCKER-USER -o eitri0 -j ACCEPT
30 ```
31
32 Docker re-creates its rules on every daemon start, so persist these (e.g.
33 `iptables-persistent`, or a systemd unit ordered after `docker.service`) —
34 a plain one-off insert is gone after the next reboot.