Skip to content
Blog

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:

  1. The external switch or router has a policy allowing only one MAC per port.
  2. Your virtual devices would exceed the NIC’s MAC capacity, pushing it into promiscuous mode with degraded performance.
  3. 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

OptionDefaultDescription
ipvlan_model2Sets the IPvlan operating mode. Can be one of: l2, l3, l3s
ipvlan_flagbridgeSets 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 --gateway and Docker picks the first usable address — --subnet=192.168.1.0/24 yields gateway 192.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.20 creates (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 eth0 is on 192.168.1.0/24; the containers live on 192.168.214.0/24.

  • --gateway is ignored. “The field is ignored if one is specified l3 mode.” 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:

FlagBehavior (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.”
vepaOffloads 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 parentSame broadcast domainMust be separate from the parent’s namespace
Broadcast / multicastPassed throughDropped entirely
--gatewayHonored (first usable address if omitted)Ignored — route is default dev eth0
Cross-subnet traffic on one parentNeeds an external routerRouted by the host
External reachabilityNormal LAN routingUpstream must route the container subnet back to the host
Scale profileDepends on switch/CAM and broadcast domainBroadcast-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.

Further reading