Menu
Article docker

Pi-hole in Docker

Rob Van Keilegom

• 3 min read

Pi-hole was originally designed with the Raspberry Pi in mind but can be installed on any Linux machine. The problem with running it in a Docker container is that you can't just bind the container to port 53 (DNS) since the port is in use on most Linux system (ex: systemd-resolved on Ubuntu).

One option would be to free up the port. Another option is to give the container its own IP on your LAN. That's what we'll do here.

First, create a docker network in the range of your LAN network. For this you'll need the IP range of your network and the name of the network adapter you're using to connect your Docker host to the network.

If the Docker host is Debian based (like Ubuntu or openmediavault) run: ip a. You'll get an output like:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host 
       valid_lft forever preferred_lft forever
2: enp6s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether xx:xx:xx:xx:xx:xx brd ff:ff:ff:ff:ff:ff
    inet 192.168.178.2/24 brd 192.168.178.255 scope global enp6s0
       valid_lft forever preferred_lft forever

Here you'll find all the info you need. enp6s0 is the adapter and 192.168.178.2 is the IP address of the machine. This means the IP range is 192.168.178.x.

With this info we'll create a Docker network where we'll put our Pi-hole container in. Replace the first 3 numbers of the IP address so they match your network, and replace the enp6s0 to match your network adapter. See the Docker documentation to learn more about macvlan networks.

docker network create \ 
	--driver=macvlan \ 
    --gateway=192.168.178.1 \ 
    --subnet=192.168.178.0/24 \ 
    --ip-range=192.168.178.248/30 \ 
    -o parent=enp6s0 \ 
    --aux-address="myserver=192.168.178.248" \ 
    pihole-network
💡
For the advanced users: this will create a network with 4 addresses in the IP range. The first IP will be 192.168.178.248, this will be used for the host. So we'll tell the network that IP is in use with the aux-address parameter. That means we have 2 addresses left for containers but we'll only need one for the Pi-hole container.

Now we have to configure our host machine to accept network traffic for the new network. For this we'll first create a virtual adapter macvlan-shim that is linked to the physical adapter. Don't forget to replace the adapter name enp6s0 with your adapter name.

ip link add macvlan-shim link enp6s0 type macvlan mode bridge

Now we'll assign an IP in the range of our Pi-hole network to the new virtual adapter. Don't forget the change the first 3 numbers of the IP address.

ip addr add 192.168.178.248/30 dev macvlan-shim

That's it, now enable the new virtual adapter with the following:

ip link set macvlan-shim up

The last thing we have to do is tell our physical adapter to accept traffic meant for the virtual adapter. By default the adapter will only accept traffic for its MAC address. Again, replace the name of the adapter enp6s0.

ip link set enp6s0 promisc on

Don't forget to put the Pi-hole container in the network. This can be done in various ways, depending if you're using Docker via the terminal, docker-compose or Portainer.

Persisting the macvlan network settings

If we don't persist these settings, the system network definition will be lost upon the next reboot. This will cause incredibly slow DNS lookups that time out, since there is no route to our pihole instance. If your DNS is very slow, this is likely the cause. Luckily, this is easy to solve.

First, make a script with the commands we used above to create the network. Save it to /usr/local/bin/pi-vlan.sh, and be sure to run chmod +x /usr/local/bin/pi-vlan.sh

Now, add a systemd file at /etc/systemd/system/pi-vlan.service with the following contents:

#!/usr/bin/env bash
ip link add macvlan-shim link enp6s0 type macvlan mode bridge
ip addr add 192.168.178.248/30 dev macvlan-shim
ip link set macvlan-shim up
[Unit]
After=network.target

[Service]
ExecStart=/usr/local/bin/pi-vlan.sh

[Install]
WantedBy=default.target

And enable it so that it starts on boot: sudo systemctl enable pi-vlan

This script will wait until the network module comes up, and then add the macvlan-shim network for our pihole.

You can test this by rebooting your server. The docker container should come up since we set restart: unless-stopped, and the network shim should be added by our systemd script.

Share