mirror of
https://github.com/docker-mailserver/docker-mailserver.git
synced 2024-01-19 02:48:50 +00:00
docs: IPv6 config examples with content tabs (#3436)
For added clarity, a user requested we document the example config snippets instead of only linking external references to them. Revised section and adjusted to presenting via the content tabs feature.
This commit is contained in:
Brennan Kinney
GitHub
parent
5ef048bfae
commit
a0fde8b83f
|
|
@ -64,35 +64,97 @@ Enable `ip6tables` support so that Docker will manage IPv6 networking rules as w
|
|||
|
||||
Now restart the daemon if it's running: `systemctl restart docker`.
|
||||
|
||||
Next, configure a network for your container with any of these:
|
||||
Next, configure a network with an IPv6 subnet for your container with any of these examples:
|
||||
|
||||
- [User-defined networks via `docker network create` or `compose.yaml`][docker-docs-ipv6-create-custom]
|
||||
- [Default docker bridge][docker-docs-ipv6-create-default] (_docker CLI only, not helpful for `compose.yaml`_)
|
||||
- [Default network for a `compose.yaml`][ipv6-config-example] (_`/etc/docker/daemon.json` settings for default bridge do not apply, instead override the generated `default` network_)
|
||||
???+ example "Create an IPv6 ULA subnet"
|
||||
|
||||
!!! danger "Do not use `2001:db8:1::/64` for your private subnet"
|
||||
??? info "About these examples"
|
||||
|
||||
The `2001:db8` address prefix is [reserved for documentation][wikipedia-ipv6-reserved]. Avoid using a subnet with this prefix.
|
||||
These examples are focused on a [IPv6 ULA subnet][wikipedia-ipv6-ula] which is suitable for most users as described in the next section.
|
||||
|
||||
!!! example "User-defined IPv6 ULA subnet"
|
||||
- You may prefer a subnet size smaller than `/64` (eg: `/112`, which still provides over 65k IPv6 addresses), especially if instead configuring for an IPv6 GUA subnet.
|
||||
- The network will also implicitly be assigned an IPv4 subnet (_from the Docker daemon config `default-address-pools`_).
|
||||
|
||||
- Either of these should work well. You can use a smaller subnet size like `/112` if you prefer.
|
||||
- The network will also include an IPv4 subnet assigned implicitly.
|
||||
=== "User-defined Network"
|
||||
|
||||
```bash
|
||||
# CLI
|
||||
docker network create --ipv6 --subnet fd00:cafe:face:feed::/64 dms-ipv6
|
||||
```
|
||||
The preferred approach is with [user-defined networks][docker-docs-ipv6-create-custom] via `compose.yaml` (recommended) or CLI with `docker network create`:
|
||||
|
||||
```yaml
|
||||
# compose.yaml
|
||||
=== "Compose"
|
||||
|
||||
Create the network in `compose.yaml` and attach a service to it:
|
||||
|
||||
```yaml title="compose.yaml"
|
||||
services:
|
||||
mailserver:
|
||||
networks:
|
||||
# Overrides the `default` compose generated network, avoids needing to attach to each service:
|
||||
default:
|
||||
- dms-ipv6
|
||||
|
||||
networks:
|
||||
dms-ipv6:
|
||||
enable_ipv6: true
|
||||
subnet: fd00:cafe:face:feed::/64
|
||||
```
|
||||
|
||||
??? tip "Override the implicit `default` network"
|
||||
|
||||
You can optionally avoid the service assignment by [overriding the `default` user-defined network that Docker Compose generates](docker-docs-network-compose-default). Just replace `dms-ipv6` with `default`.
|
||||
|
||||
The Docker Compose `default` bridge is not affected by settings for the default `bridge` (aka `docker0`) in `/etc/docker/daemon.json`.
|
||||
|
||||
??? tip "Using the network outside of this `compose.yaml`"
|
||||
|
||||
To reference this network externally (_from other compose files or `docker run`_), assign the [networks `name` key in `compose.yaml`][docker-docs-network-external].
|
||||
|
||||
=== "CLI"
|
||||
|
||||
Create the network via a CLI command (_which can then be used with `docker run --network dms-ipv6`_):
|
||||
|
||||
```bash
|
||||
docker network create --ipv6 --subnet fd00:cafe:face:feed::/64 dms-ipv6
|
||||
```
|
||||
|
||||
Optionally reference it from one or more `compose.yaml` files:
|
||||
|
||||
```yaml title="compose.yaml"
|
||||
services:
|
||||
mailserver:
|
||||
networks:
|
||||
- dms-ipv6
|
||||
|
||||
networks:
|
||||
dms-ipv6:
|
||||
external: true
|
||||
```
|
||||
|
||||
=== "Default Bridge (daemon)"
|
||||
|
||||
!!! warning "This approach is discouraged"
|
||||
|
||||
The [`bridge` network is considered legacy][docker-docs-network-bridge-legacy].
|
||||
|
||||
Add these two extra IPv6 settings to your daemon config. They only apply to the [default `bridge` docker network][docker-docs-ipv6-create-default] aka `docker0` (_which containers are attached to by default when using `docker run`_).
|
||||
|
||||
```json title="/etc/docker/daemon.json"
|
||||
{
|
||||
"ipv6": true,
|
||||
"fixed-cidr-v6": "fd00:cafe:face:feed::/64",
|
||||
}
|
||||
```
|
||||
|
||||
Compose projects can also use this network via `network_mode`:
|
||||
|
||||
```yaml title="compose.yaml"
|
||||
services:
|
||||
mailserver:
|
||||
network_mode: bridge
|
||||
```
|
||||
|
||||
!!! danger "Do not use `2001:db8:1::/64` for your private subnet"
|
||||
|
||||
The `2001:db8` address prefix is [reserved for documentation][wikipedia-ipv6-reserved]. Avoid creating a subnet with this prefix.
|
||||
|
||||
Presently this is used in examples for Dockers IPv6 docs as a placeholder, while mixed in with private IPv4 addresses which can be misleading.
|
||||
|
||||
### Configuring an IPv6 subnet
|
||||
|
||||
If you've [configured IPv6 address pools in `/etc/docker/daemon.json`][docker-docs-ipv6-supernets], you do not need to specify a subnet explicitly. Otherwise if you're unsure what value to provide, here's a quick guide (_Tip: Prefer IPv6 ULA, it's the least hassle_):
|
||||
|
|
@ -132,8 +194,10 @@ curl --max-time 5 http://[2001:db8::1]:80
|
|||
[docker-docs-ipv6-create-custom]: https://docs.docker.com/config/daemon/ipv6/#create-an-ipv6-network
|
||||
[docker-docs-ipv6-create-default]: https://docs.docker.com/config/daemon/ipv6/#use-ipv6-for-the-default-bridge-network
|
||||
[docker-docs-ipv6-supernets]: https://docs.docker.com/config/daemon/ipv6/#dynamic-ipv6-subnet-allocation
|
||||
[docker-docs-network-external]: https://docs.docker.com/compose/compose-file/06-networks/#name
|
||||
[docker-docs-network-compose-default]: https://docs.docker.com/compose/networking/#configure-the-default-network
|
||||
[docker-docs-network-bridge-legacy]: https://docs.docker.com/network/drivers/bridge/#use-the-default-bridge-network
|
||||
|
||||
[ipv6-config-example]: https://github.com/nginx-proxy/nginx-proxy/issues/133#issuecomment-1368745843
|
||||
[wikipedia-ipv6-reserved]: https://en.wikipedia.org/wiki/IPv6_address#Documentation
|
||||
[wikipedia-ipv4-private]: https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses
|
||||
[wikipedia-ipv6-ula]: https://en.wikipedia.org/wiki/Unique_local_address
|
||||
|
|
|
|||
Loading…
Reference in a new issue