# Strategia di backup e ripristino

> Cosa si salva, come, dove e come si verifica il ripristino. Riferimenti: [ambienti.md](ambienti.md); requisito di collaudo S3‑09 in `PROJECT DOCS/CRITERI_COLLAUDO.md`.

## Obiettivi

| Parametro | Valore per il pilota | Significato |
|---|---|---|
| **RPO** (perdita massima di dati) | 24 ore | Backup completo notturno |
| **RTO** (tempo massimo di ripristino) | 4 ore | Dalla decisione di ripristinare al servizio di nuovo attivo |

I valori sono da rivedere con il committente prima della produzione con clienti paganti, perché incidono sui costi.

## Cosa si salva

| Elemento | Perché è critico | Come |
|---|---|---|
| Database MariaDB | Binding Registry, audit log, utenti, Chiavi Amministratore, metadati | `mariadb-dump --single-transaction --routines --triggers`, compresso |
| Document Vault | Originali delle fatture: senza, i QR non sono più verificabili | Copia dei file, già cifrati dal Vault |
| File `.env` e configurazione | Necessari per ripartire | Copia cifrata, conservata **separatamente** dai dati |
| Chiave privata del sigillo | Senza, non si possono emettere nuovi sigilli | Copia offline cifrata, custodita dal responsabile (non nei backup automatici) |
| Chiave di cifratura del Vault | Senza, il Vault salvato è illeggibile | Come la chiave del sigillo: offline, separata dai backup |
| Codice | Già nel repository git | Non serve un backup dedicato; si ripristina da un tag |

**Regola:** chiavi e dati cifrati non stanno mai nello stesso backup. Se un backup venisse sottratto, i documenti resterebbero illeggibili.

## Come e dove

1. **Ogni notte (cron):**
   - `mariadb-dump` del database e copia incrementale del Vault in una cartella di staging locale;
   - calcolo dei checksum SHA‑256 dei file di backup;
   - invio su uno **spazio esterno alla VPS**: OVH Backup Storage oppure Object Storage S3‑compatibile in un data center UE diverso da quello della VPS.
2. **Cifratura:** il dump del database viene cifrato prima dell'invio (il Vault è già cifrato).
3. **Conservazione:** 7 backup giornalieri, 4 settimanali, 12 mensili. La retention va allineata con le policy privacy (TODO 0.9): un documento cancellato per diritto dell'interessato deve sparire anche dai backup entro il ciclo di conservazione.
4. **Esito:** ogni esecuzione scrive nel log l'esito, la dimensione e i checksum. Un backup fallito genera un avviso.

## Prova di ripristino

