Migrate from private repository.

.ansible-lint

@@ -0,0 +1,3 @@
+skip_list:
+  - unnamed-task   # unnamed tasks are used as includes.
+  - package-latest # allow 'latest' packages.

.yamllint

@@ -0,0 +1,6 @@
+rules:
+  commas:
+    max-spaces-after: -1 # enable vertical alignment of config.
+  colons:
+    max-spaces-after: -1 # enable vertical alignment of config.
+  line-length: disable   # references, vertical alignment.

README.md

@@ -0,0 +1,90 @@
+# 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

defaults/main/main.yml

@@ -0,0 +1,157 @@
+---
+###############################################################################
+# 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'
+
+###############################################################################
+# 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:      '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:          ''
+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: []

defaults/main/ports.yml

@@ -0,0 +1,17 @@
+---
+###############################################################################
+# 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)'}

handlers/main.yml

@@ -0,0 +1,9 @@
+---
+###############################################################################
+# Pi-Hole Handlers
+###############################################################################
+
+# pihole restartdns restarts all required pihole services.
+# Reference: https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738
+- name: 'restart pihole dns'
+  ansible.builtin.command: 'pihole restartdns'

meta/main.yml

@@ -0,0 +1,20 @@
+---
+galaxy_info:
+  role_name:   'pihole'
+  author:      'r_pufky'
+  description: 'Pi-Hole'
+  company:     'N/A'
+  license:     'AGPL-3.0 License'
+  min_ansible_version: 2.11
+
+  platforms:
+    - name: 'Debian'
+      versions:
+        - 'buster'
+        - 'bullseye'
+
+  galaxy_tags:
+    - 'pihole'
+    - 'dns'
+
+dependencies: []

tasks/backup.yml

@@ -0,0 +1,39 @@
+---
+###############################################################################
+# Pi-Hole Backup
+###############################################################################
+# Use teleporter to create a configuration backup.
+#
+# Reference:
+# * https://docs.pi-hole.net/core/pihole-command/#teleport
+
+# Teleporter dump created with execution timestamp. backup & standardize.
+- name: 'backup | create backup' # noqa no-changed-when always execute
+  ansible.builtin.shell: |
+    cd /root &&
+    pihole -a -t &&
+    find /root -type f -name 'pi-hole-*.tar.gz' -exec mv {} /root/pihole.tar.gz \;
+  args:
+    warn: false
+
+- name: 'backup | retrieve backup'
+  ansible.builtin.fetch:
+    src:  '/root/pihole.tar.gz'
+    dest: '{{ pihole_local_backup }}'
+    flat: true
+
+- name: 'backup | ENCRYPTION NOTICE'
+  ansible.builtin.debug:
+    msg: |
+
+      BE SURE TO ENCRYPT BEFORE COMMITING CHANGES.
+
+      ansible-vault encrypt '{{ pihole_local_backup }}'
+
+- name: 'backup | cleanup'
+  ansible.builtin.file:
+    path:  '{{ item }}'
+    state: 'absent'
+  loop:
+    - '/root/pihole.tar.gz'
+    - '/root/pi-hole-*.tar.gz'