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

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

```yaml
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:
```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'
```