From 2611b099ce25628a8624b750fdb9a64a3bf0439c Mon Sep 17 00:00:00 2001 From: Magnus Root Date: Thu, 16 Apr 2026 15:21:23 +0300 Subject: [PATCH] Renew docs --- ARCHITECTURE.md | 395 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 265 ++++++++++++++++++++++++-------- 2 files changed, 595 insertions(+), 65 deletions(-) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..64ae664 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,395 @@ +# Auspex — Architecture + +## Обзор + +Auspex — монолитное CLI-приложение на Go. Все модули живут в одном пакете `main`, конфигурация глобальная, каналы доставки алертов shared. Такой подход выбран осознанно — утилита запускается по cron, живёт секунды, сложная изоляция не нужна. + +``` +┌─────────────────────────────────────────────────────┐ +│ auspex │ +│ │ +│ main.go ──► runByFlag() / showMenu() │ +│ │ │ +│ ┌──────────┼──────────────┐ │ +│ ▼ ▼ ▼ │ +│ certcheck portcheck logcheck ... │ +│ │ │ │ │ +│ └──────────┴──────────────┘ │ +│ │ │ +│ Alert Pipeline │ +│ ┌──────────┼──────────────┐ │ +│ ▼ ▼ ▼ │ +│ telegram email mattermost │ +└─────────────────────────────────────────────────────┘ +``` + +--- + +## Файлы и их роли + +### `main.go` — точка входа + +Отвечает за два режима запуска: + +**CLI-флаги** (`runByFlag`): прямой вызов нужного модуля по флагу (`-c`, `-p`, `-l`, `-sv`, `-d`, `-m`, `-ss`). + +**Интерактивное меню** (`showMenu`): ASCII-баннер, numbered menu, `bufio.Reader` для ввода. Поддерживает как цифры (`1`-`7`), так и текстовые алиасы (`-c`, `c`). + +``` +auspex [флаг] [аргументы] + │ + ├── -ss → runPortsView() + ├── -c → runCertCheck() + ├── -p → runPortCheck() + ├── -m → runMatchCheck(clientFilter) + ├── -l → runLogCheck() + ├── -sv → runServiceCheck() + ├── -d → runDockerCheck() + ├── -v → версия + └── -h → usage +``` + +--- + +### `config.go` — конфигурация + +Все настройки — глобальные переменные вида `cfgXxx`. Загрузка из `/etc/auspex/auspex.env` при старте через `loadConfig()` → `applyConfig()`. + +Формат `.env`: +``` +KEY=VALUE # кавычки обрезаются автоматически +# комментарии игнорируются +``` + +Если файл не найден — используются значения по умолчанию, вывод предупреждения в stdout. Программа продолжает работу. + +**Группы переменных:** +- Telegram (токен, chat ID, прокси) +- Mattermost (URL, токен бота, channel ID) +- Email/SMTP (хост, порт, логин, пароль, from, to) +- PostgreSQL (user, password, dbname, port, primary host, secondary host) +- Пути (SSL dir, nginx glob, log dir, state files) +- Пороги (cert days, log stale minutes) +- Параметры проверки (timeout, retries, workers) +- Список служб для проверки + +**Вспомогательные функции:** +- `isTelegramConfigured()` — проверяет наличие токена и chat ID +- `isEmailConfigured()` — проверяет host, from, to +- `isMattermostConfigured()` — проверяет URL, токен, channel ID +- `printConfigStatus()` — выводит статус всех каналов при запуске + +--- + +### `telegram.go` — доставка в Telegram + +**Функции отправки:** +- `telegramSendHTML(message)` — HTML-форматирование (теги ``, ``, ``) +- `telegramSendPlainText(message)` — plain text без форматирования (используется в portcheck) + +**Цепочка прокси (`telegramHTTPClients`):** + +Возвращает срез `[]*http.Client` в порядке приоритета: + +``` +1. HTTP прокси (если задан TELEGRAM_HTTP_PROXY) +2. SOCKS5 (если задан TELEGRAM_SOCKS5_PROXY) +3. Прямое (всегда, как последний fallback) +``` + +`telegramDoPost` и `telegramDoPostForm` перебирают клиентов по очереди. При ошибке одного — переходят к следующему с логом предупреждения. Успешный вариант логируется. + +**SOCKS5:** реализован через `golang.org/x/net/proxy`. Логин/пароль задаются отдельными переменными (не в URL) — это исключает проблемы со спецсимволами вроде `!` и `$` в паролях. + +**HTTP прокси:** реализован через стандартный `http.Transport{Proxy: http.ProxyURL(...)}`. + +--- + +### `email.go` — доставка по Email + +**`emailSendHTML(subject, message)`** — отправка HTML-письма через SMTP. + +Особенности реализации: +- Telegram-теги (``, ``, ``) являются валидным HTML и отображаются в письме без конвертации +- `\n` заменяются на `
` для корректного отображения переносов строк +- Письмо оборачивается в HTML-шаблон с CSS стилями (`emailBuildHTML`) +- Поддерживается `AUTH LOGIN` (тип авторизации который использует Microsoft Exchange и многие корпоративные серверы) через кастомный `emailLoginAuth`, реализующий интерфейс `smtp.Auth` +- Стандартный `smtp.PlainAuth` намеренно не используется — он несовместим с рядом серверов +- Порт 587 + STARTTLS работает автоматически через `smtp.SendMail` +- `EMAIL_TO` поддерживает несколько адресов через запятую + +**Диагностика при неполной конфигурации:** +- Не задан HOST/FROM/TO → лог `[Email] Не настроен — пропускаем` +- Не задан USER или PASSWORD → предупреждение, попытка без авторизации (для relay-серверов) +- Ошибка SMTP → лог с кодом ответа и телом ошибки + +--- + +### `mattermost.go` — доставка в Mattermost + +**`mattermostSend(message)`** — отправка через Bot API. + +Endpoint: `POST /api/v4/posts` с заголовком `Authorization: Bearer `. + +Успешный ответ: `201 Created` (не `200`, как в большинстве API). + +**`mmHTMLToMarkdown(html)`** — конвертер форматирования: + +| HTML (Telegram) | Markdown (Mattermost) | +|---|---| +| `текст` | `**текст**` | +| `текст` | `_текст_` | +| `текст` | `` `текст` `` | +| `
текст
` | ` ```текст``` ` | +| `━━━━━` | `---` | +| `<` `>` `&` | `<` `>` `&` | +| Прочие теги | удаляются | + +--- + +### `certcheck.go` — проверка SSL сертификатов + +**Точка входа:** `runCertCheck()` + +**Алгоритм:** +1. `ccFindCerts(cfgSSLDir)` — рекурсивный обход директории, фильтрация по расширениям (`.crt`, `.pem`, `.cer`, `.cert`, `.der`, `.p7b`, `.p7c`, `.p7s`, `.csr`) +2. Параллельный парсинг через пул горутин (`cfgMaxWorkers`) +3. `ccParseCert(path)` — определение формата (PEM/DER), парсинг через `crypto/x509`, вычисление `daysLeft` +4. `ccCheckAndAlert(cert)` — сравнение с порогами и отправка алерта + +**Уровни алертов:** + +| Условие | Emoji | Уровень | +|---|---|---| +| `daysLeft < 0` | 💀💀💀 | Сертификат истёк | +| `daysLeft <= CERT_CRITICAL_DAYS` | 🚨🚨🚨 | Критично | +| `daysLeft <= CERT_WARNING_DAYS` | ⚠️⚠️ | Предупреждение | +| `daysLeft <= CERT_INFO_DAYS` | ℹ️ | Информация | +| Иначе | — | Алерт не нужен | + +--- + +### `portcheck.go` — проверка доступности портов + +**Точка входа:** `runPortCheck()` + +**Алгоритм:** +1. Подключение к PostgreSQL (primary → secondary failover) +2. Загрузка карты `check_ports` из таблицы `apps_settings` — какие конфиги проверять +3. `pcParseNginxConfig(file)` — парсинг `upstream { server ip:port; }` блоков regex'ом +4. Дедупликация endpoint'ов по всем файлам +5. Параллельная TCP-проверка (`net.DialTimeout`) с повторами (`cfgMaxRetries`) +6. `pcCompareStates` — сравнение с предыдущим state-файлом +7. Отправка алерта только при изменениях + +**State-файл** (`/tmp/port_checker_state.json`): +```json +{ + "timestamp": "2026-04-14 13:10:10", + "status": { + "91.206.126.83:443": {"endpoint": "...", "available": true, "config_file": "Client_12345"} + } +} +``` + +**Имена конфигов** строятся из имени файла без расширения: `Client_12345.conf` → `Client_12345`. + +--- + +### `logcheck.go` — проверка свежести логов + +**Точка входа:** `runLogCheck()` + +**Алгоритм (4 шага через PostgreSQL):** +1. `lcGetInstancesByHostname` — инстансы для текущего хоста (`instances_new`) +2. `lcGetClientsByInstances` — клиенты для этих инстансов (`client_info`) +3. `lcGetAppsByClients` — приложения с `check_write_logs = true` (`apps_settings`) +4. `lcCheckLogFile` — поиск файла по паттерну `{LOG_DIR}/*/*/{l7resourceid}*_access.log`, проверка `ModTime` + +Файл считается устаревшим если `time.Since(ModTime) > cfgLogStaleMinutes`. + +**Уровни в алерте** по времени с последней записи: + +| Минут | Emoji | +|---|---| +| 61–120 | ⚠️ | +| 121–240 | 🔥 | +| > 240 | 💀 | + +--- + +### `matchcheck.go` — проверка совпадений Angie ↔ Docker + +**Точка входа:** `runMatchCheck(clientFilter)` + +Проверяет соответствие между портами в конфигах Angie и запущенными Docker контейнерами. Поддерживает фильтрацию по имени клиента. + +**Алгоритм:** +1. Парсинг конфигов Angie из `cfgAngieConfDir` — извлечение портов на которых слушает Angie +2. `docker ps` — список запущенных контейнеров с их портами +3. Сопоставление: для каждого клиента проверяется есть ли соответствующий контейнер и совпадают ли порты +4. Алерт при расхождениях + +--- + +### `servicecheck.go` — проверка служб systemd + +**Точка входа:** `runServiceCheck()` + +**Алгоритм:** +1. Параллельная проверка всех служб из `cfgServicesToCheck` через горутины +2. `scCheckService(name)` — `systemctl is-active ` + `systemctl show --property=SubState,Description` +3. Загрузка предыдущего state-файла +4. `scCompareStates` — сравнение текущих статусов с предыдущими +5. Алерт только при изменениях + +**State-файл** (`/tmp/auspex_service_state.json`): +```json +{ + "timestamp": "2026-04-14 13:00:00", + "services": { + "angie": "active", + "docker": "failed" + } +} +``` + +**Типы изменений в алерте:** + +| Изменение | Emoji | +|---|---| +| `active` → любой другой | ❌ | +| любой → `active` | ✅ (восстановление) | +| `failed` | 💀 | +| `inactive` | 🔴 | +| `activating/deactivating` | 🟡 | + +--- + +### `dockercheck.go` — проверка Docker контейнеров + +**Точка входа:** `runDockerCheck()` + +**Алгоритм:** +1. `dcCheckDockerAvailable()` — `docker info` для проверки доступности демона +2. `dcGetContainers()` — `docker ps -a --format '{{.ID}}|{{.Names}}|{{.Status}}|{{.Image}}'` +3. `dcGetHealth(id)` — `docker inspect --format '{{if .State.Health}}...{{end}}'` для каждого контейнера отдельно (`.Health` недоступен в `docker ps` в ряде сборок) +4. Нормализация статуса: `"Up 2 hours"` → `"running"`, `"Exited (1) 3 min ago"` → `"exited"` +5. `dcCompareStates` — сравнение с предыдущим state-файлом +6. Алерт только при изменениях + +**Типы событий:** + +| Kind | Условие | Emoji | +|---|---|---| +| `appeared` | Новый контейнер (не при первом запуске) | 🆕 | +| `disappeared` | Контейнер исчез из `docker ps -a` | 👻 | +| `status_changed` → не running | Упал/завис | 🔴 💀 🔄 | +| `status_changed` → running | Восстановился | ✅ | +| `health_changed` → unhealthy | Нездоров | 🤒 | +| `health_changed` → healthy | Оздоровился | ✅ | + +**State-файл** (`/tmp/auspex_docker_state.json`): +```json +{ + "timestamp": "2026-04-14 13:00:00", + "containers": { + "portainer": {"status": "running", "health": "none"}, + "zabbix-agent-7.0": {"status": "running", "health": "none"} + } +} +``` + +--- + +### `portsview.go` — TUI просмотр портов + +**Точка входа:** `runPortsView()` + +Интерактивный TUI на базе [Bubble Tea](https://github.com/charmbracelet/bubbletea). Показывает занятые порты на хосте (`ss -tlnp` / `netstat`). Поддерживает фильтрацию, навигацию клавишами. + +--- + +## Pipeline доставки алертов + +Все модули с алертами следуют единому паттерну: + +```go +// 1. Telegram +if err := telegramSendHTML(message); err != nil { + log.Printf("❌ Ошибка отправки в Telegram: %v", err) +} else { + log.Println("✅ Алерт успешно отправлен в Telegram") +} + +// 2. Email +if err := emailSendHTML("Тема", message); err != nil { + log.Printf("❌ Ошибка отправки Email: %v", err) +} else { + log.Println("✅ Алерт успешно отправлен на Email") +} + +// 3. Mattermost +if err := mattermostSend(message); err != nil { + log.Printf("❌ Ошибка отправки в Mattermost: %v", err) +} else { + log.Println("✅ Алерт успешно отправлен в Mattermost") +} +``` + +Все три вызова независимы — ошибка одного не влияет на остальные. + +--- + +## Паттерн state-файлов + +Модули `-p`, `-sv`, `-d` используют одинаковый механизм для предотвращения спама при запуске по cron: + +``` +Запуск N: Загрузить prev_state → Получить curr_state → Compare → Alert if changed → Save curr_state +Запуск N+1: Загрузить prev_state → Получить curr_state → Compare → ... +``` + +**Первый запуск** (state-файл отсутствует): состояние сохраняется, алерты не отправляются. Исключение: в `dockercheck` появление нового контейнера (`dcKindAppeared`) тоже не алертится при первом запуске — флаг `isFirstRun` передаётся в `dcCompareStates`. + +--- + +## Параллелизм + +| Модуль | Механизм | +|---|---| +| `certcheck` | Пул горутин (`cfgMaxWorkers`) через канал задач | +| `servicecheck` | Горутина на каждую службу + `sync.WaitGroup` | +| `dockercheck` | Последовательно (inspect на каждый контейнер отдельно) | +| `portcheck` | Горутина на каждый endpoint | + +--- + +## Работа с PostgreSQL + +Модули `portcheck` и `logcheck` используют PostgreSQL с failover: + +``` +primary (cfgPrimaryDBHost) → ping OK? → использовать + → ping fail → secondary (cfgSecondaryDBHost) +``` + +Каждый модуль реализует свой `pcConnectDB()` / `lcConnectDB()` — функции идентичны по логике, префиксы разные для избежания коллизий имён в пакете `main`. + +--- + +## Соглашения по именованию + +Все идентификаторы в каждом модуле имеют уникальный префикс — это позволяет всем файлам жить в одном пакете `main` без конфликтов: + +| Модуль | Префикс | +|---|---| +| certcheck | `cc` | +| portcheck | `pc` | +| logcheck | `lc` | +| matchcheck | `mc` | +| servicecheck | `sc` | +| dockercheck | `dc` | +| email | `email` | +| mattermost | `mm` | +| config | `cfg` | \ No newline at end of file diff --git a/README.md b/README.md index 2ef5f0f..e93dc41 100644 --- a/README.md +++ b/README.md @@ -7,38 +7,30 @@ | Ключ | Описание | |------|----------| | `-ss` | Просмотр занятых портов (интерактивный TUI на bubbletea) | -| `-c` | Проверка SSL сертификатов (сроки истечения, алерты в Telegram) | +| `-c` | Проверка SSL сертификатов (сроки истечения, алерты) | | `-p` | Проверка доступности портов из nginx upstream конфигов | | `-m` | Проверка совпадений портов Angie ↔ Docker (+ проверка запуска контейнеров) | | `-l` | Проверка обновления файлов PT AF access logs | -| `-sv` | Проверка работоспособности служб | -| `-dv` или `-d` | Проверка работоспособности контейнеров | +| `-sv` | Проверка работоспособности служб systemd | +| `-d` или `-dc` | Проверка работоспособности Docker контейнеров | ## Структура проекта ``` auspex/ -├── cmd/auspex/ -│ └── main.go # Точка входа, меню, роутинг CLI-флагов -├── internal/ -│ ├── config/ -│ │ └── config.go # Общая конфигурация (хардкод + env) -│ ├── telegram/ -│ │ └── telegram.go # Общий клиент Telegram -│ ├── portsview/ -│ │ └── portsview.go # -ss: TUI просмотр портов -│ ├── certcheck/ -│ │ └── certcheck.go # -c: проверка сертификатов -│ ├── portcheck/ -│ │ └── portcheck.go # -p: проверка доступности портов -│ └── matchcheck/ -│ | └── matchcheck.go # -m: совпадения Angie ↔ Docker -│ └── servicecheck/ -│ | └── servicecheck.go # -sv: проверка работоспособности служб -│ └── dockercheck/ -│ └── dockercheck.go # -dv или -d: проверка работоспособности служб +├── main.go # Точка входа, меню, роутинг CLI-флагов +├── config.go # Глобальная конфигурация (переменные + загрузка из .env) +├── telegram.go # Отправка алертов в Telegram (поддержка HTTP и SOCKS5 прокси) +├── email.go # Отправка алертов по Email (SMTP, AUTH LOGIN) +├── mattermost.go # Отправка алертов в Mattermost (Bot API) +├── certcheck.go # -c: проверка SSL сертификатов +├── portcheck.go # -p: проверка доступности портов +├── matchcheck.go # -m: совпадения Angie ↔ Docker +├── logcheck.go # -l: проверка свежести логов +├── servicecheck.go # -sv: проверка служб systemd +├── dockercheck.go # -d: проверка Docker контейнеров +├── portsview.go # -ss: TUI просмотр занятых портов ├── go.mod -├── Makefile └── README.md ``` @@ -46,7 +38,8 @@ auspex/ ```bash go mod tidy -go build -o auspex +go build -o auspex . +sudo cp auspex /usr/local/bin/auspex ``` ## Использование @@ -63,56 +56,198 @@ go build -o auspex ./auspex -m client_name # Проверка конкретного клиента ./auspex -l # Проверка свежести логов ./auspex -sv # Проверка работоспособности служб -./auspex -dv или -d # Проверка работоспособности контейнеров +./auspex -d # Проверка работоспособности контейнеров ./auspex -h # Справка ./auspex -v # Версия ``` ## Конфигурация -Все настройки находятся в `config.go`. +Конфигурация загружается из `/etc/auspex/auspex.env`. Если файл не найден — используются значения по умолчанию. Формат файла: `KEY=VALUE`, комментарии через `#`. -### Переменные окружения +```bash +sudo mkdir -p /etc/auspex +sudo nano /etc/auspex/auspex.env +``` -| Переменная | Описание | Значение по умолчанию | -|------------|----------|----------------------| -| `AUSPEX_TELEGRAM_BOT_TOKEN` | Токен Telegram бота | `YOUR_BOT_TOKEN` | -| `AUSPEX_TELEGRAM_CHAT_ID` | Chat ID для алертов | `YOUR_CHAT_ID` | -| `AUSPEX_PTAF_BASE_DIR` | Базовая директория PTAF | `/home/install/ptaf` | -| `AUSPEX_ANGIE_CONF_DIR` | Директория конфигов Angie | `/etc/angie/http.d` | -| `AUSPEX_SSL_DIR` | Директория SSL сертификатов | `/etc/ssl` | -| `AUSPEX_NGINX_CONFIG_GLOB` | Glob-путь к nginx конфигам | `/home/install/conf/ptaf-nginx/*/*/*/*.conf` | -| `AUSPEX_STATE_FILE_PATH` | Файл состояния port checker | `/tmp/port_checker_state.json` | -| `AUSPEX_CHECK_TIMEOUT_SEC` | Таймаут проверки порта (сек) | `10` | -| `AUSPEX_MAX_RETRIES` | Количество повторов | `3` | -| `AUSPEX_RETRY_DELAY_SEC` | Задержка между повторами (сек) | `2` | -| `AUSPEX_CERT_CRITICAL_DAYS` | Порог критического алерта (дни) | `3` | -| `AUSPEX_CERT_WARNING_DAYS` | Порог предупреждения (дни) | `15` | -| `AUSPEX_CERT_INFO_DAYS` | Порог информирования (дни) | `30` | -| `cfgDBUser` | БД юзер | `user` | -| `cfgDBPassword` | БД пароль | `qJBrR` | -| `cfgDBName` | Название БД | `waf_info` | -| `cfgDBPort` | Порт БД | `5432` | -| `cfgPrimaryDBHost` | Основная БД | `10.100.10.8` | -| `cfgSecondaryDBHost` | Резервная БД | `10.100.13.5` | -| `SERVICES_TO_CHECK ` | Службы для проверки | `ansible,docker` | -| `EMAIL_SMTP_HOST` | Адрес почтового сервера | `smtp.example.com` | -| `EMAIL_SMTP_PORT` | Порт почтового сервера | `587` | -| `EMAIL_SMTP_USER` | Юзер для отправки | `auspex@example.com` | -| `EMAIL_SMTP_PASSWORD` | Пароль | `secret` | -| `EMAIL_FROM` | Юзер для отправки | `auspex@example.com` | -| `EMAIL_TO` | Получатели | `admin1@example.com, admin2@example.com` | +### Полный список параметров -## Зависимости +#### Telegram -- Go 1.22+ -- github.com/charmbracelet/bubbletea (TUI фреймворк для `-ss`) -- github.com/charmbracelet/bubbles (компоненты TUI) -- github.com/charmbracelet/lipgloss (стилизация TUI) -- github.com/lib/pq (запросы в БД) +| Переменная | Описание | По умолчанию | +|------------|----------|--------------| +| `TELEGRAM_BOT_TOKEN` | Токен бота | — | +| `TELEGRAM_CHAT_ID` | ID чата для алертов | — | +| `TELEGRAM_HTTP_PROXY` | HTTP прокси: `http://user:pass@host:port` | — | +| `TELEGRAM_SOCKS5_PROXY` | SOCKS5 прокси: `host:port` | — | +| `TELEGRAM_SOCKS5_USER` | Логин SOCKS5 прокси | — | +| `TELEGRAM_SOCKS5_PASSWORD` | Пароль SOCKS5 прокси (спецсимволы безопасны) | — | -## Требования на хосте +Порядок попыток при отправке: **HTTP прокси → SOCKS5 → прямое соединение**. Если один вариант недоступен — автоматически используется следующий. -- `ss` или `netstat` — для просмотра портов -- `docker` — для проверки запущенных контейнеров (флаг `-m`) -- `ps` — для деталей процессов (флаг `-ss`) +#### Email / SMTP + +| Переменная | Описание | По умолчанию | +|------------|----------|--------------| +| `EMAIL_SMTP_HOST` | Адрес SMTP сервера | — | +| `EMAIL_SMTP_PORT` | Порт SMTP (STARTTLS) | `587` | +| `EMAIL_SMTP_USER` | Логин SMTP | — | +| `EMAIL_SMTP_PASSWORD` | Пароль SMTP | — | +| `EMAIL_FROM` | Адрес отправителя | — | +| `EMAIL_TO` | Адреса получателей (через запятую) | — | + +Поддерживается AUTH LOGIN (Exchange/корпоративные серверы). Если `EMAIL_SMTP_HOST` не задан — отправка молча пропускается. + +#### Mattermost + +| Переменная | Описание | По умолчанию | +|------------|----------|--------------| +| `MATTERMOST_URL` | URL сервера: `https://mattermost.example.com` | — | +| `MATTERMOST_BOT_TOKEN` | Токен бота | — | +| `MATTERMOST_CHANNEL_ID` | ID канала для отправки | — | + +Используется Bot API (`POST /api/v4/posts`). HTML-теги из Telegram автоматически конвертируются в Markdown. + +#### PostgreSQL + +| Переменная | Описание | По умолчанию | +|------------|----------|--------------| +| `DB_USER` | Пользователь БД | — | +| `DB_PASSWORD` | Пароль БД | — | +| `DB_NAME` | Название БД | `waf_info` | +| `DB_PORT` | Порт БД | `5432` | +| `PRIMARY_DB_HOST` | Основной хост БД | `10.100.10.8` | +| `SECONDARY_DB_HOST` | Резервный хост БД | `10.100.13.5` | + +#### Пути + +| Переменная | Описание | По умолчанию | +|------------|----------|--------------| +| `PTAF_BASE_DIR` | Базовая директория PTAF | `/home/install/ptaf` | +| `ANGIE_CONF_DIR` | Директория конфигов Angie | `/etc/angie/http.d` | +| `SSL_DIR` | Директория SSL сертификатов | `/etc/ssl` | +| `NGINX_CONFIG_GLOB` | Glob-путь к nginx конфигам | `/home/install/conf/ptaf-nginx/*/*/*/*.conf` | +| `LOG_DIR` | Директория access логов | `/var/log/ptaf_nginx` | +| `STATE_FILE_PATH` | State-файл portcheck | `/tmp/port_checker_state.json` | +| `SERVICE_STATE_FILE_PATH` | State-файл servicecheck | `/tmp/auspex_service_state.json` | +| `DOCKER_STATE_FILE_PATH` | State-файл dockercheck | `/tmp/auspex_docker_state.json` | + +#### Пороги сертификатов + +| Переменная | Описание | По умолчанию | +|------------|----------|--------------| +| `CERT_CRITICAL_DAYS` | Критический алерт (дней до истечения) | `3` | +| `CERT_WARNING_DAYS` | Предупреждение | `15` | +| `CERT_INFO_DAYS` | Информирование | `30` | + +#### Проверка портов + +| Переменная | Описание | По умолчанию | +|------------|----------|--------------| +| `CHECK_TIMEOUT_SEC` | Таймаут TCP-соединения (сек) | `10` | +| `MAX_RETRIES` | Количество повторов | `3` | +| `RETRY_DELAY_SEC` | Задержка между повторами (сек) | `2` | +| `MAX_WORKERS` | Горутин для параллельной обработки | `10` | + +#### Проверка логов + +| Переменная | Описание | По умолчанию | +|------------|----------|--------------| +| `LOG_STALE_MINUTES` | Порог устаревшего лога (мин) | `61` | + +#### Проверка служб + +| Переменная | Описание | По умолчанию | +|------------|----------|--------------| +| `SERVICES_TO_CHECK` | Службы для проверки (через запятую) | — | + +Пример: `SERVICES_TO_CHECK=angie,docker,postgresql` + +### Пример auspex.env + +```bash +# Telegram +TELEGRAM_BOT_TOKEN=8411463479:AAF0zFi7iXTEC51sBG0Ckc8_S7JD-DuVcoo +TELEGRAM_CHAT_ID=-1001234567890 +# HTTP прокси (опционально) +TELEGRAM_HTTP_PROXY=http://10.100.12.4:8888 +# SOCKS5 прокси (опционально, fallback после HTTP) +TELEGRAM_SOCKS5_PROXY=212.87.220.230:1080 +TELEGRAM_SOCKS5_USER=proxyuser +TELEGRAM_SOCKS5_PASSWORD=ProxyPass!$ + +# Email +EMAIL_SMTP_HOST=mail.example.com +EMAIL_SMTP_PORT=587 +EMAIL_SMTP_USER=auspex@example.com +EMAIL_SMTP_PASSWORD=secret +EMAIL_FROM=auspex@example.com +EMAIL_TO=admin@example.com,devops@example.com + +# Mattermost +MATTERMOST_URL=https://mattermost.example.com +MATTERMOST_BOT_TOKEN=831yapr3xxxxxxxxxxx +MATTERMOST_CHANNEL_ID=oun39xxxxxxxxxxxx + +# База данных +DB_USER=waf_user +DB_PASSWORD=secret +DB_NAME=waf_info +PRIMARY_DB_HOST=10.100.10.8 +SECONDARY_DB_HOST=10.100.13.5 + +# Службы для проверки +SERVICES_TO_CHECK=angie,docker + +# Пороги сертификатов +CERT_CRITICAL_DAYS=3 +CERT_WARNING_DAYS=15 +CERT_INFO_DAYS=30 +``` + +## Доставка алертов + +Все модули с алертами отправляют уведомления во все настроенные каналы независимо друг от друга: + +| Канал | Условие отправки | +|-------|-----------------| +| Telegram | `TELEGRAM_BOT_TOKEN` и `TELEGRAM_CHAT_ID` заданы | +| Email | `EMAIL_SMTP_HOST`, `EMAIL_FROM`, `EMAIL_TO` заданы | +| Mattermost | `MATTERMOST_URL`, `MATTERMOST_BOT_TOKEN`, `MATTERMOST_CHANNEL_ID` заданы | + +Если канал не настроен — он молча пропускается, программа не падает. + +## State-файлы + +Модули `-p`, `-sv`, `-d` сохраняют состояние между запусками и отправляют алерты **только при изменении** статуса. Это позволяет безопасно запускать их по cron без спама. + +| Модуль | State-файл | +|--------|-----------| +| `-p` portcheck | `/tmp/port_checker_state.json` | +| `-sv` servicecheck | `/tmp/auspex_service_state.json` | +| `-d` dockercheck | `/tmp/auspex_docker_state.json` | + +При первом запуске состояние сохраняется, алерты не отправляются. + +## Пример cron + +```cron +# Проверка сертификатов — раз в сутки +0 9 * * * root /usr/local/bin/auspex -c >> /var/log/auspex/certcheck.log 2>&1 + +# Проверка портов — каждые 5 минут +*/5 * * * * root /usr/local/bin/auspex -p >> /var/log/auspex/portcheck.log 2>&1 + +# Проверка логов — каждый час +0 * * * * root /usr/local/bin/auspex -l >> /var/log/auspex/logcheck.log 2>&1 + +# Проверка служб — каждые 2 минуты +*/2 * * * * root /usr/local/bin/auspex -sv >> /var/log/auspex/servicecheck.log 2>&1 + +# Проверка контейнеров — каждые 2 минуты +*/2 * * * * root /usr/local/bin/auspex -d >> /var/log/auspex/dockercheck.log 2>&1 +``` + +## Подробнее + +См. [ARCHITECTURE.md](ARCHITECTURE.md).