macvlan and ipvlan — when you need L2 adjacency · Docker & Containers

macvlan and ipvlan make a container appear as a separate host on the same L2 segment as the host’s physical NIC. macvlan gives each container its own MAC address; ipvlan has the containers share the parent interface’s MAC and distinguishes them by IP.

Both remove NAT entirely. The container is a peer on the LAN, reachable without any port mapping, and it sees real client addresses. That is the attraction. The rest of this lesson is the price.

macvlan

Configuration changecreate a macvlan network— --ip-range is the important flag. Without it Docker allocates from the whole subnet.

PARENT=eth0

docker network create -d macvlan \
--subnet 192.0.2.0/24 \
--gateway 192.0.2.1 \
--ip-range 192.0.2.192/27 \
--aux-address 'router=192.0.2.1' \
-o parent="$PARENT" \
macvlan-net

docker network inspect macvlan-net --format '{{json .IPAM.Config}}'

A container on this network:

Has a MAC address distinct from the host’s, generated by Docker.
Holds an IP on the same subnet as the parent interface.
Is reachable from the LAN with no port mapping and no -p.
Reaches the internet through the LAN gateway, not through the host’s NAT.

Docker's IPAM does not know your DHCP server exists

--subnet 192.0.2.0/24 tells Docker it may allocate any address in that range. Your LAN DHCP server believes the same thing. Neither one asks the other.

The result is a duplicate address: a container and a laptop holding 192.0.2.57 at the same time, with two different MACs answering the same ARP request. The switch’s MAC table flaps between two ports, and traffic for that address arrives at whichever device last spoke. Both devices work intermittently, for different clients, and neither logs anything useful.

--ip-range 192.0.2.192/27 bounds Docker to 32 addresses. Then reserve that same range as a static exclusion on the DHCP server. Doing one without the other is doing neither: the exclusion without --ip-range still lets Docker allocate outside it, and --ip-range without the exclusion still lets DHCP allocate inside it.

--aux-address marks individual addresses in the range as off-limits to Docker — use it for the gateway and for anything statically assigned that happens to fall inside your range.

The host cannot talk to its own macvlan containers

This is the one that ends the afternoon, so it is worth stating in the exact form it appears:

The container pings the gateway. The container pings other LAN hosts. Other LAN hosts ping the container. The Docker host — the machine the container is running on — cannot ping it, and the container cannot ping the host. Every other path works.

Upstream states it directly: “Containers attached to a macvlan network cannot communicate with the host directly, this is a restriction in the Linux kernel.”

This is not a firewall rule, not a routing table entry, and not something sysctl will fix. A macvlan sub-interface and its parent are deliberately prevented from exchanging frames locally; the frames go out of the NIC and the NIC does not receive its own transmission.

Its practical consequences are ordinary and immediate:

A HEALTHCHECK in the image that curls itself works. A monitoring agent on the host scraping the container does not.
A reverse proxy on the host cannot reach a macvlan backend.
docker exec still works — that is the daemon entering a namespace, not a network operation.

Getting the host back onto the segment

Two workarounds, both documented upstream, with different shapes.

Configuration changeworkaround 1 — a macvlan shim on the host— Give the host its own macvlan interface on the same parent. It is then a peer like any container. Not persistent across reboot on its own.

PARENT=eth0
SHIM_ADDR=192.0.2.223/32
CONTAINER_RANGE=192.0.2.192/27

# A macvlan interface belonging to the host, on the same parent
sudo ip link add macvlan-shim link "$PARENT" type macvlan mode bridge
sudo ip addr add "$SHIM_ADDR" dev macvlan-shim
sudo ip link set macvlan-shim up

# Route the container range out of the shim rather than out of the parent
sudo ip route add "$CONTAINER_RANGE" dev macvlan-shim

ping -c1 192.0.2.194

Pick the shim address from inside the block you reserved and add it to --aux-address so Docker never allocates it. Make it persistent through your distribution’s network configuration — as a bare ip link it disappears on reboot, and the failure returns looking brand new.

The second workaround is simpler and often better: attach the container to a user-defined bridge as well as the macvlan network. It then has two interfaces, one on the LAN and one reachable from the host, and the host-side tooling talks to the bridge address.

Configuration changeworkaround 2 — dual-homed container— LAN presence from macvlan, host reachability from a bridge.

CONTAINER=lan-svc

docker network create --subnet 172.30.0.0/24 mgmt-net

docker run -d --name "$CONTAINER" --network macvlan-net nginx:1.27-alpine
docker network connect mgmt-net "$CONTAINER"

docker inspect --format \
'{{range $n, $c := .NetworkSettings.Networks}}{{$n}}={{$c.IPAddress}} {{end}}' \
"$CONTAINER"

Promiscuous mode and the switch

macvlan puts several MAC addresses behind one physical port. The upstream requirement is unambiguous: “Your networking equipment needs to be able to handle promiscuous mode, where one physical interface can be assigned multiple MAC addresses.”

On bare metal with a normal switch this is the default behaviour. Three places it is not:

Cloud VMs. AWS, GCP and Azure filter frames whose source MAC is not the one assigned to the vNIC. macvlan does not work there.
Switch ports with port security configured to a single MAC.
Wireless. 802.11 does not carry a second MAC behind an associated station. macvlan on a Wi-Fi parent does not work, and this is a protocol limitation rather than a driver bug.

