Install Docker CE on Debian with Dual stack and Firewall Support

Introduction

In this tutorial, we will install Docker Community Edition on an server with Debian and adjust its Docker and firewall configurations to easily support dual stack port forwarding (symmetric IPv4 and IPv6 routing) and firewall handling by iptables.

Prerequisites

This tutorial has been tested on a Hetzner Cloud Server, but should work with any cloud server.

A cloud server with a fresh Debian 12 Bookworm image
- Access to the root user or a user with sudo permissions
- SSH key for authentication recommended
If you want to use any internal networks or floating IPs, you should add and configure them before proceeding with this tutorial.
If you need help setting up your fresh cloud server, the official Hetzner Cloud Server FAQ and the basic Debian Server Tutorial may help you. Please skip any firewall and Docker installation steps.

https://docs.docker.com/engine/daemon/ipv6/

Example terminology

Server
- Public IPv4: 203.0.113.1
- Public IPv6: 2001:db8:5678::1
Private subnets
- IPv4: 192.168.0.0/24
- IPv6: fd00::/64
New bridge
- Name: dnetDefault
- Private IPv4: 192.168.0.1
- Private IPv6: fd00::1
Docker container
- Private IPv4: 192.168.0.2
- Private IPv6: fd00::2

Step 1 - Preparation of the environment

First, connect to the server via SSH. If you're not logged in as root, use sudo to open a root shell:

sudo -i

Step 1.1 - Set environment variables

Some values like the main IPv4 and IPv6 address will be used multiple times so we will export them as environment variables for easy reuse.

Please enter your values and run these export commands:

Replace the IPs and the port with your own IPs and the port you're using.

# Main IPv4 address for the cloud server
export TUT_IPV4MAIN="203.0.113.1"
# Main IPv6 address for the cloud server
export TUT_IPV6MAIN="2001:db8:5678::1"
# Configured SSH port used to connect to the server (default: 22)
export TUT_SSHPORT="22"

Step 1.2 - Update and upgrade cloud server

We have to make sure, that the server runs the latest upgrades and its package lists are up-to-date:

apt update && apt dist-upgrade -y

Step 2 - Configure kernel modules for Debian 12

Step 2.1 - Loading br_netfilter on boot

Docker uses the br_netfilter kernel module which sometimes cannot be loaded dynamically by the Docker daemon itself. To make sure that this module is loaded, we will directly load it on boot:

cat << \EOF > /etc/modules-load.d/br_netfilter.conf
br_netfilter
EOF

Step 2.2 - Set kernel parameter for network routing

Some kernel parameters have to be adjusted to support a robust IPv4 and IPv6 routing with Docker:

cat << \EOF > /etc/sysctl.d/85-network.conf
net.ipv4.conf.default.rp_filter=1
net.ipv4.conf.all.rp_filter=1
net.ipv4.ip_forward=1
net.ipv6.conf.all.forwarding=1
net.ipv4.conf.all.accept_redirects = 0
net.ipv6.conf.all.accept_redirects = 0
net.ipv4.conf.all.send_redirects = 0
net.ipv4.conf.all.accept_source_route = 0
net.ipv6.conf.all.accept_source_route = 0
EOF

sysctl --system

Step 3 - Install and configure firewall

We (and Docker) will use iptables and ip6tables for configuring our firewall.

Step 3.1 - Install iptables with persistence job

Iptables is probably already be installed (iptables --version). In addition, we need a persistence systemd job, which will load saved firewall rules on boot:

apt install iptables iptables-persistent

The installation process will ask if we want to save current IPv4 and IPv6 firewall rules. It does not matter if we save or not save the current rulesets as we did not add any rules yet.

Step 3.2 - Create basic firewall rules

Firewall configuration is a complex topic which we will not and cannot cover completly in this tutorial. We will use a very basic default configuration which will only allow incoming SSH connections on all main IPs of the server and some ICMP/ICMPv6 packets:

