ansible-pi-hole

一个用于安装 Pi-Hole 的 ansible 角色

角色配置

• pi_hole_repo（默认值："https://github.com/pi-hole/pi-hole.git"） - 定义 pi-hole 库
• pi_hole_prerequisites（默认值："git"） - 定义 pi-hole 必要条件

定义 pi-hole 配置

添加 pi-hole 变量进行配置。这些变量可以省略

• pi_hole_version - （默认值："HEAD"） - 定义将要克隆的 pi-hole 库的分支/标签/提交
• pi_hole_download_dir - （默认值："/home/pihole"） - 定义pi-hole克隆的基础目录
• pi_hole_install_dir - （默认值："pi-hole"） - 定义克隆pi-hole的目录
• pi_hole_query_logging - （默认值：true） - 定义 pi-hole 是否记录查询
• pi_hole_install_web_server - （默认值：true） - 定义是否需要安装 pi-hole 网络服务器
• pi_hole_install_web_interface - （默认值：true） - 定义是否需要安装 pi-hole 网络界面
• pi_hole_enable_lighttpd - （默认值：true） - lighttpd 是否需要启用
• pi_hole_webpasswd - （默认值：省略） - 定义 pi-hole 网络密码，如果省略将生成一个
• pi_hole_dnsmasq_listening - （默认值："single"） -
• pi_hole_dns_1 - （默认值："8.8.8.8"） - pi-hole 上游 DNS 服务器
• pi_hole_dns_1_port - （默认值："53"） - pi-hole 上游 DNS 服务器端口
• pi_hole_dns_2 - （默认值："8.8.4.4"） - pi-hole 上游 DNS 服务器
• pi_hole_dns_1_port - （默认值："53"） - pi-hole 上游 DNS 服务器端口
• pi_hole_fqdn_required - （默认值：false） - pi-hole 是否需要 fqdn 查询
• pi_hole_bogus_priv - （默认值：false） - pi-hole 是否在私有区域进行虚假响应
• pi_hole_dnssec - （默认值：false） - pi-hole 是否使用 dnssec
• pi_hole_rev_server - （默认值：true） - pi-hole 是否回答反向查询
• pi_hole_rev_server_domain - （默认值：""） - pi-hole 反向域名
• pi_hole_rev_server_target - （默认值：""） - pi-hole 反向服务器目标
• pi_hole_rev_server_cidr - （默认值：""） - pi-hole 反向 CIDR
• pi_hole_blocking_enabled - （默认值：true） - 启用 pi-hole 阻止功能

定义 pi-hole DHCP 配置

• pi_hole_dhcp_active - （默认值：false） - 启用 pi-hole DHCP 服务器
• pi_hole_dhcp_start - （默认值：""） - 开始分配的第一个 IP 地址
• pi_hole_dhcp_end - （默认值：""） - 开始分配的最后一个 IP 地址
• pi_hole_dhcp_router - （默认值：""） - 网关 IP 地址
• pi_hole_dhcp_leasetime - （默认值："24"） - DHCP 租约时间
• pi_hole_domain - （默认值："lan"） - pi-hole 域名
• pi_hole_dhcp_ipv6 - （默认值：false） - 启用 IPv6 支持
• pi_hole_dhcp_rapid_commit - （默认值：false） - 启用 DHCP v4 快速提交

定义 pi-hole 本地 DNS 配置

• pi_hole_local_dns_records - （默认值：""） - 定义 pi-hole 本地 DNS 记录。需要一个字典列表，每个条目包含 ip 和 name 键。

示例：

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 配置

添加 pi-hole-FTL 变量进行配置。这些变量可以省略

• pi_hole_ftl_blockingmode - （默认值："NULL"） - FTL 应如何回复被阻止的查询？
• pi_hole_ftl_cname_deep_inspect - （默认值：true） - 使用此选项禁用深度 CNAME 检查。对于非常低端的设备可能会有好处
• pi_hole_ftl_block_esni - （默认值：true） - 加密服务器名称指示（ESNI）无疑是增强网络隐私的一步。它通过加密 TLS 服务器名称指示（SNI）扩展，防止路径观察者（包括 ISP、咖啡店老板和防火墙）截取 SNI。这防止 SNI 被用来判断用户正在访问哪些网站。
• pi_hole_ftl_maxlogage - （默认值："24.0"） - 最多应从数据库和日志中导入多少小时的查询？
• pi_hole_ftl_privacylevel - （默认值："0"） - 使用哪个隐私级别？
• pi_hole_ftl_ignore_localhost - （默认值："no"） - FTL 是否应忽略来自本地机器的查询？
• pi_hole_ftl_query_analysis - （默认值："yes"） - FTL 是否应分析 AAAA 查询？DNS 服务器会按照相同方式处理 AAAA 查询，无论此设置如何。此选项仅在计算 Pi-hole 的统计数据时忽略 AAAA 查询。此设置被认为是过时的，可能在未来版本中被移除。
• pi_hole_ftl_analyze_only_a_and_aaaa - （默认值：false） - FTL 是否只分析 A 和 AAAA 查询？
• pi_hole_ftl_socket_listening - （默认值："localonly"） - 仅监听本地套接字连接或允许所有连接
• pi_hole_ftl_port - （默认值："4711"） - FTL 应监听哪个端口？
• pi_hole_ftl_resolve_ipv6 - （默认值："yes"） - FTL 是否应尝试将 IPv6 地址解析为主机名？
• pi_hole_ftl_resolve_ipv4 - （默认值："yes"） - FTL 是否应尝试将 IPv4 地址解析为主机名？
• pi_hole_ftl_delay_startup - （默认值："0"） - 在某些配置中，您可能希望 FTL 在尝试启动 DNS 解析器之前等待一定时间。通常在网络接口出现较晚时发现，并且接口启动优先级配置不正确。此设置接受 0 到 300 秒之间的任何整数值
• pi_hole_ftl_nice - （默认值："-10"） - 可用于改变 Pi-hole FTL 的优先权。默认值为 -10，可以通过设置为 -999 完全禁用。
• pi_hole_ftl_names_from_netdb - （默认值：true） - 控制 FTL 是否应使用回退选项尝试通过检查网络表获得客户端名称。此行为可以通过此选项禁用
• pi_hole_refresh_hostnames - （默认值："IPV4"） - 使用此选项，您可以更改每小时 PTR 请求如何（以及是否）检查客户端和上游服务器主机名的变化
• pi_hole_ftl_dbimport - （默认值："true"） - FTL 是否应在启动时从数据库加载信息，以了解最新的历史记录？
• pi_hole_ftl_maxdbdays - （默认值："365"） - 查询应在数据库中存储多长时间？将此值设置为 0 将禁用数据库
• pi_hole_ftl_dbinterval - （默认值："1.0"） - 我们多久存储一次查询到 FTL 的数据库 [分钟]？
• pi_hole_ftl_dbfile - （默认值："/etc/pihole/pihole-FTL.db"） - 指定 FTL 的 SQLite3 长期数据库的路径和文件名。将此设置为 DBFILE=将完全禁用数据库
• pi_hole_ftl_logfile - （默认值："/var/log/pihole-FTL.log"） - FTL 日志文件的位置。如果您要将日志文件移动到另一个地方
• pi_hole_ftl_pidfile - （默认值："/run/pihole-FTL.pid"） - 包含 FTL 主进程 PID 的文件。
• pi_hole_ftl_portfile - （默认值："/run/pihole-FTL.port"） - 包含 FTL API 监听的端口的文件。
• pi_hole_ftl_socket_file - （默认值："/run/pihole/FTL.sock"） - 包含 FTL API 监听的套接字的文件。
• pi_hole_ftl_setupvarsfile - （默认值："/etc/pihole/setupVars.conf"） - Pi-hole 的配置文件，包含当前的阻止状态（请勿更改）。
• pi_hole_ftl_macvendordb - （默认值："/etc/pihole/macvendor.db"） - 包含 MAC -> 供应商信息的网络表数据库。
• pi_hole_ftl_gravitydb - （默认值："/etc/pihole/gravity.db"） - 指定 FTL 的 SQLite3 重力数据库的路径和文件名。此数据库包含与 Pi-hole 的 DNS 阻止相关的所有域名
• pi_hole_ftl_debug_all - （默认值：false） - 启用所有调试标志。如果此选项设置为 true，所有其他调试配置选项都将被忽略。
• pi_hole_ftl_debug_database - （默认值：false） - 打印关于数据库操作的调试信息。这会打印执行的 SQL 语句以及一些一般信息，例如存储查询所需的时间和已经保存到数据库中的数量。
• pi_hole_ftl_debug_networking - （默认值：false） - 在 pihole-FTL 启动时打印检测到的接口列表。此外，打印这些接口是 IPv4 还是 IPv6 接口。
• pi_hole_ftl_debug_locks - （默认值：false） - 打印有关共享内存锁的信息。在等待、获取和释放锁时会生成消息。
• pi_hole_ftl_debug_queries - （默认值：false） - 打印详细的查询信息（域、类型、响应等）。这一直是 pihole-FTL 的传统调试模式的一部分。
• pi_hole_ftl_debug_flags - （默认值：false） - 打印 DNS 钩子接收到的查询标志。仅在启用 DEBUG_QUERIES 时有效。
• pi_hole_ftl_debug_shmem - （默认值：false） - 打印有关共享内存缓冲区的信息。消息可能涉及创建或增大共享内存对象或字符串注入。
• pi_hole_ftl_debug_gc - （默认值：false） - 打印有关垃圾回收（GC）的信息：什么内容将被删除，删除了多少，以及进行垃圾回收花费了多长时间。
• pi_hole_ftl_debug_arp - （默认值：false） - 打印有关 ARP 表处理的信息：解析花费了多长时间，读取的 MAC 地址是否有效，以及 macvendor.db 文件是否存在。
• pi_hole_ftl_debug_regex - （默认值：false） - 控制 FTLDNS 是否应打印有关正则表达式匹配的扩展详细信息到 pihole-FTL.log。由于遗留原因，我们也支持使用以下设置来启用相同的功能：REGEX_DEBUGMODE=false|true。请注意，如果其中一个设置为 true，另一个无法再次用于禁用此设置。
• pi_hole_ftl_debug_api - （默认值：false） - 在 telnet API 调用期间打印额外的调试信息。目前仅用于在获取所有查询时发送额外信息。
• pi_hole_ftl_debug_overtime - （默认值：false） - 打印有关超时内存操作的信息，例如初始化或移动超时槽。
• pi_hole_ftl_debug_extbloqued - （默认值：false） - 打印为什么 FTL 判断某些查询被识别为被外部阻止的信息。
• pi_hole_ftl_debug_caps - （默认值：false） - 打印授予 pihole-FTL 进程的能力的信息。接收到 SIGHUP 时会打印当前能力，即可以查询当前能力集而无需重新启动 pihole-FTL（通过设置 DEBUG_CAPS=true 并随后发送 killall -HUP pihole-FTL）。
• pi_hole_ftl_debug_dnsmasq_lines - （默认值：false） - 打印导致 dnsmasq 事件的文件和行到 FTL 的日志文件。这对于实现缺少的附加钩子非常方便。
• pi_hole_ftl_debug_vectors - （默认值：false） - FTL 使用动态分配的向量执行各种任务。此配置选项启用有关分配、引用、删除和附加的广泛调试信息。
• pi_hole_ftl_debug_resolver - （默认值：false） - 有关主机名解析的广泛信息，例如在第一次和第二次主机名解析尝试中使用了哪些 DNS 服务器（仅影响内部生成的 PTR 查询）。
• pi_hole_ftl_rate_limit - （默认值："1000/60"） - 阻止在 y 秒内发出超过 x 查询的客户端（默认 1000 查询，60 秒）。通过将两个值都设置为零，可以完全禁用速率限制。