ns8-backup-monitor/README.md

ns8-backup-monitor

Sistema di monitoraggio dei backup per NethServer 8 basato su tre livelli:

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 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	Nessuno stato trovato in Redis, o errori di connessione/scrittura sulla destinazione

Requisiti

• NethServer 8 (leader node)
• Python 3.9+
• 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

ns8-backup-monitor/
├── README.md
├── install.sh
├── ns8_backup_monitor/
│   ├── __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

Installazione

# 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:

receivers:
  - name: ns8-backup-monitor
    webhook_configs:
      - url: 'http://localhost:9099/alert'
        send_resolved: true

route:
  receiver: ns8-backup-monitor
  matchers:
    - alertname =~ "NsBackupFailed|NsBackupMissing"

Riavviare Alertmanager dopo la modifica:

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

# 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'