Pi-hole container setup

Apr 16, 2023 - Last update: Feb 19, 2025

Introduction

Pi-hole is a network-level ad blocker that acts as a DNS sinkhole, filtering out unwanted advertisements and tracking domains to enhance privacy and improve browsing speed. Using Unbound in combination with Pi-hole allows you to run a recursive DNS server, adding an extra layer of privacy by ensuring DNS queries are resolved locally without relying on third-party DNS providers.

Setup

Below are the steps you can follow for the Linux terminal or NixOS configuration.

Linux Terminal

To allow Pi-hole to communicate with Unbound, you need to create a Docker network first. You only need to do this if you want to use Unbound as an upstream DNS server. So it is for example also possible to use the Cloudflare DNS server as an upstream DNS server.

1. Create the network dns-net

   Run the following command:

   Linux

   # Open your terminal application
   sudo docker network create --driver=bridge --subnet=172.19.0.0/16 --gateway=172.19.0.1 dns-net

2. Create the folders needed by the container

   Run the following commands inside your home folder:

   Linux

   # Open your terminal application
   cd ~
   mkdir -p pihole/etc-pihole
   mkdir -p pihole/etc-dnsmasq.d
   cd pihole

3. Create the script needed to run the container

   Save the following script as pihole_run.sh:

   Linux

   pihole_run.sh

   # To create this script use your text editor application, for example Nano
   docker run -d \
   --hostname=pihole \
   --name=pihole \
   --network=dns-net \
   --ip=172.19.0.4 \
   -p 53:53/tcp \
   -p 53:53/udp \
   -p 67:67/udp \
   -p 81:80/tcp \
   -v $PWD/etc-pihole:/etc/pihole \
   -v $PWD/etc-dnsmasq.d:/etc/dnsmasq.d \
   -e FTLCONF_LOCAL_IPV4=172.19.0.4 \
   -e FTLCONF_dns_upstreams=172.19.0.5#5053 \
   -e FTLCONF_webserver_api_password=<password> \
   -e TZ="Europe/Amsterdam" \
   --cap-add=NET_ADMIN \
   --dns 127.0.0.1 \
   --restart=unless-stopped \
   pihole/pihole:latest
   # IMPORTANT: Please read the instructions below

   Instructions:

   • Optional Replace docker with podman if needed
   • Optional The setting --ip=172.19.0.4 contains the fixed IP address of the container in the range of the dns-net network, you can change this if needed
   • Optional The setting -p 67:67/udp is only required if you are using Pi-hole as your DHCP server
   • Optional Replace port 81 of 81:80/tcp to whatever port you want to use to to access the web interface
   • Optional Replace $PWD/etc-pihole with your own location if needed. This can be a fileserver
   • Optional Replace $PWD/etc-dnsmasq.d with your own location if needed. This can be a fileserver
   • Optional The setting FTLCONF_LOCAL_IPV4=172.19.0.4 contains the fixed IP address of the container in the range of the dns-net network
   • Optional Replace 172.19.0.5#5053 with the IP address and port of the upstream DNS server, in this case it is the IP address of the Unbound container in the range of the dns-net network. You can also configure this within the web interface. Replace FTLCONF_dns_upstreams with PIHOLE_DNS_ if you are using an older version of Pi-hole
   • Required Replace <password> with your own password to access the web interface. Replace FTLCONF_webserver_api_password with WEBPASSWORD if you are using an older version of Pi-hole
   • Required Replace Europe/Amsterdam with your own timezone
   • Optional The setting --cap-add=NET_ADMIN is only required if you are using Pi-hole as your DHCP server
   • Optional The setting --dns 127.0.0.1 is maybe needed so the container can resolve DHCP hostnames from Pi-hole’s DNSMasq, may fix resolution errors on container restart. Here is the link to the documentation

   Note

   Make sure the ports are available. Check this with netstat. With the following command you can find out which service is running on port 53:

   Linux

   # Open your terminal application
   sudo ss -lp "sport = :domain"

   Note

   When you need to disable systemd-resolved, please read this.

4. Run the script to create the container

   Run the following command:

   Linux

   # Open your terminal application
   sudo sh pihole_run.sh

   The image pihole/pihole is automatically pulled and the container is created.

   Tip

   If you need to update this container you can remove the container with sudo docker rm pihole and run this script again or read my note about updating containers. The data is retained due to the volumes we have set in the script. And it is also possible to run Docker commands without sudo.

5. Check the results

   If needed you can check if the container is running properly.

   Now you can browse to the Pi-hole web interface by opening a web browser and going to: https://localhost:81/admin. Replace localhost with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier.

   Tip

   I am only using one adlist: https://big.oisd.nl/. You can set this up by going to Group Management and then add this adlist. Do not forget to update Gravity.

   Note

   I did also set up Conditional Forwarding (replace with your own network settings):

   • Local network in CIDR notation: 192.168.1.0/24

   • IP address of your DHCP server (router): 192.168.1.1

   • Local domain name (optional): home.arpa

   Home.ARPA has been specifically created to handle “home” or “small business” name queries by shunting it to “black holes” early in the hops.

NixOS Configuration

Note

This configuration uses Podman as container backend.

1. Add virtualisation to configuration.nix

   Add virtualisation and the import to a seperate nix file for the container to configuration.nix:

   Linux

   /etc/nixos/configuration.nix

     # To edit use your text editor application, for example Nano
     virtualisation = {
       podman = {
         enable = true;
         dockerCompat = true; # Create a `docker` alias for podman, to use it as a drop-in replacement
         defaultNetwork.settings.dns_enabled = true; # release 23.05
       };
       oci-containers = {
         backend = "podman";
         containers = {
           pihole = import ./containers/pihole.nix;
         };
       };
     };

