Docker macvlan and ipvlan on a VPS
Why Docker macvlan usually fails on a rented VPS, what to ask your provider, when ipvlan L2 or L3 works, and why the host cannot reach its own containers.
What Docker macvlan does, and why a VPS is the wrong place for it
Docker macvlan gives each container its own MAC address and its own IP address on the host's network interface, so the container looks like a separate device on the network. On a home LAN (local area network) that is often what you want. On a rented VPS it usually fails, because the provider's network must accept MAC addresses it never assigned and deliver IP addresses to them. Docker's own macvlan page puts it in one line: "Most cloud providers block macvlan networking."
This guide explains the mechanism, then the questions to ask your provider before you try. It covers ipvlan, which avoids the extra MAC addresses, and what to use on a VPS instead. The Compose examples are for you to run on your own host. Whether they work depends on your provider's network, and no test container can reproduce that.
How Docker macvlan works
A normal Docker network is a bridge. Containers get private addresses behind the host, and the host rewrites their traffic with NAT (network address translation). The outside world only ever sees the host's IP address.
Macvlan skips the bridge and the NAT. Docker assigns a MAC address to each container's virtual network interface and attaches it to a parent interface on the host, such as eth0. Docker describes the result as a container that appears to be "a physical network interface directly connected to the physical network". Other machines on the network see a new device with its own MAC address and its own IP address.
Docker lists these requirements on its macvlan page:
- It works on Linux hosts only.
- It needs Linux kernel 3.9 or later. Docker recommends 4.0 or later.
- It is not supported in rootless mode.
- The networking equipment must handle "promiscuous mode", where one physical interface can be assigned multiple MAC addresses.
The last requirement decides everything on a VPS. Docker also warns that macvlan can degrade a network through IP address exhaustion or "VLAN spread". It suggests a bridge network on a single host, or an overlay network across several hosts, when your application can work with them.
Docker's own example creates a macvlan network like this:
docker network create -d macvlan \
--subnet=172.16.86.0/24 \
--gateway=172.16.86.1 \
-o parent=eth0 \
pub_net-o parent= names the host interface the containers attach to. Do not assume it is eth0. Run ip route show default and use the name printed after dev, which on current images is often something like enp1s0 or ens3.
Docker's options table lists macvlan_mode with a default of bridge. The other values are vepa, passthru and private. If you ever create a macvlan interface by hand with ip link, set the mode explicitly, because the ip-link(8) man page documents vepa as its own default. The two tools do not share a default.
Why macvlan usually breaks on a rented VPS
Your VPS is a virtual machine. Its network interface is virtual, and the provider's network decides which frames from it are delivered. A macvlan container sends frames from a MAC address the provider never gave you. Whether those frames go anywhere is a property of the provider's network, not of Docker. Docker's page adds that "You may need physical access to your networking equipment", which a VPS customer does not have.
Even when the frames get through, the container needs an IP address that the provider actually routes to you. An address you pick from the subnet your VPS sits in is not yours unless the provider assigned it to you. It may belong to another customer, or it may not be routed at all.
So before you build on macvlan, ask your provider four questions:
- Does your network accept frames from MAC addresses other than the one assigned to my VPS?
- Can I get additional IPv4 addresses, and are they delivered to my VPS's existing MAC address or does each one need its own MAC?
- Can you route a whole subnet to my VPS's main IP address?
- Is there a network firewall or anti-spoofing filter in front of my VPS that I need to change?
The answers pick the driver for you. A yes to question 1 plus extra addresses means macvlan can work. Extra addresses on your existing MAC point to ipvlan L2. A routed subnet points to ipvlan L3. No to all of them means a bridge network or host networking, covered below.
Test it before you rely on it
Replace the subnet, gateway and address below with the values your provider gave you. The 203.0.113.x addresses here are documentation placeholders.
ip route show default
docker network create -d macvlan \
--subnet=203.0.113.0/24 \
--gateway=203.0.113.1 \
-o parent=eth0 \
test_mac
docker run --rm --network test_mac --ip 203.0.113.50 alpine ping -c 3 1.1.1.1
docker network rm test_macA healthy result is three replies from 1.1.1.1. No replies means the container's traffic is not getting out and back. The likely reasons are the provider filtering the new MAC address, or the address not being routed to you. Those are questions 1 and 2 above.
Run the reverse test from another machine, such as your laptop, not from the VPS itself. The VPS cannot reach its own macvlan containers, so a failed ping from the host proves nothing. The next section explains why.
Why the host cannot reach its own macvlan containers
This is the classic surprise. The container works for every other machine on the network, but curl or ping from the Docker host to the container's address times out. Docker's page states it directly: "Containers attached to a macvlan network cannot communicate with the host directly, this is a restriction in the Linux kernel."
Docker gives two workarounds.
Attach the container to a bridge network as well. A container can join more than one network, and Docker's docker network connect reference says the networks need not be the same type. The host and other containers then reach the service over the bridge, while the LAN reaches it on the macvlan address. In Compose that is a second entry under the service's networks:, shown in the Compose section below.
Give the host its own macvlan interface. Docker's page says you can "create a macvlan interface on the host with the same parent interface" and "assign it an IP address in the Docker network's subnet". This is often called a shim interface. Docker describes it only in prose, so take the exact syntax from the MACVLAN section of man ip-link and set mode bridge, since ip link defaults to vepa. An interface added with ip link lasts until the next reboot. Make it permanent in your distribution's network configuration once it works.
Switching to ipvlan does not remove this problem. Docker's ipvlan page says the containers "can NOT ping the underlying host interfaces" and that "The default namespace is not reachable per IPvlan design". The same two workarounds apply.
Docker ipvlan: one MAC address, more IP addresses
Docker's macvlan page has a section called "Use an IPvlan instead of Macvlan". It says the ipvlan driver does not assign a MAC address to each container. The Linux kernel documentation explains the mechanism: ipvlan is conceptually very similar to macvlan, but it uses L3 (layer 3, the IP layer) to sort traffic between containers, and it uses the MAC address of the parent device. The kernel docs name the case it exists for: a host connected to a switch or router whose policy "allows only one mac per port".
That is the reason ipvlan gets past filtering that drops unknown MAC addresses. It does not create IP addresses for you. Every container still needs an address the provider routes to your VPS. ipvlan needs Linux kernel 4.2 or later, and Docker notes that all of its ipvlan examples are single host.
Docker's ipvlan driver offers l2 and l3 modes. The options table also lists l3s, which the kernel describes as L3 mode with iptables connection tracking working.
ipvlan L2 with extra IPs assigned to your VPS
The default mode is l2. In L2 mode the containers sit on the parent interface's network and send and receive broadcast and multicast traffic. Docker's example:
docker network create -d ipvlan \
--subnet=192.168.1.0/24 \
--gateway=192.168.1.1 \
-o ipvlan_mode=l2 \
-o parent=eth0 \
db_netOn a VPS, use the subnet and gateway of your VPS's main address, and give each container one of the extra addresses the provider assigned to you. Pin those addresses with ipv4_address in Compose, so Docker never hands a container an address you do not own. Do not configure the same address on the host's interface and on a container.
ipvlan L3 with a routed subnet
L3 mode is a different design. The container subnet must be separate from the parent interface's subnet, and Docker says "IPvlan L3 mode drops all broadcast and multicast traffic." You must set -o ipvlan_mode=l3 explicitly, because the default is l2. There is no gateway: Docker ignores a --gateway value in L3 mode.
For other machines to reach the containers, Docker says "the remote host or the physical network in between need to have a route pointing to the host IP address". On a VPS the network in between belongs to the provider, so L3 works only if the provider routes a subnet to your VPS's main IP. That is question 3 above.
Because broadcast is dropped, anything that depends on it stops working in L3 mode. DHCP (dynamic host configuration protocol) is the common example, since Pi-hole's docs describe the DHCP protocol as operating "through a network 'broadcast'".
Compose syntax for macvlan and ipvlan networks
Compose passes these settings to Docker. The network's driver key picks the driver, and Compose returns an error if that driver is not available on the platform. driver_opts holds driver-dependent key-value pairs, which is where parent and the mode go. ipam holds the address plan: each config entry can carry subnet, ip_range, gateway and aux_addresses.
The Compose reference has no macvlan or ipvlan example, so treat the files below as starting points that you run and check yourself. Run docker compose config first. It prints the file as Compose reads it, which catches indentation mistakes before anything starts.
A macvlan network on a home LAN, with a bridge network added so the host can still reach the service:
services:
web:
image: nginx:stable
networks:
lan:
ipv4_address: 192.168.1.241
hostside: {}
networks:
lan:
driver: macvlan
driver_opts:
parent: eth0
macvlan_mode: bridge
ipam:
config:
- subnet: 192.168.1.0/24
ip_range: 192.168.1.240/28
gateway: 192.168.1.1
aux_addresses:
reserved: 192.168.1.242
hostside:
driver: bridgeip_range limits Docker to a small block inside the LAN subnet. Choose a block your router's DHCP server never hands out, or two devices can end up with the same address. aux_addresses keeps named addresses out of Docker's allocation, the same job as --aux-address on the command line.
An ipvlan L2 network on a VPS with one extra address from your provider:
services:
app:
image: nginx:stable
networks:
extra:
ipv4_address: 203.0.113.50
networks:
extra:
driver: ipvlan
driver_opts:
parent: eth0
ipvlan_mode: l2
ipam:
config:
- subnet: 203.0.113.0/24
gateway: 203.0.113.1An ipvlan L3 network for a subnet the provider routes to your VPS. Note that there is no gateway line:
services:
app:
image: nginx:stable
networks:
routed:
ipv4_address: 198.51.100.10
networks:
routed:
driver: ipvlan
driver_opts:
parent: eth0
ipvlan_mode: l3
ipam:
config:
- subnet: 198.51.100.0/28Set gateway explicitly for macvlan and ipvlan L2 rather than relying on a default. If the container has no default route, read the Docker Engine release notes for your version. If you would rather create the network once with docker network create and share it between projects, declare it in Compose as external: true. Compose then does not create it and returns an error if it does not exist. With external, every attribute except name is rejected, so the driver and ipam settings live only in the docker network create command. For more on how Compose names and scopes networks, read how Docker Compose networks work.
What to use on a VPS instead
Most services on a VPS do not need their own address on the provider's network. One of these covers nearly every case.
A user-defined bridge network with published ports. Docker calls the default bridge network "a legacy detail of Docker" that is not recommended for production, and says user-defined bridges are superior. Publishing a port with -p 8080:80 listens on every address on the host, and Docker's port-publishing page says "Publishing container ports is insecure by default." Put 127.0.0.1: in front, as in 127.0.0.1:8080:80, when only a reverse proxy on the same host should reach the port. Docker notes that in releases older than 28.0.0, hosts on the same L2 segment could reach ports published to localhost. Read how published Docker ports interact with ufw before you trust a host firewall to protect them, and the guide to running Docker on a VPS for the rest of the setup. If Docker refuses a bridge subnet you chose, the non-overlapping IPv4 address pool error walks through it.
Host networking. With network_mode: host the container shares the host's network namespace and does not get its own IP address. Published ports are ignored, and Docker prints WARNING: Published ports are discarded when using host network mode. The port the service listens on must be free on the host. Host networking only works on Linux hosts, plus Docker Desktop 4.34 and later as an opt-in feature.
An extra IP plus ipvlan. When the provider confirms extra addresses on your existing MAC, or a routed subnet, ipvlan L2 or L3 from the sections above gives a container a public address of its own.
A private network between servers. If the real goal is for containers on two servers to talk to each other, you do not need macvlan at all. Join the servers with a private network between two VPSes, or use an overlay network, which Docker itself suggests for traffic across multiple hosts.
Where macvlan is the right choice: a home DNS server
Macvlan earns its place on a home server you control, where your own switch or router accepts the extra MAC address. The common case is giving AdGuard Home or Pi-hole its own address on the LAN.
The problem it solves is real. AdGuard Home's Docker page says that to see original client IPs "as opposed to something like 172.17.0.1", you must add --network host, and its DHCP server also needs host networking. On a host running systemd-resolved, AdGuard's page also says DNSStubListener must be disabled to prevent a port 53 bind conflict. Pi-hole's Docker docs say DHCP runs best with --net=host, otherwise your router must support DHCP relay settings.
Macvlan is the other option. Pi-hole's Docker DHCP page describes it as similar to host mode, except that instead of borrowing the host's IP the container "grabs a new IP address off your LAN network". A container on macvlan listens on its own address inside its own network namespace, so nothing on the host has to give up port 53, and no ports: list is needed.
A Pi-hole on macvlan, built from Pi-hole's own Compose example with the ports removed:
services:
pihole:
image: pihole/pihole:latest
environment:
TZ: 'Europe/London'
FTLCONF_webserver_api_password: 'change-this-password'
FTLCONF_dns_listeningMode: 'ALL'
volumes:
- './etc-pihole:/etc/pihole'
restart: unless-stopped
networks:
lan:
ipv4_address: 192.168.1.250
networks:
lan:
driver: macvlan
driver_opts:
parent: eth0
ipam:
config:
- subnet: 192.168.1.0/24
ip_range: 192.168.1.248/29
gateway: 192.168.1.1Point your router's DNS setting at 192.168.1.250. Remember the host restriction: the Docker host itself cannot query this Pi-hole on its macvlan address. Either keep the host on another resolver, or add a bridge network or a shim interface as described above. If you plan to use Pi-hole's DHCP server, its docs say the container needs the NET_ADMIN capability, which Docker does not grant to non-privileged containers by default.
FAQ
Why can my Docker host not reach its own macvlan container?
Docker documents this as a restriction in the Linux kernel: containers on a macvlan network cannot communicate with the host directly. Other machines reach the container, but the host's own requests time out. Fix it by attaching the container to a bridge network as well, or by creating a macvlan interface on the host with the same parent and an address in the Docker network's subnet. ipvlan has the same restriction by design.
Does Docker macvlan work on a VPS?
Usually not. Docker's documentation says most cloud providers block macvlan networking, and macvlan needs a network that accepts several MAC addresses on one interface. Each container also needs an IP address the provider routes to you. Ask your provider whether extra MAC addresses are accepted and whether they can assign extra IPs or route a subnet to your VPS, then test from a second machine.
What is the difference between macvlan and ipvlan in Docker?
Macvlan gives every container its own MAC address. ipvlan does not: the kernel documentation says it uses the MAC address of the parent device. That lets ipvlan work where the network allows only one MAC address per port. Both still need IP addresses that are really yours, and in both the host cannot reach the containers directly.
Should I use ipvlan L2 or L3 on a VPS?
Use L2 when the provider gives you extra IP addresses on your VPS's existing network and MAC address. Use L3 when the provider routes a separate subnet to your VPS's main IP. L3 needs a container subnet separate from the parent's, ignores any gateway you set, and drops all broadcast and multicast traffic, so DHCP will not work in it. With neither, use a bridge network with published ports or host networking.