docs: обязательный NOTIFY_CHAIN в README и ssh-monitor.conf.example

Made-with: Cursor

README.md

@@ -10,16 +10,18 @@ Bash-скрипт мониторинга **SSH**, **SUDO** и событий **`
  - `sudo cp ./ssh-monitor.conf.example /etc/ssh-monitor.conf`
 2. Ограничьте доступ:
  - `sudo chmod 600 /etc/ssh-monitor.conf`
-3. Заполните минимум:
- - `TELEGRAM_BOT_TOKEN`
- - `TELEGRAM_CHAT_ID`
+3. Заполните минимум — **хотя бы один канал доставки оповещений** (иначе скрипт сразу завершится с ошибкой; см. абзац **«Обязательное условие»** ниже и раздел **«Каналы оповещений и пустой NOTIFY_CHAIN»**):
+ - для **Telegram**: `TELEGRAM_BOT_TOKEN` и `TELEGRAM_CHAT_ID`;
+ - или настройте **Zabbix** / **почту** по переменным ниже при `NOTIFY_ORDER=""` (автовыбор каналов).
+
+**Обязательное условие:** после загрузки конфигурации в цепочке **`NOTIFY_CHAIN`** должен быть **минимум один** канал (`telegram`, `zabbix` или `email`). Если каналов **нет** (пустой `NOTIFY_ORDER` и ни Telegram, ни Zabbix, ни SMTP не удовлетворяют критериям «настроен», либо в `NOTIFY_ORDER` остались только неизвестные имена), скрипт **не входит** в основной цикл и завершается с кодом **1**, в stderr: **`Не настроен ни один канал отправки оповещений`**. Это же правило действует для **`--check-config`** и **`--dry-run`**. Резервный **`BACKUP_WEBHOOK_URL`** в эту проверку **не входит** — он используется только когда основные каналы уже есть, но доставка через них не удалась.
 
 Поддерживаемые параметры:
 
 - `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`
-- `NOTIFY_ORDER` — явная очередь каналов оповещений (`telegram`, `zabbix`, `email` и сокращения); пусто = в цепочку попадают только настроенные каналы (порядок по умолчанию см. в `ssh-monitor.conf.example`). Если итоговая цепочка пуста — скрипт не стартует (см. описание `NOTIFY_ORDER` ниже).
+- `NOTIFY_ORDER` — явная очередь каналов оповещений (`telegram`, `zabbix`, `email` и сокращения); пусто = в цепочку попадают только настроенные каналы (порядок по умолчанию см. в `ssh-monitor.conf.example`). Если итоговая цепочка пуста — скрипт не стартует (см. раздел **«Каналы оповещений и пустой NOTIFY_CHAIN»**).
 - `ZABBIX_SERVER`, `ZABBIX_HOST_NAME`, `ZABBIX_ALERT_KEY`, `ZABBIX_SEQ_KEY` — отправка в Zabbix через `zabbix_sender`; подробнее — раздел **«Zabbix (`zabbix_sender`)»** ниже
-- `BACKUP_WEBHOOK_URL` — резервная доставка JSON `{"text":"..."}` (например Slack Incoming Webhook), если Telegram недоступен или вернул ошибку
+- `BACKUP_WEBHOOK_URL` — резервная доставка JSON `{"text":"..."}` (например Slack Incoming Webhook), если каналы из **`NOTIFY_CHAIN`** недоступны или вернули ошибку; **не заменяет** обязательность хотя бы одного основного канала (см. шаг 3)
 - `LOG_FILE`, `LAST_HEARTBEAT_FILE`, `LAST_REPORT_FILE`, `LAST_SSH_CHECK_FILE`, `LAST_SUDO_CHECK_FILE`, `LAST_SECURITY_EVENTS_FILE`, `LAST_LOGIND_CHECK_FILE`, `BAN_LIST_FILE`
 - `ENABLE_LOGIND_MONITOR`, `LOGIND_NOTIFY_NEW`, `LOGIND_NOTIFY_REMOVED`, `LOGIND_NOTIFY_FAILED`, `LOGIND_SKIP_REMOTE` — см. раздел «Мониторинг systemd-logind» ниже
 - `DAILY_REPORT_HOUR` (0..23), `DAILY_REPORT_TZ` (опционально), `DAILY_REPORT_TOP_IPS`
@@ -36,12 +38,12 @@ Bash-скрипт мониторинга **SSH**, **SUDO** и событий **`
 
 - `TELEGRAM_BOT_TOKEN` — токен Telegram-бота для отправки уведомлений.
 - `TELEGRAM_CHAT_ID` — ID чата/пользователя, куда отправляются уведомления.
