Pi-hole

Обзор

Pi-hole — DNS-резолвер со списками блокировки. Установите его в доверенной сети и укажите в роутере как DNS-сервер: запросы к рекламным и отслеживающим доменам будут блокироваться для телефонов, телевизоров и других устройств без браузерных дополнений. Он подходит для домашней или небольшой частной сети, где администратор управляет DHCP или DNS-настройками клиентов. Это собственная альтернатива сервисам вроде NextDNS и AdGuard DNS.

Веб-интерфейс показывает недавние запросы, блокировки, клиентов и управление списками; сам интерфейс Pi-hole доступен только на английском языке. Pi-hole также поддерживает локальные DNS-записи. DNS-фильтрация не уберёт рекламу с того же домена, что и полезный контент, а клиент со своим зашифрованным DNS может обойти сетевой резолвер.

Рецепт запускает один официальный контейнер. В томе pi-hole-data хранятся pihole.toml, базы Gravity и запросов, а также данные списков. Порт DNS сначала слушает 127.0.0.1; для других устройств выберите конкретный адрес доверенной LAN или VPN. Веб-панель остаётся доступной только на loopback хоста.

Оценка безопасности

Контейнер использует bridge-сеть Docker без привилегированного режима, host networking и доступа к Docker socket. Для DNS нужен только порт 53; встроенные службы DHCP и NTP не опубликованы. Встроенный healthcheck официального образа проверяет готовность DNS.

Не привязывайте DNS к публичному интерфейсу: открытый резолвер может использоваться в атаках с усилением трафика. Администратор Pi-hole видит домены, запрошенные всеми клиентами, поэтому защищайте веб-панель паролем и HTTPS при удалённом доступе. Пароль в .env и архивы backup содержат чувствительные данные. См. официальную инструкцию Docker и справочник настроек.

Пошаговая инструкция

1. Подготовьте сервер

Нужны Ubuntu 22.04+ или Debian 12+ с Docker Engine и Docker Compose v2.24+. Выделите минимум одно ядро CPU, 512 МБ RAM и 2 ГБ диска; для хранения журнала запросов и нескольких списков лучше 1 ГБ RAM и 4 ГБ диска. Отдельная база не нужна. Проверьте инструменты и занятость порта 53:

docker --version
docker compose version
sudo ss -luntp | grep ':53 ' || true

systemd-resolved часто слушает 127.0.0.53, и это не обязательно конфликтует с привязкой рецепта к 127.0.0.1. Меняйте системный резолвер только при реальном конфликте адресов. Не направляйте /etc/resolv.conf на Pi-hole до его запуска.

2. Подготовьте рецепт

Поместите compose.yaml, .env.example, backup.sh, restore.sh и proxy/ в отдельный каталог и создайте приватный файл переменных:

mkdir -p ~/services/pi-hole
cd ~/services/pi-hole
cp .env.example .env
chmod 600 .env
openssl rand -hex 24

Замените пример PIHOLE_WEB_PASSWORD в .env сгенерированным значением. Не запускайте рабочий сервер с паролем из примера. Переменные:

• PIHOLE_VERSION — закреплённый официальный тег образа;
• PIHOLE_WEB_PASSWORD — пароль администратора;
• PIHOLE_DNS_BIND — адрес хоста для TCP и UDP DNS, сначала 127.0.0.1;
• PIHOLE_DNS_PORT — внешний порт DNS, обычно 53;
• PIHOLE_WEB_PORT — локальный порт панели, сначала 8080;
• PIHOLE_VOLUME — Docker volume со всеми постоянными данными Pi-hole;
• TZ — часовой пояс IANA для графиков и расписаний.

Compose устанавливает FTLCONF_dns_listeningMode=ALL, поскольку DNS-запросы приходят через bridge-сеть Docker. Слушатели DHCP (67/udp), NTP (123/udp) и встроенного HTTPS с самоподписанным сертификатом (443/tcp) не публикуются.

3. Запустите на VPS

docker compose config --quiet
docker compose pull
docker compose up -d --wait
docker compose ps

По умолчанию DNS и панель доступны только с самого хоста. На VPS оставьте DNS на приватном адресе VPN, например WireGuard или Tailscale: задайте адрес интерфейса в PIHOLE_DNS_BIND. Не используйте 0.0.0.0 или публичный адрес: открытые резолверы используют для DNS-амплификации. К панели можно подключиться через SSH-туннель:

ssh -L 8080:127.0.0.1:8080 user@server.example

Откройте http://localhost:8080/admin/ и войдите с паролем из .env. Панель Pi-hole пока доступна только на английском языке; скриншоты показывают её настоящий интерфейс. Проверьте DNS на хосте:

dig @127.0.0.1 pi.hole

Доверенная локальная сеть

Укажите в .env для PIHOLE_DNS_BIND конкретный LAN-адрес сервера, например 192.168.1.10, и пересоздайте контейнер:

docker compose up -d --wait
docker compose port pi-hole 53/udp

Разрешите UDP и TCP 53 только из доверенной подсети. Для UFW:

sudo ufw allow from 192.168.1.0/24 to 192.168.1.10 port 53 proto udp
sudo ufw allow from 192.168.1.0/24 to 192.168.1.10 port 53 proto tcp

Затем задайте 192.168.1.10 как DNS-сервер в DHCP-настройках роутера или настройте клиентов по отдельности. Проверьте с другого устройства командой nslookup pi.hole 192.168.1.10. DHCP самого Pi-hole в этом рецепте не включайте: bridge-сеть не передаёт нужные ему широковещательные пакеты.

Домен и HTTPS

