BBRKN DNS Configurator

Описание

BBRKN — это инструмент для автоматического формирования и деплоя конфигураций для dnsmasq (через Pi-hole), необходимых для корректной работы целевых сайтов и сервисов.

Проект решает задачу: у нас есть список базовых доменов (domains.txt), но для работы сайтов часто требуется множество дополнительных ресурсов — CDN, API-эндпоинты, трекеры и т.д. Ручное отслеживание этих зависимостей неудобно.

Для этого используется сервис на базе Chromium, который автоматически анализирует страницу и возвращает список всех связанных доменов. Проект берёт этот список, нормализует его и формирует два конфигурационных файла для dnsmasq:

• 91-ipset-bbrkn.conf — добавляет все домены в ipset bbrkn
• 92-resolve-bbrkn.conf — указывает резолвить все эти домены через DNS-сервер 8.8.8.8

Эти файлы затем автоматически деплоятся в Pi-hole и активируются перезапуском контейнера.

---

Архитектура

flowchart TD
    A[domains.txt] --> B[generate-configs.sh]
    B -->|HTTP API| C[Chromium service<br/>API_URL]
    B --> D[91-ipset-bbrkn.conf<br/>92-resolve-bbrkn.conf]
    D --> E[deploy-to-gateway.sh]
    E --> F[Pi-hole<br/>dnsmasq]

---

Переменные окружения

Все важные параметры конфигурируются через переменные окружения. Если переменная не задана, используется дефолтное значение.

Переменная	По умолчанию	Назначение
INPUT_FILE	domains.txt	Входной список доменов
IPSET_CONF	/tmp/91-ipset-bbrkn.conf	Временный файл конфигурации для ipset
RESOLVE_CONF	/tmp/92-resolve-bbrkn.conf	Временный файл конфигурации для серверов
API_URL	http://10.100.1.2:3000/domains?domain=	Адрес API сервиса Chromium
DNS_SERVER	8.8.8.8	DNS-сервер, через который резолвятся домены
TARGET_DIR	/opt/appdata/pihole/etc/dnsmasq.d	Директория для установки конфигов в Pi-hole
DOCKER_CONTAINER	pihole	Имя контейнера Pi-hole

👉 В Forgejo workflow все эти переменные задаются в секции env:.

---

Пример работы

Пример запроса к Chromium-сервису:

curl "http://10.100.1.2:3000/domains?domain=pornhub.com"

Ответ:

{
  "domains": [
    "a.adtng.com",
    "cdn1-smallimg.phncdn.com",
    "ei.phncdn.com",
    "ht-cdn2.adtng.com",
    "media.trafficjunky.net",
    "pix-cdn77.phncdn.com",
    "pornhub.com",
    "www.pornhub.com"
  ]
}

В итоговые конфиги будут добавлены все эти домены.

Если сайт недоступен (например, сервисный домен):

curl "http://10.100.1.2:3000/domains?domain=bt1.t-ru.org"

Ответ:

{
  "error": "page.goto: net::ERR_NAME_NOT_RESOLVED at https://bt1.t-ru.org/"
}

Такой домен будет классифицирован как service и попадёт в конфиг без связанных.

---

Установка и запуск

Требования

• Linux-система или self-hosted runner Forgejo
• Pi-hole
• jq для парсинга JSON
• make
• docker (для управления Pi-hole контейнером)
• доступ к сервису Chromium (по умолчанию: http://10.100.1.2:3000/domains)

Ручной запуск

make clean     # очистка временных файлов
make check     # только отчёт по доменам
make test      # генерация + превью файлов
make deploy    # генерация + деплой на шлюз

Автоматический запуск (Forgejo CI/CD)

Workflow (.forgejo/workflows/deploy.yml) автоматически срабатывает при изменении domains.txt. CI делает:

1. Валидацию синтаксиса domains.txt
2. make clean
3. make all (генерация + деплой)
4. Сохранение артефактов (91-ipset-bbrkn.conf и 92-resolve-bbrkn.conf)

---

Пример отладочного отчёта

===== DEBUG REPORT =====
Original domains file: 50 entries
Final unique domains: 135
  - Base domains:     50
  - Related domains:  85

auth.openai.com - site
cdn.oaistatic.com - site
oaistatic.com - site
ab.chatgpt.com - site
realtime.chatgpt.com - site
ws.chatgpt.com - site
chatgpt.com - site
byspotify.com - site
pscdn.co - service
...
========================

---

Траблшутинг

1. Chromium-сервис недоступен

• Проверь, что сервис слушает на ${API_URL}.

• Убедись, что firewall не блокирует доступ с runner-а.

• Можно протестировать напрямую:

  curl "${API_URL}example.com"
  

  Если ответа нет или ошибка — перезапусти сервис.

2. В отчёте все домены помечены как service

Это значит, что сервис не смог открыть страницы. Возможные причины:

• Сайты блокируются провайдером → нужен обход (VPN/проксирование).
• Chromium-сервис работает без доступа к интернету.

3. Конфиги пустые или слишком маленькие

• Проверь содержимое domains.txt (убери комментарии, пустые строки).
• Убедись, что jq установлен (иначе парсинг JSON не сработает).
• В debug-отчёте будет видно, какие домены обработаны.

4. Pi-hole не поднимается после деплоя

• Запусти docker logs ${DOCKER_CONTAINER}, проверь ошибки.
• Откати конфиги из бэкапа (они создаются с суффиксом .backup.YYYYMMDD-HHMMSS).
• Убедись, что новые конфиги не содержат невалидных строк.

5. Forgejo CI падает

• Проверь, что runner имеет доступ к /tmp (для генерации файлов).
• Проверь, что установлены зависимости: make, jq, docker.
• Логи CI подскажут, на каком шаге сломалось (check, generate, deploy).

---

Зачем это нужно?

• Автоматически отслеживать скрытые зависимости сайтов (CDN, API-сервера и т.п.).
• Поддерживать актуальные списки для маршрутизации/блокировки/разделения трафика.
• Исключить ручную рутину: всё обновление конфигов делается одной командой или автоматически через CI/CD.