cat << EOF > /etc/iptables/rules.v4
*filter
:INPUT DROP [0:0]
:FORWARD DROP [0:0]
:OUTPUT DROP [0:0]
:HCFW-ICMP - [0:0]
:HCFW-Local - [0:0]
:HCFW-Services - [0:0]
:HCFW-State - [0:0]
-A INPUT -j HCFW-Local
-A INPUT -j HCFW-State
-A INPUT -p icmp -j HCFW-ICMP
-A INPUT -j HCFW-Services
-A OUTPUT -j HCFW-Local
-A OUTPUT -j HCFW-State
-A OUTPUT -j ACCEPT
-A HCFW-ICMP -p icmp -m icmp --icmp-type 3 -j ACCEPT
-A HCFW-ICMP -p icmp -m icmp --icmp-type 11 -j ACCEPT
-A HCFW-ICMP -p icmp -m icmp --icmp-type 8 -m limit --limit 8/sec -j ACCEPT
-A HCFW-Local -i lo -j ACCEPT
-A HCFW-Services -p tcp -m tcp -d $TUT_IPV4MAIN --dport $TUT_SSHPORT -j ACCEPT
-A HCFW-State -m conntrack --ctstate INVALID -j DROP
-A HCFW-State -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
COMMIT
EOF

cat << EOF > /etc/iptables/rules.v6
*filter
:INPUT DROP [0:0]
:FORWARD DROP [0:0]
:OUTPUT DROP [0:0]
:WCFW-ICMP - [0:0]
:WCFW-Local - [0:0]
:WCFW-Services - [0:0]
:WCFW-State - [0:0]
-A INPUT -j WCFW-Local
-A INPUT -j WCFW-State
-A INPUT -p ipv6-icmp -j WCFW-ICMP
-A INPUT -j WCFW-Services
-A OUTPUT -j WCFW-Local
-A OUTPUT -j WCFW-State
-A OUTPUT -j ACCEPT
-A WCFW-ICMP -p ipv6-icmp -m icmp6 --icmpv6-type 1 -j ACCEPT
-A WCFW-ICMP -p ipv6-icmp -m icmp6 --icmpv6-type 2 -j ACCEPT
-A WCFW-ICMP -p ipv6-icmp -m icmp6 --icmpv6-type 3 -j ACCEPT
-A WCFW-ICMP -p ipv6-icmp -m icmp6 --icmpv6-type 4 -j ACCEPT
-A WCFW-ICMP -p ipv6-icmp -m icmp6 --icmpv6-type 133 -j ACCEPT
-A WCFW-ICMP -p ipv6-icmp -m icmp6 --icmpv6-type 134 -j ACCEPT
-A WCFW-ICMP -p ipv6-icmp -m icmp6 --icmpv6-type 135 -j ACCEPT
-A WCFW-ICMP -p ipv6-icmp -m icmp6 --icmpv6-type 136 -j ACCEPT
-A WCFW-ICMP -p ipv6-icmp -m icmp6 --icmpv6-type 128 -m limit --limit 8/sec -j ACCEPT
-A WCFW-Local -i lo -j ACCEPT
-A WCFW-Services -p tcp -m tcp -d $TUT_IPV6MAIN --dport $TUT_SSHPORT -j ACCEPT
-A WCFW-State -m conntrack --ctstate INVALID -j DROP
-A WCFW-State -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
COMMIT
EOF

Step 4 - Install and configure Docker CE

Now we can install Docker CE on our Debian system. We will install the official packages from Docker Inc. as the Debian package repositories do not contain the latest updates for Docker CE.

Step 4.1 - Configure Docker Inc. APT repositories

Before installing Docker CE, we need to add the apt repositories of Docker Inc. to our package sources and the Docker Inc. Debian Signing Key to our trusted apt keys:

apt install apt-transport-https curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  tee /etc/apt/sources.list.d/docker.list > /dev/null

Step 4.2 - Install Docker Community Edition

Now we can install Docker CE and add our user to the Docker group.

apt update
apt install docker-ce
docker --version
usermod -aG docker <user>

