Debian 12 Bookworm: Docker Port Mapping Ignored on Bridge Network Troubleshooting

Experiencing Docker host port mapping failures on Debian 12 Bookworm's bridge network? This guide details root causes and step-by-step `nftables` and Docker configuration fixes.

When deploying Docker containers on Debian 12 (Bookworm), you might encounter a frustrating issue where your specified host port mappings (-p 8080:80) are seemingly ignored, making your services inaccessible from outside the host machine, even though the containers appear to be running correctly. This often manifests despite docker ps showing the correct port bindings and docker-proxy listening on the host. This guide will delve into the underlying causes, specifically concerning Debian 12's default use of nftables, and provide a highly technical, step-by-step resolution.

Symptom & Error Signature

The primary symptom is a lack of connectivity to Docker-mapped ports from external networks, or even from the host machine's external IP address, despite all appearances indicating correct configuration.

Typical observations:

1. Container running with correct port mapping:

   $ docker ps
   CONTAINER ID   IMAGE                 COMMAND                  CREATED         STATUS         PORTS                     NAMES
   a1b2c3d4e5f6   nginx:latest          "/docker-entrypoint.…"   2 minutes ago   Up 2 minutes   0.0.0.0:8080->80/tcp      webserver
   

   Here, 0.0.0.0:8080->80/tcp indicates Docker should be listening on port 8080 on all host interfaces and forwarding to container port 80.

2. docker-proxy is listening on the host:

   $ sudo ss -tulnp | grep 8080
   tcp   LISTEN 0      4096   0.0.0.0:8080     0.0.0.0:*    users:(("docker-proxy",pid=12345,fd=4))
   tcp   LISTEN 0      4096      [::]:8080        [::]:*    users:(("docker-proxy",pid=12345,fd=5))
   

   This confirms docker-proxy has bound to the specified port on the host.

3. Localhost access works, external access fails:

   $ curl http://localhost:8080 # This works
   <!DOCTYPE html>
   <html>
   <head>
   <title>Welcome to nginx!</title>
   ...
   

   $ curl http://YOUR_SERVER_IP:8080 # This times out or connection refused
   curl: (7) Failed to connect to YOUR_SERVER_IP port 8080 after X ms: Connection timed out
   

4. iptables rules appear correct:

   $ sudo iptables -t nat -L -n -v
   # ...
   Chain DOCKER (2 references)
    pkts bytes target     prot opt in     out     source               destination
       0     0 DNAT       tcp  --  !docker0 *       0.0.0.0/0            0.0.0.0/0            tcp dpt:8080 to:172.17.0.2:80
   # ...
   

   Docker has successfully added the necessary DNAT (Destination Network Address Translation) rule to redirect traffic.

Despite these checks, external connections are blocked.

Root Cause Analysis

The core of this issue on Debian 12 (Bookworm) stems from its transition to nftables as the default packet filtering framework, replacing the traditional iptables-legacy. While Docker primarily interacts with the netfilter subsystem via iptables commands (which on Debian 12 are typically aliased to iptables-nft, a compatibility layer), the underlying nftables ruleset can override or preempt Docker's rules, especially concerning default policies or specific chain priorities.

Here's a breakdown of the underlying reasons:

1. nftables Default Policies: Debian 12's nftables configuration, especially if firewalld or ufw are not explicitly managing it, often defaults to a policy drop on critical chains like filter input and filter forward.
2. Docker's netfilter Interaction: When you map a host port (e.g., -p 8080:80), Docker performs two key actions:
   • It starts a docker-proxy process that listens on the host's 0.0.0.0:8080.
   • It adds iptables NAT rules to redirect incoming traffic destined for HOST_IP:8080 to the container's IP and port (e.g., 172.17.0.2:80). This DNAT occurs in the nat PREROUTING chain.
   • It adds iptables FILTER rules (in the FORWARD chain) to allow the forwarded packet to reach the container.
3. nftables Precedence: Even though iptables-nft aims for compatibility, nftables rules can have higher precedence or be evaluated earlier in the packet processing pipeline, especially if default input or forward policies are set to drop. A packet destined for HOST_IP:8080 (before DNAT) or for CONTAINER_IP:80 (after DNAT) might be dropped by nftables before it hits the iptables chain where Docker's ACCEPT rules reside, or nftables might simply have a broader drop rule.
   • Specifically, after the DNAT in the nat PREROUTING chain, the packet is now destined for the container. It then enters the filter FORWARD chain. If nftables has a drop policy on this chain and no explicit accept rule for traffic originating externally and destined for the docker0 bridge (or specific container IPs), the packet will be dropped.
4. Inconsistent Firewall Management: If you have multiple firewall management tools (e.g., firewalld and ufw) installed or partially configured, or if nftables rules are manually managed in addition to Docker's iptables rules, conflicts can arise.

Step-by-Step Resolution

This section outlines the most robust and recommended approaches to resolve Docker port mapping issues on Debian 12. We prioritize nftables configuration as it is the default.

1. Verify Docker Network Configuration

First, ensure Docker's internal networking is configured to manage iptables rules.

1. Check daemon.json: Ensure Docker is configured to manage iptables rules. By default, it is. If you have /etc/docker/daemon.json, make sure it does not contain "iptables": false. If it does, remove or set it to true.

   {
     "iptables": true
   }
   

   If you modified it, restart Docker:

   sudo systemctl restart docker
   

2. Confirm Docker's iptables Rules: Check the nat and filter tables for Docker-related rules.

   sudo iptables -t nat -L -n -v
   sudo iptables -L -n -v # Checks filter table
   

   You should see DOCKER chains with DNAT rules in the nat table and ACCEPT rules in the filter FORWARD chain targeting the docker0 bridge.

