Update README.md based on new version of the package
All checks were successful
Deploy DNS Configuration / deploy (push) Successful in 1m26s
All checks were successful
Deploy DNS Configuration / deploy (push) Successful in 1m26s
This commit is contained in:
Kirill Kodanev
parent
2e1a1bae74
commit
09fc9ef676
1 changed files with 144 additions and 156 deletions
300
README.md
300
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<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]
|
||||
```
|
||||
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.
|
||||
MIT
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue