0x25/bbrkn

Kirill Kodanev 70bde9af2d Fix mermaid syntax

2025-09-11 20:01:09 +03:00

8.3 KiB

Raw Blame History

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
dnsmasq через 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 делает:

Валидацию синтаксиса domains.txt
make clean
make check
make all (генерация + деплой)
Сохранение артефактов (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.

8.3 KiB Raw Blame History Unescape Escape