2. Identify the Active Firewall Solution

Debian 12 primarily uses nftables, but it can be managed by firewalld, ufw, or directly. Determining which is active is crucial.

1. Check firewalld status:

   sudo systemctl status firewalld
   

   If it's active (running), firewalld is managing your firewall.

2. Check ufw status:

   sudo ufw status
   

   If it's Status: active, ufw is managing your firewall.

3. Check nftables directly: If neither firewalld nor ufw are active, your system is likely managing nftables directly.

   sudo nft list ruleset
   

   This command displays the entire active nftables ruleset. Look for table ip filter and chains like input and forward. Pay close attention to their policies (e.g., policy drop;).

   Never blindly disable your firewall without understanding the security implications. This can expose your server to significant risks.

3. Configure the Active Firewall to Allow Docker Traffic

Proceed based on your active firewall.

If firewalld is Active

firewalld on Debian 12 uses nftables as its backend. You need to open the specific host ports in firewalld.

# Example: Allow TCP traffic on port 8080
sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
# If you have other Docker-mapped ports, add them too (e.g., 8443)
sudo firewall-cmd --zone=public --add-port=8443/tcp --permanent
# Reload firewalld to apply changes
sudo firewall-cmd --reload

This should allow incoming connections to your Docker-mapped ports. firewalld should correctly handle the interaction with Docker's iptables rules.

If ufw is Active

ufw (Uncomplicated Firewall) also leverages nftables on Debian 12.

# Example: Allow TCP traffic on port 8080
sudo ufw allow 8080/tcp
# If you have other Docker-mapped ports, add them too (e.g., 8443)
sudo ufw allow 8443/tcp
# Reload ufw (or disable/enable) to apply changes
sudo ufw reload # Or: sudo ufw disable && sudo ufw enable

ufw will create the necessary nftables rules.

If nftables is Directly Managed

This is the most likely scenario on a minimal Debian 12 installation without firewalld or ufw. You need to explicitly add rules to your nftables configuration. The key is to ensure the filter forward chain permits traffic to your Docker bridge interface.

1. Backup current nftables config:

   sudo cp /etc/nftables.conf /etc/nftables.conf.bak
   

2. Edit /etc/nftables.conf: Open the configuration file for editing:

   sudo nano /etc/nftables.conf
   

   Locate your table ip filter block. If a chain forward exists, modify it. If not, create it. The critical part is to explicitly allow traffic that is being forwarded to and from the docker0 bridge interface.

   Add or modify your filter forward chain similar to this example (adjusting policy drop if your existing policy is accept):

   table ip filter {
       chain input {
           type filter hook input priority 0; policy drop; # Common default policy
           # ... (existing rules for localhost, SSH, established connections) ...
           iif "lo" accept
           ct state established,related accept
           tcp dport 22 accept # Allow SSH
           # Add any other specific host services here (e.g., web server running directly)
           # Example: tcp dport { 80, 443 } accept # If Nginx/Apache runs directly
       }
   
       chain forward {
           type filter hook forward priority 0; policy drop; # <--- THIS IS OFTEN THE CULPRIT
           ct state established,related accept
   
           # Allow traffic FROM the docker0 bridge interface (container to external)
           iifname "docker0" accept
   
           # Allow traffic TO the docker0 bridge interface (external to container via Docker NAT)
           oifname "docker0" accept
   
           # For IPv6 Docker configurations, you might also need similar rules in `table ip6 filter`
       }
   
       chain output {
           type filter hook output priority 0; policy accept; # Common default policy
           ct state established,related accept
           # ... (other output rules) ...
       }
   }
   

3. Apply and persist nftables rules:

   sudo nft -f /etc/nftables.conf
   # Enable the nftables service to load rules on boot
   sudo systemctl enable nftables
   sudo systemctl restart nftables
   

   After modifying nftables.conf, it's critical to test connectivity from an external machine to YOUR_SERVER_IP:YOUR_DOCKER_PORT. Use nc -vz YOUR_SERVER_IP YOUR_DOCKER_PORT or curl. If you lose SSH access, you may need console access to revert changes.

4. Alternative: Revert to iptables-legacy (Less Recommended)

While nftables is the modern approach, if you encounter persistent issues, or if you have complex legacy iptables configurations, you can force Docker to use iptables-legacy.

Switching to iptables-legacy can have implications if other services on your system are configured to interact specifically with nftables. This should be considered a last resort or for specific compatibility needs, as it deviates from Debian 12's default.

1. Configure update-alternatives:

   sudo update-alternatives --config iptables
   # Select the option corresponding to 'iptables-legacy'
   
   sudo update-alternatives --config ip6tables
   # Select the option corresponding to 'ip6tables-legacy'
   

   You will be presented with a list like:

     Selection    Path                       Priority   Status
   ------------------------------------------------------------
   * 0            /usr/sbin/iptables-nft      90        auto mode
     1            /usr/sbin/iptables-legacy   50        manual mode
     2            /usr/sbin/iptables-nft      90        manual mode
   
   Press <enter> to keep the current choice[*], or type selection number:
   

   Type 1 and press Enter for iptables-legacy. Repeat for ip6tables.

2. Restart Docker:

   sudo systemctl restart docker
   

   Docker will now configure rules using the iptables-legacy binaries, which might behave more predictably in some scenarios.

5. Verify Connectivity

After applying any of the above changes, re-test access to your Docker-mapped ports:

# From an external machine or different host
curl http://YOUR_SERVER_IP:8080

# You can also use netcat for a quick port check
nc -vz YOUR_SERVER_IP 8080

A successful connection or "Connection to YOUR_SERVER_IP 8080 port [tcp/*] succeeded!" indicates the issue is resolved.