Host-to-Container Communication via Shim

The Problem

While setting up a Pi-Hole instance via Docker macvlan to give it a dedicated IP on my LAN, I hit a frustrating networking wall: the host machine itself could not reach the container. While every other device on the network could resolve DNS through the new Pi-Hole IP without issue, the host was met with constant timeouts.

I discovered this is a known behavior of the Linux kernel. The macvlan implementation intentionally isolates the host from its own containers for security, effectively making the container invisible to the host’s own network stack.

The Solution

To bypass this, you must create a “shim” interface on the host. This interface acts as a secondary macvlan link that allows the host to route traffic to the container’s IP address.

1. Create the Docker Macvlan Network

First, create the network. We use --aux-address to reserve an IP on the subnet specifically for the host’s shim interface to prevent IP conflicts.

# Replace eno1 with your actual physical interface
docker network create -d macvlan \
  --subnet=10.20.30.0/24 \
  --gateway=10.20.30.1 \
  --aux-address 'host=10.20.30.14' \
  -o parent=eno1 \
  macvlan

2. Configure Persistence

Since ip link and ip route commands are ephemeral, they must be added to your network configuration. For Debian-based systems using ifupdown, add these post-up hooks to /etc/network/interfaces.

# /etc/network/interfaces
auto eno1
iface eno1 inet dhcp

# Create the shim interface and route to the container (10.20.30.13)
post-up ip link add macvlan-shim link eno1 type macvlan mode bridge
post-up ip addr add 10.20.30.14 dev macvlan-shim
post-up ip link set macvlan-shim up
post-up ip route add 10.20.30.13 dev macvlan-shim

3. Deploy the Container

When running the container, ensure you assign the static IP that matches the route you created in the shim.

docker run -d \
  --name pihole \
  --network macvlan \
  --ip 10.20.30.13 \
  --cap-add NET_ADMIN \
  --restart unless-stopped \
  --hostname pihole.local.example.com \
  -e PIHOLE_DNS_=10.20.30.1#53 \
  -e VIRTUAL_HOST=pihole.local.example.com \
  -e ServerIP=10.20.30.13 \
  -v /data/pihole/config:/etc/pihole \
  -v /data/pihole/dnsmasq.d:/etc/dnsmasq.d \
  -v /data/pihole/resolv.d/resolv.conf:/etc/resolv.conf \
  pihole/pihole

4. Configure Host DNS

Point the host’s resolver to the container’s IP.

/etc/resolv.conf

nameserver 10.20.30.13
search local.example.com

Standard macvlan networking isolates the host from its containers. By creating a secondary macvlan-shim interface on the host and explicitly routing the container’s IP through that shim, you restore bidirectional communication. Always ensure the shim’s IP is reserved via --aux-address to avoid subnet collisions.