Skip to content
Blog

Macvlan Modes Explained: Bridge, VEPA, Passthru, and Private

Docker's macvlan_mode option selects bridge, vepa, passthru, or private. How each mode moves frames at layer 2, when to pick it, and how to verify the mode a network is using.

Published on • November 19, 2026

AI Assistant

Almost nobody changes macvlan_mode. The default works, containers get their MACs, traffic flows — until a switch policy, a compliance rule, or a tenant-isolation requirement makes the path a container’s frames take become the question. Then you discover Docker quietly exposes four layer-2 behaviors behind one -o flag, and they’re worth understanding before you’re debugging a network that half-works.

The knob itself

Docker’s driver options table for macvlan is small — two entries:

OptionDefaultDescription
macvlan_modebridgeSets the Macvlan mode. Can be one of: bridge, vepa, passthru, private
parent—Specifies the parent interface to use

You pass it at network creation:

$ docker network create -d macvlan \
    --subnet=172.16.86.0/24 \
    --gateway=172.16.86.1 \
    -o parent=eth0 \
    -o macvlan_mode=vepa \
    pub_net

One terminology trap first: Docker’s docs also use the phrase “bridge mode” for something else — the choice between a plain parent (parent=eth0) and an 802.1Q trunk parent (parent=eth0.50), which they contrast with “802.1Q trunk bridge mode.” Those describe which interface traffic leaves through. macvlan_mode describes how frames move between containers sharing that interface. Two independent axes; don’t let the shared word conflate them.

What each mode actually does

The authoritative semantics come from the kernel’s own interface documentation, ip-link(8), which is what ip link add ... type macvlan mode ... implements — Docker passes your value down to exactly this mechanism.

bridge — the default

“In bridge mode, all endpoints are directly connected to each other, communication is not redirected through the physical interface’s peer.”

Two containers on the same parent reach each other directly inside the host, without their traffic bouncing out to the switch and back. Traffic bound for the rest of the network still egresses through the physical device — Docker’s phrasing: “In bridge mode, Macvlan traffic goes through a physical device on the host.” This is the sensible default: no hairpin requirement, no surprises, normal LAN behavior.

vepa — Virtual Ethernet Port Aggregator

“Data from one macvlan instance to the other on the same physical interface is transmitted over the physical interface. Either the attached switch needs to support hairpin mode, or there must be a TCP/IP router forwarding the packets in order to allow communication.”

In VEPA, container-to-container traffic on the same host is sent out to the switch and has to come back (hairpin), or go through a router. That’s usually a deliberate choice: the switch gets to see, count, ACL, or mirror every frame — at the cost of depending on hairpin support. One wrinkle from the man page: ip-link lists vepa as its default mode, but Docker’s macvlan_mode default is bridge — so a Docker network gets bridge mode unless you ask otherwise.

passthru — one container owns the NIC

“This mode gives more power to a single endpoint… It is not allowed for more than one endpoint on the same physical interface. All traffic will be forwarded to this endpoint.”

Exactly one container may be attached, and everything the parent receives is handed to it — including traffic that container can then reshape: change its MAC, run promiscuous, stack its own VLAN interfaces. The man page notes passthru “forces the underlying interface into promiscuous mode” by default. This is the VM-replacement use case: an appliance that expects to be the NIC, not a peer on it.

private — hard L2 isolation

“Do not allow communication between macvlan instances on the same physical interface, even if the external switch supports hairpin mode.”

Containers sharing a parent cannot talk to each other at all — the isolation happens at the host, so no switch configuration can undo it. Each container still reaches the LAN through the parent normally. It’s the mode for untrusted tenants or hostile workloads sharing one uplink.

The four modes at a glance

ModeContainer ↔ container on same parentTraffic leaves via parentEndpoints allowedDocker default
bridgeDirect, in-host switch pathYesMultipleYes
vepaHairpinned out to the switch (needs hairpin or a router)Yes — all of itMultipleNo (ip-link’s default)
passthruN/A — the one endpoint receives everythingEverything lands on itExactly oneNo
privateBlocked outright, switch hairpin or notYesMultipleNo

Choosing one

  • Leave it at bridge unless something forces the question. It’s Docker’s documented default and needs nothing from your switch.
  • Switch to vepa when the network must observe inter-container traffic — switch-side ACLs, packet capture at the ToR, or policy enforcement that assumes all frames traverse the fabric. Confirm hairpin support first, or you’ll find same-host containers mysteriously unable to reach each other.
  • Use private when containers on the same parent must not speak to each other, full stop — shared-host multi-tenancy where the isolation has to survive anything the switch does.
  • Use passthru only for a single container that needs the NIC to itself: MAC changes, its own promiscuous mode, its own VLAN stack. Attach a second container and you’re outside documented behavior.

Verifying what’s actually running

What you passed and what the kernel got are two different checks. First, the network’s recorded options:

$ docker network inspect pub_net --format '{{.Options}}'
map[macvlan_mode:vepa parent:eth0]

If you never set macvlan_mode, that field simply won’t appear — Docker’s default lives in the driver, not your options map. Ground truth is the interface inside the container, where ip -d prints the kernel’s recorded mode:

$ docker exec web1 ip -d link show eth0
3: eth0@if2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP
    link/ether 02:42:ac:10:56:02 brd ff:ff:ff:ff:ff:ff
    macvlan  mode bridge

That macvlan mode ... line is the mode the kernel is actually operating in — check it after any change, and after recreating networks, rather than trusting the create command alone.

The bottom line

macvlan_mode chooses how frames travel between containers that share a parent NIC: bridge (Docker’s default) connects them directly in-host, vepa forces their traffic out through the switch, private blocks container-to-container traffic outright, and passthru hands the entire NIC to a single container. Docker’s option table gives you the four values; ip-link(8) defines what they mean at layer 2. Most environments should stay on bridge — but when switch visibility or strict isolation becomes a requirement, the right mode is one flag away, and ip -d link show will tell you exactly what you got.

Further reading