ansible-pi-hole

Ansible role to install Pi-Hole.

Role Configuration

• pi_hole_repo (default: "https://github.com/pi-hole/pi-hole.git") - Specify the Pi-Hole repository.
• pi_hole_prerequisites (default: "git") - Specify the necessary tools for Pi-Hole.

Pi-Hole Configuration

You can add the pi-hole variables for configuration. These can be left out if not needed.

• pi_hole_version (default: "HEAD") - Specify the branch/tag/commit of the Pi-Hole repository to clone.
• pi_hole_download_dir (default: "/home/pihole") - Base directory for Pi-Hole files.
• pi_hole_install_dir (default: "pi-hole") - Directory where Pi-Hole will be cloned.
• pi_hole_query_logging (default: true) - Choose if Pi-Hole will log queries.
• pi_hole_install_web_server (default: true) - Choose if to install the Pi-Hole web server.
• pi_hole_install_web_interface (default: true) - Choose if to install the Pi-Hole web interface.
• pi_hole_enable_lighttpd (default: true) - Turn on lighttpd server.
• pi_hole_webpasswd (default: omit) - Set the password for the Pi-Hole web interface; if omitted, one will be generated.
• pi_hole_dnsmasq_listening (default: "single") -
• pi_hole_dns_1 (default: "8.8.8.8") - First upstream DNS server for Pi-Hole.
• pi_hole_dns_1_port (default: "53") - Port for the first DNS server.
• pi_hole_dns_2 (default: "8.8.4.4") - Second upstream DNS server.
• pi_hole_dns_2_port (default: "53") - Port for the second DNS server.
• pi_hole_fqdn_required (default: false) - Specifies if full domain names (FQDN) are required.
• pi_hole_bogus_priv (default: false) - Choose if Pi-Hole answers queries incorrectly on a private network.
• pi_hole_dnssec (default: false) - Enable DNSSEC in Pi-Hole.
• pi_hole_rev_server (default: true) - Decide if Pi-Hole will respond to reverse queries.
• pi_hole_rev_server_domain (default: "") - Set the domain name for reverse lookups.
• pi_hole_rev_server_target (default: "") - Define the target for reverse lookups.
• pi_hole_rev_server_cidr (default: "") - Set the CIDR for reverse lookups.
• pi_hole_blocking_enabled (default: true) - Enable blocking of unwanted content.

Pi-Hole DHCP Configuration

• pi_hole_dhcp_active (default: false) - Enable the DHCP server in Pi-Hole.
• pi_hole_dhcp_start (default: "") - Starting IP address for DHCP assignment.
• pi_hole_dhcp_end (default: "") - Last IP address for DHCP assignment.
• pi_hole_dhcp_router (default: "") - Gateway IP address.
• pi_hole_dhcp_leasetime (default: "24") - DHCP lease duration in hours.
• pi_hole_domain (default: "lan") - Domain name for Pi-Hole.
• pi_hole_dhcp_ipv6 (default: false) - Enable DHCP for IPv6.
• pi_hole_dhcp_rapid_commit (default: false) - Enable rapid commit for DHCP v4.

Pi-Hole Local DNS Configuration

• pi_hole_local_dns_records (default: "") - Set local DNS records for Pi-Hole. Provide a list of dictionaries with ip and name.

Example:

vars:
  pi_hole_local_dns_records:
    - name: db.lan
      ip: 10.0.13.37
    - name: web.lan
      ip: 10.0.13.38

Pi-Hole FTL Configuration

You can add pi-hole-FTL variables for configuration, which can also be omitted.

• pi_hole_ftl_blockingmode (default: "NULL") - How FTL should respond to blocked queries.
• pi_hole_ftl_cname_deep_inspect (default: true) - Disable deep CNAME inspection if required for low-end devices.
• pi_hole_ftl_block_esni (default: true) - Option to enhance privacy by encrypting certain data.
• pi_hole_ftl_maxlogage (default: "24.0") - Duration for query data imports from the database and logs.
• pi_hole_ftl_privacylevel (default: "0") - Set privacy level.
• pi_hole_ftl_ignore_localhost (default: "no") - Whether to ignore local machine queries.
• pi_hole_ftl_query_analysis (default: "yes") - Analyze AAAA queries.
• pi_hole_ftl_analyze_only_a_and_aaaa (default: false) - Analyze only A and AAAA queries.
• pi_hole_ftl_socket_listening (default: "localonly") - Specify if to allow only local connections.
• pi_hole_ftl_port (default: "4711") - Port for FTL to listen on.
• pi_hole_ftl_resolve_ipv6 (default: "yes") - Enable resolution for IPv6 addresses to hostnames.
• pi_hole_ftl_resolve_ipv4 (default: "yes") - Enable resolution for IPv4 addresses to hostnames.
• pi_hole_ftl_delay_startup (default: "0") - Time to wait before starting the DNS resolver if needed.
• pi_hole_ftl_nice (default: "-10") - Adjust process priority for FTL.
• pi_hole_ftl_names_from_netdb (default: true) - Get client names from the network table.
• pi_hole_refresh_hostnames (default: "IPV4") - Control how client hostname checks are made hourly.
• pi_hole_ftl_dbimport (default: "true") - Should recent history be loaded from the database on startup?
• pi_hole_ftl_maxdbdays (default: "365") - Specify how long to store queries in the database.
• pi_hole_ftl_dbinterval (default: "1.0") - Define how often to save queries in FTL’s database (in minutes).
• pi_hole_ftl_dbfile (default: "/etc/pihole/pihole-FTL.db") - Path for FTL's SQLite database file.
• pi_hole_ftl_logfile (default: "/var/log/pihole-FTL.log") - Location for FTL’s log file.
• pi_hole_ftl_pidfile (default: "/run/pihole-FTL.pid") - File containing the PID of FTL's main process.
• pi_hole_ftl_portfile (default: "/run/pihole-FTL.port") - File with the port FTL's API is listening on.
• pi_hole_ftl_socket_file (default: "/run/pihole/FTL.sock") - File for the socket FTL's API listens on.
• pi_hole_ftl_setupvarsfile (default: "/etc/pihole/setupVars.conf") - FTL configuration file containing the current blocking status.
• pi_hole_ftl_macvendordb (default: "/etc/pihole/macvendor.db") - Database for mapping MAC addresses to vendors.
• pi_hole_ftl_gravitydb (default: "/etc/pihole/gravity.db") - Database for domains used by Pi-Hole.
• pi_hole_ftl_debug_all (default: false) - Enable all debug flags.
• pi_hole_ftl_debug_database (default: false) - Show debug info about database actions.
• pi_hole_ftl_debug_networking (default: false) - Print detected interfaces on startup.
• pi_hole_ftl_debug_locks (default: false) - Information about memory locks.
• pi_hole_ftl_debug_queries (default: false) - Detailed query information.
• pi_hole_ftl_debug_flags (default: false) - Show flags of queries received.
• pi_hole_ftl_debug_shmem (default: false) - Information about shared memory buffers.
• pi_hole_ftl_debug_gc (default: false) - Info about garbage collection.
• pi_hole_ftl_debug_arp (default: false) - Info about ARP table processing.
• pi_hole_ftl_debug_regex (default: false) - Enable extended details about regex matching.
• pi_hole_ftl_debug_api (default: false) - Extra info during API calls.
• pi_hole_ftl_debug_overtime (default: false) - Info about overTime memory operations.
• pi_hole_ftl_debug_extbloqued (default: false) - Info on why certain queries are marked as blocked.
• pi_hole_ftl_debug_caps (default: false) - Info about the capabilities of pihole-FTL.
• pi_hole_ftl_debug_dnsmasq_lines (default: false) - Show the line causing a dnsmasq event.
• pi_hole_ftl_debug_vectors (default: false) - Detailed info about dynamic memory allocations.
• pi_hole_ftl_debug_resolver (default: false) - Info about hostname resolution.
• pi_hole_ftl_rate_limit (default: "1000/60") - Block clients making too many queries in a given time. Disable by setting both values to zero.