Docker Macvlan Network Connectivity Fix

In this tutorial, you'll learn about Docker Macvlan Network Connectivity Fix. We cover key concepts, practical examples, and best practices.

Docker macvlan assigns containers their own MAC and IP addresses on the physical network, but connectivity fails when the parent interface is wrong, IP ranges overlap, or the physical switch does not allow multiple MAC addresses on a single port.

The Problem

docker run --network=macvlan-net --ip=192.168.1.100 nginx

The container starts but is unreachable:

ping 192.168.1.100
# Request timeout for icmp_seq 0

Or the container cannot reach the internet:

docker run --network=macvlan-net alpine ping 8.8.8.8
# ping: sendto: Network is unreachable

Wrong Approach

# WRONG — missing gateway, wrong subnet, or incorrect parent
docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=eth0 \
  macvlan-net

Right Approach

# RIGHT — correct subnet, gateway, and parent interface
docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  --ip-range=192.168.1.200/28 \
  -o parent=eth0 \
  macvlan-net

Expected output:

$ docker run --network=macvlan-net --ip=192.168.1.201 alpine ping -c 3 192.168.1.1
PING 192.168.1.1 (192.168.1.1): 56 data bytes
64 bytes from 192.168.1.1: seq=0 ttl=64 time=0.5 ms
64 bytes from 192.168.1.1: seq=1 ttl=64 time=0.4 ms
64 bytes from 192.168.1.1: seq=2 ttl=64 time=0.5 ms

Step-by-Step Fix

Step 1: Identify the correct parent interface

ip addr show

Look for the interface connected to the physical network, typically eth0, enp0s3, or ens33.

Step 2: Create the macvlan network correctly

docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  --ip-range=192.168.1.200/28 \
  -o parent=eth0 \
  macvlan-net

Step 3: Run a container on the macvlan network

docker run --network=macvlan-net --ip=192.168.1.201 alpine ping -c 3 192.168.1.1

Step 4: Fix internet connectivity with a routing table

# The container can reach local network but not the internet
# Add the default gateway inside the container
docker exec -it my-container ip route add default via 192.168.1.1

Step 5: Enable promiscuous mode on the parent interface

sudo ip link set eth0 promisc on

Step 6: Create a bridge macvlan for host-container communication

docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=eth0 \
  -o macvlan_mode=bridge \
  macvlan-bridge

Prevention Tips

• Use --ip-range to avoid IP conflicts with other devices on the network
• Set the parent interface to promiscuous mode on hypervisors
• Use bridge mode instead of 802.1q trunking unless you need VLAN separation
• Verify physical switch supports port MAC learning for multiple addresses
• Consider ipvlan (l2 mode) as an alternative that uses fewer MAC addresses

Common Mistakes with macvlan connect

1. Using foldl instead of foldl' causing stack overflow on large lists
2. Forgetting deriving (Show, Eq) on custom data types needed for debugging
3. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable

These mistakes appear frequently in real-world DOCKER code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