Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates for moby 28.0 networking #21612

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from
+151 −37
Draft

Updates for moby 28.0 networking #21612

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ce035f4
Fix description of 'inhibit_ipv4'
robmry Dec 11, 2024
e9cb32e
Updates to default bridge address config
robmry Dec 11, 2024
d2bc218
Describe IPv6-only network config
robmry Dec 11, 2024
c46b7bc
Update description of gateway modes
robmry Dec 11, 2024
3160618
Describe gateway selection in the networking overview.
robmry Dec 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions content/manuals/engine/network/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,41 @@
For more information about the different drivers, see [Network drivers
overview](./drivers/_index.md).

### Connecting to multiple networks

A container can be connected to multiple networks.

For example, a frontend container may be connected to a bridge network
with external access, and a
[`--internal`](/reference/cli/docker/network/create/#internal) network
to communicate with containers running backend services that do not need
external network access.

A container may also be connected to different types of network. For example,
an `ipvlan` network to provide internet access, and a `bridge` network for
access to local services.

When sending packets, if the destination is an address in a directly connected
network, packets are sent to that network. Otherwise, packets are sent to
a default gateway for routing to their destination. In the example above,

Check warning on line 82 in content/manuals/engine/network/_index.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'previous' instead of 'above'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'previous' instead of 'above'", "location": {"path": "content/manuals/engine/network/_index.md", "range": {"start": {"line": 82, "column": 68}}}, "severity": "INFO"}
the `ipvlan` network's gateway must be the default gateway.

The default gateway is selected by Docker, and may change whenever a
container's network connections change.
To make Docker choose a specific default gateway when creating the container
or connecting a new network, set a gateway priority. See option `gw-priority`
for the [`docker run`](/reference/cli/docker/container/run.md) and
[`docker network connect`](/reference/cli/docker/network/connect.md) commands.

The default `gw-priority` is `0` and the gateway in the network with the
highest priority is the default gateway. So, when a network should always
be the default gateway, it is enough to set its `gw-priority` to `1`.

```console
$ docker run --network name=gwnet,gw-priority=1 --network anet1 --name myctr myimage
$ docker network connect anet2 myctr
```

## Container networks

In addition to user-defined networks, you can attach a container to another
Expand Down Expand Up @@ -144,6 +179,14 @@

## IP address and hostname

When creating a network, IPv4 address allocation is enabled by default, it
can be disabled using `--ipv4=false`. IPv6 address allocation can be enabled
using `--ipv6`.

```console
$ docker network create --ipv6 --ipv4=false v6net
```

By default, the container gets an IP address for every Docker network it attaches to.
A container receives an IP address out of the IP subnet of the network.
The Docker daemon performs dynamic subnetting and IP address allocation for containers.
Expand Down
81 changes: 57 additions & 24 deletions content/manuals/engine/network/drivers/bridge.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,16 +105,16 @@
The following table describes the driver-specific options that you can pass to
`--option` when creating a custom network using the `bridge` driver.

| Option | Default | Description |
|-------------------------------------------------------------------------------------------------|-----------------------------|------------------------------------------------------------------------------------------------|
| `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.bridge.gateway_mode_ipv4`<br/>`com.docker.network.bridge.gateway_mode_ipv6` | `nat` | Enable NAT and masquerading (`nat`), or only allow direct routing to the container (`routed`). |
| `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. |
| `com.docker.network.driver.mtu` | `0` (no limit) | Set the containers network Maximum Transmission Unit (MTU). |
| `com.docker.network.container_iface_prefix` | `eth` | Set a custom prefix for container interfaces. |
| `com.docker.network.bridge.inhibit_ipv4` | `false` | Prevent Docker from [assigning an IP address](#skip-ip-address-configuration) to the network. |
| Option | Default | Description |
|-------------------------------------------------------------------------------------------------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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.bridge.gateway_mode_ipv4`<br/>`com.docker.network.bridge.gateway_mode_ipv6` | `nat` | Enable NAT and masquerading (`nat`), or only allow direct routing to the container (`routed`). See [Packet filtering and firewalls](packet-filtering-firewalls.md). |

Check warning on line 112 in content/manuals/engine/network/drivers/bridge.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'let' instead of 'allow'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'let' instead of 'allow'", "location": {"path": "content/manuals/engine/network/drivers/bridge.md", "range": {"start": {"line": 112, "column": 176}}}, "severity": "INFO"}
| `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. |
| `com.docker.network.driver.mtu` | `0` (no limit) | Set the containers network Maximum Transmission Unit (MTU). |
| `com.docker.network.container_iface_prefix` | `eth` | Set a custom prefix for container interfaces. |
| `com.docker.network.bridge.inhibit_ipv4` | `false` | Prevent Docker from [assigning an IP address](#skip-bridge-ip-address-configuration) to the bridge. |

Some of these options are also available as flags to the `dockerd` CLI, and you
can use them to configure the default `docker0` bridge when starting the Docker
Expand Down Expand Up @@ -229,6 +229,20 @@
$ docker network create --ipv6 --subnet 2001:db8:1234::/64 my-net
```

If you do not provide a `--subnet` option, a Unique Local Address (ULA) prefix
will be chosen automatically.

## IPv6-only bridge networks

To skip IPv4 address configuration on the bridge and in its containers, create
the network with option `--ipv4=false`, and enable IPv6 using `--ipv6`.

```console
$ docker network create --ipv6 --ipv4=false v6net
```

IPv4 address configuration cannot be disabled in the default bridge network.

## Use the default bridge network

The default `bridge` network is considered a legacy detail of Docker and is not
Expand Down Expand Up @@ -259,7 +273,12 @@
}
```

Restart Docker for the changes to take effect.
In this example:

- The bridge's address is "192.168.1.1/24" (from `bip`).
- The bridge network's subnet is "192.168.1.0/24" (from `bip`).
- Container addresses will be allocated from "192.168.1.0/25" (from `fixed-cidr`).


### Use IPv6 with the default bridge network

Expand All @@ -270,22 +289,34 @@
user-defined networks. The addresses in below are examples from the
IPv6 documentation range.

- Option `ipv6` is required
- Option `fixed-cidr-v6` is required, it specifies the network prefix to be used.
- Option `ipv6` is required.
- Option `bip6` is optional, it specifies the address of the default bridge, which
will be used as the default gateway by containers. It also specifies the subnet
for the bridge network.
- Option `fixed-cidr-v6` is optional, it specifies the address range Docker may
automatically allocate to containers.
- The prefix should normally be `/64` or shorter.
- For experimentation on a local network, it is better to use a Unique Local
prefix (matching `fd00::/8`) than a Link Local prefix (matching `fe80::/10`).
Address (ULA) prefix (matching `fd00::/8`) than a Link Local prefix (matching
`fe80::/10`).
- Option `default-gateway-v6` is optional. If unspecified, the default is the first
address in the `fixed-cidr-v6` subnet.

```json
{
"ipv6": true,
"bip6": "2001:db8::1111/64",
"fixed-cidr-v6": "2001:db8::/64",
"default-gateway-v6": "2001:db8:abcd::89"
}
```

If no `bip6` is specified, `fixed-cidr-v6` defines the subnet for the bridge
network. If no `bip6` or `fixed-cidr-v6` is specified, a ULA prefix will be
chosen.

Restart Docker for changes to take effect.

## Connection limit for bridge networks

Due to limitations set by the Linux kernel, bridge networks become unstable and
Expand All @@ -295,20 +326,22 @@
For more information about this limitation, see
[moby/moby#44973](https://github.com/moby/moby/issues/44973#issuecomment-1543747718).

## Skip IP address configuration
## Skip Bridge IP address configuration

The bridge is normally assigned the network's `--gateway` address, which is
used as the default route from the bridge network to other networks.

The `com.docker.network.bridge.inhibit_ipv4` option lets you create a network
that uses an existing bridge and have Docker skip configuring the IPv4 address
on the bridge. This is useful if you want to configure the IP address for the
bridge manually. For instance if you add a physical interface to your bridge,
and need to move its IP address to the bridge interface.
without the IPv4 gateway address being assigned to the bridge. This is useful
if you want to configure the gateway IP address for the bridge manually. For
instance if you add a physical interface to your bridge, and need it to have
the gateway address.

To use this option, you should first configure the Docker daemon to use a
self-managed bridge, using the `bridge` option in the `daemon.json` or the
`dockerd --bridge` flag.
With this configuration, north-south traffic (to and from the bridge network)
won't work unless you've manually configured the gateway address on the bridge,
or a device attached to it.

With this configuration, north-south traffic won't work unless you've manually
configured the IP address for the bridge.
This option can only be used with user-defined bridge networks.

## Next steps

Expand Down
64 changes: 51 additions & 13 deletions content/manuals/engine/network/packet-filtering-firewalls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,31 +129,69 @@ clients. No routes are normally set up in the host's network for container
addresses that exist within a host.

But, particularly with IPv6 you may prefer to avoid using NAT and instead
arrange for external routing to container addresses.
arrange for external routing to container addresses ("direct routing").

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, Border Gateway Protocol
(BGP), or any other means appropriate for your network.

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>`.
Within a local layer 2 network, remote hosts can set up static routes
to a container network using the Docker daemon host's address on the local
network. Those hosts can access containers directly. For remote hosts
outside the local network, direct access to containers requires router
configuration to enable the necessary routing.

