From 02fa70722c228906b8a9e2dac8a34e3ee33f191f Mon Sep 17 00:00:00 2001 From: ssh-monitor Date: Tue, 14 Apr 2026 09:56:18 +1000 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=BE=D0=B1=D1=8F=D0=B7=D0=B0=D1=82?= =?UTF-8?q?=D0=B5=D0=BB=D1=8C=D0=BD=D1=8B=D0=B9=20NOTIFY=5FCHAIN=20=D0=B2?= =?UTF-8?q?=20README=20=D0=B8=20ssh-monitor.conf.example?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Made-with: Cursor --- README.md | 28 +++++++++++++++++++++------- ssh-monitor.conf.example | 24 ++++++++++++++++++------ 2 files changed, 39 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index c9815a6..73267b2 100644 --- a/README.md +++ b/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`**. diff --git a/ssh-monitor.conf.example b/ssh-monitor.conf.example index a0c21ad..4d388ee 100644 --- a/ssh-monitor.conf.example +++ b/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.