Pihole

Pi-hole role. This will install Pi-hole®: A black hole for Internet advertisements – A black hole for Internet advertisements for you.

It also helps you administering Pi-Hole using a simple CSV file that you can edit with your favourite editor.

Requirements

A host running Ubuntu/Debian/Photon OS or e.g. a raspberry pi running Raspberry Pi OS (Lite).

If you run into problems, a look into the Pi-hole documentation may help.

Host CSV File

Pi-hole configuration is done via a csv file. This gives you a nice overview and makes it easy to manage your environment.

The role includes a full example CSV file in the files folder for you to review.

The following lines do show dhcp-option settings that will be written into the dnsmasq configuration file. The lines tag one IP address as the vm based DNS server and the raspberry pi based DNS server running on an actual raspberry pi.

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>>","Sets value of dhcp-option configuration option, here which DNS server to use"
,,,,,"tag:pi-dns,option:dns-server,192.168.30.254","<<tag>>","Sets value of dhcp-option configuration option, here which DNS server to use"

Note: If you are setting up multiple DNS servers here, you probably do want to set the riv_pihole_dns_default_tag option when configuring your setup to set a default DNS server for clients without a specific configuration.

Setup IP/Host mapping

The configuration below configures the host with the name slash to receive an IP address of 192.168.128.2 if that address is still available. If a DHCP lease was already handed out to another machine, a new IP address will be assigned. It also identifies the machine as a physical host.

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

If you want to make sure that the IP address is assigned to a specific hostname only, you can set the static field to true to achieve that. Setting this option will instruct dnsmasq to ignore DHCP requests from any host named vmhole as shown in the example below. The type is also identified as a virtual machine.

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 assign a specific IP address and hostname to a special device using the mac address of the device, use the following entry in the csv configuration database.

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

Setting up a special DNS server for some devices can be achieved by supplying the appropriate DHCP option when defining the mapping. The below example 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","<<virtual>>","Proxy server VM based on a docker image, using vm-dns server"

Role Variables

The role uses the following variables:

Variable	Default	Description
riv_pihole_admin_password_generated	{{ lookup('password', '/dev/null length=15 chars=ascii_letters') }}	This variable sets the password for the web user interface. If no password is set, it will be auto-generated. The password value is shown in plain text in the last step if the variable riv_pihole_show_summary is set to true.
riv_pihole_dns_default_tag		This variable sets a DHCP tag that lets you specify a default DNS server for hosts not listed in the configuration csv file.
riv_pihole_show_summary	false	If set true the last step will show the (generated) password in plain text along with some useful information like the IP address and name of the host pihole was installed on.
riv_pihole_docker_network	host	The network to which docker connects. If you want to use DHCP, you need to connect to the host network.
riv_pihole_docker_purge_networks	yes	Remove the created network when the docker container is shut down.
riv_pihole_dhcp_active	false	Enable or disable the built-in DHCP server. If you want to use Pi-hole as DHCP server, you need to turn this on.
riv_pihole_dhcp_leasetime	24h	The default lease time to set when handing out a client IP address
riv_pihole_dhcp_start	192.168.1.2	The starting range of the built-in DHCP server.
riv_pihole_dhcp_end	192.168.1.253	The last address of the built-in DHCP server.
riv_pihole_dhcp_router	192.168.1.1	The router which should be advertised to clients getting an IP address.
riv_pihole_domain	example.net	The domain of your local network.
riv_pihole_interface	eth0	The interface processes inside Pi-hole will bind to
riv_pihole_dhcp_ipv6	false	Enable IPv6 support on DHCP.
riv_pihole_dhcp_rapid_commit	false	Control switch for the rapid commit option.
riv_pihole_dnsmasq_listening	all	The interface dnsmasq should listen on.
riv_pihole_query_logging	true	Log DNS queries.
riv_pihole_install_web_server	true	Install the built in Web-Server
riv_pihole_install_web_interface	true	Install the Web-Interface.
riv_pihole_lighttpd_enabled		Enable lighttpd
riv_pihole_ipv4_address	{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] | default(ansible_host) }}	The IPv4 address you want Pi-Hole to listen on.
riv_pihole_ipv6_address		The IPv6 address you want Pi-Hole to listen on.
riv_pihole_dns_bogus_priv		Control bogus private reverse lookups
riv_pihole_dns_fqdn_required		Controls if the unqualified name is put into DNS as well
riv_pihole_dnssec		Control DNSSEC
riv_pihole_rev_server_enabled		Enable DNS conditional forwarding for device name resolution.
riv_pihole_rev_server_cidr		If conditional forwarding is enabled, set the reverse DNS zone (e.g. 192.168.0.0/24)
riv_pihole_rev_server_domain		If conditional forwarding is enabled, set the domain of the local network router (e.g example.net).
riv_pihole_rev_server_target		If conditional forwarding is enabled, set the IP of the local network router.
riv_pihole_docker_image	pihole/pihole:latest	Which docker image to pull. You can e.g. specify a version.
riv_pihole_configuration_base_folder	/opt/pihole	Where do you want your configuration to live on the target host.
riv_pihole_etc_pihole_folder	{{ riv_pihole_configuration_base_folder }}/pihole	Control position of pihole folder.
riv_pihole_etc_dnsmasq_folder	{{ riv_pihole_configuration_base_folder }}/dnsmasq.d	Control position of dnsmasq.d folder.
riv_pihole_sys_dns_server1	127.0.0.1	System DNS servers for Pi-hole. The first one HAS TO BE 127.0.0.1
riv_pihole_sys_dns_server2	8.8.8.8	System DNS server for Pi-hole
riv_pihole_dns_server1	1.1.1.1	DNS Server used inside the docker container
riv_pihole_dns_server2	8.8.8.8	DNS Server used inside the docker container
riv_pihole_serverip	{{ hostvars[inventory_hostname]['ansible_default_ipv4']['address'] | default(ansible_host) }}	The IP address of the Pi-hole host
riv_pihole_timezone	Europe/Berlin	Your timezone
riv_pihole_open_firewall_ports	true	Set to false if you don't want the role to open required firewall ports.
riv_pihole_dns_db_configuration_file	{{ role_path }}/files/mappings.csv	The location of the DNS configuration file. The default file pointed to should be copied and adopted appropriately.

Example Playbook

The example below shows a playbook you can use to configure pi-hole on a Photon OS based virtual machine which is reflected in the inventory file.

Folder structure

The folder structure is as follows (the roles folder will be created automatically later):

|-- 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 using:

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

Create database

This is a copy of the example database in roles/authsec.pihole/files.

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 configuration option"
,,,,,"tag:pi-dns,option:dns-server,192.168.128.254","Sets value of dhcp-option configuration option"
slash,example.net,192.168.128.2,,,,"ESXi Host"
mohh,example.net,192.168.128.5,,,,"The Brain (vCenter Server)"
blib,example.net,192.168.128.18,,00:0c:29:43:37:dc,"pi-dns","VM using Raspberry Pi based DNS (and DHCP) 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 backed Pi-Hole DNS and DHCP server for this network, docker based and ansible managed"

inventory:

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

pihole-vm.yml:

---
# Configure a machine to run pi-hole inside a docker container
- hosts: dns_vms
  gather_facts: yes
  become: yes
  tasks: 
    - include_role: 
        name: authsec.pihole
      vars:
        # true|false
        riv_pihole_admin_password: "secure.me"
        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

Once everything is configured, you can run ansible to setup pi-hole on the system configured in the inventory.

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

License

MIT