Merge pull request #23409 from robmry/moby29_bug_fixes

Networking docs fixes for moby 29

Author: dvdksn

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`<br/>`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`<br/>`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.                                                            |

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
@@ -94,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
 ```
 

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
+
+NAT is enabled by default for bridge networks, meaning outgoing packets
+from containers are masqueraded. 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"`