Pihole DNS Filter

Linux
Containers
Vagrant
Published

October 12, 2021

Modified

February 21, 2024

Pi-Hole 1 is a network-level DNS sinkhole to…

Block internet advertisement, tracking and malware

Installation

Script

Using the official installation script 2.

Simple test environment with Vagrant:

mkdir -p ~/services/pihole ; cd ~/services/pihole
# prepare a virtual machine for testing
cat > Vagrantfile <<EOF
# -*- mode: ruby -*-
# vi: set ft=ruby :
Vagrant.configure("2") do |config|
  config.vm.define  "pihole"
  config.vm.box = "generic/ubuntu2310"
  config.vm.box_check_update = false
  config.vm.synced_folder ".", "/vagrant", disabled: true
  config.vm.network "private_network", ip: "192.168.50.10"
  config.vm.provider :libvirt do |libvirt|
    libvirt.autostart = true
  end
end
EOF
vagrant up && vagrant ssh

Deployment using the official script:

# after login install the software (make sure to select the 
# right network interface in the dialog)
curl -sSL https://install.pi-hole.net | bash

# display running status
pihole status

# set the admin password
pihole -a -p 12345678

# open the web-interface
$BROWSER http://192.168.50.10/admin/

# query the DNS
host www.google.de 192.168.50.10

Podman

podman pull pihole/pihole:latest
podman run -d --name pihole \
      -e TZ="Europa/Berlin" \
      -e WEBPASSWORD="12345678" \
      -p 53:53/tcp -p 53:53/udp -p 67:67/udp -p 80:80 -p 443:443 \
      -v "/etc/pihole/" \
      --restart=unless-stopped \
      --cap-add=NET_ADMIN \
      --dns=127.0.0.1 --dns=1.1.1.1 \
   pihole/pihole:latest

Docker

Deployment using the official docker container 3

# install Docker (Debian packages) 
apt-get install -y docker docker-compose
# download a docker configuration file
wget -O docker-compose.yml \
      https://raw.githubusercontent.com/pi-hole/docker-pi-hole/master/docker-compose.yml.example
sudo su 
# start the docker container
docker-compose up --detach
# find the randomly generated admin password
docker logs pihole | grep random
# use the `pihole` command in the container
docker exec pihole pihole SUBCOMMAND
# start a shell in the container
docker exec -it pihole bash

Vagrantfile which installs Docker and writes docker-compose.yml file to pull the Pi-hole docker container and start the service:

cd $(mktemp -d)
cat > Vagrantfile <<EOF
# -*- mode: ruby -*-
# vi: set ft=ruby :
docker_compose = %q(
version: '3'
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp"
      - "80:80/tcp"
    environment:
      TZ: 'Europa/Berlin'
      WEBPASSWORD: '12345678'
      PIHOLE_DNS_: 1.1.1.1;1.0.0.1
      IPv6: 'false'
    volumes:
      - './etc-pihole/:/etc/pihole/'
      - './etc-dnsmasq.d/:/etc/dnsmasq.d/'
    cap_add:
      - NET_ADMIN
    restart: unless-stopped
)
Vagrant.configure("2") do |config|
  config.vm.define  "pihole"
  config.vm.box = "debian/buster64"
  config.vm.network "private_network", ip: "192.168.50.10"
  config.vm.box_check_update = false
  config.vm.synced_folder ".", "/vagrant", disabled: true
  # this is only required for the deployment using Docker
  config.vm.provision "shell" do |s|
    s.privileged = true,
    s.inline = %Q(
      apt-get update -q
      apt-get install -q -y docker docker-compose
      echo "#{docker_compose}" > docker-compose.yml 
      docker-compose up --detach
    )
  end
end
EOF
vagrant up && vagrant ssh

Configuration

Select your upstream DNS providers or setup with a recursive DNS server 4

Configure blocklists 5 …

  • Defaults to list hosted at github.com/StevenBlack/hosts 6…
  • …alternative lists with expanded blocking for adult content and fake news
  • OISD 7 provides a very comprehensive “Full” blocklist

The pihole command:

pihole status        # status of blocking services
pihole -v            # list versions of components
pihole -g            # [gravity] retrieve blocklists, consolidate with black/whitelists
pihole -q DOMAIN     # search white/blacklist, wildcards and adlists for a specified domain
pihole -w DOMAIN     # whitelist DNS domain
pihole -w DOMAIN -d  # remove a DNS domain from whitelist
pihole -c -e         # [cronometer] console dashboard

Usage

Configure a DNS resolver to use the Pi-hole service deployed above depending on the implementation on your host system:

  • Modify /etc/resolv.conf nameserver configuration line
  • If the systemd-resolved service is enabled use the following command
resolvectl dns ${iface} 192.168.50.10

Permanent configuration:

mkdir -p /etc/systemd/resolved.conf.d
cat > /etc/systemd/resolved.conf.d/dns-servers.conf <<EOF
[Resolve]
DNS=192.168.50.10
FallbackDNS=1.1.1.1 8.8.8.8
EOF