Master Docker Networking: Choosing the Right Mode (Bridge, Host, Overlay, Macvlan)

Overview

Container networking is the most error‑prone part of Docker usage. Understanding how containers communicate with each other, reach the external network, and expose services is essential for effective troubleshooting.

Docker networking relies on Linux network namespaces, veth pairs, iptables, and a bridge (docker0). Each container gets its own namespace and connects to the host bridge via a veth pair; external access is performed through iptables NAT.

Docker network modes

bridge : default mode, uses docker0 bridge and NAT; good isolation, ~5‑10% performance loss.

host : container shares the host network stack, no NAT overhead, performance identical to host, but no isolation.

none : container has only a loopback interface, completely isolated; suited for batch jobs or security‑sensitive tasks.

container : multiple containers share the same network namespace; containers communicate via localhost. Kubernetes Pods are built on this principle.

overlay : VXLAN‑based cross‑host network used by Docker Swarm and some K8s plugins.

macvlan : container receives a physical‑network IP and MAC address, behaving like a standalone host; ideal when direct physical network access is required.

Applicable scenarios

bridge – most single‑host deployments, development and testing.

host – high‑performance apps (e.g., Nginx reverse proxy, high‑frequency trading) that need to listen on many ports.

none – tasks that must not have any network access.

container – sidecar patterns such as log collection or monitoring agents.

overlay – cross‑host service communication in Docker Swarm clusters.

macvlan – containers that need independent MAC/IP addresses, typical for migrating traditional network architectures.

Environment requirements

Docker Engine: 20.10+ (24.0+ recommended)

Linux kernel: 3.10+ (4.0+ required for overlay VXLAN)

iptables: 1.4+ (required for bridge NAT)

bridge-utils, iproute2, tcpdump – useful for debugging.

Detailed steps

Preparation

System check

# Check kernel network modules
lsmod | grep -E "bridge|vxlan|macvlan|overlay"

# Verify IP forwarding is enabled (must be 1)
sysctl net.ipv4.ip_forward

# List iptables rules
iptables -L -n
iptables -t nat -L -n

# Show docker0 bridge
ip addr show docker0
brctl show docker0

# Install debugging tools
# Debian/Ubuntu
sudo apt install -y bridge-utils tcpdump iproute2 net-tools
# CentOS/RHEL
sudo yum install -y bridge-utils tcpdump iproute net-tools

View current Docker networks

# List all Docker networks
docker network ls

# Default networks:
# bridge – default bridge network
# host   – host network
# none   – no network

# Inspect bridge network details
docker network inspect bridge

# List containers attached to bridge
docker network inspect bridge --format '{{range .Containers}}{{.Name}}: {{.IPv4Address}}{{"
"}}{{end}}'

Core configuration

Bridge mode details

Bridge is Docker's default network. Docker creates a docker0 virtual bridge; each container connects via a veth pair. Containers communicate through the bridge (layer‑2 forwarding) and reach the external network via iptables MASQUERADE.

Packet flow :

container eth0 → veth pair → docker0 bridge → iptables NAT → host eth0 → external network

Create a custom bridge network (recommended) with more features:

# docker network create \
  --driver bridge \
  --subnet 172.20.0.0/24 \
  --gateway 172.20.0.1 \
  --opt "com.docker.network.bridge.name"="br-mynet" \
  --opt "com.docker.network.bridge.enable_icc"="true" \
  --opt "com.docker.network.bridge.enable_ip_masquerade"="true" \
  mynet

Run containers in the custom network and benefit from built‑in DNS name resolution:

# Start two containers
docker run -d --name web1 --network mynet nginx:1.24-alpine
docker run -d --name web2 --network mynet nginx:1.24-alpine

# Verify DNS resolution
docker exec web1 ping -c 3 web2

Default bridge vs. custom bridge :

Container name DNS resolution – default: not supported; custom: supported.

Isolation – default: all containers on the same bridge can reach each other; custom: isolation between different custom bridges.

Hot‑plug – default: not supported; custom: supports docker network connect/disconnect.

Custom subnet – default: fixed; custom: user‑defined.

Note : In production, avoid the default bridge; use a custom bridge with DNS and isolation.

Host mode details

Host mode makes the container use the host's network namespace directly, eliminating NAT and providing native performance. The container sees the same interfaces as the host.

# Run Nginx in host mode
docker run -d --name nginx-host --network host nginx:1.24-alpine

# No -p needed; Nginx listens on host port 80
curl http://localhost:80

Performance comparison : iperf3 tests show host mode can deliver ~15‑25% higher throughput than bridge mode.

Warning : All host ports are occupied by the container, and the container can see every host interface, so isolation is zero.

None mode details

Containers have only a loopback interface (lo) and no external connectivity. Useful for tasks that do not need networking or for fully custom network setups.

# Run an isolated container
docker run -d --name isolated --network none alpine sleep 3600

# Verify only lo exists
docker exec isolated ip addr

# Ping external address fails
docker exec isolated ping -c 1 8.8.8.8

Container mode details

One container shares another's network namespace. Both see the same IP and ports, communicating via localhost. This is the basis for sidecar patterns.

# Start a base container
docker run -d --name base-container -p 8080:80 nginx:1.24-alpine

# Start a sidecar sharing the network
docker run -d --name sidecar --network container:base-container alpine sleep 3600

# Sidecar can reach the base container via localhost
docker exec sidecar wget -qO- http://localhost:80

Overlay mode details

Overlay networks use VXLAN tunnels to enable cross‑host container communication. Packets are encapsulated on the source host, sent over UDP 4789, and decapsulated on the destination host.

# Initialize Swarm (required for overlay)
docker swarm init --advertise-addr 192.168.1.10

# Create overlay network
docker network create \
  --driver overlay \
  --subnet 10.10.0.0/24 \
  --gateway 10.10.0.1 \
  --attachable \
  my-overlay

# Deploy a service on the overlay network
docker service create \
  --name web \
  --network my-overlay \
  --replicas 3 \
  -p 80:80 \
  nginx:1.24-alpine

Note : Overlay adds ~10‑15% latency due to VXLAN encapsulation; latency‑sensitive workloads may prefer macvlan or host mode.

Macvlan mode details

Macvlan gives each container a real MAC address and an IP on the physical network, bypassing NAT and achieving near‑native performance.

# Create macvlan network
docker network create \
  --driver macvlan \
  --subnet 192.168.1.0/24 \
  --gateway 192.168.1.1 \
  --opt parent=eth0 \
  my-macvlan

# Run a container with a fixed IP
docker run -d --name db --network my-macvlan --ip 192.168.1.200 mysql:8.0.35

Note : By design, the host cannot communicate with macvlan containers. Create a macvlan sub‑interface on the host to enable host‑to‑container traffic.

# Host side interface for macvlan communication
ip link add macvlan-host link eth0 type macvlan mode bridge
ip addr add 192.168.1.201/24 dev macvlan-host
ip link set macvlan-host up

Connecting containers to multiple networks

# Create two separate networks
docker network create frontend --subnet 172.20.0.0/24
docker network create backend  --subnet 172.21.0.0/24

# Nginx on frontend
docker run -d --name nginx --network frontend -p 80:80 nginx:1.24-alpine

# App on both networks
docker run -d --name app --network frontend myapp:1.0
docker network connect backend app

# MySQL only on backend
docker run -d --name mysql --network backend mysql:8.0.35

Best practices and cautions

Performance optimisation

Disable userland‑proxy : set "userland-proxy": false in daemon.json to use iptables for port mapping, reducing CPU overhead.

Use host network for high‑throughput services : e.g., Nginx or HAProxy gains 15‑20% throughput.

Increase conntrack table : default 65 536 entries may be insufficient; raise to 1 000 000 with sysctl -w net.netfilter.nf_conntrack_max=1048576.

Security hardening

Network isolation : place databases and caches in a backend network, web services in a frontend network, and only the application connects to both.

Disable inter‑container communication (ICC) when not needed:

