diff --git a/README.md b/README.md index f3a1486..45a8999 100644 --- a/README.md +++ b/README.md @@ -1,201 +1,189 @@ -# BBRKN DNS Configurator +# DNS Bypass Config Generator -## Описание +Этот проект автоматизирует генерацию конфигураций для **Pi-hole / dnsmasq**, чтобы маршрутизировать трафик к заблокированным доменам через VPN-туннель (WireGuard). -**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 и активируются перезапуском контейнера. +Скрипт `generate-configs.sh`: +- нормализует входные доменные имена; +- для каждого домена запрашивает внешний API (Chromium headless service); +- определяет, является ли домен **сайтом** (site), **сервисом** (service) или **мертвым**; +- формирует конфиги: + - `91-ipset-bbrkn.conf` — правила `ipset` для маркировки трафика; + - `92-resolve-bbrkn.conf` — правила `server=` для резолвинга через Google DNS. --- -## Архитектура +## Классификация доменов -```mermaid -flowchart TD - A[domains.txt] --> B[generate-configs.sh] - B -->|HTTP API| C[Chromium service
API_URL] - B --> D[91-ipset-bbrkn.conf
92-resolve-bbrkn.conf] - D --> E[deploy-to-gateway.sh] - E --> F[Pi-hole
dnsmasq] -``` +1. **Сайт (site)** + API возвращает JSON с полем `relatedDomains`. + В конфиги попадает **сам домен** + все связанные домены. + +2. **Сервис (service)** + API возвращает ошибку: + - `ERR_CERT_COMMON_NAME_INVALID` + - `ERR_CONNECTION_REFUSED` + В конфиги попадает только **сам домен**. + +3. **Мертвый домен** + API возвращает ошибку: + - `ERR_NAME_NOT_RESOLVED` + - `Timeout` + Такие домены полностью исключаются из конфигов. --- ## Переменные окружения -Все важные параметры конфигурируются через **переменные окружения**. -Если переменная не задана, используется дефолтное значение. - -| Переменная | По умолчанию | Назначение | -| ------------------ | ---------------------------------------- | ------------------------------------------- | -| `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:`. +| Переменная | Значение (по умолчанию) | Описание | +|----------------|-------------------------|----------| +| `DOMAINS_FILE` | `domains.txt` | Входной файл со списком доменов | +| `IPSET_CONF` | `/tmp/91-ipset-bbrkn.conf` | Файл с правилами ipset | +| `RESOLVE_CONF` | `/tmp/92-resolve-bbrkn.conf` | Файл с правилами server= | +| `CHROME_SERVER`| `http://127.0.0.1:3000` | Адрес API headless Chromium | +| `DNS_SERVER` | `8.8.8.8` | DNS для резолвинга через VPN | +| `DEBUG` | `0` | Включить (1) / выключить (0) отладку | +| `DEBUG_LOG` | `/tmp/generate-configs.debug.log` | Файл для подробного лога | --- -## Пример работы - -Пример запроса к Chromium-сервису: +## Запуск ```bash -curl "http://10.100.1.2:3000/domains?domain=pornhub.com" -``` +# обычный запуск +./generate-configs.sh -Ответ: +# отладочный режим +DEBUG=1 ./generate-configs.sh -```json -{ - "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" - ] -} -``` +# dry-run (ничего не пишет в файлы) +./generate-configs.sh --dry-run +```` -В итоговые конфиги будут добавлены все эти домены. +После запуска будут сгенерированы файлы: -Если сайт недоступен (например, сервисный домен): - -```bash -curl "http://10.100.1.2:3000/domains?domain=bt1.t-ru.org" -``` - -Ответ: - -```json -{ - "error": "page.goto: net::ERR_NAME_NOT_RESOLVED at https://bt1.t-ru.org/" -} -``` - -Такой домен будет классифицирован как `service` и попадёт в конфиг без связанных. +* `$IPSET_CONF` — список правил ipset; +* `$RESOLVE_CONF` — список правил server=. --- -## Установка и запуск +## Интеграция в CI/CD -### Требования +Переменные окружения передаются в `make` и далее в скрипт: -* Linux-система или self-hosted runner Forgejo -* [Pi-hole](https://pi-hole.net/) -* [jq](https://stedolan.github.io/jq/) для парсинга JSON -* make -* docker (для управления Pi-hole контейнером) -* доступ к сервису Chromium (по умолчанию: `http://10.100.1.2:3000/domains`) +```yaml +jobs: + generate-configs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 -### Ручной запуск - -```bash -make clean # очистка временных файлов -make check # только отчёт по доменам -make test # генерация + превью файлов -make deploy # генерация + деплой на шлюз + - name: Run generator + run: | + make generate-configs + env: + DOMAINS_FILE: domains.txt + IPSET_CONF: ./out/91-ipset-bbrkn.conf + RESOLVE_CONF: ./out/92-resolve-bbrkn.conf + CHROME_SERVER: http://chrome-headless:3000 + DNS_SERVER: 8.8.8.8 ``` -### Автоматический запуск (Forgejo CI/CD) +Файл `Makefile` прокидывает переменные дальше: -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`) +```make +generate-configs: + ./generate-configs.sh +``` --- -## Пример отладочного отчёта +## Архитектура решения + +```mermaid +flowchart TD + A[Клиент в локальной сети] -->|DNS запрос| B[Pi-hole DNS на шлюзе] + B -->|если домен заблокирован| C[Google DNS 8.8.8.8 через VPN] + C --> D[Ответ с IP] + D --> B + B -->|IP в ipset| E[iptables / netfilter] + E -->|маршрутизация по mark| F[VPN WireGuard] + F --> G[Интернет ресурс] + + subgraph "CI/CD" + X[domains.txt] --> Y[generate-configs.sh] + Y --> P1[ipset conf] + Y --> P2[resolve conf] + end +``` + +--- + +## Диаграмма потока обработки + +```mermaid +sequenceDiagram + participant Client + participant PiHole + participant ChromeAPI + participant VPN + participant Internet + + Client->>PiHole: DNS-запрос к домену + PiHole->>ChromeAPI: Проверка домена + ChromeAPI-->>PiHole: relatedDomains / error + PiHole->>VPN: Резолвинг через 8.8.8.8 (для заблокированных) + VPN->>Internet: Запрос к сайту + Internet-->>VPN: Ответ + VPN-->>PiHole: IP-адрес + PiHole-->>Client: Ответ DNS + Client->>Internet: Трафик с IP через VPN +``` + +--- + +## Отчёт после запуска + +Скрипт выводит статистику: + +* количество строк во входном файле; +* сколько доменов нормализовано / отброшено; +* сколько API-ответов успешные, сервисные, мёртвые; +* список **валидных основных сайтов**. + +--- + +## Пример ``` ===== DEBUG REPORT ===== -Original domains file: 50 entries -Final unique domains: 135 - - Base domains: 50 - - Related domains: 85 +Input file: domains.txt +Raw input lines: 100 +Processed lines: 100 +Normalized OK: 97 +Normalized skipped: 3 -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 -... -======================== +API success (sites): 25 +API error/ignored: 5 +Related domains added: 122 +Final unique domains: 140 + +---- VALID BASE SITES ---- +example1.com +example2.org +example3.info +===== END DEBUG REPORT ===== ``` --- -## Траблшутинг +## Зависимости -### 1. Chromium-сервис недоступен - -* Проверь, что сервис слушает на `${API_URL}`. -* Убедись, что firewall не блокирует доступ с runner-а. -* Можно протестировать напрямую: - - ```bash - 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`). +* `bash` +* `curl` +* `jq` --- -## Зачем это нужно? +## Лицензия -* Автоматически отслеживать **скрытые зависимости сайтов** (CDN, API-сервера и т.п.). -* Поддерживать актуальные списки для маршрутизации/блокировки/разделения трафика. -* Исключить ручную рутину: всё обновление конфигов делается одной командой или автоматически через CI/CD. \ No newline at end of file +MIT