Pihole

This guide provides an easy way to set up Pi-hole®, a tool that stops internet ads.

You can manage Pi-hole using a simple CSV file that you can edit with any text editor.

Requirements

You need a machine running Ubuntu, Debian, Photon OS, or a Raspberry Pi with Raspberry Pi OS.

If you have issues, check the Pi-hole documentation for help.

Host CSV File

Pi-hole settings are configured in a CSV file. This makes it easy to keep track of everything.

The role includes an example CSV file in the files folder for you to look at.

The lines below show dhcp-option settings that will be added to the dnsmasq configuration file. One line marks the IP address of the virtual machine DNS server, and another for the Raspberry Pi DNS server.

Set DHCP Options

hostname,domainname,ip_address,static,mac_address,dhcp_option,type,comment
,,,,,"tag:vm-dns,option:dns-server,192.168.30.253","<<tag>>","Defines DNS server for DHCP"
,,,,,"tag:pi-dns,option:dns-server,192.168.30.254","<<tag>>","Defines DNS server for DHCP"

Note: If you have multiple DNS servers, set the riv_pihole_dns_default_tag option to choose a default DNS server for clients without a specific setting.

Setup IP/Host Mapping

The example below shows how to configure a host named slash to get the IP address 192.168.128.2, if it's available.

hostname,domainname,ip_address,static,mac_address,dhcp_option,type,comment
slash,example.net,192.168.128.2,true,,,"<<physical>>","ESXi Host"

Setup Static IP Address

To ensure that an IP address is only assigned to one hostname, set the static field to true. This will make dnsmasq ignore DHCP requests from any host named vmhole.

hostname,domainname,ip_address,static,mac_address,dhcp_option,type,comment
vmhole,example.net,192.168.128.253,true,,,"<<virtual>>","Pi-hole Virtual machine DNS server"

Setup MAC Address/IP Address Mapping

To link a specific IP address and hostname to a device using its MAC address, use the entry below in the CSV file.

hostname,domainname,ip_address,static,mac_address,dhcp_option,type,comment
blib,example.net,192.168.128.18,,00:0c:29:43:37:dc,,"<<virtual>>","Pi-hole Virtual machine DNS server"

Set Different DNS Server

You can assign a separate DNS server to some devices by using the appropriate DHCP option in the mapping. The example below shows how to set the vm-dns DNS server for the photon host.

hostname,domainname,ip_address,static,mac_address,dhcp_option,type,comment
photon,example.net,192.168.128.19,,00:0c:29:51:80:1f,"vm-dns","Proxy server VM using docker"

Role Variables

These are the variables used in the role:

Variable	Default	Description
riv_pihole_admin_password_generated	{{ lookup('password', '/dev/null length=15 chars=ascii_letters') }}	Password for the web interface. It will be auto-generated unless specified.
riv_pihole_dns_default_tag		Sets a DHCP tag for the default DNS server for hosts not listed in the CSV file.
riv_pihole_show_summary	false	If true, shows the generated password and useful info like the IP address and the name of the Pi-hole host in the last step.
riv_pihole_docker_network	host	Network for Docker connections. Use the host network for DHCP functionality.
riv_pihole_docker_purge_networks	yes	Deletes the created network when the Docker container stops.
riv_pihole_dhcp_active	false	Enables or disables the DHCP server. Turn this on to use Pi-hole as a DHCP server.
riv_pihole_dhcp_leasetime	24h	Default lease time when assigning a client IP address.
riv_pihole_dhcp_start	192.168.1.2	Starting range of the built-in DHCP server.
riv_pihole_dhcp_end	192.168.1.253	Last IP address of the built-in DHCP server.
riv_pihole_dhcp_router	192.168.1.1	The router advertised to clients receiving an IP address.
riv_pihole_domain	example.net	Domain for your local network.
riv_pihole_interface	eth0	Network interface for Pi-hole.
riv_pihole_dhcp_ipv6	false	Enables IPv6 support on DHCP.
riv_pihole_dhcp_rapid_commit	false	Controls the rapid commit option for DHCP.
riv_pihole_dnsmasq_listening	all	Interface dnsmasq listens to.
riv_pihole_query_logging	true	Log DNS queries.
riv_pihole_install_web_server	true	Installs the built-in web server.
riv_pihole_install_web_interface	true	Installs the web interface.
riv_pihole_lighttpd_enabled		Enables lighttpd.
riv_pihole_ipv4_address	{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] | default(ansible_host) }}	The IPv4 address for Pi-hole to listen on.
riv_pihole_ipv6_address		The IPv6 address for Pi-hole to listen on.
riv_pihole_dns_bogus_priv		Controls bogus private reverse lookups.
riv_pihole_dns_fqdn_required		Controls if unqualified names are put into DNS.
riv_pihole_dnssec		Controls DNSSEC.
riv_pihole_rev_server_enabled		Enables DNS conditional forwarding for device name resolution.
riv_pihole_rev_server_cidr		If forwarding is enabled, set the reverse DNS zone (e.g. 192.168.0.0/24).
riv_pihole_rev_server_domain		If forwarding is enabled, set the local network router domain (e.g. example.net).
riv_pihole_rev_server_target		If forwarding is enabled, set the local network router's IP.
riv_pihole_docker_image	pihole/pihole:latest	Docker image to pull for Pi-hole.
riv_pihole_configuration_base_folder	/opt/pihole	Folder for Pi-hole configuration on the target host.
riv_pihole_etc_pihole_folder	{{ riv_pihole_configuration_base_folder }}/pihole	Location of Pihole folder.
riv_pihole_etc_dnsmasq_folder	{{ riv_pihole_configuration_base_folder }}/dnsmasq.d	Location of dnsmasq.d folder.
riv_pihole_sys_dns_server1	127.0.0.1	First system DNS server for Pi-hole. This must be 127.0.0.1.
riv_pihole_sys_dns_server2	8.8.8.8	Second system DNS server for Pi-hole.
riv_pihole_dns_server1	1.1.1.1	DNS Server used within Docker.
riv_pihole_dns_server2	8.8.8.8	Secondary DNS Server used within Docker.
riv_pihole_serverip	{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] | default(ansible_host) }}	The IP address of the host running Pi-hole.
riv_pihole_timezone	Europe/Berlin	Set your timezone.
riv_pihole_open_firewall_ports	true	Set to false to avoid opening the necessary firewall ports.
riv_pihole_dns_db_configuration_file	{{ role_path }}/files/mappings.csv	Path to the DNS configuration file. Edit this default file as needed.

