Pi-Hole

Guide for installing Pi-Hole from the official release.

Requirements

Make sure your Pi-Hole devices have a static IP address, as per the Pi-Hole guide.

Support for RedHat systems is experimental and may not work perfectly.

Role Variables

Settings are clearly explained and can be found in these files:

• defaults/main.yml
• defaults/blocklist.yml
• defaults/ftl.yml

Ports

All necessary ports and protocols are defined.

Only set up firewall rules for the ports you actually need.

• defaults/ports.yml

For RedHat installations, a pihole zone will be created in firewalld to allow traffic.

Dependencies

None

Example Playbook

For multiple Pi-Hole devices, put common settings in group_vars and specific settings in host_vars. Use host_vars for single instances.

group_vars/pihole/vars/pihole.yml

pihole_webpassword: '{{ vault_pihole_webpassword }}'

pihole_ad_sources:
  - id: 1
    address: 'https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts'
    enabled: true
    comment: 'Migrated from /etc/pihole/adlists.list'
  - id: 2
    address: 'https://adaway.org/hosts.txt'
    enabled: true
    comment: 'ansible adlist'
  - id: 3
    address: 'https://bitbucket.org/ethanr/dns-blacklists/raw/8575c9f96e5b4a1308f2f12394abd86d0927a4a0/bad_lists/Mandiant_APT1_Report_Appendix_D.txt'
    enabled: true
    comment: 'ansible adlist'

pihole_domain_blocklists:
  - id: 1
    type: 1
    domain: 'choice.microsoft.com'
    enabled: true
    comment: 'ansible blacklist'
  - id: 2
    type: 1
    domain: 'events.gfe.nvidia.com'
    enabled: true
    comment: 'ansible blacklist'

host_vars/pihole.example.com/vars/pihole.yml

pihole_pihole_interface: 'eth0'
pihole_ipv4_address:     '10.9.9.2/24'
pihole_ipv6_address:     ''
pihole_pihole_dns_1:     '10.9.9.1#53'
pihole_pihole_dns_2:     ''

host_vars/pihole2.example.com/vars/pihole.yml

pihole_pihole_interface: 'eth0'
pihole_ipv4_address:     '10.9.9.3/24'
pihole_ipv6_address:     ''
pihole_pihole_dns_1:     '10.9.9.1#53'
pihole_pihole_dns_2:     ''

site.yml

- name: 'pihole servers'
  hosts: 'pihole'
  become: true
  roles:
    - 'r_pufky.pihole'

When configuring multiple Pi-Hole servers, it's recommended to use serial: 1. This allows one at a time changes to be made without disrupting the DNS service.

Versions

3.x: FTL Configuration Support

• Added FTL-DNS configuration support.
• Added a toggle for operations.
• Standardized setup variables to use YAML types (no changes needed).
• Managed default adlist.
• Documented previously undocumented options in 'setupvars.conf'.

If you've set custom FTL configurations, ensure they are in *_vars before applying this version. See:

defaults/ftl.yml.

2.x: RedHat Support

• Added support for RedHat, which is experimental only.
• Added conditional forwarding configuration support.
• Included reference for ports.yml usage.

1.x: Initial Release

• Supported updating the Pi-Hole installation.
• Added DHCP configuration and domain list management via CLI.
• Allowed check_mode operation.
• Reconfigured Pi-Hole on changes instead of needing a restart.
• Managed domain whitelist/blacklist via the CLI.

Issues

If you find a bug, please report it with detailed information.

Link pull requests to the reported bug.

RedHat support is best-effort only and should be assigned to @rkoosaar.

License

AGPL-3.0 License

Author Information

https://keybase.io/rpufky