-- `NOTIFY_ORDER` — CSV имён каналов (`telegram`, `zabbix`, `email` или `tg`, `zbx`, `mail`). Пустая строка: автоматически собирается цепочка только из реально настроенных каналов (по умолчанию порядок telegram → zabbix → email). Если после сборки цепочки **нет ни одного** канала (ни Telegram, ни Zabbix, ни почты по критериям ниже), скрипт **сразу завершается** с ошибкой: **«Не настроен ни один канал отправки оповещений»** (в том числе режим `--check-config` и `--dry-run`).
+- `NOTIFY_ORDER` — CSV имён каналов (`telegram`, `zabbix`, `email` или `tg`, `zbx`, `mail`). Пустая строка: автоматически собирается цепочка только из реально настроенных каналов (по умолчанию порядок telegram → zabbix → email; критерии «настроен» — **таблица** в разделе **«Каналы оповещений и пустой NOTIFY_CHAIN»**). Если после сборки цепочки **нет ни одного** канала, скрипт **сразу завершается** с ошибкой: **«Не настроен ни один канал отправки оповещений»** (в том числе режим `--check-config` и `--dry-run`).
 - `ZABBIX_SERVER` — имя или IP сервера Zabbix для `zabbix_sender -z` (пусто = канал Zabbix отключён).
 - `ZABBIX_HOST_NAME` — имя **хоста в Zabbix**, как в конфигурации агента/шаблона (`-s` у `zabbix_sender`); должно совпадать с тем, для какого хоста созданы trapper-элементы.
 - `ZABBIX_ALERT_KEY` — ключ **первого** trapper-элемента: в него уходит **текст** оповещения (одна строка, переводы строк заменены пробелами).
 - `ZABBIX_SEQ_KEY` — ключ **второго** trapper-элемента: в него при каждой отправке пишется **монотонно растущий счётчик** (1, 2, 3, … за время работы процесса скрипта). Значение по умолчанию — `ssh.monitor.seq`. Назначение: чтобы Zabbix и триггеры видели **новое значение** даже при **одинаковом** тексте алерта (иначе повтор с тем же текстом может плохо отражаться на логике «изменилось ли значение»); также по счётчику удобнее отслеживать порядок событий. В шаблоне Zabbix нужны **два** элемента типа **Zabbix trapper** с ключами, совпадающими с `ZABBIX_ALERT_KEY` и `ZABBIX_SEQ_KEY` (второй — обычно **числовой**).
-- `BACKUP_WEBHOOK_URL` — URL для резервной отправки (тело JSON `{"text":"..."}`).
+- `BACKUP_WEBHOOK_URL` — URL для резервной отправки (тело JSON `{"text":"..."}`); только fallback при сбое основных каналов, **не засчитывается** как «настроенный канал» (см. шаг 3).
 - `LOG_FILE` — путь к основному лог-файлу скрипта.
 - `LAST_HEARTBEAT_FILE` — файл с timestamp последнего heartbeat-сообщения.
 - `LAST_REPORT_FILE` — дата последнего ежедневного отчёта в формате `YYYY-MM-DD` (старый формат Unix-времени при первом запуске будет автоматически интерпретирован).