#### Gateway modes

The bridge network driver has the following options:
- `com.docker.network.bridge.gateway_mode_ipv6`
- `com.docker.network.bridge.gateway_mode_ipv4`

Each of these can be set to one of the gateway modes:
- `nat`
- `nat-unprotected`
- `routed`

The default is `nat`, NAT and masquerading rules are set up for each
published container port. With mode `routed`, no NAT or masquerading rules
are set up, but `iptables` are still set up so that only published container
ports are accessible.
published container port. Packets leaving the host will use a host address.

With mode `routed`, no NAT or masquerading rules are set up, but `iptables`
are still set up so that only published container ports are accessible.
Outgoing packets from the container will use the container's address,
not a host address.

In `nat` mode, when a port is published to a specific host address, that
port is only accessible via the host interface with that address. So,
for example, publishing a port to an address on the loopback interface
means remote hosts cannot access it.

However, using direct routing, published container ports are always
accessible from remote hosts, unless the Docker host's firewall has
additional restrictions. Hosts on the local layer-2 network can set up
direct routing without needing any additional network configuration.
Hosts outside the local network can only use direct routing to the
container if the network's routers are configured to enable it.

In `nat-unprotected` mode, unpublished container ports are also
accessible using direct routing, no port filtering rules are set up.
This mode is included for compatibility with legacy default behaviour.

The gateway mode also affects communication between containers that
are connected to different Docker networks on the same host.
- In `nat` and `nat-unprotected` modes, containers in other bridge
networks can only access published ports via the host addresses they
are published to. Direct routing from other networks is not allowed.
- In `routed` mode containers in other networks can use direct
routing to access ports, without going via a host address.

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 a mapping only applies to `routed`
mode, 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 is set up in the network, unless the
Docker host's firewall has additional restrictions.
mode, only addresses `0.0.0.0` or `::` should be used, and a host port
should not be given. If a specific address or port is given, it will
have no effect on the published port and a warning message will be
logged.

#### Example

Expand Down