2. Add the macvlan network to configuration.nix

   The container will use a macvlan network (net_macvlan) with a dedicated IP address. Add the following to configuration.nix:

   Linux

   /etc/nixos/configuration.nix

   # To edit use your text editor application, for example Nano
   systemd.services.create-podman-network = with config.virtualisation.oci-containers; {
     serviceConfig.Type = "oneshot";
     wantedBy = [ "${backend}-pihole.service" ];
     script = ''${pkgs.podman}/bin/podman network exists net_macvlan || \ ${pkgs.podman}/bin/podman network create --driver=macvlan --gateway=192.168.1.1 --subnet=192.168.1.0/24 -o parent=ens18 net_macvlan'';
   };
   # IMPORTANT: Please read the instructions below

   Instructions:

   • Required Replace 192.168.1.1 with your gateway IP address
   • Required Replace 192.168.1.0 with your subnet
   • Required Replace ens18 with the name of own network interface

3. Add a script to create folders to configuration.nix

   Make sure the folders for use with the container are created by adding the following to configuration.nix:

   Linux

   /etc/nixos/configuration.nix

   # To edit use your text editor application, for example Nano
   system.activationScripts = {
     script.text = ''
       install -d -m 755 /home/<username>/pihole/etc-pihole -o root -g root
       install -d -m 755 /home/<username>/pihole/etc-dnsmasq.d -o root -g root
     '';
   };
   # IMPORTANT: Please read the instructions below

   Caution

   Make sure the folders are created with the root user and group, else the container will not work properly

   Instructions:

   • Required Replace <username> with your NixOS username

4. Create the containers folder

   Run the following command:

   Linux

   # Open your terminal application
   mkdir -p /etc/nixos/containers # Make sure the directory exists

5. Add the container configuration to pihole.nix

   Add the following to pihole.nix:

   Linux

   /etc/nixos/containers/pihole.nix

   # To edit use your text editor application, for example Nano
   {
     image = "pihole/pihole:latest";
   
     environment = {
       "TZ" = "Europe/Amsterdam";
       "FTLCONF_webserver_api_password" = "<password>";
       "FTLCONF_dns_upstreams" = "<upstream DNS server>"; # Default port #53
       "FTLCONF_LOCAL_IPV4" = "<IP address>";
       "VIRTUAL_HOST" = "pihole.home.arpa";
     };
   
     volumes = [
       "/home/<username>/pihole/etc-pihole:/var/lib/mysql"
       "/home/<username>/pihole/etc-dnsmasq.d:/etc/mysql/conf.d"
     ];
   
     extraOptions = [
       "--pull=newer" # Pull if the image on the registry is newer than the one in the local containers storage
       "--name=pihole"
       "--hostname=pihole"
       "--network=net_macvlan"
       "--ip=<IP address>"
       "--mac-address=<MAC address>"
     ];
   }
   # IMPORTANT: Please read the instructions below

   Instructions:

   • Required Replace Europe/Amsterdam with your own timezone

   • Required Replace <password> with your password for use with the Pi-hole web interface. Replace FTLCONF_webserver_api_password with WEBPASSWORD if you are using an older version of Pi-hole

   • Required Replace <upstream DNS server> with the IP address of the upstream DNS server you want to use. In my case this is Unbound. Replace FTLCONF_dns_upstreams with PIHOLE_DNS_ if you are using an older version of Pi-hole

   • Required Replace <IP address> with the IP address of this container. Make sure it is within the range of the macvlan network

   • Optional Replace pihole.home.arpa with what your web server ‘virtual host’ is

   • Required Replace <username> with your NixOS username

   • Optional Replace --pull=newer with --pull=never if you do not want the image to be automatically replaced by new versions

   • Optional Replace net_macvlan with the name of your macvlan network if needed

   • Required Replace <MAC address> a (randomly generated) MAC address. Otherwise, every time the container is started, a new mac address will be used, which for example will be created as a new device within the Unifi Network Application. Or temporarily disable this option, and add the MAC address that is generated the first time when this container is started. Use inspect to get the MAC address if needed: sudo podman inspect <container name> |grep MacAddress|tr -d ' ,"'|sort -u

6. Switch NixOS configuration

   Now you can switch to the new configuration within NixOS, the image will be downloaded and the container will be created:

   Run the following command:

   Linux

   # Open your terminal application
   sudo nix-collect-garbage # Optional: clean up
   sudo nixos-rebuild switch

7. Check the results

   Run the following commands to check if the container and Pi-hole is working properly:

   Linux

   # Open your terminal application
   journalctl -u podman-pihole.service
   # Optionally test Pi-hole with dig
   dig pi-hole.net @<IP address> -p 53
   # IMPORTANT: Please read the instructions below

   Instructions:

   • Required Replace <IP address> with the IP address of the Pi-hole container

   Now you can browse to the Pi-hole web interface by opening a web browser and going to: https://localhost/admin. Replace localhost with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier.

   Tip

   I am only using one adlist: https://big.oisd.nl/. You can set this up by going to Group Management and then add this adlist. Do not forget to update Gravity.

   Note

   I did also set up Conditional Forwarding (replace with your own network settings):

   • Local network in CIDR notation: 192.168.1.0/24

   • IP address of your DHCP server (router): 192.168.1.1

   • Local domain name (optional): home.arpa

   Home.ARPA has been specifically created to handle “home” or “small business” name queries by shunting it to “black holes” early in the hops.

Favorites

Pi-hole Docker container readme

Comments

No comments found for this note.

Join the discussion for this note on Github. Comments appear on this page instantly.

Tags:

• Virtualisation
• Networking
• Linux

Caddy NixOS container setup

Homer NixOS container setup