Un backup non provato non conta. La prova si esegue:
- **la prima volta** appena esiste un database MariaDB con dati di prova (in locale c'è dal 15/10/2026);
- **prima di ogni collaudo SAL** e del go‑live (test S3‑09);
- **ogni mese** in produzione.

**Procedura:**
1. Creare un ambiente pulito (database vuoto e cartella del Vault vuota).
2. Scaricare l'ultimo backup e verificarne i checksum.
3. Ripristinare il database con il client `mariadb` (`mariadb domuscan < dump.sql`) e i file del Vault.
4. Fornire le chiavi dalla copia offline.
5. Verifiche:
   - conteggio di documenti, binding e utenti uguale a quello dell'origine;
   - ricalcolo degli SHA‑256 di un campione di documenti del Vault, che devono coincidere con quelli registrati nel database;
   - verifica di alcuni sigilli con la chiave pubblica;
   - apertura di alcuni QR tramite il resolver.
6. Registrare data, backup usato, tempo impiegato (da confrontare con l'RTO) ed esito.

## Uso

Gli script sono `strumenti/backup.sh` e `strumenti/ripristino.sh`. Usano funzioni comuni in `strumenti/libreria_backup.sh` e leggono il `.env` dell'ambiente con le stesse regole dell'applicazione. Il test automatico è `test/test_backup.sh`.

### Variabili del `.env`

| Variabile | Significato |
|---|---|
| `PERCORSO_BACKUP` | Cartella dei backup, fuori da `pubblico/` (es. `/srv/domuscan/produzione/backup`) |
| `BACKUP_GPG_DESTINATARIO` | Impronta (fingerprint) della chiave pubblica GPG del responsabile |
| `BACKUP_REMOTO` | Destinazione `rclone` fuori dal server. Vuota = backup solo locale, con l'avviso `AVVISO backup solo locale` nel log a ogni esecuzione |
| `BACKUP_RETENTION_GIORNALIERI` / `_SETTIMANALI` / `_MENSILI` | Quanti backup conservare per tipo (predefiniti 7, 4, 12) |

Anche `PERCORSO_VAULT` e `PERCORSO_LOG` sono usati: il Vault viene archiviato, e l'esito va in `PERCORSO_LOG/backup.log`.

### Chiave GPG (una volta sola, sul PC del responsabile)

```bash
gpg --quick-gen-key "DOMUSCAN backup <responsabile@...>" default default never   # con passphrase
gpg --fingerprint                                     # impronta da mettere in BACKUP_GPG_DESTINATARIO
gpg --armor --export <impronta> > domuscan_backup_pubblica.asc
gpg --armor --export-secret-keys <impronta> > domuscan_backup_PRIVATA.asc   # custodire offline
```

Sul server, con l'utente di servizio, si importa **solo** la pubblica:

```bash
gpg --import domuscan_backup_pubblica.asc
```

La chiave privata non resta mai sul server. Senza la privata (e la sua passphrase) i backup sono irrecuperabili: va custodita in due copie offline.

### Backup

```bash
bash strumenti/backup.sh --env /srv/domuscan/produzione/app/.env
```

Ogni esecuzione crea `PERCORSO_BACKUP/AAAA-MM-GG_HHMMSS_<tipo>/` con:

| File | Contenuto |
|---|---|
| `database.sql.gz.gpg` | `mariadb-dump --single-transaction --routines --triggers --events`, compresso e cifrato in pipe (nessun dump in chiaro su disco) |
| `vault.tar.gz.gpg` | Archivio del Vault, cifrato anche se i file lo sono già (nomi e date non restano in chiaro) |
| `configurazione/env.gpg` | Copia cifrata del `.env`, separata dai dati |
| `SHA256SUMS` | Checksum di tutti i file del backup |

Comportamento:
- **Tipo:** `mensile` il giorno 1, `settimanale` la domenica, altrimenti `giornaliero` (date in UTC). Poi la retention elimina i backup più vecchi di ciascun tipo oltre la soglia. Considera solo le cartelle con quel formato di nome.
- **Blocco:** un secondo backup lanciato mentre il primo è in corso esce con codice `3`. Un blocco lasciato da un processo terminato viene rimosso da solo.
- **In caso di errore** il backup incompleto viene eliminato, nel log si scrive `ESITO=errore passo="..."` e lo script esce con `1`.
- **Opzioni:** `--destinazione <cartella>` (sostituisce `PERCORSO_BACKUP`), `--senza-remoto` (salta la copia remota).

**Privilegi del database:** l'utente MariaDB dell'ambiente deve avere su quel database anche `EVENT`, oltre a `SELECT`, `LOCK TABLES`, `SHOW VIEW` e `TRIGGER`, perché il dump include eventi e trigger.

### Ripristino

```bash
gpg --import domuscan_backup_PRIVATA.asc     # solo per la durata della prova
export GPG_TTY=$(tty)                        # in SSH: senza, gpg non riesce a chiedere la passphrase
bash strumenti/ripristino.sh --env /srv/domuscan/produzione/app/.env \
  --da /srv/domuscan/produzione/backup/2026-11-14_031500_giornaliero \
  --database domuscan_ripristino --cartella-vault /tmp/vault_ripristino
gpg --delete-secret-keys <impronta>          # a prova finita
```

Ordine delle operazioni: verifica di `SHA256SUMS`, poi controlli sulla destinazione, poi database, poi Vault, poi riepilogo dei conteggi. Se un controllo fallisce, nulla viene modificato. Lo script si rifiuta se:
- i checksum non corrispondono;
- la cartella del Vault di destinazione non è vuota;
- il database di destinazione contiene già tabelle, a meno di `--conferma`, che le elimina tutte prima di caricare il dump.

Il `.env` salvato nel backup non viene ripristinato in automatico: si decifra a mano con `gpg --decrypt configurazione/env.gpg` solo se serve.

## Da realizzare

- **Copia fuori dalla VPS:** per ora non c'è (decisione 5 del piano 261113), quindi il backup esiste solo sulla VPS. Prima dei dati reali va scelto lo spazio esterno (OVH Object Storage o altro) e impostato `BACKUP_REMOTO`.
- Prove di ripristino da registrare in [registro_prove_ripristino.md](registro_prove_ripristino.md).