Read-only / Safewhat the failure looks like— Asymmetric reachability is the signature: the container's frames leave, the replies never come back.

$ CONTAINER=lan-svc

# From the container: outbound works
docker exec "$CONTAINER" ping -c2 192.0.2.1

# From another LAN host: inbound does not
# (run on 192.0.2.30)  ping -c2 192.0.2.194

PING 192.0.2.1 (192.0.2.1): 56 data bytes
64 bytes from 192.0.2.1: seq=0 ttl=64 time=0.43 ms
64 bytes from 192.0.2.1: seq=1 ttl=64 time=0.39 ms

--- 192.0.2.194 ping statistics ---
2 packets transmitted, 0 packets received, 100% packet loss

Illustrative output

Outbound succeeding while inbound fails is the fingerprint. The container’s ARP replies carry a MAC the switch will not forward, so nothing on the LAN can complete an ARP resolution for it. Check the switch’s MAC address table for the host’s port: if you see one MAC where you expect several, the switch is the problem, not Docker.

802.1Q trunking

Name a VLAN sub-interface as the parent and Docker creates it for you:

Configuration changeone network per VLAN— A parent of the form ifname.vlanid makes Docker create and manage the sub-interface.

docker network create -d macvlan \
--subnet 192.0.2.0/24 --gateway 192.0.2.1 \
--ip-range 192.0.2.192/27 \
-o parent=eth0.50 \
vlan50-net

# Docker created the sub-interface
ip -brief link show eth0.50

The host port must be a trunk carrying that VLAN. Docker removes the sub-interface when the network is removed — but only the ones it created, so a hand-made eth0.50 survives and will be reused rather than recreated.

ipvlan

Configuration changeipvlan l2— l2 is the default mode. Containers share the parent's MAC and are distinguished by IP.

docker network create -d ipvlan \
--subnet 192.0.2.0/24 \
--gateway 192.0.2.1 \
--ip-range 192.0.2.192/27 \
-o parent=eth0 \
-o ipvlan_mode=l2 \
ipvlan-net

ipvlan_mode accepts l2, l3 and l3s; ipvlan_flag accepts bridge, private and vepa. l2 with the bridge flag is the default and the one to start from.

l3 mode is a different thing entirely. The kernel routes rather than bridges: broadcast and multicast are dropped, ARP does not traverse, and containers use a default route out of their interface with no next hop. It follows that:

DHCP does not work — the discover is a broadcast.
mDNS, NetBIOS discovery and anything else broadcast-based does not work.
The upstream network must have routes to your container subnets, because nothing will ARP for them. That is a router change, not a Docker one.

Choose l3 when you want containers on their own routed subnets and you control the routers. Choose l2 when you want them to look like they are plugged into the same switch.

Comparison

Feature	macvlan	ipvlan (l2)	ipvlan (l3)	bridge
Container has own MAC	yes	no	no	no
Reachable from LAN without publishing	yes	yes	routed only	no
Needs multiple MACs per port	yes	no	no	no
Works on AWS / GCP / Azure	no	usually	usually	yes
Broadcast / DHCP / mDNS reaches container	yes	yes	no	yes
Upstream router config required	no	no	yes	no
NAT for outbound	no	no	no	yes
Host can reach its own containers	no	no	no	yes

The last row is the one people read after they have already deployed.

Where the frames actually go

A macvlan sub-interface is a virtual netdev bound to a parent netdev with its own MAC. On transmit, the kernel pushes the frame straight out of the parent, using the sub-interface’s MAC as the source. On receive, the parent demultiplexes incoming frames by destination MAC and hands each to the matching sub-interface.

Local delivery between a sub-interface and its parent is not part of that path. A frame from the container to the host’s own address is transmitted out of the NIC; the NIC does not loop it back; nothing receives it. That is the “kernel restriction” — it is the design of the device, not a policy layered on top.

mode bridge (Docker’s default) does allow macvlan sub-interfaces to reach each other directly, which is why two containers on the same macvlan network talk fine. mode vepa sends everything to the switch and requires the switch to hairpin it back; mode private blocks sub-interface-to- sub-interface traffic entirely.

ipvlan shares one MAC and demultiplexes by IP instead, but the parent-to-child delivery gap is identical, which is why the host-reachability restriction carries over unchanged.

Why this matters

macvlan and ipvlan are the right tools when a container has to be a peer on the LAN — a DHCP server, a media server that needs mDNS, a service whose audit trail must show real client addresses, an appliance replacement that other equipment expects to find at a fixed address.

They are also the drivers with the most surprising failure modes, and both of the big ones are asymmetric: the host cannot reach containers that everyone else can, or the LAN cannot reach a container that reaches the LAN. Neither looks like a network driver problem while you are in it.

Decide up front whether anything on the Docker host needs to talk to these containers. If the answer is yes — and it usually is, because monitoring lives there — plan the bridge attachment or the shim interface into the initial deployment rather than bolting it on during an incident.

Sanity check

docker network inspect shows an IPRange narrower than the subnet, and the same range is excluded on the DHCP server.
A LAN host that is not the Docker host can reach the container.
You have consciously decided how the Docker host reaches the container, and tested it.
The parent is the bond or VLAN device that survives a NIC failover, not a member interface.