Step 4.3 - Configure Docker daemon

We now need to set some configuration options for the Docker daemon. As DNS servers, Docker will use its own DNS proxy by default but as a backup we will provide an IPv4 and IPv6 Hetzner DNS server. As we use iptables/ip6tables for port forwarding, userland proxy is not needed and should be disabled. In addition to that, we will create a new default bridge which will be used by Docker containers so Docker's own default bridge is not needed anymore.

cat << \EOF > /etc/docker/daemon.json
{
    "log-driver": "journald",
    "bridge": "none",
    "userland-proxy": false,
    "dns": ["2a01:4ff:ff00::add:2", "185.12.64.2"]
}
EOF

Step 4.4 - Create new default bridge for Docker

We now create our new default bridge with a private IPv4 subnet and a private IPv6 subnet:

If those subnets are not used on your system yet, you can keep the private subnets used in this example.

docker network create \
  -d bridge \
  --ipv6 \
  --subnet 192.168.0.0/24 \
  --subnet fd00::/64 \
  -o "com.docker.network.bridge.enable_icc=false" \
  -o "com.docker.network.bridge.name=dnetDefault" \
  dnetDefault

Containers will be able to access external network addresses through NAT but they will not be able to communicate between each other. If you want container-to-container communication, create an additional network and set com.docker.network.bridge.enable_icc to true.

We do not use the docker0 bridge so we need to specify the network with docker run --network dnetDefault <image> for each container. Otherwise the container would be created without networking. As a side effect, this will prevent you from accidentally creating containers with networking capabilities.

Step 4.5 - Patch docker.service systemd service unit

Docker will add and remove iptables rules to our ruleset. If we have existing iptables rules, they need to be loaded before Docker starts. This can be achieved by starting docker.service after netfilter-persistent.service. In addition to that, some IP addresses might not be directly ready at startup (e.g. DHCP for internal networks) so we will delay the Docker service start for two seconds. The following command will override the existing systemd service unit for Docker:

cat << \EOF > /etc/systemd/system/docker.service
[Unit]
Description=Docker Application Container Engine
Documentation=https://docs.docker.com
BindsTo=containerd.service
After=network-online.target firewalld.service netfilter-persistent.service containerd.service
Wants=network-online.target
Requires=docker.socket

[Service]
Type=notify
# the default is not to use systemd for cgroups because the delegate issues still
# exists and systemd currently does not support the cgroup feature set required
# for containers run by docker
ExecStartPre=/bin/sleep 5
ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
ExecReload=/bin/kill -s HUP $MAINPID
TimeoutSec=0
RestartSec=2
Restart=always

# Note that StartLimit* options were moved from "Service" to "Unit" in systemd 229.
# Both the old, and new location are accepted by systemd 229 and up, so using the old location
# to make them work for either version of systemd.
StartLimitBurst=3

# Note that StartLimitInterval was renamed to StartLimitIntervalSec in systemd 230.
# Both the old, and new name are accepted by systemd 230 and up, so using the old name to make
# this option work for either version of systemd.
StartLimitInterval=60s

# Having non-zero Limit*s causes performance problems due to accounting overhead
# in the kernel. We recommend using cgroups to do container-local accounting.
LimitNOFILE=infinity
LimitNPROC=infinity
LimitCORE=infinity

# Comment TasksMax if your systemd version does not support it.
# Only systemd 226 and above support this option.
TasksMax=infinity

# set delegate yes so that systemd does not reset the cgroups of Docker containers
Delegate=yes

# kill only the Docker process, not all processes in the cgroup
KillMode=process

[Install]
WantedBy=multi-user.target
EOF

Step 4.6 - Setup kernel flags in GRUB_CMDLINE

Some kernel features have to be enabled for the Docker daemon on system startup and need to be added to the default grub commandline:

sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT="/GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1 /g' /etc/default/grub
update-grub

Step 5 - Reboot

We can now reboot the server and exit the root shell:

reboot

Step 7 - Spawn a basic HTTPD webserver (Optional)

