Analysis and Solutions for iptables Error When Starting Docker Containers

Problem Description and Context

When attempting to run a Docker container, the user encountered the following error message:

Error response from daemon: Cannot start container b005715c40ea7d5821b15c44f5b7f902d4b39da7c83468f3e5d7c042e5fe3fbd: iptables failed: iptables --wait -t filter -A DOCKER ! -i docker0 -o docker0 -p tcp -d 172.17.0.43 --dport 80 -j ACCEPT: iptables: No chain/target/match by that name.
 (exit status 1)

This error occurred while executing the command: docker run -d -p 10080:80 -v /srv/http/website/data:/srv/http/www/data -v /srv/http/website/logs:/srv/http/www/logs myimage. The user had configured iptables firewall rules, including allowing access to port 80, but Docker still failed to start the container properly.

Root Cause Analysis

The core issue lies in the following two lines from the user's iptables configuration script:

iptables -t filter -F
iptables -t filter -X

These commands perform:

• -F: Flushes all rules from chains
• -X: Deletes user-defined empty chains

When the Docker daemon starts, it automatically creates a custom iptables chain named DOCKER for managing container network traffic. This chain is a fundamental component of Docker's networking functionality, responsible for handling container port mapping, network isolation, and other critical operations.

The user's script, while clearing custom rules, also removes the DOCKER chain created by Docker. When subsequently attempting to start a container, Docker needs to add rules to this non-existent chain, triggering the "No chain/target/match by that name" error.

Docker and iptables Integration Mechanism

Docker utilizes iptables to implement the following key networking features:

1. Port Mapping: When using the -p parameter, Docker adds NAT rules to the DOCKER chain
2. Network Isolation: Controls inter-container communication through the DOCKER-ISOLATION chain
3. Traffic Forwarding: References the DOCKER chain in the FORWARD chain to handle container traffic

A typical Docker network rule structure appears as:

Chain FORWARD (policy DROP)
target     prot opt source               destination         
DOCKER-ISOLATION  all  --  anywhere             anywhere            
DOCKER     all  --  anywhere             anywhere            
ACCEPT     all  --  anywhere             anywhere            ctstate RELATED,ESTABLISHED
ACCEPT     all  --  anywhere             anywhere            
ACCEPT     all  --  anywhere             anywhere            

Chain DOCKER (1 references)
target     prot opt source               destination         
ACCEPT     tcp  --  anywhere             172.17.0.2          tcp dpt:http

Solution Approaches

Solution 1: Adjust Execution Order (Recommended)

Based on the best answer, the most fundamental solution is to ensure the Docker daemon starts after the iptables configuration script. This guarantees:

1. Docker creates necessary chains and rules first
2. User-defined rules are added on top without disrupting Docker's infrastructure

Implementation approach:

# 1. Start Docker service
sudo systemctl start docker

# 2. Execute custom iptables configuration
sudo ./firewall-script.sh

Solution 2: Restart Docker Service

If Docker chains have been accidentally cleared, simply restarting the Docker service can resolve the issue:

sudo systemctl restart docker

After restart, Docker automatically recreates all necessary iptables chains and base rules. This method is simple and effective but may interrupt running containers.

Solution 3: Selective Rule Cleanup

Modify the iptables script to avoid cleaning Docker-related chains:

#!/bin/bash

# Save current chain list
CHAIN_LIST=$(iptables -t filter -L | grep Chain | awk '{print $2}')

# Clean only non-Docker chains
for chain in $CHAIN_LIST; do
    if [[ "$chain" != "DOCKER"* ]] && [[ "$chain" != "DOCKER-ISOLATION" ]]; then
        iptables -t filter -F "$chain"
    fi
done

# Continue with other configurations...

Deep Understanding and Best Practices

To prevent such issues, understanding several key concepts is essential:

1. Docker Network Namespaces
Docker creates independent network namespaces for each container, with iptables rules coordinated across namespaces via veth pairs and bridges. The docker0 bridge serves as the default container network gateway, relying on proper iptables configuration for traffic control.

2. Rule Persistence
Using iptables-save and iptables-restore provides better rule persistence management:

# Save current rules
sudo iptables-save > /etc/iptables/rules.v4

# Restore on system boot
# Add to /etc/rc.local or systemd service:
iptables-restore < /etc/iptables/rules.v4

3. Leveraging Docker Native Network Features
Consider using Docker's native network features to replace some iptables configurations:

# Create custom network
docker network create --subnet=172.20.0.0/16 mynetwork

# Run container with specified network
docker run --network=mynetwork -p 80:80 myimage

Troubleshooting Steps

When encountering similar problems, follow these troubleshooting steps:

1. Check if Docker chains exist: sudo iptables -t filter -L -n | grep DOCKER
2. Examine Docker service status: sudo systemctl status docker
3. Review Docker logs: sudo journalctl -u docker.service
4. Verify network configuration: sudo docker network ls and sudo docker network inspect bridge

Conclusion

The integration of Docker with iptables provides powerful networking capabilities but requires careful management. The key is understanding Docker's automatic iptables chain management mechanism and avoiding unintentional disruption of this infrastructure in custom firewall scripts. By adjusting script execution order, using selective cleanup, or restarting Docker service when necessary, the "No chain/target/match by that name" error can be effectively resolved, ensuring proper container network operation.

In production environments, it is recommended to separate iptables configuration from Docker management, using dedicated configuration management tools or writing more refined firewall scripts that clearly distinguish between system rules, Docker infrastructure rules, and application rules. This approach enables more stable and reliable containerized deployments.