Linux MACVLAN Container IP Assignment Explained

MACVLAN is a Linux kernel networking feature that allows a single physical network interface to be subdivided into multiple virtual interfaces, each with its own unique MAC address and direct IP assignment on the underlying physical local area network (LAN). When applied to container networking, MACVLAN bypasses default container bridge and Network Address Translation (NAT) models, placing containers directly onto the host's physical L2 network. This guide explains the internal Linux mechanisms that enable MACVLAN interface creation, network namespace movement, and container IP allocation.

The MACVLAN Kernel Module

At the kernel level, the MACVLAN driver acts as a virtual multiplexer sitting directly above a physical Ethernet interface (the "parent" device, such as eth0). Rather than relying on a traditional Linux software bridge (br0) that requires MAC learning and packet replication, the MACVLAN driver intercepts packets at the data link layer (Layer 2).

When a MACVLAN interface is instantiated, the kernel registers a unique, distinct MAC address for that sub-interface with the network driver. The parent device is placed into promiscuous mode or leverages hardware-level MAC address filtering (if supported by the Network Interface Card) to listen for frames addressed to any of its child MAC addresses.

Moving Interfaces into Container Namespaces

Linux isolates container networking using network namespaces (netns). To assign an interface directly to a container, the container runtime (such as Docker or containerd) performs the following low-level sequence using the Netlink API:

1. Interface Creation: A new MACVLAN sub-interface is created in the host's root network namespace using the ip link add link <parent> name <sub-interface> type macvlan command.
2. Namespace Migration: The created interface is moved into the target container's network namespace using ip link set <sub-interface> netns <container-pid>.
3. Activation: Inside the target namespace, the interface is typically renamed to standard convention (like eth0) and brought up.

Once inside the namespace, the container possesses an independent network stack with full access to send and receive frames directly through the host's physical NIC.

IP Address Assignment

Because a MACVLAN interface functions as a dedicated endpoint on the physical L2 broadcast domain, container IP addresses can be assigned in two ways:

• Static Allocation via IPAM: The container runtime's IP Address Management (IPAM) driver statically configures an IPv4/IPv6 address, subnet, and default gateway directly on the interface inside the namespace. The default gateway is typically the physical router on the local LAN, not the host machine.
• External DHCP: Since the container's virtual interface has a valid, distinct MAC address, a DHCP client running inside the container (or managed by a CNI plugin) can broadcast DHCP requests to the local physical network. An external network DHCP server handles lease allocation just as it would for a physical server.

Operating Modes and Traffic Handling

The Linux kernel processes MACVLAN traffic differently depending on the configured mode:

• Bridge Mode (Most Common): The MACVLAN driver maintains an internal MAC lookup table. Frames routed between containers attached to the same parent interface are switched directly in kernel memory without hitting the physical wire. Frames addressed outside the host are emitted straight onto the physical network.
• VEPA (Virtual Ethernet Port Aggregator): All traffic, even between local containers on the same host, is forced out through the physical switch port. The upstream switch must support "hairpin" mode to bounce traffic back to the host.
• Private Mode: Containers on the same parent cannot communicate with each other, even if upstream switching allows it.
• Passthru Mode: Gives a single container exclusive control over the physical interface, binding one MAC directly to the parent.

Host-to-Container Isolation

By design in the Linux kernel, the host cannot communicate directly with its own MACVLAN-based containers over the parent interface. The kernel's egress routing logic drops packets destined for a MAC address residing on a sub-interface of the transmitting device. To resolve this, network administrators must create a separate MACVLAN interface specifically for the host, route traffic through it, and allow the kernel's L2 switching to bridge the connection between the host sub-interface and the container sub-interfaces.