From 15827fbd8621ccc054f935ba7e1a72b944a2dcf3 Mon Sep 17 00:00:00 2001 From: admin Date: Mon, 18 May 2026 15:26:12 +0000 Subject: [PATCH] docs: update README with deploy instructions, systemd unit, multi-backend notes --- README.md | 136 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 95 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 16d22a3..5089723 100644 --- a/README.md +++ b/README.md @@ -2,57 +2,44 @@ Sistema di monitoraggio dei backup per **NethServer 8** basato su tre livelli: -1. **Trigger**: riceve l'alert da Prometheus/Alertmanager (`NsBackupFailed`) -2. **Correlazione**: interroga lo stato del piano e dei singoli moduli via Redis/cluster API +1. **Trigger**: riceve l'alert da Prometheus/Alertmanager (`NsBackupFailed`, `NsBackupMissing`) +2. **Correlazione**: interroga lo stato del piano e dei singoli moduli via Redis cluster 3. **Classificazione**: distingue tra successo totale, fallimento parziale o fallimento globale di repository ## Architettura ``` Alertmanager --webhook--> receiver.py - | - +-----------v-----------+ - | correlator.py | <- stato piano + per-modulo - +-----------+-----------+ - | - +-----------v-----------+ - | repo_check.py | <- verifica repository destinazione - +-----------+-----------+ - | - +-----------v-----------+ - | notifier.py | <- email unica con esito classificato - +-----------------------+ + | + +--------------v--------------+ + | correlator.py | <- stato piano + per-modulo via Redis HGETALL + +--------------+--------------+ + | + +--------------v--------------+ + | repo_check.py | <- verifica repository destinazione (restic) + +--------------+--------------+ + | + +--------------v--------------+ + | notifier.py | <- email unica con esito classificato (HTML+text) + +-----------------------------+ ``` ## Logica di classificazione | Esito | Condizione | |---|---| -| SUCCESS | Tutti i moduli del piano completati, nessun errore repo | -| PARTIAL | Almeno un modulo fallito, repository raggiungibile | -| REPO_FAILURE | Errori di connessione/scrittura sulla destinazione, backup non avviati | +| `SUCCESS` | Tutti i moduli del piano completati, nessun errore repo | +| `PARTIAL` | Almeno un modulo fallito, repository raggiungibile | +| `REPO_FAILURE` | Nessuno stato trovato in Redis, o errori di connessione/scrittura sulla destinazione | ## Requisiti - NethServer 8 (leader node) - Python 3.9+ -- Accesso Redis locale del cluster NS8 -- `metrics1` configurato con `mail_to` e `mail_from` -- Alertmanager webhook abilitato verso `http://localhost:9099/alert` - -## Installazione - -```bash -bash install.sh -``` - -## Configurazione - -```bash -cp config/config.yml.example config/config.yml -# editare config.yml con smtp, mail_to, soglie temporali -systemctl enable --now ns8-backup-monitor -``` +- `redis-cli` installato (pacchetto `redis` su Rocky Linux) +- `restic` installato e nel PATH (per `repo_check.py`) +- Accesso Redis locale del cluster NS8 via socket Unix +- `metrics1` configurato con Alertmanager webhook abilitato verso `http://localhost:9099/alert` ## Struttura file @@ -61,17 +48,46 @@ ns8-backup-monitor/ ├── README.md ├── install.sh ├── ns8_backup_monitor/ -│ ├── receiver.py # HTTP webhook receiver (porta 9099) -│ ├── correlator.py # correlazione stato backup cluster -│ ├── repo_check.py # verifica repository destinazione -│ └── notifier.py # invio email con esito classificato -├── systemd/ -│ └── ns8-backup-monitor.service +│ ├── __init__.py +│ ├── __main__.py # entry point: python3 -m ns8_backup_monitor +│ ├── receiver.py # HTTP webhook receiver (porta 9099) +│ ├── correlator.py # correlazione stato backup cluster +│ ├── repo_check.py # verifica repository destinazione +│ ├── notifier.py # invio email con esito classificato +│ └── utils.py # config loading + logging setup +├── deploy/ +│ └── ns8-backup-monitor.service # systemd unit └── config/ └── config.yml.example ``` -## Integrazione Alertmanager +## Installazione + +```bash +# 1. Clona la repo +cd /opt +git clone https://repo.lelekaos.com/admin/ns8-backup-monitor.git +cd ns8-backup-monitor + +# 2. Installa dipendenze Python +pip3 install pyyaml + +# 3. Crea configurazione +mkdir -p /etc/ns8-backup-monitor +cp config/config.yml.example /etc/ns8-backup-monitor/config.yml +# Edita /etc/ns8-backup-monitor/config.yml con smtp, mail.to, ecc. + +# 4. Installa e avvia il servizio +cp deploy/ns8-backup-monitor.service /etc/systemd/system/ +systemctl daemon-reload +systemctl enable --now ns8-backup-monitor + +# 5. Verifica +systemctl status ns8-backup-monitor +journalctl -u ns8-backup-monitor -f +``` + +## Configurazione Alertmanager Aggiungere in `alertmanager.yml` il receiver: @@ -87,3 +103,41 @@ route: matchers: - alertname =~ "NsBackupFailed|NsBackupMissing" ``` + +Riavviare Alertmanager dopo la modifica: +```bash +systemctl restart alertmanager +``` + +## Backend supportati per repo_check + +`repo_check.py` legge le credenziali direttamente da Redis e imposta le variabili d'ambiente necessarie per `restic`: + +| Backend | Campi Redis letti | Env vars impostate | +|---|---|---| +| `local` / `fs` | `url` o `path` | `RESTIC_PASSWORD` | +| `s3` / `aws` | `url`, `aws_access_key_id`, `aws_secret_access_key` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | +| `b2` / `backblaze` | `url`, `b2_account_id`, `b2_account_key` | `B2_ACCOUNT_ID`, `B2_ACCOUNT_KEY` | +| `sftp` | `url` (formato `sftp:host:path`) | `RESTIC_PASSWORD` | +| `rclone` | `url`, `rclone_config` | `RCLONE_CONFIG` | + +## Debug / test manuale + +```bash +# Test del correlatore (senza inviare email) +python3 -c " +import json +from ns8_backup_monitor.utils import load_config +from ns8_backup_monitor.correlator import correlate_backup_status +cfg = load_config() +print(json.dumps(correlate_backup_status(cfg), indent=2)) +" + +# Test invio webhook simulato +curl -s -X POST http://localhost:9099/alert \ + -H 'Content-Type: application/json' \ + -d '{"alerts":[{"status":"firing","labels":{"alertname":"NsBackupFailed"}}]}' + +# Verifica log +journalctl -u ns8-backup-monitor --since '1 hour ago' +```