After rebooting the server, we can test our configuration and spawn a basic HTTPD webserver.

Step 7.1 - Check systemd services

First we need to check if all systemd services are executed correctly:

sudo systemctl status netfilter-persistent.service --no-pager
sudo systemctl status docker.service --no-pager

The netfilter-persistent job should be executed successfully. The other service should be running without errors.

Step 7.2 - Check networking

As the next step, we have to check if our Docker bridge is configured correctly.

ip addr

You should now see the dnetDefault interface (using example values for subnets):

4: dnetDefault: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default
    link/ether 02:42:e5:a0:9b:4f brd ff:ff:ff:ff:ff:ff
    inet 192.168.0.1/24 brd 192.168.0.255 scope global dnetDefault
       valid_lft forever preferred_lft forever
    inet6 fd00::1/64 scope global tentative
       valid_lft forever preferred_lft forever

Step 7.3 - Check kernel modules

br_netfilter should be loaded:

lsmod | grep br_netfilter

The output should look like that:

br_netfilter           24576  0
bridge                188416  1 br_netfilter

Step 7.4 - Spawn HTTPD container

We can now spawn the container (replace values accordingly):

Replace 203.0.113.1 and 2001:db8:5678::1 with the public IPs of your server.

# Main IPv4 address for the cloud server
export HCTUT_IPV4MAIN="203.0.113.1"
# Main IPv6 address for the cloud server
export HCTUT_IPV6MAIN="2001:db8:5678::1"
sudo docker run \
  -d \
  --restart always \
  --name test-httpd \
  --network dnetDefault \
  --publish $HCTUT_IPV4MAIN:8080:80 \
  --publish [$HCTUT_IPV6MAIN]:8080:80 \
  httpd:latest

You should now be able to access http://203.0.113.1:8080 and http://[2001:db8:5678::1]:8080.

The Docker container should have private IPs assigned from the new network dnetDefault. To check, run:

docker inspect test-httpd | grep -A 1 '"Networks":' | tail -n 1
docker inspect test-httpd | grep  -E '"IPAddress":|"GlobalIPv6Address":'

You should be able to ping those private IPs with:

ping <container_ipv4>
ping6 <container_ipv6>

Step 7.5 - Check iptables

sudo iptables -t nat -nvL
sudo iptables -nvL

Click here to view an example output

root@tutorial:~# sudo iptables -t nat -nvL
Chain PREROUTING (policy ACCEPT 0 packets, 0 bytes)
 pkts bytes target     prot opt in     out     source               destination
   59  2532 DOCKER     0    --  *      *       0.0.0.0/0            0.0.0.0/0            ADDRTYPE match dst-type LOCAL

Chain INPUT (policy ACCEPT 0 packets, 0 bytes)
 pkts bytes target     prot opt in     out     source               destination

Chain OUTPUT (policy ACCEPT 0 packets, 0 bytes)
 pkts bytes target     prot opt in     out     source               destination
    0     0 DOCKER     0    --  *      *       0.0.0.0/0            0.0.0.0/0            ADDRTYPE match dst-type LOCAL

Chain POSTROUTING (policy ACCEPT 0 packets, 0 bytes)
 pkts bytes target      prot opt in     out           source               destination
    3   208 MASQUERADE  0    --  *      dnetDefault   0.0.0.0/0            0.0.0.0/0            ADDRTYPE match src-type LOCAL
    4   288 MASQUERADE  0    --  *      !dnetDefault  192.168.0.0/24       0.0.0.0/0
    0     0 MASQUERADE  6    --  *      *             192.168.0.2          192.168.0.2          tcp dpt:80

Chain DOCKER (2 references)
 pkts bytes target     prot opt in     out     source               destination
    2   104 DNAT       6    --  *      *       0.0.0.0/0            203.0.113.1           tcp dpt:8080 to:192.168.0.2:80

