Configuring Macvlan and IPVlan for Docker on Linux: Direct LAN IP Assignment and NAT Bypass

Real-World Context: When Docker Bridge Becomes the Bottleneck

Over six months ago, our internal server cluster (supporting around 50 team members across 12 datacenter nodes) started experiencing bizarre packet drops. Typically, the default Docker bridge with iptables NAT (masquerading) runs smoothly for standard API or web app workloads. You just run -p 8080:80, and you’re good to go.

Things fell apart when I migrated our Asterisk voice system (SIP/RTP), 30 RTSP camera streams, and infrastructure SNMP monitoring agents into containers. At that point, the NAT layer exposed three critical weaknesses:

• Conntrack table exhaustion: Each SIP/RTP call opens thousands of random UDP ports. The kernel’s nf_conntrack table repeatedly hit its ceiling of 262,144 sessions. Host CPU usage spiked from 15% to 75% just from evaluating iptables rules.
• Loss of source IP visibility: All outbound requests inherited the Docker host’s IP. Enforcing pfSense firewall policies per container based on distinct IPs was virtually impossible.
• Broadcast/multicast deafness: Docker bridge isolates the broadcast domain. Consequently, auto-discovery protocols like mDNS, BACnet, or ONVIF camera discovery simply could not reach the containers.

To resolve these issues at the root, I moved container networking directly onto the physical LAN using two Linux kernel drivers: Macvlan and IPVlan.

Macvlan vs. IPVlan: Which One to Choose?

After months of running both side-by-side in production, here is a quick breakdown:

• Macvlan: The kernel generates a dedicated virtual MAC address for each container. The switch treats the container like a physical machine plugged directly into the port. The downside: It easily triggers Port Security on Cisco or Aruba switches (which often limit learning to 1–2 MACs per port by default). On VMware ESXi, AWS, or GCP, packets will be dropped immediately due to MAC spoofing prevention.
• IPVlan (L2 mode): All containers share the parent physical NIC’s MAC address while maintaining distinct IP addresses. The upstream switch only sees a single MAC from the host, smoothly bypassing Port Security restrictions. IPVlan is the ideal choice for virtualized environments or private cloud setups.

Preparing the Host Network Environment

First, identify your primary network interface (we’ll use eth0 here) and its current subnet:

ip -br addr show eth0

Enable IP forwarding on the Linux host to ensure smooth packet transit:

sudo sysctl -w net.ipv4.ip_forward=1
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.d/99-docker-network.conf

Infrastructure note: If you are running Macvlan on VMware ESXi, navigate to your vSwitch or Port Group settings and set both Promiscuous Mode and MAC Address Changes to Accept.

Step-by-Step Implementation

1. Deploying Macvlan

Assuming your local office network is 192.168.1.0/24 with a gateway at 192.168.1.1, carve out a small slice (such as 192.168.1.192/27, providing 30 IPs) exclusively for Docker to prevent collisions with your DHCP pool:

docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --ip-range=192.168.1.192/27 \
  --gateway=192.168.1.1 \
  -o parent=eth0 \
  macvlan_lan

Launch a container with your desired static IP:

docker run -d --name legacy-app \
  --net=macvlan_lan \
  --ip=192.168.1.200 \
  --restart=always \
  nginx:alpine

Fixing the Classic Pitfall: Host Cannot Ping Container

By Linux kernel security design, the physical NIC drops all traffic routed directly between the host and child Macvlan interfaces. Pinging 192.168.1.200 from the host will consistently time out, even while other workstations on the LAN access the web service without issue.

The fix is to create a dedicated macvlan sub-interface directly on the host:

# 1. Create a virtual macvlan interface on the host
sudo ip link add mac0 link eth0 type macvlan mode bridge

# 2. Assign a dedicated IP and bring it up (pick an unused IP in the subnet)
sudo ip addr add 192.168.1.220/32 dev mac0
sudo ip link set mac0 up

# 3. Route the container IP range through the newly created interface
sudo ip route add 192.168.1.192/27 dev mac0

Now host-to-container communication works seamlessly.

2. Deploying IPVlan (L2 Mode)

On Proxmox VMs or cloud platforms that restrict MAC spoofing, IPVlan L2 is the preferred solution. The creation syntax is straightforward:

docker network create -d ipvlan \
  --subnet=192.168.1.0/24 \
  --ip-range=192.168.1.224/28 \
  --gateway=192.168.1.1 \
  -o ipvlan_mode=l2 \
  -o parent=eth0 \
  ipvlan_lan

Attach a container to the IPVlan network:

docker run -d --name voip-service \
  --net=ipvlan_lan \
  --ip=192.168.1.225 \
  alpine sleep 3600

Verification and Testing

Once deployed, verify the ARP table and packet flow to ensure everything is functioning as expected.

Verify IP and Gateway Inside the Container

# Check the actual IP assigned to the container
docker exec -it legacy-app ip -br addr show

# Ping the default gateway to confirm L2 connectivity
docker exec -it legacy-app ping -c 3 192.168.1.1

Packet Capture to Inspect MAC Addresses

From another workstation on the LAN, run a continuous ping to the container (192.168.1.200). At the same time, open a terminal on the host and run tcpdump:

sudo tcpdump -i eth0 icmp and host 192.168.1.200 -n -e

With Macvlan, the destination MAC in the tcpdump output will be the container’s unique virtual MAC. With IPVlan, the destination MAC will match the host’s physical eth0 interface MAC exactly.

Conclusion

For standard web APIs and microservices, the default bridge network remains the most convenient option thanks to its portability. However, when dealing with VoIP, RTSP camera streams, or L2 discovery protocols, placing containers directly onto the physical LAN using Macvlan or IPVlan delivers dramatic CPU savings, eliminates NAT bottlenecks, and enables clean, granular network firewall policies.