@@ -74,6 +76,18 @@ Bash-скрипт мониторинга **SSH**, **SUDO** и событий **`
 - `WATCHDOG_SERVICE_NAME` — имя systemd-сервиса, который контролирует watchdog (по умолчанию `ssh-monitor.service`).
 - `WATCHDOG_NOTIFY_ON_RECOVERY` — `1` включает служебные сообщения watchdog при штатном состоянии, `0` отключает.
 
+### Каналы оповещений и пустой NOTIFY_CHAIN
+
+Кратко, что считается **настроенным** каналом (только такие попадают в автоматическую цепочку при **`NOTIFY_ORDER=""`**):
+
+| Канал | Условие «настроен» |
+|--------|-------------------|
+| `telegram` | заданы **`TELEGRAM_BOT_TOKEN`** и **`TELEGRAM_CHAT_ID`** |
+| `zabbix` | непустые **`ZABBIX_SERVER`**, **`ZABBIX_HOST_NAME`**, в PATH есть **`zabbix_sender`** |
+| `email` | непустые **`MAIL_SMTP_HOST`**, **`MAIL_FROM`**, **`MAIL_TO`**, в PATH есть **`python3`** |
+
+Если итоговый **`NOTIFY_CHAIN` пуст**, скрипт завершается с сообщением **`Не настроен ни один канал отправки оповещений`** (см. шаг 3 в разделе «Конфигурация» выше).
+
 ### Zabbix (`zabbix_sender`)
 
 Канал активен, если в **`NOTIFY_CHAIN`** есть `zabbix`, заданы **`ZABBIX_SERVER`** и **`ZABBIX_HOST_NAME`**, в PATH есть **`zabbix_sender`**.

ssh-monitor.conf.example

@@ -2,14 +2,26 @@ TELEGRAM_BOT_TOKEN="replace_with_telegram_bot_token"
 TELEGRAM_CHAT_ID="replace_with_telegram_chat_id"
 
 # Резервный webhook, если все каналы из NOTIFY_CHAIN недоступны (JSON {"text":"..."}).
+# ВАЖНО: BACKUP_WEBHOOK_URL НЕ заменяет основной канал — без хотя бы одного из telegram/zabbix/email
+# скрипт сразу завершится с ошибкой в stderr: «Не настроен ни один канал отправки оповещений» (код 1),
+# в том числе при --check-config и --dry-run. Сначала настройте Telegram, Zabbix или SMTP ниже.
 BACKUP_WEBHOOK_URL=""
 
-# Очередь оповещений: CSV из telegram, zabbix, email (или tg, zbx, mail).
-# Пусто = авто: в цепочку попадают только настроенные каналы, порядок telegram → zabbix → email.
-# Пример явной очереди: NOTIFY_ORDER="telegram,zabbix,email"
-# Только Telegram: NOTIFY_ORDER="telegram"
-# Только Zabbix: NOTIFY_ORDER="zabbix"
-# Только почта: NOTIFY_ORDER="email"
+# --- Очередь оповещений (NOTIFY_ORDER) ---
+# CSV: telegram, zabbix, email (или сокращения tg, zbx, mail).
+#
+# Пустая строка NOTIFY_ORDER="" = авто: в цепочку NOTIFY_CHAIN попадают ТОЛЬКО реально настроенные каналы,
+# порядок по умолчанию: telegram → zabbix → email (см. критерии «настроен» в README, раздел про каналы).
+#
+# Если после сборки цепочки каналов список ПУСТ (ни один канал не настроен, либо в NOTIFY_ORDER только
+# неизвестные токены), скрипт НЕ запускает мониторинг и выходит с ошибкой:
+#   Не настроен ни один канал отправки оповещений
+#
+# Примеры явной очереди:
+# NOTIFY_ORDER="telegram,zabbix,email"
+# NOTIFY_ORDER="telegram"
+# NOTIFY_ORDER="zabbix"
+# NOTIFY_ORDER="email"
 NOTIFY_ORDER=""
 
 # Zabbix trapper (zabbix_sender). Нужны ZABBIX_SERVER и ZABBIX_HOST_NAME.