docker network create --opt "com.docker.network.bridge.enable_icc"="false" isolated-net

.

Bind port mappings to internal IPs instead of 0.0.0.0 to avoid exposing services to the internet.

High‑availability configuration

DNS round‑robin : assign the same network alias to multiple containers; Docker DNS will rotate the returned IPs.

Overlay network HA : Docker Swarm automatically reschedules services on healthy nodes.

Automatic restart : set --restart=unless-stopped so containers recover after network glitches.

Common errors and troubleshooting

Container cannot reach external network : check net.ipv4.ip_forward, NAT MASQUERADE rule, and DNS configuration.

Port mapping not effective : verify firewall rules, ensure the port is not already in use, and inspect Docker's iptables chains.

Containers cannot ping each other : ensure they are attached to the same Docker network or use docker network connect.

DNS resolution fails : default bridge does not provide DNS; switch to a custom bridge.

Conntrack table full : increase nf_conntrack_max and monitor usage.

Macvlan container unreachable from host : create a macvlan sub‑interface on the host as described above.

Diagnostic commands

# View Docker network logs
sudo journalctl -u docker.service | grep -i -E "network|bridge|iptables"

# Watch network events
docker events --filter 'type=network'

# Inspect iptables NAT and filter tables
sudo iptables -t nat -L -n -v
sudo iptables -L DOCKER -n -v

# Check conntrack usage
sudo conntrack -L | head -20
sudo conntrack -C

Performance monitoring

# Container network I/O
docker stats --no-stream --format "table {{.Name}}	{{.NetIO}}"

# Bridge traffic counters
cat /sys/class/net/docker0/statistics/rx_bytes
cat /sys/class/net/docker0/statistics/tx_bytes

# Conntrack utilization
echo "$(cat /proc/sys/net/netfilter/nf_conntrack_count) / $(cat /proc/sys/net/netfilter/nf_conntrack_max)" | bc -l

# veth error counters
ip -s link show | grep -A 6 veth

# iptables rule hit counts
sudo iptables -t nat -L -n -v | grep DOCKER

Backup and restore

# Backup custom networks
BACKUP_DIR="/backup/docker-network/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"
for net in $(docker network ls --filter 'type=custom' -q); do
  NET_NAME=$(docker network inspect --format '{{.Name}}' $net)
  docker network inspect $net > "$BACKUP_DIR/${NET_NAME}.json"
done

# Backup iptables
sudo iptables-save > "$BACKUP_DIR/iptables-rules.txt"
sudo ip6tables-save > "$BACKUP_DIR/ip6tables-rules.txt"

# Backup sysctl network parameters
sysctl -a 2>/dev/null | grep -E "net\.(ipv4|bridge|netfilter)" > "$BACKUP_DIR/sysctl-network.txt"

# Backup daemon.json
cp /etc/docker/daemon.json "$BACKUP_DIR/"

echo "Network backup completed: $BACKUP_DIR"

Restore procedure

Restore daemon.json and restart Docker.

Apply saved sysctl parameters and reload with sysctl --system.

Re‑create custom networks using the saved JSON files (extract subnet, gateway, driver, etc.).

Validate connectivity by launching test containers.

Conclusion

Key takeaways

Bridge is the default; use a custom bridge for DNS and isolation.

Host mode eliminates NAT overhead but removes isolation.

Network isolation is achieved by separating services into distinct custom networks.

Performance tuning: disable userland‑proxy, enlarge conntrack, prefer host mode for latency‑critical workloads.

Troubleshooting flow: IP forwarding → iptables NAT → DNS → conntrack → veth errors covers >90% of issues.

Further learning paths

Container Network Interface (CNI) – the standard used by Kubernetes; study Flannel, Calico source code.

eBPF‑based networking (e.g., Cilium) – replaces iptables for higher performance and observability.

Service mesh (Istio, Linkerd) – adds traffic management, circuit breaking, and tracing on top of container networking.

References

Docker official networking documentation.

Linux network namespaces and iptables tutorials.

nicolaka/netshoot – container debugging toolbox.