使用了望塔?请参阅本自述文件底部有关守望台的注释
自2023.01
起,如果您通过external.conf
文件对 lighttpd 进行了任何修改,则现在需要将该文件映射到/etc/lighttpd/conf-enabled/whateverfile.conf
由于 Docker 和 libseccomp <2.5 的已知问题,您可能会在使用旧版本libseccomp2
的主机系统(例如 Debian/Raspbian buster 或 Ubuntu 20.04,也许还有 CentOS 7)上运行2022.04
及更高版本时遇到问题。
第一个建议是升级您的主机操作系统,其中将包括更新的(和固定的)版本的libseccomp
。
如果您绝对无法做到这一点,一些用户报告称通过 debian 上的向后移植成功更新了libseccomp2
,或者通过 Ubuntu 上的更新进行了类似的操作。您可以自行承担风险尝试此解决方法(注意,您可能还会发现您需要最新的docker.io
(更多详细信息请参见此处)
一些用户报告了在2022.04
及更高版本上使用--privileged
标志的问题。 TL;DR,不要使用该模式,并明确使用允许的上限(如果需要)
# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
services :
pihole :
container_name : pihole
image : pihole/pihole:latest
# For DHCP it is recommended to remove these ports and instead add: network_mode: "host"
ports :
- " 53:53/tcp "
- " 53:53/udp "
- " 67:67/udp " # Only required if you are using Pi-hole as your DHCP server
- " 80:80/tcp "
environment :
TZ : ' America/Chicago '
# WEBPASSWORD: 'set a secure password here or it will be random'
# Volumes store your data between container upgrades
volumes :
- ' ./etc-pihole:/etc/pihole '
- ' ./etc-dnsmasq.d:/etc/dnsmasq.d '
# https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
cap_add :
- NET_ADMIN # Required if you are using Pi-hole as your DHCP server, else not needed
restart : unless-stopped
docker compose up -d
来构建并启动 pi-hole (在旧系统上语法可能是docker-compose
)bridge
网络设置,请使用 Pi-hole Web UI 将 DNS 设置接口侦听行为更改为“侦听所有接口,允许所有来源”。 (这也可以通过将环境变量DNSMASQ_LISTENING
设置为all
来实现)这是一个等效的 docker run 脚本。
一个 Docker 项目,用于制作具有 Pi-hole 功能的轻量级 x86 和 ARM 容器。
该容器使用2个流行端口,端口53和端口80,因此可能与现有应用程序端口冲突。如果您没有使用端口 53/80 的其他服务或 docker 容器(如果有,请继续阅读下面的反向代理示例),运行此容器所需的最少参数位于脚本 docker_run.sh 中
如果您使用的是带有 SELinux 强制策略的基于 Red Hat 的发行版,请添加:z
以与卷对齐,如下所示:
-v "$(pwd)/etc-pihole:/etc/pihole:z"
-v "$(pwd)/etc-dnsmasq.d:/etc/dnsmasq.d:z"
建议使用卷来跨容器重新创建保留数据以更新映像。 IP 查找变量可能并不适合所有人,请检查它们的值并在必要时硬编码 IP 和 IPv6。
您可以通过在调用docker_run.sh
时设置PIHOLE_BASE
环境变量来自定义存储持久数据的位置(例如PIHOLE_BASE=/opt/pihole-storage ./docker_run.sh
)。如果未设置PIHOLE_BASE
,则当您调用脚本时,文件将存储在当前目录中。
自动广告列表更新- 自 3.0+ 版本以来, cron
被烘焙到容器中,并将获取最新版本的列表并刷新日志。设置您的 TZ环境变量以确保午夜日志轮换与您所在时区的午夜同步。
有多种不同的方法可以在 Docker Pi-hole 容器内运行 DHCP,但它稍微高级一些,并且一种方法并不适合所有情况。我们的文档网站详细介绍了 DHCP 和 Docker 的多种网络模式:Docker DHCP 和网络模式
如果您想在 docker 容器内自定义各种内容,还有其他环境变量:
多变的 | 默认 | 价值 | 描述 |
---|---|---|---|
TZ | 世界标准时间 | <Timezone> | 设置您的时区以确保日志在当地午夜而不是 UTC 午夜轮换。 |
WEBPASSWORD | 随机的 | <Admin password> | http://pi.hole/管理员密码。运行docker logs pihole | grep random 找到你的随机通道。 |
FTLCONF_LOCAL_IPV4 | 未设置 | <Host's IP> | 设置为服务器的 LAN IP,由 Web 阻止模式使用。 |
多变的 | 默认 | 价值 | 描述 |
---|---|---|---|
PIHOLE_DNS_ | 8.8.8.8;8.8.4.4 | IP 由; 分隔 | Pi-hole 转发查询的上游 DNS 服务器,以分号分隔 (支持带有 #[port number] 非标准端口)例如127.0.0.1#5053;8.8.8.8;8.8.4.4 (支持 Docker 服务名称和链接,而不是 IP)例如 upstream0;upstream1 ,其中upstream0 和upstream1 是docker 服务的服务名称或链接注意:此环境变量的存在假定这是上游 DNS 的唯一管理。通过 Web 界面添加的上游 DNS 将在容器重新启动/重新创建时被覆盖 |
DNSSEC | false | <"true"|"false"> | 启用 DNSSEC 支持 |
DNS_BOGUS_PRIV | true | <"true"|"false"> | 切勿转发私有范围的反向查找 |
DNS_FQDN_REQUIRED | true | <"true"|"false"> | 切勿转发非 FQDN |
REV_SERVER | false | <"true"|"false"> | 启用 DNS 条件转发以进行设备名称解析 |
REV_SERVER_DOMAIN | 未设置 | 网络域 | 如果启用条件转发,请设置本地网络路由器的域 |
REV_SERVER_TARGET | 未设置 | 路由器的IP | 如果启用条件转发,设置本地网络路由器的IP |
REV_SERVER_CIDR | 未设置 | 反向域名解析 | 如果启用条件转发,请设置反向 DNS 区域(例如192.168.0.0/24 ) |
DHCP_ACTIVE | false | <"true"|"false"> | 启用 DHCP 服务器。静态 DHCP 租约可以使用自定义/etc/dnsmasq.d/04-pihole-static-dhcp.conf 进行配置 |
DHCP_START | 未设置 | <Start IP> | 由 DHCP 服务器分发的 IP 地址范围的开始(如果启用了 DHCP 服务器,则为强制项)。 |
DHCP_END | 未设置 | <End IP> | DHCP 服务器分发的 IP 地址范围的结尾(如果启用了 DHCP 服务器,则为强制项)。 |
DHCP_ROUTER | 未设置 | <Router's IP> | 由 DHCP 服务器发送的路由器(网关)IP 地址(如果启用了 DHCP 服务器,则为必填项)。 |
DHCP_LEASETIME | 24 | <hours> | DHCP 租用时间(以小时为单位)。 |
PIHOLE_DOMAIN | lan | <domain> | DHCP服务器发送的域名。 |
DHCP_IPv6 | false | <"true"|"false"> | 启用 DHCP 服务器 IPv6 支持 (SLAAC + RA)。 |
DHCP_rapid_commit | false | <"true"|"false"> | 启用 DHCPv4 快速提交(快速地址分配)。 |
VIRTUAL_HOST | ${HOSTNAME} | <Custom Hostname> | 您的网络服务器“虚拟主机”是什么,通过此主机名/IP 访问管理允许您除了默认的“http://pi.hole/admin/”地址之外还可以更改白名单/黑名单 |
IPv6 | true | <"true"|"false"> | 为了实现 unraid 兼容性,如果为 false,则从 DNS/Web 服务中删除所有 IPv6 配置。 |
TEMPERATUREUNIT | c | <c|k|f> | 将首选温度单位设置为c :摄氏度、 k :开氏度或f 华氏度单位。 |
WEBUIBOXEDLAYOUT | boxed | <boxed|traditional> | 使用盒装布局(在大屏幕上工作时很有帮助) |
QUERY_LOGGING | true | <"true"|"false"> | 是否启用查询日志记录。 |
WEBTHEME | default-light | <"default-dark"|"default-darker"|"default-light"|"default-auto"|"high-contrast"|"high-contrast-dark"|"lcars"> | 要使用的用户界面主题。 |
WEBPASSWORD_FILE | 未设置 | <Docker secret path> | 使用 Docker 机密设置管理员密码。如果设置了WEBPASSWORD ,则忽略WEBPASSWORD_FILE 。如果WEBPASSWORD 为空,并且WEBPASSWORD_FILE 设置为有效的可读文件路径,则WEBPASSWORD 将设置为WEBPASSWORD_FILE 的内容。 |
多变的 | 默认 | 价值 | 描述 |
---|---|---|---|
INTERFACE | 未设置 | <NIC> | 默认值适用于我们的基本示例 docker run 命令。如果您尝试将 DHCP 与--net host 模式一起使用,那么您可能必须自定义此选项或 DNSMASQ_LISTENING。 |
DNSMASQ_LISTENING | 未设置 | <local|all|single> | local 侦听所有本地子网,除了本地之外, all 还允许侦听 Internet 源子网, single 仅侦听指定的接口。 |
WEB_PORT | 未设置 | <PORT> | 这将破坏 Pi-hole 的“网页被阻止”功能,但它可能有助于高级设置,例如运行 Synology 或--net=host docker 参数的设置。本指南介绍如何使用 Linux 路由器 DNAT 规则恢复网页被阻止的功能:替代 Synology 安装方法 |
WEB_BIND_ADDR | 未设置 | <IP> | Lighttpd 的绑定地址。如果未设置,lighttpd 将绑定到每个接口,除非在主机网络模式下运行时它将使用FTLCONF_LOCAL_IPV4 代替。 |
SKIPGRAVITYONBOOT | 未设置 | <unset|1> | 使用此选项可以在启动容器时跳过更新重力数据库。默认情况下,未设置此环境变量,因此重力数据库将在容器启动时更新。将此环境变量设置为 1(或任何值)将导致容器启动时重力数据库不会更新。 |
CORS_HOSTS | 未设置 | <FQDNs delimited by ,> | 允许 CORS 的域/子域的列表。不支持通配符。例如: CORS_HOSTS: domain.com,home.domain.com,www.domain.com 。 |
CUSTOM_CACHE_SIZE | 10000 | 数字 | 设置 dnsmasq 的缓存大小。对于增加默认缓存大小或将其设置为 0 很有用。请注意,当DNSSEC 为“true”时,此设置将被忽略。 |
FTL_CMD | no-daemon | no-daemon -- <dnsmasq option> | 自定义 dnsmasq 启动的选项。例如no-daemon -- --dns-forward-max 300 以增加最大值。高负载设置上并发 DNS 查询的数量。 |
FTLCONF_[SETTING] | 未设置 | 根据文档 | 使用 FTLDNS 配置页面中描述的设置自定义 pihole-FTL.conf。例如,要自定义 LOCAL_IPV4,请确保设置了FTLCONF_LOCAL_IPV4 环境变量。 |
多变的 | 默认 | 价值 | 描述 |
---|---|---|---|
DNSMASQ_USER | 未设置 | <pihole|root> | 允许更改 FTLDNS 运行的用户。默认值: pihole ,某些系统(例如 Synology NAS)可能要求您将其更改为root (请参阅#963) |
PIHOLE_UID | 999 | 数字 | 覆盖图像的默认 pihole 用户 ID 以匹配主机用户 ID 重要提示:id 不得已在容器内使用! |
PIHOLE_GID | 999 | 数字 | 覆盖图像的默认 pihole 组 ID 以匹配主机组 ID 重要提示:id 不得已在容器内使用! |
WEB_UID | 33 | 数字 | 覆盖图像的默认 www-data 用户 ID 以匹配主机用户 ID 重要提示:id 不得已在容器内使用! (如果您也使用 PIHOLE_UID,请确保它与 PIHOLE_UID 不同) |
WEB_GID | 33 | 数字 | 覆盖图像的默认 www-data 组 ID 以匹配主机组 ID 重要提示:id 不得已在容器内使用! (如果您也使用 PIHOLE_GID,请确保它与 PIHOLE_GID 不同) |
WEBLOGS_STDOUT | 0 | 0|1 | 0 记录到定义的文件,1 将访问和错误日志重定向到标准输出 |
虽然这些可能仍然有效,但它们可能会在未来的版本中被删除。在适用的情况下,会标明替代变量名称。请查看上表以了解替代变量的用法
Docker 环境变量。 | 描述 | 替换为 |
---|---|---|
CONDITIONAL_FORWARDING | 启用 DNS 条件转发以进行设备名称解析 | REV_SERVER |
CONDITIONAL_FORWARDING_IP | 如果启用条件转发,设置本地网络路由器的IP | REV_SERVER_TARGET |
CONDITIONAL_FORWARDING_DOMAIN | 如果启用条件转发,请设置本地网络路由器的域 | REV_SERVER_DOMAIN |
CONDITIONAL_FORWARDING_REVERSE | 如果启用条件转发,请设置本地网络路由器的反向 DNS(例如0.168.192.in-addr.arpa ) | REV_SERVER_CIDR |
DNS1 | 主要上游 DNS 提供商,默认为 google DNS | PIHOLE_DNS_ |
DNS2 | 第二上游 DNS 提供商,默认为 google DNS,如果只应使用一个 DNS, no | PIHOLE_DNS_ |
ServerIP | 设置为服务器的 LAN IP,由 Web 阻止模式和 lighttpd 绑定地址使用 | FTLCONF_LOCAL_IPV4 |
ServerIPv6 | 如果您将 v6 网络设置为服务器的 LAN IPv6 以完全阻止 IPv6 广告 | FTLCONF_LOCAL_IPV6 |
FTLCONF_REPLY_ADDR4 | 设置为服务器的 LAN IP,由 Web 阻止模式和 lighttpd 绑定地址使用 | FTLCONF_LOCAL_IPV4 |
FTLCONF_REPLY_ADDR6 | 如果您将 v6 网络设置为服务器的 LAN IPv6 以完全阻止 IPv6 广告 | FTLCONF_LOCAL_IPV6 |
要以 docker run 格式使用这些环境变量,请使用以下样式: -e DNS1=1.1.1.1
以下是 docker-compose / docker 运行的其他参数的概述。
Docker 参数 | 描述 |
---|---|
-p <port>:<port> 推荐 | 要公开的端口(53、80、67),Pi-holes HTTP 和 DNS 服务所需的最低端口 |
--restart=unless-stopped 受到推崇的 | 在启动时或发生崩溃时自动(重新)启动 Pi-hole |
-v $(pwd)/etc-pihole:/etc/pihole 受到推崇的 | Pi-hole 配置的卷有助于在 docker 镜像更新过程中保持更改 |
-v $(pwd)/etc-dnsmasq.d:/etc/dnsmasq.d 受到推崇的 | dnsmasq 配置的卷有助于在 docker 映像更新中保留更改 |
--net=host 选修的 | 如果您不运行任何其他 Web 应用程序,则可以替代-p <port>:<port> 参数(不能与 -p 同时使用)。 DHCP 在 --net=host 下运行效果最佳,否则您的路由器必须支持 dhcp-relay 设置。 |
--cap-add=NET_ADMIN 受到推崇的 | 通常添加的 DHCP 功能,请参阅下面的“功能注释”了解其他功能。 |
--dns=127.0.0.1 选修的 | 将容器的解析设置设置为 localhost,以便它可以从 Pi-hole 的 DNSMasq 解析 DHCP 主机名,可以修复容器重新启动时的解析错误。 |
--dns=1.1.1.1 选修的 | 设置您选择的备份服务器,以防 DNSMasq 启动出现问题 |
--env-file .env 选修的 | 用于存储 docker 环境变量的文件,替换-e key=value 设置。这里是为了方便 |
docker exec -it pihole_container_name pihole -a -p
- 然后在提示符中输入您的密码-p 8080:80
。如果您使用的是旧版 IP 阻止模式,则不应重新映射此端口。DEFAULT_HOST
env,并且您需要为 Pi-hole 的容器设置匹配的VIRTUAL_HOST
。如果遇到问题,请阅读 nginxproxy/nginx-proxy 自述文件以获取更多信息。bridge
将容器与主机网络隔离。这是一个更安全的设置,但需要将接口侦听行为的 Pi-hole DNS 选项设置为“侦听所有接口,允许所有来源”。Ubuntu (17.10+) 和 Fedora (33+) 的现代版本包括systemd-resolved
,默认配置为实现缓存 DNS 存根解析器。这将阻止 pi-hole 侦听端口 53。应使用以下命令禁用存根解析器: sudo sed -r -i.orig 's/#?DNSStubListener=yes/DNSStubListener=no/g' /etc/systemd/resolved.conf
这不会更改名称服务器设置,该设置指向存根解析器,从而阻止 DNS 解析。更改/etc/resolv.conf
符号链接以指向/run/systemd/resolve/resolv.conf
,该链接会自动更新以遵循系统的netplan
: sudo sh -c 'rm /etc/resolv.conf && ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf'
进行这些更改后,您应该使用systemctl restart systemd-resolved
安装 pi-hole 后,您需要配置客户端以使用它(请参阅此处)。如果您使用上面的符号链接,您的 docker 主机将使用 DHCP 提供的任何服务,或者您配置的任何静态设置。如果您想显式设置 docker 主机的名称服务器,您可以编辑/etc/netplan
中找到的 netplan,然后运行sudo netplan apply
。网络规划示例:
network :
ethernets :
ens160 :
dhcp4 : true
dhcp4-overrides :
use-dns : false
nameservers :
addresses : [127.0.0.1]
version : 2
请注意,也可以完全禁用systemd-resolved
。但是,这可能会导致 VPN 中的名称解析出现问题(请参阅错误报告)。它还禁用 netplan 的功能,因为 systemd-resolved 被用作默认渲染器(请参阅man netplan
)。如果您选择禁用该服务,则需要手动设置名称服务器,例如通过创建新的/etc/resolv.conf
。
旧版 Ubuntu 版本(大约 17.04)的用户需要禁用 dnsmasq。
@Rikj000 制作了一份指南来帮助用户在 Dokku 上安装 Pi-hole
下表解释了主要的 docker 标签。单击此处查看标签的完整列表。请参阅 GitHub 发行说明,了解该发行版中包含的 Pi-hole Core、Web 和 FTL 的具体版本。
基于日期的(包括递增的“补丁”版本)不涉及任何类型的语义版本号,而是使用日期来区分新版本和旧版本,仅此而已。发行说明将始终包含容器中更改的完整详细信息,包括对核心 Pi-hole 组件的更改
标签 | 描述 |
---|---|
latest | 始终最新版本 |
2022.04.0 | 基于日期的发布 |
2022.04.1 | 指定月份的第二次发布 |
dev | 与latest 类似,但针对开发分支(偶尔推送) |
*beta | 即将推出的版本的早期测试版 - 这里是龙 |
nightly | 与dev 类似,但每天晚上都会推送并从核心 Pi-hole 组件(Pi-hole、web、FTL)的最新development 分支中提取 |
标准的 Pi-hole 定制能力适用于该 docker,但也有 docker 的一些变化,例如使用 docker 卷挂载来映射主机存储的文件配置到容器默认值上。但是,应避免将这些配置文件安装为只读。如果您删除了 Pi-hole 容器(这是一种典型的 Docker 升级模式),卷对于保留配置也很重要。
不要尝试升级 ( pihole -up
) 或重新配置 ( pihole -r
)。新的镜像将被发布用于升级,通过用新的升级镜像替换旧容器来进行升级是“docker方式”。长期存在的 docker 容器不是 docker 方式,因为它们的目标是可移植和可复制,为什么不经常重新创建它们呢!只是为了证明你可以。
docker pull pihole/pihole
docker rm -f pihole
docker run <args> pihole/pihole
( <args>
是您首选的运行卷和环境变量)为什么这种升级方式好呢?有几个原因:每个人都从同一个基础镜像开始,该镜像已经过测试,知道它可以工作。推出更新时无需担心从 A 升级到 B、从 B 升级到 C、或从 A 升级到 C,它降低了复杂性,并且每次都允许“全新开始”,同时保留卷的自定义设置。基本上我鼓励您的容器采用 Phoenix 服务器原则。
要重新配置 Pi-hole,您需要使用现有的容器环境变量,或者如果没有满足您需要的变量,请使用 Web UI 或 CLI 命令。
以下是 Pi-hole 文档中的一些相关 wiki 页面。 Web 界面或命令行工具可用于实现对 pihole 的更改。
我们安装所有 pihole 实用程序,以便内置 pihole 命令将通过docker exec <container> <command>
工作,如下所示:
docker exec pihole_container_name pihole updateGravity
docker exec pihole_container_name pihole -w spclient.wg.spotify.com
docker exec pihole_container_name pihole -wild example.com
如有需要,可以自定义容器内的Web服务器和DNS服务。当容器启动或重新启动时,或者如果您需要修改位于/etc/dnsmasq.d/01-pihole.conf
Pi-hole 配置,您批量挂载到/etc/dnsmasq.d/
任何配置文件都将由 dnsmasq 加载/etc/dnsmasq.d/01-pihole.conf
。 docker 启动脚本在启动之前运行配置测试,因此它会告诉您 docker 日志中的任何错误。
同样,对于网络服务器,您可以在 /etc/lighttpd 中自定义配置
只要您的 docker 系统服务在启动时自动启动,并且您使用--restart=unless-stopped
运行容器,您的容器应该始终在启动时启动并在崩溃时重新启动。如果您希望将 docker 容器作为 systemd 服务运行,请将文件 pihole.service 添加到“/etc/systemd/system”;自定义容器名称并从 docker 运行中删除--restart=unless-stopped
。然后,在使用上面的 docker run 命令初始创建 docker 容器后,您可以使用“systemctl start pihole”或“systemctl stop pihole”(而不是docker start
/ docker stop
)来控制它。您还可以使用“systemctl enable pihole”使其在启动时自动启动(而不是--restart=unless-stopped
并确保 docker 服务在启动时自动启动)。
注意:初次运行后,您可能需要使用“docker stop pihole”手动停止 docker 容器,然后 systemctl 才能开始控制容器。
DNSMasq / FTLDNS 预计具有以下可用功能:
CAP_NET_BIND_SERVICE
:允许 FTLDNS 绑定到 1024 以下的 TCP/UDP 套接字(特别是端口 53 上的 DNS 服务)CAP_NET_RAW
:使用原始套接字和数据包套接字(需要处理 DHCPv6 请求,并在租赁 IP 之前验证 IP 未被使用)CAP_NET_ADMIN
:修改路由表和其他与网络相关的操作(特别是在邻居表中插入条目以使用单播数据包应答 DHCP 请求)CAP_SYS_NICE
:FTL 将自身设置为重要进程,以便在后者运行不足时获得更多处理时间CAP_CHOWN
:我们需要能够更改日志文件和数据库的所有权,以防 FTL 作为与pihole
不同的用户启动该映像会自动将这些功能(如果可用)授予 FTLDNS 进程,即使以非 root 身份运行也是如此。
默认情况下,docker 不包含非特权容器的NET_ADMIN
功能,建议使用--cap-add=NET_ADMIN
显式将其添加到容器中。
但是,如果未使用 DHCP 和 IPv6 路由器通告,则可以安全地跳过它。对于最偏执的人来说,甚至应该可以显式删除NET_RAW
功能以防止 FTLDNS 自动获取它。
我们注意到很多人使用 Watchtower 来保持 Pi-hole 容器的最新状态。出于同样的原因,我们不在裸机安装上提供自动更新功能,您也不应该让系统自动更新您的 Pi-hole 容器。特别是无人值守。尽管我们尽力确保不会出现任何问题,但有时确实会出现问题 - 您需要留出时间来手动拉取并更新到您希望运行的容器的版本。升级过程应遵循以下原则:
Pi-hole是你网络中不可或缺的一部分,不要因为半夜无人值守的更新而让它崩溃。
当您怀疑与 docker 相关的问题时,请报告 GitHub 项目上的问题。 Pi-hole 或一般 docker 问题最好在我们的用户论坛上得到解答。