Примеры proxy/Caddyfile, proxy/nginx.conf и proxy/traefik.yaml публикуют только веб-панель; замените dns.example.com своим доменом. Caddy получает сертификаты автоматически, Nginx ожидает сертификат Certbot, Traefik применяет настроенный resolver letsencrypt. Если Traefik запущен в контейнере, замените 127.0.0.1 на доступный ему адрес host gateway. Оставьте включённым вход в Pi-hole и ограничьте доступ к панели доверенными пользователями. Обычный DNS на порту 53 через HTTP proxy не проходит.

Резервное копирование

Все постоянные настройки, списки блокировки, база Gravity и журнал запросов лежат в Docker volume pi-hole-data (или в имени из PIHOLE_VOLUME). Скрипт ненадолго останавливает Pi-hole, чтобы SQLite-файлы сохранились согласованно:

chmod +x backup.sh restore.sh
./backup.sh

Скопируйте полученный ./backups/pi-hole-*.tar.gz за пределы сервера и защитите его: архив содержит историю DNS и конфигурацию. Пароль из .env хранится отдельно и тоже требует защиты. Экспорт Teleporter в интерфейсе полезен для части настроек, но для полного восстановления нужен архив всего тома.

Восстановление

Восстановление заменяет всё содержимое PIHOLE_VOLUME. Сначала скрипт создаёт страховочную копию текущего состояния:

./restore.sh ./backups/pi-hole-YYYYMMDDTHHMMSS.NNNNNNNNNZ.tar.gz
docker compose ps

Если пароль или имя тома менялись, отдельно восстановите соответствующий .env.

Обновление

Прочитайте заметки о выпуске Docker и создайте backup. Поменяйте PIHOLE_VERSION в .env на проверенный тег с датой; не используйте latest. Затем:

./backup.sh
docker compose pull
docker compose up -d --wait
docker compose logs --tail=100 pi-hole

Откат

Верните предыдущий закреплённый тег в .env, загрузите его и пересоздайте контейнер. Если новая версия изменила pihole.toml или базы SQLite, восстановите и архив до обновления: старый образ может не прочитать новые данные.

docker compose pull
docker compose up -d --wait
./restore.sh ./backups/pi-hole-YYYYMMDDTHHMMSS.NNNNNNNNNZ.tar.gz

Скрипт сначала сохраняет текущее состояние, затем заменяет том. После отката проверьте панель и DNS-запрос.

Остановка и удаление

docker compose down удаляет контейнер, сохраняя данные. После перевода роутера и клиентов на другой DNS-сервер удалите данные командой docker compose down --volumes (или удалите том с именем из PIHOLE_VOLUME). Сохраните нужные внешние backup-архивы. Если удалить резолвер раньше смены DNS у клиентов, разрешение имён перестанет работать.

Источники: официальная установка в Docker, настройки и capabilities, требования к оборудованию и конфигурация Pi-hole v6.

Сообщить о проблеме с рецептом

Рассказать, как прошло на вашем сервере

Откроется предзаполненный issue на GitHub. Нужен аккаунт GitHub; после отправки сообщение будет публичным.

Диагностика

Порт 53 уже занят

Проверьте точный адрес слушателя, а не только номер порта:

sudo ss -luntp | grep ':53 '
docker compose logs --tail=100 pi-hole

127.0.0.53 у systemd-resolved отличается от адреса рецепта по умолчанию 127.0.0.1. Если другая служба слушает 127.0.0.1:53 или все интерфейсы, выберите свободный конкретный адрес LAN/VPN либо перенастройте конфликтующую службу. Не меняйте системный резолвер, пока не подготовили рабочую замену.

Контейнер остаётся unhealthy

Healthcheck официального образа направляет DNS-запрос собственному процессу FTL:

docker compose ps
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q pi-hole)"
docker compose logs --tail=150 pi-hole

Если журнал сообщает о повреждённой базе, восстановите проверенный архив тома. При ошибке прав или диска проверьте том и свободное место.

Устройство в LAN не разрешает имена

docker compose port pi-hole 53/udp
nslookup pi.hole 192.168.1.10

Если Compose показывает 127.0.0.1, укажите реальный LAN-адрес в PIHOLE_DNS_BIND и пересоздайте контейнер. Разрешите в LAN-файрволе и TCP, и UDP 53. Проверьте, что роутер выдаёт тот же адрес по DHCP.

Реклама видна или сайт перестал работать

Проверьте журнал запросов: если там нет запросов клиента, он может использовать собственный DNS-over-HTTPS или другой DNS-сервер. Сетевая фильтрация не удалит контент, который приходит с того же домена, что и страница. Если сайт сломался, найдите заблокированный домен в Query Log и добавьте в разрешённые только его. Не отключайте всю блокировку из-за одного ложного срабатывания.

Не подходит пароль веб-панели

Убедитесь, что в .env задан нужный PIHOLE_WEB_PASSWORD, и пересоздайте контейнер командой docker compose up -d. Переменная FTLCONF_webserver_api_password задаёт пароль при каждом запуске. Не оставляйте пароль в истории команд и не публикуйте вывод docker inspect.

Восстановленный сервер выглядит новым

Убедитесь, что PIHOLE_VOLUME указывает на тот же том, что и backup, а архив содержит pihole.toml и gravity.db:

docker compose config
docker volume inspect pi-hole-data
tar -tzf ./backups/pi-hole-YYYYMMDDTHHMMSS.NNNNNNNNNZ.tar.gz | grep -E 'pihole.toml|gravity.db'

Не создавайте новые списки, пока не найдёте правильный том или не восстановите архив до обновления.