Pi-hole

Pi-hole 项目是一个 DNS 接收黑洞 (DNS sinkhole)，它通过整理来自多个第三方来源的域名拦截列表来工作。Pi-hole 使用 pi-hole-ftl^AUR（一个 dnsmasq 的分支）来无缝丢弃所有处于拦截列表中的域名请求。运行它无需配置各个客户端即可实现全网范围的广告拦截。该软件包附带一个可选的 Web 管理界面。

注意 Pi-hole 项目官方并不支持在 Arch Linux 上运行 Pi-hole。

安装

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

配置

本文或本章节已过时。

原因： 以下许多章节仍参考 Pi-hole 5，因此不完全适用于 Pi-hole 6。Pi-hole 6 有许多重大变动，包括集成的 Web 服务器以及迁移到 .toml 配置文件（在讨论页讨论）。

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 文件

本文或本节需要在语言、wiki 语法或风格方面进行改进。请参阅 Help:Style 获取参考。

原因： 至少部分重复了网络配置#localhost 通过网络解析。（在讨论页讨论）。

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 服务器。通常有两种方法可以实现这一点：

在路由器的局域网 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 地址，请在 /etc/dnsmasq.conf 中追加 bind-interfaces 以便 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-FTL --config dns.upstreams '["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 setpassword

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

Cloudflare DoH

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

原因： 据报道此功能已不再有效。根据 cloudflared 的说明：“DNS Proxy 不再被支持。”（在讨论页讨论）。

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

要使 Cloudflared 与 Pi-hole 协同工作，只需启动 cloudflared 并将 Pi-hole 配置为使用它作为其 DNS 条目即可。

使用建议的 cloudflared 服务文件，配置将是：

# systemctl start cloudflared
# pihole-FTL --config dns.upstreams '["127.0.0.1#54"]'

通过以下命令测试 Pi-hole 是否工作：

$ drill archlinux.org @127.0.0.1 -p 53

注意该端口是绑定到 Pi-hole 的端口，而不是绑定到 cloudflared 的端口。

针对固态硬盘优化

如果 Pi-hole 运行在固态硬盘（SD 卡、SSD 等）上，建议将 DBinterval 的值更改为至少一小时，以尽量减少对数据库的写入。

/etc/pihole/pihole.toml

...

[database]

  ...

  # How often do we store queries in FTL's database [seconds]?
  DBinterval = 3600
  
  ...

提示 log2ram^AUR 在树莓派 (RaspberryPi) 上也很有用。

禁用查询日志

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

要禁用历史数据的查询数据库，请在 Web 管理界面中（Settings > Privacy）将隐私级别设置为 Anonymous mode，或者编辑配置文件中的 privacylevel 值。

/etc/pihole/pihole.toml

...

[misc]
  
  ...
  
  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-FTL --config dns.listeningMode LOCAL

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

附加拦截列表

Pi-hole 的初衷是拦截广告，但它也可以用来拦截其他不需要的内容：

追踪域名
恶意软件域名
盗版网站
假新闻网站
钓鱼网站

注意 Pi-hole 拦截列表必须包含域名。有些拦截列表可能包含 127.0.0.1 与域名的组合——这种格式被 Pi-hole 接受。

有许多来源提供这些拦截列表。一些例子包括：firebog.net 和 oisd.nl。

使用正则表达式拦截/允许域名

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

$ pihole --wild yourdomain.com

注意它将被添加为域名列表中的 (\.|^)yourdomain\.com$ 条目。

要使用自定义正则表达式拦截域名：

$ pihole --regex '^example\.com$'

要从黑名单中删除同一个域名，只需在 pihole 命令中添加 -d 标志：

$ pihole --wild -d yourdomain.com
$ pihole --regex -d '^example\.com$'

另请参阅正则表达式教程。

使用 Unbound 作为上游 DNS 服务器

默认情况下，Pi-hole 将请求转发给上游 DNS 服务器，这可能会引发隐私问题。请查阅官方文档，获取有关在本地设置 Unbound 以解析 DNS 请求的指南。

故障排除

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

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

重启后数据丢失

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

对于缺少 RTC 的设备：一个权宜之计是针对 pihole-FTL.service 使用放置文件 (drop-in files)，在 ExecStartPre 语句中通过调用 /usr/bin/sleep x 内置延迟。请注意，sleep 时间中 "x" 的值取决于特定硬件建立时间同步所需的时间。

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

无法启动 Pi-hole FTLDNS 引擎

提示以 root 身份检查哪个进程占用了 53 端口：lsof -i :53。

很有可能 systemd-resolved.service 已经占用了 53 端口，而这是 pihole-FTL.service 所必需的。要解决此问题，请通过为 systemd-resolved 的配置文件创建放置片段 (drop-in snippet) 来禁用存根监听器 (stub listener)：

/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 可能不是个好主意。（在讨论页讨论）。

如果浏览器报告“正在解析主机”或者网页加载时间比平时长，请确保 /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 以应用更改。

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

Pi-hole 启动时网络接口未就绪

如果开机后域名解析无法工作，并且日志显示如下错误消息：

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 验证过程需要使用缓存。

参考.

升级到 6 版本后缺失 Web GUI

从 5 版本升级到 6 版本后，访问 Web GUI 时可能会遇到 404 Site not found 错误。尽管如此，Web GUI 很可能仍然可以通过端口 8080 访问。

原因：Pi-hole 现在包含自己的 Web 服务器。

之前的 lighttpd 服务器可能在升级期间运行在端口 80 上，因此将 8080 设置为默认监听端口。此外，如果另一个 Web 服务器在升级期间监听在端口 8080 上，Pi-hole Web GUI 将完全不可用。参见 [3]。

解决干扰的 Web 服务器后，你可以通过编辑 /etc/pihole/pihole.toml 中 [webserver] 部分的 port 键，或者通过新的 Web GUI（Settings > System > 打开右上角的 Expert mode > All settings > Webserver and API > webserver.port）将 Web GUI 的监听端口重置为 80。

参见