admin/ns8-backup-monitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README with deploy instructions, systemd unit, multi-backend notes

Browse Source
This commit is contained in:
admin
2026-05-18 15:26:12 +00:00
parent a9c771e3f5
commit 15827fbd86
1 changed files with 95 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+95 -41
View File
@@ -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'
```