7.2.5.1 Macvlan Physical Peer

A macvlan physical peer is the specific physical network interface on the host that a macvlan network is configured against, determining exactly which physical network segment a container on that macvlan network actually appears to be directly connected to.

Specifying the Parent Interface

The parent option identifies which of the host's physical network interfaces the macvlan network should be associated with.

docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  -o parent=eth0 \
  macvlan-net

Containers on macvlan-net will appear directly on whatever physical network eth0 is connected to.

Why the Correct Parent Interface Matters

Choosing the wrong parent interface results in containers appearing on a physical network segment that isn't actually the intended one, potentially making them unreachable from where they were expected to be reachable, or reachable from somewhere unintended.

ip addr

Confirming exactly which physical interface corresponds to the intended network segment, before configuring the macvlan network, avoids this kind of misconfiguration.

Using a VLAN Sub-Interface as the Parent

For networks using VLAN tagging, a macvlan network can be associated with a specific VLAN sub-interface rather than the raw physical interface itself.

docker network create -d macvlan \
  --subnet=192.168.10.0/24 \
  -o parent=eth0.10 \
  macvlan-vlan10-net

This places containers on this macvlan network specifically onto VLAN 10, rather than the untagged physical network.

Verifying Correct Physical Connectivity

Confirming a container on a macvlan network is actually reachable from elsewhere on the intended physical network segment validates that the parent interface was configured correctly.

ping 192.168.1.50

Why Understanding the Physical Peer Relationship Matters

Correctly identifying and configuring the parent physical interface is essential to macvlan networking actually working as intended — a misconfigured parent interface is a common source of confusing connectivity issues when first setting up this less commonly used driver.