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** — это инструмент для автоматического формирования и деплоя конфигураций
|
Скрипт `generate-configs.sh`:
|
||||||
для `dnsmasq` (через Pi-hole), необходимых для корректной работы целевых сайтов и сервисов.
|
- нормализует входные доменные имена;
|
||||||
|
- для каждого домена запрашивает внешний API (Chromium headless service);
|
||||||
Проект решает задачу: у нас есть список базовых доменов (`domains.txt`), но для работы
|
- определяет, является ли домен **сайтом** (site), **сервисом** (service) или **мертвым**;
|
||||||
сайтов часто требуется множество дополнительных ресурсов — CDN, API-эндпоинты,
|
- формирует конфиги:
|
||||||
трекеры и т.д. Ручное отслеживание этих зависимостей неудобно.
|
- `91-ipset-bbrkn.conf` — правила `ipset` для маркировки трафика;
|
||||||
|
- `92-resolve-bbrkn.conf` — правила `server=` для резолвинга через Google DNS.
|
||||||
Для этого используется сервис на базе Chromium, который автоматически анализирует
|
|
||||||
страницу и возвращает список всех связанных доменов. Проект берёт этот список,
|
|
||||||
нормализует его и формирует два конфигурационных файла для `dnsmasq`:
|
|
||||||
|
|
||||||
- `91-ipset-bbrkn.conf` — добавляет все домены в ipset `bbrkn`
|
|
||||||
- `92-resolve-bbrkn.conf` — указывает резолвить все эти домены через DNS-сервер `8.8.8.8`
|
|
||||||
|
|
||||||
Эти файлы затем автоматически деплоятся в Pi-hole и активируются перезапуском контейнера.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Архитектура
|
## Классификация доменов
|
||||||
|
|
||||||
```mermaid
|
1. **Сайт (site)**
|
||||||
flowchart TD
|
API возвращает JSON с полем `relatedDomains`.
|
||||||
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]
|
2. **Сервис (service)**
|
||||||
D --> E[deploy-to-gateway.sh]
|
API возвращает ошибку:
|
||||||
E --> F[Pi-hole<br/>dnsmasq]
|
- `ERR_CERT_COMMON_NAME_INVALID`
|
||||||
```
|
- `ERR_CONNECTION_REFUSED`
|
||||||
|
В конфиги попадает только **сам домен**.
|
||||||
|
|
||||||
|
3. **Мертвый домен**
|
||||||
|
API возвращает ошибку:
|
||||||
|
- `ERR_NAME_NOT_RESOLVED`
|
||||||
|
- `Timeout`
|
||||||
|
Такие домены полностью исключаются из конфигов.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Переменные окружения
|
## Переменные окружения
|
||||||
|
|
||||||
Все важные параметры конфигурируются через **переменные окружения**.
|
| Переменная | Значение (по умолчанию) | Описание |
|
||||||
Если переменная не задана, используется дефолтное значение.
|
|----------------|-------------------------|----------|
|
||||||
|
| `DOMAINS_FILE` | `domains.txt` | Входной файл со списком доменов |
|
||||||
| Переменная | По умолчанию | Назначение |
|
| `IPSET_CONF` | `/tmp/91-ipset-bbrkn.conf` | Файл с правилами ipset |
|
||||||
| ------------------ | ---------------------------------------- | ------------------------------------------- |
|
| `RESOLVE_CONF` | `/tmp/92-resolve-bbrkn.conf` | Файл с правилами server= |
|
||||||
| `INPUT_FILE` | `domains.txt` | Входной список доменов |
|
| `CHROME_SERVER`| `http://127.0.0.1:3000` | Адрес API headless Chromium |
|
||||||
| `IPSET_CONF` | `/tmp/91-ipset-bbrkn.conf` | Временный файл конфигурации для ipset |
|
| `DNS_SERVER` | `8.8.8.8` | DNS для резолвинга через VPN |
|
||||||
| `RESOLVE_CONF` | `/tmp/92-resolve-bbrkn.conf` | Временный файл конфигурации для серверов |
|
| `DEBUG` | `0` | Включить (1) / выключить (0) отладку |
|
||||||
| `API_URL` | `http://10.100.1.2:3000/domains?domain=` | Адрес API сервиса Chromium |
|
| `DEBUG_LOG` | `/tmp/generate-configs.debug.log` | Файл для подробного лога |
|
||||||
| `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-сервису:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl "http://10.100.1.2:3000/domains?domain=pornhub.com"
|
# обычный запуск
|
||||||
```
|
./generate-configs.sh
|
||||||
|
|
||||||
Ответ:
|
# отладочный режим
|
||||||
|
DEBUG=1 ./generate-configs.sh
|
||||||
|
|
||||||
```json
|
# dry-run (ничего не пишет в файлы)
|
||||||
{
|
./generate-configs.sh --dry-run
|
||||||
"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"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
В итоговые конфиги будут добавлены все эти домены.
|
После запуска будут сгенерированы файлы:
|
||||||
|
|
||||||
Если сайт недоступен (например, сервисный домен):
|
* `$IPSET_CONF` — список правил ipset;
|
||||||
|
* `$RESOLVE_CONF` — список правил server=.
|
||||||
```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` и попадёт в конфиг без связанных.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Установка и запуск
|
## Интеграция в CI/CD
|
||||||
|
|
||||||
### Требования
|
Переменные окружения передаются в `make` и далее в скрипт:
|
||||||
|
|
||||||
* Linux-система или self-hosted runner Forgejo
|
```yaml
|
||||||
* [Pi-hole](https://pi-hole.net/)
|
jobs:
|
||||||
* [jq](https://stedolan.github.io/jq/) для парсинга JSON
|
generate-configs:
|
||||||
* make
|
runs-on: ubuntu-latest
|
||||||
* docker (для управления Pi-hole контейнером)
|
steps:
|
||||||
* доступ к сервису Chromium (по умолчанию: `http://10.100.1.2:3000/domains`)
|
- uses: actions/checkout@v3
|
||||||
|
|
||||||
### Ручной запуск
|
- name: Run generator
|
||||||
|
run: |
|
||||||
```bash
|
make generate-configs
|
||||||
make clean # очистка временных файлов
|
env:
|
||||||
make check # только отчёт по доменам
|
DOMAINS_FILE: domains.txt
|
||||||
make test # генерация + превью файлов
|
IPSET_CONF: ./out/91-ipset-bbrkn.conf
|
||||||
make deploy # генерация + деплой на шлюз
|
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`.
|
```make
|
||||||
CI делает:
|
generate-configs:
|
||||||
|
./generate-configs.sh
|
||||||
1. Валидацию синтаксиса `domains.txt`
|
```
|
||||||
2. `make clean`
|
|
||||||
3. `make all` (генерация + деплой)
|
|
||||||
4. Сохранение артефактов (`91-ipset-bbrkn.conf` и `92-resolve-bbrkn.conf`)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Пример отладочного отчёта
|
## Архитектура решения
|
||||||
|
|
||||||
|
```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 =====
|
===== DEBUG REPORT =====
|
||||||
Original domains file: 50 entries
|
Input file: domains.txt
|
||||||
Final unique domains: 135
|
Raw input lines: 100
|
||||||
- Base domains: 50
|
Processed lines: 100
|
||||||
- Related domains: 85
|
Normalized OK: 97
|
||||||
|
Normalized skipped: 3
|
||||||
|
|
||||||
auth.openai.com - site
|
API success (sites): 25
|
||||||
cdn.oaistatic.com - site
|
API error/ignored: 5
|
||||||
oaistatic.com - site
|
Related domains added: 122
|
||||||
ab.chatgpt.com - site
|
Final unique domains: 140
|
||||||
realtime.chatgpt.com - site
|
|
||||||
ws.chatgpt.com - site
|
---- VALID BASE SITES ----
|
||||||
chatgpt.com - site
|
example1.com
|
||||||
byspotify.com - site
|
example2.org
|
||||||
pscdn.co - service
|
example3.info
|
||||||
...
|
===== END DEBUG REPORT =====
|
||||||
========================
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Траблшутинг
|
## Зависимости
|
||||||
|
|
||||||
### 1. Chromium-сервис недоступен
|
* `bash`
|
||||||
|
* `curl`
|
||||||
* Проверь, что сервис слушает на `${API_URL}`.
|
* `jq`
|
||||||
* Убедись, что 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`).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Зачем это нужно?
|
## Лицензия
|
||||||
|
|
||||||
* Автоматически отслеживать **скрытые зависимости сайтов** (CDN, API-сервера и т.п.).
|
MIT
|
||||||
* Поддерживать актуальные списки для маршрутизации/блокировки/разделения трафика.
|
|
||||||
* Исключить ручную рутину: всё обновление конфигов делается одной командой или автоматически через CI/CD.
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue