Skip to content

docs: fix Engine networking pages that don't match the daemon - #26695

Open
corhere wants to merge 8 commits into
docker:mainfrom
corhere:engine-network-doc-fixes
Open

corhere wants to merge 8 commits into
docker:mainfrom
corhere:engine-network-doc-fixes

Conversation

@corhere

@corhere corhere commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Summary

Several Engine pages describe networking behavior that doesn't match the daemon. Each commit fixes one of them, and its message explains the daemon behavior it was checked against.

  • Port publishing: remote hosts can't use direct routing to reach published ports in a nat network unless allow-direct-routing or trusted_host_interfaces allows it (Engine 28.0.0 and later).
  • Port publishing: containers in other networks can reach any port in a nat-unprotected network, and only published ports in a routed network (Engine 29.0.0 and later, moby/moby#49981).
  • Ubuntu, Debian, and Raspberry Pi OS install pages: with the nftables firewall backend, put your own rules in your own nftables tables.
  • Bridge driver: an unset MTU means the kernel default, not "no limit".
  • Bridge driver: remove the note that says DNS resolves only custom container names. Generated names resolve too.
  • IPvlan driver: Docker refuses to create IPvlan networks on kernels older than 4.2.
  • Pruning: docker network prune also removes networks that only stopped containers use.
  • iptables page: remove DOCKER-INGRESS, which Engine 29.8.0 and later don't create (moby/moby#53118).

The commits are independent of each other. Please keep them separate when merging.

Generated by Claude Code

Since Engine 28.0.0, the bridge driver drops packets from remote hosts
addressed to a container in a `nat` mode network, unless
`trusted_host_interfaces` or `allow-direct-routing` allows them. The
gateway modes section said published ports in `nat` networks are
always reachable by direct routing. That contradicts the "Direct
routing to containers in bridge networks" section and the example at
the end of the same section.

Signed-off-by: Cory Snider <csnider@mirantis.com>
The Ubuntu, Debian and Raspberry Pi OS install pages said firewall
rules created with `nft` are not supported. With the experimental
nftables firewall backend, "Docker with nftables" tells users to put
their rules in their own nftables tables. Scope the iptables advice to
the default backend and link to the nftables page.

Signed-off-by: Cory Snider <csnider@mirantis.com>
With `com.docker.network.driver.mtu` unset or 0, the bridge driver
does not set an MTU on the bridge or the container's veth pair. The
interfaces keep the MTU the kernel gave them, which is 1500 for a veth
device. "No limit" is not a possible MTU.

Signed-off-by: Cory Snider <csnider@mirantis.com>
The note said automatic service discovery resolves only custom
container names. On a user-defined network the daemon registers the
container's name as a DNS name whatever its origin, generated names
included (buildEndpointDNSNames in moby's
daemon/container_operations.go), along with its aliases, short ID and
hostname.

Signed-off-by: Cory Snider <csnider@mirantis.com>
The kernel requirement said support for earlier kernels exists but is
buggy. The ipvlan driver checks the kernel version when it creates a
network, and returns an error on kernels older than 4.2.

Signed-off-by: Cory Snider <csnider@mirantis.com>
`docker network prune` skips a local network only while it has
endpoints, and a container has an endpoint only while it is running.
"Networks which aren't used by any containers" reads as if a stopped
container's network is kept.

Signed-off-by: Cory Snider <csnider@mirantis.com>
Since Engine 29.8.0, Swarm ingress ports are published through the
bridge driver's port mappings on docker_gwbridge, and the daemon
deletes the DOCKER-INGRESS chains that earlier releases created. Drop
the chain and the FORWARD jump to it from the list, and say which
releases have it.

Signed-off-by: Cory Snider <csnider@mirantis.com>
Since Engine 29.0.0, direct routing between bridge networks follows
the same rules as direct routing from outside the host. The
raw-PREROUTING rule that drops directly routed packets is only created
in `nat` mode, and a `nat-unprotected` network accepts forwarded
packets to any port. A `routed` network still drops packets to
unpublished ports.

The page said containers in other networks could not use direct
routing to reach a `nat-unprotected` network, and that they could
reach any port in a `routed` network. The `nat` bullet also names the
two options that let containers in other networks use direct routing
to its published ports: `allow-direct-routing`, and
`trusted_host_interfaces` listing the other network's bridge.

Signed-off-by: Cory Snider <csnider@mirantis.com>
@corhere
corhere requested a review from dvdksn as a code owner November 19, 2026 19:28
@github-actions github-actions Bot added area/engine Issue affects Docker engine/daemon area/install Relates to installing a product area/networking Relates to anything around networking labels Nov 19, 2026
@netlify

netlify Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for docsdocker ready!

Built without sensitive environment variables

Name Link
🔨 Latest commit 6c4af08
🔍 Latest deploy log https://app.netlify.com/projects/docsdocker/deploys/6aff4dcafeaa03f91cffe215
😎 Deploy Preview https://deploy-preview-26695--docsdocker.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/engine Issue affects Docker engine/daemon area/install Relates to installing a product area/networking Relates to anything around networking

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant