Pi-hole

Pi-hole 项目是一个 DNS 沉洞，它从多个第三方来源编译域名阻止列表。Pi-hole 使用 pi-hole-ftl^AUR ( dnsmasq 的一个分支) 来无缝丢弃对其阻止列表中任何域名的所有请求。运行它可以有效地部署全网络范围的广告拦截，而无需配置单独的客户端。该软件包带有一个可选的 Web 管理界面。

注意： Pi-hole 在 Arch Linux 上未获得 Pi-hole 项目的官方支持。

安装

安装 pi-hole-core^AUR 软件包。

配置

FTL (Faster Than Light)

Pi-hole 的 FTL 是一个 DNS 解析器/转发器和一个类似数据库的包装器/API，它提供请求的长期存储，用户可以通过 WebGUI 的“长期数据”部分查询这些请求。数据收集并存储在两个位置

每日数据存储在 RAM 中，并在 /run/log/pihole/pihole.log 中实时捕获
历史数据（几天/几周/几个月）存储在文件系统 /etc/pihole/pihole-FTL.db 上，并以用户指定的时间间隔写出。

注意

要禁用日志记录，请参阅 #禁用查询日志。
启动 pihole-FTL.service 很可能失败。请参阅 #无法启动 Pi-hole FTLDNS 引擎。

pihole-FTL.service 是静态启用的；重新/启动它。有关 FTL 配置，请参阅上游文档。

FTL 集成 Web 界面

Pi-hole 具有强大、用户友好但完全可选的 Web 界面。除了更改设置外，用户还可以分析和可视化 Pi-hole 处理的 DNS 查询。

更新 hosts 文件

filesystem 软件包附带一个空的 /etc/hosts 文件，已知该文件会阻止 Pi-hole 获取阻止列表。必须将以下内容附加到此文件以确保正确操作，请注意 ip.address.of.pihole 应该是运行 Pi-hole 的机器的实际 IP 地址（例如 192.168.1.250），myhostname 应该是运行 Pi-hole 的机器的实际主机名

/etc/hosts

127.0.0.1              localhost
ip.address.of.pihole   pi.hole myhostname

有关更多信息，请参阅 Issue#1800。

使设备使用 Pi-hole

要使用 Pi-hole，网络内的设备应使用 Pi-hole 的 IP 地址作为其唯一的 DNS 服务器。要实现此目的，通常有两种方法

在路由器的 LAN DHCP 设置中，将 Pi-hole 的 IP 地址设置为连接设备的唯一可用 DNS 服务器。
手动配置每个设备以使用 Pi-hole 的 IP 地址作为其唯一的 DNS 服务器。

注意： 某些路由器（甚至 ISP）不允许修改 LAN DNS 设置，因此禁用路由器的 DHCP 服务器并使用 Pi-hole 的内置 DHCP 服务器可能是解决方案。

有关使其他设备使用 Pi-hole 的更多信息，请访问上游文档。

提示： 托管 Pi-hole 的设备也可以使用 Pi-hole。只需将 DNS 设置更改为仅 IP 地址 127.0.0.1。

用法

更改计算机的网络设置，使唯一使用的 DNS 服务器为 127.0.0.1。

如果使用 DHCP 从外部路由器租用 IP 地址，请将 bind-interfaces 附加到 /etc/dnsmasq.conf 以解析 DNS 查询。

使用 ldns 软件包的 drill 命令，通过 drill @127.0.0.1 archlinux.org 在独立于 /etc/resolv.conf 中网络配置的名称服务器的情况下测试 DNS 查询。

用法

独立版本和服务器版本都可以通过 CLI 控制，但只有服务器版本可以通过 Web 界面控制。

使用 Web 界面

转到 pi.hole 或 <Pi-hole IP 地址>/admin/ 访问 Web 界面。

使用 CLI

Pi-hole DNS 管理

默认情况下，Pi-hole 使用 Google DNS 服务器。使用以下命令更改 Pi-hole 使用的 DNS 服务器：

$ pihole -a setdns ipaddress#port

通过逗号分隔地址来指定多个 DNS 服务器。

强制更新广告域名列表

要更新阻止域名列表，请执行：

$ pihole -g

临时禁用 Pi-hole

可以通过 CLI 执行以下命令暂停 Pi-hole：

$ pihole disable [time]

将 time 的值留空，禁用将是永久性的，直到以后手动重新启用。time 可以用秒或分钟表示，语法分别为 #s 和 #m。例如，要禁用 Pi-hole 5 分钟：

$ pihole disable 5m

随时可以通过执行以下命令重新启用 Pi-hole：

$ pihole enable

技巧和提示

密码保护的 Web 界面

要密码保护 Pi-hole Web 界面，请运行以下命令并输入密码：

$ pihole -a -p

要禁用密码保护，请设置一个空白密码。

Cloudflare DoH

可以将 Pi-hole 配置为使用 Cloudflared 来实现 DNS over HTTPS 功能。

要使 Cloudflared 与 Pi-hole 一起工作，只需启动 cloudflared 并配置 pi-hole 以将其用作其 DNS 条目。

使用 Cloudflared 的建议服务文件，那将是：

# systemctl start cloudflared
$ pihole -a setdns 127.0.0.1#5300

测试 pi-hole 是否正常工作：

drill archlinux.org @127.0.0.1 -p 53

（请注意，端口是绑定到 pi-hole 的端口，而不是绑定到 cloudflared 的端口）。

针对固态硬盘优化

如果 Pi-hole 在固态硬盘（SD 卡，SSD 等）上运行，建议取消注释 DBINTERVAL 值并将其更改为至少 60.0，以最大限度地减少对数据库的写入：

/etc/pihole/pihole-FTL.conf

...

## Database Interval
## How often do we store queries in FTL's database -minutes-?
## See: https://docs.pi-hole.net/ftldns/database/
## Options: number of minutes
DBINTERVAL=60.0

...

执行更改后，重启 pihole-FTL.service。

禁用查询日志

默认情况下收集的每日和历史数据都包含可能被认为是敏感的查询数据。

要禁用历史数据的查询数据库，请在 Web 管理界面（设置 > 隐私）或配置文件 /etc/pihole/pihole-FTL.conf 中将隐私级别设置为最大值匿名模式，方法是编辑以下行：

PRIVACYLEVEL=3

要同时禁用每日数据的日志记录，请使用以下命令：

$ pihole logging off

警告： Pi-hole 将在执行此命令后擦除所有统计信息。

与 VPN 服务器一起使用

连接的 VPN 客户端可以使用 Pi-hole。

OpenVPN

OpenVPN 服务器可以配置为向其客户端通告 Pi-hole 实例。将以下两行添加到 /etc/openvpn/server/server.conf：

push "redirect-gateway def1 bypass-dhcp"
push "dhcp-option DNS Pi-hole-IP"

如果仍然不起作用，请尝试创建一个文件 /etc/dnsmasq.d/00-openvpn.conf，内容如下：

interface=tun0

可能需要使 dnsmasq 监听 tun0。

WireGuard

WireGuard 客户端可以配置为使用 Pi-hole DNS 服务器。在客户端配置文件中，指定以下行：

DNS = Pi-hole-IP

为了使 DNS 从 VPN 工作，Pi-hole 必须监听所有本地接口：

pihole -a -i local

更多信息，请参见 WireGuard#客户端配置。

使用 Nginx 代替 Lighttpd

这是非官方的、社区支持的配置。确保 PHP 已设置好（请参阅 #设置 PHP）并且 lighttpd 服务器处于非活动状态。

安装 nginx-mainline 和 php-fpm。

修改 /etc/nginx/nginx.conf 以在 http 部分包含以下内容：

gzip            on;
gzip_min_length 1000;
gzip_proxied    expired no-cache no-store private auth;
gzip_types      text/plain application/xml application/json application/javascript application/octet-stream text/css;
include /etc/nginx/conf.d/*.conf;

复制软件包提供的 Pi-hole 默认配置：

# mkdir /etc/nginx/conf.d
# cp /usr/share/pihole/configs/nginx.example.conf /etc/nginx/conf.d/pihole.conf

编辑 /etc/nginx/conf.d/pihole.conf 并将 fastcgi_pass 指令更改为以下内容：

fastcgi_pass  unix:/run/php-fpm/php-fpm.sock;

可选地，如果打算在 Nginx 上运行多个虚拟主机，请将 VIRTUAL_HOST 设置为 Pi-hole 的 CNAME。

fastcgi_param VIRTUAL_HOST "pihole.example.com";

自 7.4 版本以来，php-fpm 默认情况下已加强，并撤销了对 /usr（和子目录）的读/写访问权限。

为 php-fpm 创建一个 drop-in 文件，内容如下：

/etc/systemd/system/php-fpm.service.d/pihole.conf

[Service]
ReadWritePaths = /srv/http/pihole
ReadWritePaths = /run/pihole-ftl/pihole-FTL.port
ReadWritePaths = /run/log/pihole/pihole.log
ReadWritePaths = /run/log/pihole-ftl/pihole-FTL.log
ReadWritePaths = /etc/pihole
ReadWritePaths = /etc/hosts
ReadWritePaths = /etc/hostname
ReadWritePaths = /etc/dnsmasq.d/01-pihole.conf
ReadWritePaths = /proc/meminfo
ReadWritePaths = /proc/cpuinfo
ReadWritePaths = /sys/class/thermal/thermal_zone0/temp
ReadWritePaths = /tmp

然后启动并启用 nginx.service 和 php-fpm.service。

额外的阻止列表

Pi-hole 旨在阻止广告，但它也可以用于阻止其他不需要的内容：

跟踪域名
恶意软件域名
盗版站点
虚假新闻站点
网络钓鱼站点

注意： Pi-hole 阻止列表必须包含域名。某些阻止列表可能包含 127.0.0.1 的 IP 地址和域名组合 - Pi-hole 接受此格式。

有许多来源提供这些阻止列表。一些示例：firebog.net 和 oisd.nl。

基于正则表达式阻止/允许自定义域名

如果要将通配符域名添加到拒绝/黑名单，请使用以下 pihole 命令：

$ /usr/local/bin/pihole --wild yourdomain.com

注意： 域名列表中的条目将类似于 (\.|^)yourdomain\.com$

如果要从拒绝/黑名单中删除相同的域名，只需在 pihole 命令中添加 -d 标志：

$ /usr/local/bin/pihole --wild -d yourdomain.com

要阻止来自自定义正则表达式的所有域名，请使用以下 pihole 命令：

$ pihole --regex "[a-z]test.com"

如果要从拒绝/黑名单中删除相同的自定义正则表达式，只需在 pihole 命令中添加 -d 标志：

$ pihole --regex -d "[a-z]test.com"

使用 Unbound 作为上游 DNS 服务器

默认情况下，Pi-hole 将请求转发到上游 DNS 服务器，这可能会导致隐私问题。有关设置本地 Unbound 以解析 DNS 请求的指南，请参阅上游文档。

故障排除

升级后 Web 界面中出现异常行为

Web GUI 中的一些奇怪/无法解释的渲染问题通常可以通过清除浏览器缓存来解决。

重启后数据丢失

没有 RTC 的系统（例如某些 ARM 设备）可能会在重启时遇到查询日志中的数据丢失。当缺少 RTC 的系统启动时，时间是在网络和解析器启动之后设置的。Pi-hole 的某些方面可能会在此之前启动，从而导致数据丢失。不正确设置的 RTC 也可能导致问题。请参阅：安装指南#时间和系统时间。

对于缺少 RTC 的设备：对此的一种变通方法是针对 pihole-FTL.service 使用 drop-in 文件，其中在 ExecStartPre 语句中内置了调用 /usr/bin/sleep x 的延迟。请注意，睡眠时间中 “x” 的值取决于特定硬件建立时间同步所需的时间。

针对 systemd-timesyncd 的 Issue#11008 当前阻止了使用 time-sync.target 来自动化此操作。

无法启动 Pi-hole FTLDNS 引擎

提示： 使用 # lsof -i :53 检查哪个进程打开了端口 53。

可能是 systemd-resolved.service 已经占用了端口 53，这是 pihole-FTL.service 所必需的。要解决此问题，请通过 drop-in snippet 形式从 systemd-resolved 的配置文件中禁用存根监听器：

/etc/systemd/resolved.conf.d/pi-hole.conf

[Resolve]
DNSStubListener=no

然后重启 systemd-resolved.service 和 pihole-FTL.service。

更多信息，请参阅 resolved.conf(5)。

或者，通过取消注释 /etc/dnsmasq.conf 中的行 bind-interfaces，告诉 dnsmasq 显式绑定到每个接口，而不是通配符 0.0.0.0:53。这将避免与监听 127.0.0.53:53 的 systemd-resolved 冲突。

DNSMasq 软件包冲突

自 Pi-hole-FTL 4.0 以来，dnsmasq 的私有分支已集成到 FTL 子项目中。原始的 dnsmasq 软件包现在与 pi-hole-ftl^AUR 冲突，并且在从以前的版本升级时将被卸载。仍然可以使用以前的 dnsmasq 配置文件，只需确保原始 /etc/dnsmasq.conf 中的 conf-dir=/etc/dnsmasq.d/,*.conf 没有被注释掉。

未知状态且更改未被保存

如 FS#63704 中所示，问题出在 systemd-sysusers 创建的用户 http 上，该用户是在过期状态下创建的。要修复它，请运行：

# chage --expiredate -1 http

加载时间过长

本文或本节的准确性存在争议。

原因： 此问题似乎与 DNS 配置有关。指示直接更改 /etc/resolv.conf 可能不是一个好主意。（在 Talk:Pi-hole 中讨论）

如果浏览器报告“正在解析主机”或加载页面比平时花费更长的时间，请确保 /etc/resolv.conf 看起来完全像这样：

/etc/resolv.conf

nameserver 127.0.0.1

如果页面加载时间过长，则可能是 php 调用的 pihole 脚本（/usr/bin/pihole）中的 lsof 调用有问题。在加载页面时使用以下命令验证它：ps -ef | grep lsof。终止它，如果页面显示，则将 pihole 脚本（只有一个）中的 lsof 调用替换为：

ss -lnp '( sport = 53 )'

防止其他虚拟主机的 DNS 解析问题

默认情况下，DNS 服务 (pihole-FTL) 将绑定到 0.0.0.0 IP 地址

# netstat -ltnp | grep 53

tcp        0      0 0.0.0.0:53              0.0.0.0:*               LISTEN      2196/pihole-FTL
tcp6       0      0 :::53                   :::*                    LISTEN      2196/pihole-FTL

这将阻止同一台托管 pihole 实例的机器上的任何其他虚拟主机（例如 docker 容器）获得 DNS 解析。[1][2]

为了解决这个问题，您需要在 /etc/dnsmasq.d/ 中创建一个配置文件，内容如下（其中 X.X.X.X 是您的 pi-hole 的 IP 地址）

/etc/dnsmasq.d/99-dns-bind.conf

listen-address=X.X.X.X
bind-interfaces

然后，您需要重启 pihole-FTL.service 以应用更改。

提示： 要完成此配置，您可能需要激活网络管理器的在线等待服务

pihole 启动时接口未启动

如果在启动后域名解析不起作用，并且日志显示类似以下的错误消息：

pihole-FTL [...] FATAL ERROR in dnsmasq core: unknown interface wlo1

那么可能是接口名称错误，或者接口在 pihole 尝试运行时未启动。

使用 ip a 检查接口名称。如果名称错误，请在 /etc/pihole/setupVars.conf 中将 PIHOLE_INTERFACE 设置为正确的值：
如果接口名称正确，则可能是接口在 pihole 启动时未启动（即使 systemd 服务依赖于 After=network-online.target）。在 /etc/pihole/pihole-FTL.conf 中将 DELAY_STARTUP 设置为大于 0 的值（以秒为单位表示）。

重启以验证问题是否已修复。

参考.

DNS 缓存逐出大于零

提示： 将缓存大小设置为零将禁用缓存。

当此数字大于零时，应增加缓存大小。您可以通过取消注释或添加以下设置以及您想要的数字来在 /etc/dnsmasq.conf 中设置缓存限制：

/etc/dnsmasq.conf

cache-size=12345

执行更改后，重启 pihole-FTL.service

注意： 除非 DNS 缓存逐出的数量大于零，否则增加此数量没有好处。

更大的缓存将消耗节点上更多的内存，从而减少 Pi-hole 其他缓存可用的内存。如果将此数字推向极端，甚至可能导致 Pi-hole 内存不足并且无法按预期运行。

启用 DNSSEC 后，您不能将缓存大小减小到 150 以下，因为 DNSSEC 验证过程会使用缓存。

参考.

参见