From ab2bc5de332b7813d5c6f87399631e39997cba07 Mon Sep 17 00:00:00 2001 From: benya Date: Sun, 8 Feb 2026 01:08:17 +0300 Subject: [PATCH] Add README and CONFIG in RU and EN --- CONFIG.en.md | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++ CONFIG.md | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.en.md | 65 +++++++++++++++++++++++++++++++++++ README.md | 65 +++++++++++++++++++++++++++++++++++ 4 files changed, 322 insertions(+) create mode 100644 CONFIG.en.md create mode 100644 CONFIG.md create mode 100644 README.en.md create mode 100644 README.md diff --git a/CONFIG.en.md b/CONFIG.en.md new file mode 100644 index 0000000..221a503 --- /dev/null +++ b/CONFIG.en.md @@ -0,0 +1,96 @@ +# Configuration + +This project uses `config.yaml`. Start from `config.example.yaml`. + +## telegram + +- `token` (string, required): Telegram bot token. +- `admin_id` (int, required): Telegram user id with admin access. + +## paths + +- `artifact_state` (string): JSON file for artifact state. +- `restic_env` (string): Path to a file with RESTIC_* environment variables. + +## thresholds + +- `disk_warn` (int, percent): Disk usage warning threshold. +- `load_warn` (float): System load warning threshold. + +## alerts + +- `enabled` (bool): Enable resource alerts. +- `interval_sec` (int): Poll interval. +- `cooldown_sec` (int): Cooldown between alerts. +- `notify_recovery` (bool): Send recovery notifications. +- `smart_enabled` (bool): Enable SMART health polling. +- `smart_interval_sec` (int): SMART poll interval. +- `smart_cooldown_sec` (int): SMART alert cooldown. +- `smart_temp_warn` (int): SMART temperature warning (C). + +## audit + +- `enabled` (bool): Enable audit logging. +- `path` (string): Log file path. Default `/var/server-bot/audit.log`. +- `rotate_when` (string): Rotation schedule for `TimedRotatingFileHandler`. Example `W0` for weekly on Monday. +- `backup_count` (int): How many rotated files to keep. + +## arcane + +- `base_url` (string): Arcane API base url. +- `api_key` (string): Arcane API key. +- `env_id` (int): Arcane environment id. + +## npmplus + +Used for SSL certificate status. + +- `base_url` (string): NPMplus API base url, for example `https://10.10.10.10:81/api`. +- `identity` (string): Login email. +- `secret` (string): Login password. +- `token` (string): Optional static token (not recommended if it expires). +- `verify_tls` (bool): Set to `false` for self-signed TLS. + +Token flow: + +- First token: `POST /api/tokens` with `identity` and `secret`. +- Refresh: `GET /api/tokens` using the cached token. + +## security + +- `reboot_password` (string): Password required before reboot. + +## docker + +- `autodiscovery` (bool): Discover containers by name/label. +- `watchdog` (bool): Enable container watchdog notifications. +- `label` (string): Optional label filter `key=value`. +- `match` (list): Name substrings used for discovery. +- `aliases` (map): Alias -> real container name. +- `containers` (map): Explicit container list (legacy modules). Each item can define: + - `name` (string): Container name. + - `url` (string): Health URL for the URLs check. + +Example: + +```yaml +telegram: + token: "YOUR_TELEGRAM_BOT_TOKEN" + admin_id: 123456789 + +paths: + artifact_state: "/opt/tg-bot/state.json" + restic_env: "/etc/restic/restic.env" + +audit: + enabled: true + path: "/var/server-bot/audit.log" + rotate_when: "W0" + backup_count: 8 + +npmplus: + base_url: "https://10.10.10.10:81/api" + identity: "your@email.com" + secret: "yourPassword" + verify_tls: false +``` diff --git a/CONFIG.md b/CONFIG.md new file mode 100644 index 0000000..fe3f7ac --- /dev/null +++ b/CONFIG.md @@ -0,0 +1,96 @@ +# Конфигурация + +Проект использует `config.yaml`. Начни с `config.example.yaml`. + +## telegram + +- `token` (string, обяз.): токен бота. +- `admin_id` (int, обяз.): Telegram user id администратора. + +## paths + +- `artifact_state` (string): JSON файл состояния артефактов. +- `restic_env` (string): путь к файлу с RESTIC_* переменными. + +## thresholds + +- `disk_warn` (int, %): порог предупреждения по диску. +- `load_warn` (float): порог предупреждения по нагрузке. + +## alerts + +- `enabled` (bool): включить алерты. +- `interval_sec` (int): интервал опроса. +- `cooldown_sec` (int): кулдаун между алертами. +- `notify_recovery` (bool): уведомлять о восстановлении. +- `smart_enabled` (bool): SMART проверки. +- `smart_interval_sec` (int): интервал SMART. +- `smart_cooldown_sec` (int): кулдаун SMART. +- `smart_temp_warn` (int): порог температуры (C). + +## audit + +- `enabled` (bool): включить аудит. +- `path` (string): путь к лог-файлу. По умолчанию `/var/server-bot/audit.log`. +- `rotate_when` (string): режим ротации (`TimedRotatingFileHandler`), например `W0`. +- `backup_count` (int): сколько файлов хранить. + +## arcane + +- `base_url` (string): base url API Arcane. +- `api_key` (string): ключ API Arcane. +- `env_id` (int): ID окружения Arcane. + +## npmplus + +Используется для статуса SSL сертификатов. + +- `base_url` (string): base url API, например `https://10.10.10.10:81/api`. +- `identity` (string): email логин. +- `secret` (string): пароль. +- `token` (string): опционально статический токен (не рекомендуется при истечении). +- `verify_tls` (bool): `false` для self-signed TLS. + +Логика токена: + +- первый токен: `POST /api/tokens` с `identity` и `secret`. +- refresh: `GET /api/tokens` с текущим токеном. + +## security + +- `reboot_password` (string): пароль для подтверждения reboot. + +## docker + +- `autodiscovery` (bool): автодискавери по имени/label. +- `watchdog` (bool): уведомления о контейнерах. +- `label` (string): фильтр label `key=value`. +- `match` (list): подстроки для поиска контейнеров. +- `aliases` (map): alias -> реальное имя. +- `containers` (map): явный список (legacy). Можно задавать: + - `name` (string) + - `url` (string) для URLs проверки + +Пример: + +```yaml +telegram: + token: "YOUR_TELEGRAM_BOT_TOKEN" + admin_id: 123456789 + +paths: + artifact_state: "/opt/tg-bot/state.json" + restic_env: "/etc/restic/restic.env" + +audit: + enabled: true + path: "/var/server-bot/audit.log" + rotate_when: "W0" + backup_count: 8 + +npmplus: + base_url: "https://10.10.10.10:81/api" + identity: "your@email.com" + secret: "yourPassword" + verify_tls: false +``` diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..0f7be8c --- /dev/null +++ b/README.en.md @@ -0,0 +1,65 @@ +# tg-admin-bot + +Telegram admin bot for Linux servers. Provides quick status checks, backup controls, and ops actions from a chat. + +## Features + +- Docker: status, restart, logs (tail, since, filter). +- Arcane: list projects, refresh, up/down, restart. +- Backups (restic): snapshots, repo stats, run backup, queue, restic check, weekly report. +- System: disks, security, URLs health, metrics, package updates, upgrade, reboot, hardware info, SSL cert status (NPMplus). +- Alerts: disk/load and SMART monitoring with cooldown. +- Audit log: all button presses and messages (weekly rotation). + +## Requirements + +- Linux host. +- Python 3.11+ (tested with 3.13). +- System tools as needed: + - docker + - restic + - smartctl (smartmontools) + - sudo access for reboot/upgrade/backup scripts + - systemd (for timers/status, optional but recommended) + +## Install + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r req.txt +``` + +## Configure + +1. Copy the example config: + +```bash +cp config.example.yaml config.yaml +``` + +2. Edit `config.yaml` and set at least: + +- `telegram.token` +- `telegram.admin_id` + +3. Optional: + +- Restic env file path (`paths.restic_env`). +- Docker autodiscovery or explicit `docker.containers`. +- Arcane and NPMplus API settings. +- Audit log path and rotation. + +See `CONFIG.en.md` for full details. + +## Run + +```bash +python bot.py +``` + +## Notes + +- For NPMplus with self-signed TLS, set `npmplus.verify_tls: false`. +- The bot uses `sudo` for certain actions (reboot, upgrade, backup scripts). Ensure the service user has the required permissions. +- Audit log default path is `/var/server-bot/audit.log`. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4464c28 --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ +# tg-admin-bot + +Telegram-бот администратора для Linux-серверов. Даёт быстрый доступ к статусам, бэкапам и операциям через чат. + +## Возможности + +- Docker: статус, рестарт, логи (tail, since, фильтр). +- Arcane: список проектов, refresh, up/down, restart. +- Бэкапы (restic): снапшоты, статистика репозитория, запуск бэкапа, очередь, restic check, weekly report. +- Система: диски, безопасность, проверка URL, метрики, обновления, upgrade, reboot, железо, SSL (NPMplus). +- Алерты: диск/нагрузка и SMART с cooldown. +- Аудит: все нажатия и сообщения (ротация раз в неделю). + +## Требования + +- Linux-хост. +- Python 3.11+ (проверено на 3.13). +- Системные утилиты по необходимости: + - docker + - restic + - smartctl (smartmontools) + - sudo для reboot/upgrade/backup скриптов + - systemd (для таймеров/статуса, желательно) + +## Установка + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r req.txt +``` + +## Настройка + +1. Скопировать пример: + +```bash +cp config.example.yaml config.yaml +``` + +2. Заполнить минимум: + +- `telegram.token` +- `telegram.admin_id` + +3. Опционально: + +- путь к restic env (`paths.restic_env`) +- docker autodiscovery или явный список `docker.containers` +- Arcane и NPMplus API +- аудит логов + +Подробности в `CONFIG.md`. + +## Запуск + +```bash +python bot.py +``` + +## Примечания + +- Для NPMplus с self-signed TLS установи `npmplus.verify_tls: false`. +- Бот использует `sudo` для части операций — настрой права. +- Аудит по умолчанию пишется в `/var/server-bot/audit.log`.