IPvlan L2 and L3 Modes for Container Addressing
Docker ipvlan shares the parent NIC's MAC address. Compare L2 (default) and L3 modes, plus L3s and the bridge/private/vepa flags, with a docker network create example for each.
Published on • November 19, 2026
AI Assistant

macvlan hands every container a MAC address — which is exactly why some networks refuse it: one-MAC-per-port switch policies, CAM table pressure, cloud providers that block promiscuous mode. ipvlan is the sibling driver that sidesteps all of it by sharing the parent interface’s MAC address across every container. One MAC for the host, and two operating modes — L2 and L3 — that behave like genuinely different networks.
One MAC, shared layer 2
Docker’s own summary of the difference: ipvlan “doesn’t assign a MAC address to each container, the layer-2 network stack is shared by devices in the ipvlan network. So, containers use the parent interface’s MAC address. The network will see fewer MAC addresses, and the host’s MAC address will be associated with the IP address of each container.”
The kernel’s ipvlan HOWTO gives three situations where you should pick ipvlan over macvlan:
- The external switch or router has a policy allowing only one MAC per port.
- Your virtual devices would exceed the NIC’s MAC capacity, pushing it into promiscuous mode with degraded performance.
- The container sits in a hostile or untrusted namespace where control of layer 2 could be misused.
Requirements are modest: Docker documents kernel v4.2+ for ipvlan (“support for earlier kernels exists but is buggy” — check with uname -r). Like macvlan, it’s Linux-engine only.
The driver options
| Option | Default | Description |
|---|---|---|
ipvlan_mode | l2 | Sets the IPvlan operating mode. Can be one of: l2, l3, l3s |
ipvlan_flag | bridge | Sets the IPvlan mode flag. Can be one of: bridge, private, vepa |
parent | — | Specifies the parent interface to use |
Note the defaults differ from raw ip link: the kernel’s iproute2 syntax defaults to l3 mode, but Docker’s driver defaults to l2 — so an ipvlan network with no mode specified behaves as L2.
L2 mode: the default
L2 mode keeps containers in the parent’s broadcast domain — same subnet as the host’s interface, ARP and broadcast working as usual, no bridge device anywhere in the path:
$ ip addr show eth0
3: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP
inet 192.168.1.250/24 brd 192.168.1.255 scope global eth0
$ docker network create -d ipvlan \
--subnet=192.168.1.0/24 \
--gateway=192.168.1.1 \
-o ipvlan_mode=l2 \
-o parent=eth0 \
db_net
$ docker run --net=db_net --name ipv1 -itd alpine sleep 1d
$ docker run --net=db_net --name ipv2 -it --rm alpine ping -c 2 ipv1
Behavior worth knowing from the docs:
- Containers can’t ping the host’s interfaces. Docker’s comment in its own example: they “can NOT ping the underlying host interfaces as they are intentionally filtered by Linux for additional isolation.” The default namespace is unreachable by design.
- Omit
--gatewayand Docker picks the first usable address —--subnet=192.168.1.0/24yields gateway192.168.1.1. - Multicast and broadcast pass through (kernel L2 semantics), so discovery protocols keep working.
- Different subnets on the same parent can’t reach each other — that needs a router. L3 solves this, below.
- VLAN trunking works exactly like macvlan:
-o parent=eth0.20creates (or adopts) the tagged sub-interface, and networks on separate VLANs stay isolated until a router joins them.
L3 mode: routing instead of bridging
L3 throws away the broadcast domain entirely. The host acts as a router for the container networks, and Docker’s docs are explicit that the mode must be requested:
$ docker network create -d ipvlan \
--subnet=192.168.214.0/24 \
-o ipvlan_mode=l3 \
-o parent=eth0 \
ipnet210
Three consequences, all documented:
-
The subnet must differ from the parent’s. L3 “needs to be on a separate subnet as the default namespace since it requires a netlink route in the default namespace pointing to the IPvlan parent interface.” Your
eth0is on192.168.1.0/24; the containers live on192.168.214.0/24. -
--gatewayis ignored. “The field is ignored if one is specifiedl3mode.” Inside the container there is no next hop:$ docker exec ipnet210-c1 ip route default dev eth0 192.168.214.0/24 dev eth0 src 192.168.214.10 -
Broadcast and multicast are dropped entirely — no ARP, no BPDU, no broadcast domain to loop. Docker positions this as “a prime candidate for those looking for massive scale and predictable network integrations,” since bridging loops (the cascading BPDUs that cause hard-to-diagnose outages) simply can’t exist.
The flip side of routing: different subnets sharing the same -o parent can ping each other in L3 (the host routes between them), but reaching the outside world needs cooperation — “the remote host or the physical network in between need to have a route pointing to the host IP address of the container’s Docker host eth interface.”
L3s: L3 with conntracking
Docker’s option table lists a third value, l3s, and the kernel HOWTO explains it precisely: “This is very similar to the L3 mode except that iptables (conn-tracking) works in this mode and hence it is L3-symmetric (L3s). This will have slightly less performance but that shouldn’t matter since you are choosing this mode over plain-L3 mode to make conn-tracking work.”
$ docker network create -d ipvlan \
--subnet=192.168.214.0/24 \
-o ipvlan_mode=l3s \
-o parent=eth0 \
ipnet-stateful
Pick l3s when you need iptables rules or connection tracking to see container traffic in L3 mode — NAT’d services, firewall rules keyed on conntrack — and accept the slight cost.
The flags: bridge, private, vepa
Orthogonal to the mode, ipvlan_flag (kernel default bridge) shapes cross-container talk between slaves on the same parent:
| Flag | Behavior (kernel HOWTO) |
|---|---|
bridge (default) | “Slaves can cross-talk among themselves apart from talking through the master device.” |
private | ”Port won’t allow cross communication between slaves.” |
vepa | Offloads switching to the external entity per 802.1Qbg — with a caveat: ipvlan uses the master’s MAC, so packets to an adjacent neighbor have source and destination MAC identical, which “will make the switch / router send the redirect message.” |
$ docker network create -d ipvlan \
--subnet=192.168.1.0/24 \
-o parent=eth0 \
-o ipvlan_flag=private \
isolated-peers
For most setups the default bridge flag is right; reach for private when containers sharing a parent must not talk to each other.
L2 vs L3 at a glance
| L2 (default) | L3 | |
|---|---|---|
| Container subnet vs parent | Same broadcast domain | Must be separate from the parent’s namespace |
| Broadcast / multicast | Passed through | Dropped entirely |
--gateway | Honored (first usable address if omitted) | Ignored — route is default dev eth0 |
| Cross-subnet traffic on one parent | Needs an external router | Routed by the host |
| External reachability | Normal LAN routing | Upstream must route the container subnet back to the host |
| Scale profile | Depends on switch/CAM and broadcast domain | Broadcast-free, failure domain reduced to a single host |
One bonus documented on both driver pages: omit -o parent (or pass --internal) and Docker creates a dummy parent — an isolated network with no physical path at all. Both commands produce identical networks, and leaving out --subnet too assigns the default IPAM subnet of 172.18.0.0/16.
The bottom line
ipvlan trades macvlan’s one-MAC-per-container model for a single shared parent MAC, which is precisely why it survives switch and cloud policies that block macvlan. Docker gives you ipvlan_mode=l2 by default — same-subnet, broadcast-friendly, host filtered by design — and ipvlan_mode=l3 on request: separate subnet, ignored gateway, no broadcast, host-local routing, and no bridging loops to chase at 3 a.m. l3s adds conntrack to that L3 world, and the bridge/private/vepa flags tune container-to-container talk underneath. Match the mode to how your underlay expects to see traffic, and the network stops fighting you.