Pi-Hole
Block nefarious websites & Ads.
Ansible Role: pihole
Clients will send DNS requets to Pi-Hole. Pi-Hole will either block, resolve or foward those requests to the router. The router will be able to resolve local DNS names and forward remaining unknown queries to upstream DNS servers.
Optionally, if the router supports destination NAT, all DNS traffic will be routed directly to Pi-Hole. This catches hard-coded DNS servers that many phone apps, IoT devices, and applications use.
# Pi-Hole
Pi-Hole installation from public release.
## Requirements
Pi-Hole hosts should be configured with static IP's per Pi-Hole documentation.
## Role Variables
Settings have been throughly documented for usage.
[defaults/main.yml](https://github.com/r-pufky/ansible_pihole/blob/main/defaults/main/main.yml).
### Ports
All ports and protocols have been defined for the role.
Hosts should only define firewall rules for ports they need.
[defaults/ports.yml](https://github.com/r-pufky/ansible_pihole/blob/main/defaults/main/ports.yml).
## Dependencies
N/A
## Example Playbook
For multiple Pi-Hole nodes apply configuration in group_vars and node specific
settings in host_vars. Singleton instances can be applied in host_vars.
group_vars/pihole/vars/pihole.yml
``` yaml
pihole_webpassword: '{{ vault_pihole_webpassword }}'
pihole_api_key: '{{ vault_pihole_api_key }}'
pihole_ad_sources:
- 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
``` yaml
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
``` yaml
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
``` yaml
- name: 'pihole servers'
hosts: 'pihole'
become: true
roles:
- 'r_pufky.pihole'
```
## Issues
Create a bug and provide as much information as possible.
Associate pull requests with a submitted bug.
## License
[AGPL-3.0 License](https://github.com/r-pufky/ansible_pihole/blob/main/LICENSE)
## Author Information
https://keybase.io/rpufky
BLOCKING OS Distribution upgrades REQUIRE: git/php source; confirm php dependency changes.
Role Details: Updated: 2022-10-08 galaxy source service docs
Ports
---
###############################################################################
# Ports Configuration
###############################################################################
# Ports should be managed externally via an OS role.
#
# Reference:
# * https://docs.pi-hole.net/main/prerequisites/?h=port#ports
# * https://docs.ansible.com/ansible/latest/collections/community/general/ufw_module.html
ports:
- {proto: 'udp', from_ip: 'any', to_port: 53, direction: 'in', comment: 'dns server'}
- {proto: 'udp', from_ip: 'any', to_port: 67, direction: 'in', comment: 'dhcp ipv4 server'}
- {proto: 'udp', from_ip: 'any', to_port: 547, direction: 'in', comment: 'dhcp ipv6 server'}
- {proto: 'tcp', from_ip: 'any', to_port: 53, direction: 'in', comment: 'dns server'}
- {proto: 'tcp', from_ip: 'any', to_port: 80, direction: 'in', comment: 'webui'}
- {proto: 'tcp', from_ip: '127.0.0.1', to_ip: '127.0.0.1', to_port: 4711, direction: 'in', comment: 'ftl service (localhost only)'}
Note
FTL API should not be acessible from any other interface.
Defaults
---
###############################################################################
# Pi-Hole Role Configuration
###############################################################################
# DB configuration is optional. DB updates are applied then gravity update is
# run to ensure database ID's are consistent. Apply before UI changes are made
# to ensure consistency.
#
# Exact configuration state may be exported/imported with teleporter. this
# provides a pre-configured deployement for Pi-Hole service.
#
# Configuration contains basic setup and domain blocking lists. Lists can be
# set via Group Management -> Adlists; and updated via Tools -> Update Gravity.
#
# If running multiple instances; be sure changes are applied to both.
# Target location of backup file on ansible host.
pihole_local_backup: 'group_vars/pihole/data/pihole-teleporter.tar.gz'
# Use pi-hole CLI for all possible DB modifications instead of direct edits.
# Default: False.
pihole_use_cli: false
# Apply any pihole updates during configuration? Otherwise updates must be done
# via the GUI or CLI. Default: False.
pihole_update_enable: false
###############################################################################
# Pi-Hole setupVars.conf
###############################################################################
# Pihole reads True/False as STRINGS; use strings or install will fail.
pihole_blocking_enabled: 'true'
pihole_admin_email: ''
pihole_webui_boxed_layout: 'boxed'
pihole_webtheme: 'default-dark'
# A random password will be set if empty.
pihole_webpassword: ''
pihole_dnsmasq_listening: 'single'
pihole_dns_fqdn_required: 'false'
pihole_dns_bogus_priv: 'false'
pihole_dnssec: 'false'
pihole_rev_server: 'false'
pihole_pihole_interface: '{{ ansible_default_ipv4.interface }}'
pihole_ipv4_address: "{{ (ansible_default_ipv4.address + '/' + ansible_default_ipv4.netmask) | ansible.utils.ipaddr('address/prefix') }}"
pihole_ipv6_address: ''
pihole_dhcp_active: 'false'
pihole_dhcp_start: "{{ (ansible_default_ipv4.address + '/' + ansible_default_ipv4.netmask) | ansible.utils.nthhost(200) }}"
pihole_dhcp_end: "{{ (ansible_default_ipv4.address + '/' + ansible_default_ipv4.netmask) | ansible.utils.nthhost(-5) }}"
pihole_dhcp_router: '{{ ansible_default_ipv4.gateway }}'
pihole_dhcp_leasetime: '24'
pihole_pihole_domain: 'lan'
pihole_dhcp_ipv6: 'false'
pihole_dhcp_rapid_commit: 'false'
pihole_pihole_dns_1: "{{ ansible_dns.nameservers | ansible.utils.ipv4() | first | default('1.1.1.1') }}#53"
pihole_pihole_dns_2: ''
pihole_query_logging: 'true'
pihole_install_web_server: 'true'
pihole_install_web_interface: 'true'
pihole_lighttpd_enabled: 'true'
pihole_cache_size: '10000'
###############################################################################
# Pi-Hole Adlist Table
###############################################################################
# Define Adlist sources for generating domain blocklists.
#
# Pi-Hole currently adds the stevenblack adlist when installing, as ID 1.
# https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
#
# pihole_ad_sources:
# - id: int (unique id starting at 2)
# address: str (URL for adlist)
# enabled: bool (enable use)
# comment: str (user comment)
#
# Reference:
# * https://docs.pi-hole.net/database/gravity/#adlist-table-adlist
pihole_ad_sources: []
###############################################################################
# Pi-Hole Domain Blocklist Table
###############################################################################
# Define domain blocking behavior (whitelist, blacklist).
#
# pihole_domain_blocklists:
# - id: int (unique id starting at 1)
# type: int (0 = exact whitelist,
# 1 = exact blacklist,
# 2 = regex whitelist,
# 3 = regex blacklist)
# domain: str (domain)
# enabled: bool (enable use)
# comment: str (user comment)
#
# Reference:
# * https://docs.pi-hole.net/database/gravity/#domain-tables-domainlist
pihole_domain_blocklists: []
###############################################################################
# Pi-Hole Clients Table
###############################################################################
# Define Pi-Hole clients.
#
# pihole_clients:
# - id: int (unique id starting at 1)
# ip: str (IPv4,IPv6,CIDR)
# comment: str (user comment)
#
# Reference:
# * https://docs.pi-hole.net/database/gravity/#client-table-client
pihole_clients: []
###############################################################################
# Pi-Hole Groups Table
###############################################################################
# Define Pi-Hole group management.
#
# pihole_groups:
# - id: int (unique id starting at 1)
# enabled: bool (enable use)
# name: str (group name)
# description: str (description)
#
# Reference:
# * https://docs.pi-hole.net/database/gravity/groups/#group-management
pihole_groups: []
###############################################################################
# Pi-Hole Groups Adlist Table
###############################################################################
# Define Pi-Hole group adlist management.
#
# pihole_ad_groups_blocklist:
# - adlist_id: int (existing adlist ID)
# group_id: int (existing group ID)
#
# Reference:
# * https://docs.pi-hole.net/database/gravity/groups/
pihole_ad_groups_blocklist: []
###############################################################################
# Pi-Hole Groups Clients Table
###############################################################################
# Define Pi-Hole group clients management.
#
# pihole_ad_groups_blocklist:
# - client_id: int (existing client ID)
# group_id: int (existing group ID)
#
# Reference:
# * https://docs.pi-hole.net/database/gravity/groups/
pihole_client_groups_blocklist: []
###############################################################################
# Pi-Hole Groups Domain Blocklists Table
###############################################################################
# Define Pi-Hole group domain blocklists management.
#
# pihole_ad_groups_blocklist:
# - domainlist_id: int (existing domain blocklist ID)
# group_id: int (existing group ID)
#
# Reference:
# * https://docs.pi-hole.net/database/gravity/groups/
pihole_domain_groups_blocklist: []