root@tutorial:~# sudo iptables -nvL
Chain INPUT (policy DROP 61 packets, 2588 bytes)
 pkts bytes target         prot opt in     out     source               destination
  858 50802 HCFW-Local     0    --  *      *       0.0.0.0/0            0.0.0.0/0
  858 50802 HCFW-State     0    --  *      *       0.0.0.0/0            0.0.0.0/0
    0     0 HCFW-ICMP      1    --  *      *       0.0.0.0/0            0.0.0.0/0
   64  2728 HCFW-Services  0    --  *      *       0.0.0.0/0            0.0.0.0/0

Chain FORWARD (policy DROP 0 packets, 0 bytes)
 pkts bytes target                    prot  opt in           out           source               destination
  640 9370K DOCKER-ISOLATION-STAGE-1  0     --  *            *             0.0.0.0/0            0.0.0.0/0
  479 9359K ACCEPT                    0     --  *            dnetDefault   0.0.0.0/0            0.0.0.0/0            ctstate RELATED,ESTABLISHED
    2   104 DOCKER                    0     --  *            dnetDefault   0.0.0.0/0            0.0.0.0/0
  159 10444 ACCEPT                    0     --  dnetDefault  !dnetDefault  0.0.0.0/0            0.0.0.0/0
    0     0 DROP                      0     --  dnetDefault  dnetDefault   0.0.0.0/0            0.0.0.0/0

Chain OUTPUT (policy DROP 0 packets, 0 bytes)
 pkts bytes target      prot opt in     out     source               destination
  644 84784 HCFW-Local  0    --  *      *       0.0.0.0/0            0.0.0.0/0
  644 84784 HCFW-State  0    --  *      *       0.0.0.0/0            0.0.0.0/0
    5   288 ACCEPT      0    --  *      *       0.0.0.0/0            0.0.0.0/0

Chain DOCKER (1 references)
 pkts bytes target     prot opt in            out           source        destination
    2   104 ACCEPT     6    --  !dnetDefault  dnetDefault   0.0.0.0/0     192.168.0.2          tcp dpt:80

Chain DOCKER-ISOLATION-STAGE-1 (1 references)
 pkts bytes target     prot opt in     out     source               destination
  159 10444 DOCKER-ISOLATION-STAGE-2  0    --  dnetDefault !dnetDefault  0.0.0.0/0            0.0.0.0/0
  640 9370K RETURN     0    --  *      *       0.0.0.0/0            0.0.0.0/0

Chain DOCKER-ISOLATION-STAGE-2 (1 references)
 pkts bytes target     prot opt in     out     source               destination
    0     0 DROP       0    --  *      dnetDefault  0.0.0.0/0            0.0.0.0/0
  159 10444 RETURN     0    --  *      *       0.0.0.0/0            0.0.0.0/0

Chain HCFW-ICMP (1 references)
 pkts bytes target     prot opt in     out     source               destination
    0     0 ACCEPT     1    --  *      *       0.0.0.0/0            0.0.0.0/0            icmptype 3
    0     0 ACCEPT     1    --  *      *       0.0.0.0/0            0.0.0.0/0            icmptype 11
    0     0 ACCEPT     1    --  *      *       0.0.0.0/0            0.0.0.0/0            icmptype 8 limit: avg 8/sec burst 5

Chain HCFW-Local (2 references)
 pkts bytes target     prot opt in     out     source               destination
    0     0 ACCEPT     0    --  lo     *       0.0.0.0/0            0.0.0.0/0

Chain HCFW-Services (1 references)
 pkts bytes target     prot opt in     out     source               destination
    3   140 ACCEPT     6    --  *      *       0.0.0.0/0            203.0.113.1          tcp dpt:22

Chain HCFW-State (2 references)
 pkts bytes target     prot opt in     out     source               destination
    1    40 DROP       0    --  *      *       0.0.0.0/0            0.0.0.0/0            ctstate INVALID
 1432  133K ACCEPT     0    --  *      *       0.0.0.0/0            0.0.0.0/0            ctstate RELATED,ESTABLISHED

Step 7.6 - Check ip6tables

sudo ip6tables -t nat -nvL
sudo ip6tables -nvL