Bridge network gateway_mode_ipv[46]=<nat|routed>

Signed-off-by: Rob Murray <[email protected]>

content/network/_index.md

@@ -91,9 +91,9 @@ $ docker run --rm -it --network container:redis example/redis-cli -h 127.0.0.1
 ## Published ports
 
 By default, when you create or run a container using `docker create` or `docker run`,
-the container doesn't expose any of its ports to the outside world.
+containers on bridge networks don't expose any ports to the outside world.
 Use the `--publish` or `-p` flag to make a port available to services
-outside of Docker.
+outside the bridge network.
 This creates a firewall rule in the host,
 mapping a container port to a port on the Docker host to the outside world.
 Here are some examples:
@@ -111,11 +111,12 @@ Here are some examples:
 > a container's ports it becomes available not only to the Docker host, but to
 > the outside world as well.
 >
-> If you include the localhost IP address (`127.0.0.1`) with the publish flag,
-> only the Docker host can access the published container port.
+> If you include the localhost IP address (`127.0.0.1`, or `::1`) with the
+> publish flag, only the Docker host and its containers can access the
+> published container port.
 >
 > ```console
-> $ docker run -p 127.0.0.1:8080:80 nginx
+> $ docker run -p 127.0.0.1:8080:80 -p '[::1]:8080:80' nginx
 > ```
 >
 > > **Warning**
@@ -132,6 +133,80 @@ it isn't necessary to publish the container's ports.
 You can enable inter-container communication by connecting the containers to the
 same network, usually a [bridge network](./drivers/bridge.md).
 
+On an IPv6-enabled Docker host, if no host IP is given in a port mapping
+and the bridge network is IPv4-only, ports on the Docker host's IPv6
+addresses will be mapped to the container's IPv4 address - unless docker-proxy
+is disabled.
+
+### Direct routing for bridge networks
+
+By default, IPv4 and IPv6 networks both use NAT and masquerading to map
+ports between host IP addresses and the container. For example,
+`docker run -p 8080:80 [...]` creates a mapping between port 8080 on any
+address on the Docker host, and the container's port 80. Outgoing
+connections from the container will masquerade, using the Docker host's
+IP address.
+
+However, particularly with IPv6, you may prefer to avoid using NAT. To
+access containers on a bridge network from outside the Docker host, you
+must set up routing to the bridge network via an address on the Docker
+host. This can be achieved using static routes, BGP, or any other means
+appropriate for your network.
+
+To avoid NAT and masquerading, one option is to disable `ip6tables`
+(or `iptables` for IPv4) in [daemon configuration](https://docs.docker.com/reference/cli/dockerd/).
+All ports of all containers will then be accessible from the network,
+and none will be mapped from Docker host IP addresses.
+
+Alternatively, the bridge network driver has options
+`com.docker.network.bridge.gateway_mode_ipv6=<nat|routed>` and
+`com.docker.network.bridge.gateway_mode_ipv4=<nat|routed>`. The default
+is `nat`, described above; NAT and masquerading rules are set up for
+each mapped container port. With mode `routed`, no NAT or masquerading
+rules are set up, and only mapped container ports will be directly
+accessible.
+
+In `routed` mode, a host port in a `-p` or `--publish` port mapping is
+not used, and the host address is only used to decide whether to apply
+the mapping to IPv4 or IPv6. So, when mapping only applies to `routed`
+mode, because an IPv4 or IPv6 host address is included, only addresses
+`0.0.0.0` or `::1` are allowed, and a host port must not be given.
+
+Mapped container ports, in `nat` or `routed` mode, are accessible from
+any remote address, if routing it set up in the network, unless the
+Docker host's firewall has additional restrictions.
+
+#### Example
+
+Create a network suitable for direct routing for IPv6, with NAT enabled
+for IPv4:
+```console
+$ docker network create --ipv6 --subnet 2001:db8::/64 -o com.docker.network.bridge.gateway_mode_ipv6=routed mynet
+```
+
+Create a container with a port mapping:
+```console
+$ docker run --network=mynet -p 8080:80 myimage
+```
+
+Then:
+- Only container port 80 will be open, for IPv4 and IPv6. It is accessible
+  from anywhere, if there is routing to the container's address, and access
+  is not blocked by the host's firewall.
+- For IPv6, port 80 will be open on the container's IP address. Port 8080
+  will not be opened on the host's IP addresses, and outgoing packets will
+  use the container's IP address.
+- For IPv4, the container's port 80 will also be accessible via port 8080 on
+  the host's IP addresses. Connections originating from the container will
+  masquerade, using the host's IP address.
+
+Alternatively, to make the mapping IPv6-only, disabling IPv4 access to the
+container's port 80, use the unspecified IPv6 address `[::]` and do not
+include a host port number:
+```console
+$ docker run --network mynet -p '[::]::80'
+```
+
 ## IP address and hostname
 
 By default, the container gets an IP address for every Docker network it attaches to.