Example Playbook

The following playbook shows how to set up Pi-hole on a Photon OS machine, as represented in the inventory file.

Folder Structure

Your folder structure should look like this (the roles folder will be created automatically):

|-- dns-db.csv
|-- inventory
|-- pihole-vm.yml
`-- roles
    `-- authsec.pihole
        |-- defaults
        |   `-- main.yml
        |-- files
        |   `-- mappings.csv
        |-- LICENSE
        |-- meta
        |   `-- main.yml
        |-- README.md
        |-- tasks
        |   |-- checkssh-photonos.yml
        |   |-- checkssh.yml
        |   |-- firewall-iptables.yml
        |   |-- install-apt.yml
        |   |-- install-photonos.yml
        |   `-- main.yml
        `-- templates
            |-- 02-pihole-dhcp.conf.j2
            |-- 10-pihole-custom-static.conf.j2
            `-- setupVars.conf.j2

Import Role

You can import the role into your project by running:

#> ansible-galaxy install -p roles authsec.pihole

Create Database

Copy the example database from roles/authsec.pihole/files into your project.

dns-db.csv:

hostname,domainname,ip_address,static,mac_address,dhcp_option,comment
,,,,,"tag:vm-dns,option:dns-server,192.168.128.253","Sets value of DHCP option"
,,,,,"tag:pi-dns,option:dns-server,192.168.128.254","Sets value of DHCP option"
slash,example.net,192.168.128.2,,,,"ESXi Host"
mohh,example.net,192.168.128.5,,,,"vCenter Server"
blib,example.net,192.168.128.18,,00:0c:29:43:37:dc,"pi-dns","VM using Raspberry Pi based DNS server"
photon,example.net,192.168.128.19,,00:0c:29:51:80:1f,"vm-dns","VM using VM based DNS server"
vmhole,example.net,192.168.128.253,true,,,"Pi-hole Virtual machine DNS server"
pihole,example.net,192.168.128.254,,,,"Raspberry Pi Pi-hole DNS and DHCP server for this network"

inventory:

[dns_vms]
vmhole.example.net ansible_host=192.168.128.253 ansible_user=pihole ansible_become_method='su' ansible_become_password='your_password' ansible_python_interpreter=/usr/bin/python3

pihole-vm.yml:

---
# Configure a machine to run Pi-hole in a docker container
- hosts: dns_vms
  gather_facts: yes
  become: yes
  tasks: 
    - include_role: 
        name: authsec.pihole
      vars:
        riv_pihole_admin_password: "secure_password"
        riv_pihole_dhcp_active: "false"
        riv_pihole_dhcp_start: "192.168.128.8"
        riv_pihole_dhcp_end: "192.168.128.252"
        riv_pihole_dhcp_router: "192.168.128.1"
        riv_pihole_domain: "example.net"
        riv_pihole_show_summary: true
        riv_pihole_dns_db_configuration_file: "dns-db.csv"

Run Ansible

After configuration, run ansible to set up Pi-hole on the system in inventory.

#> ansible-playbook -i inventory pihole-vm.yml

License

MIT