From 6ec12e0b3095f2d2f4c51e7d0d522827bf61d864 Mon Sep 17 00:00:00 2001 From: Rob Murray Date: Fri, 12 Sep 2025 18:19:30 +0100 Subject: [PATCH 1/3] Engine: document com.docker.network.host_ipv4 / host_ipv6 Signed-off-by: Rob Murray --- .../manuals/engine/network/drivers/bridge.md | 1 + .../manuals/engine/network/port-publishing.md | 22 +++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/content/manuals/engine/network/drivers/bridge.md b/content/manuals/engine/network/drivers/bridge.md index f1f2ae079ca2..e967e7816af6 100644 --- a/content/manuals/engine/network/drivers/bridge.md +++ b/content/manuals/engine/network/drivers/bridge.md @@ -118,6 +118,7 @@ The following table describes the driver-specific options that you can pass to |-------------------------------------------------------------------------------------------------|-----------------------------|-----------------------------------------------------------------------------------------------------| | `com.docker.network.bridge.name` | | Interface name to use when creating the Linux bridge. | | `com.docker.network.bridge.enable_ip_masquerade` | `true` | Enable IP masquerading. | +| `com.docker.network.host_ipv4`
`com.docker.network.host_ipv6` | | Address to use for source NAT. See [Packet filtering and firewalls](packet-filtering-firewalls.md). | | `com.docker.network.bridge.gateway_mode_ipv4`
`com.docker.network.bridge.gateway_mode_ipv6` | `nat` | Control external connectivity. See [Packet filtering and firewalls](packet-filtering-firewalls.md). | | `com.docker.network.bridge.enable_icc` | `true` | Enable or Disable inter-container connectivity. | | `com.docker.network.bridge.host_binding_ipv4` | all IPv4 and IPv6 addresses | Default IP when binding container ports. | diff --git a/content/manuals/engine/network/port-publishing.md b/content/manuals/engine/network/port-publishing.md index 89388843d71e..dd1f45f01108 100644 --- a/content/manuals/engine/network/port-publishing.md +++ b/content/manuals/engine/network/port-publishing.md @@ -289,6 +289,28 @@ For example: > Changing the default bind address doesn't have any effect on Swarm services. > Swarm services are always exposed on the `0.0.0.0` network interface. +### Masquerade or SNAT for outgoing packets + +By default, if NAT is enabled for a bridge network, outgoing packets from +containers are masqueraded. This means the source address of packets +leaving the Docker host is changed to an address on the host interface +the packet is sent on. + +Masquerading can be disabled for a user-defined bridge network by using +the `com.docker.network.bridge.enable_ip_masquerade` driver option when +creating the network. For example: +```console +$ docker network create mybridge \ + -o com.docker.network.bridge.enable_ip_masquerade=false ... +``` + +To use a specific source address for outgoing packets for a user-defined +network, instead of letting masquerading select an address, use options +`com.docker.network.host_ipv4` and `com.docker.network.host_ipv6` to +specify the Source NAT (SNAT) address to use. The +`com.docker.network.bridge.enable_ip_masquerade` option must +be `true`, the default, for these options to have any effect. + ### Default bridge To set the default binding for the default bridge network, configure the `"ip"` From a2909ab2271ac6601650ca99f0cff03471c5ba2f Mon Sep 17 00:00:00 2001 From: Rob Murray Date: Fri, 12 Sep 2025 18:50:42 +0100 Subject: [PATCH 2/3] Engine: note that macvlan containers can't reach the host Signed-off-by: Rob Murray --- content/manuals/engine/network/drivers/macvlan.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/content/manuals/engine/network/drivers/macvlan.md b/content/manuals/engine/network/drivers/macvlan.md index 43e67a7a04e3..2090d39f3f96 100644 --- a/content/manuals/engine/network/drivers/macvlan.md +++ b/content/manuals/engine/network/drivers/macvlan.md @@ -32,6 +32,13 @@ Keep the following things in mind: overlay (to communicate across multiple Docker hosts), these solutions may be better in the long term. +- Containers attached to a macvlan network cannot communicate with the host + directly, this is a restriction in the Linux kernel. If you need communication + between the host and the containers, you can connect the containers to a + bridge network as well as the macvlan. It is also possible to create a + macvlan interface on the host with the same parent interface, and assign it + an IP address in the Docker network's subnet. + ## Options The following table describes the driver-specific options that you can pass to From bfb53e1f7d8723bf5f82cf84a18c74f346d34eac Mon Sep 17 00:00:00 2001 From: Rob Murray Date: Fri, 12 Sep 2025 19:04:53 +0100 Subject: [PATCH 3/3] Engine: fix mention of ipvlan-l2 in macvlan doc Signed-off-by: Rob Murray --- .../manuals/engine/network/drivers/macvlan.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/content/manuals/engine/network/drivers/macvlan.md b/content/manuals/engine/network/drivers/macvlan.md index 2090d39f3f96..cb9083787ee3 100644 --- a/content/manuals/engine/network/drivers/macvlan.md +++ b/content/manuals/engine/network/drivers/macvlan.md @@ -101,15 +101,23 @@ $ docker network create -d macvlan \ ### Use an IPvlan instead of Macvlan -In the above example, you are still using a L3 bridge. You can use `ipvlan` -instead, and get an L2 bridge. Specify `-o ipvlan_mode=l2`. +An `ipvlan` network created with option `-o ipvlan_mode=l2` is similar +to a macvlan network. The main difference is that the `ipvlan` driver +doesn't assign a MAC address to each container, the layer-2 network stack +is shared by devices in the ipvlan network. So, containers use the parent +interface's MAC address. + +The network will see fewer MAC addresses, and the host's MAC address will be +associated with the IP address of each container. + +The choice of network type depends on your environment and requirements. +There are some notes about the trade-offs in the [Linux kernel +documentation](https://docs.kernel.org/networking/ipvlan.html#what-to-choose-macvlan-vs-ipvlan). ```console $ docker network create -d ipvlan \ --subnet=192.168.210.0/24 \ - --subnet=192.168.212.0/24 \ --gateway=192.168.210.254 \ - --gateway=192.168.212.254 \ -o ipvlan_mode=l2 -o parent=eth0 ipvlan210 ```