# Manuale operativo – AdHoc Backup (GUI + Script)

> Versione script GUI: **install-AdHoc-Backup-GUI.ps1**  
> Motore di backup: **AdHoc-Backup.ps1**  
> Configurazione: **backup.conf**  
> Report email: **send-mail.ps1 + report_template.html**  

---

## 1. Obiettivo del progetto

Questo pacchetto serve a:

* fare **backup automatici** di:
  * cartelle/file (es. installazione Zucchetti AdHoc)
  * database **SQL Server**
* mantenere copie locali con **retention automatica**
* inviare gli archivi verso uno storage remoto (Dropbox, S3, ecc.) tramite **rclone**
* inviare una **mail HTML di report** con:
  * esito (OK / WARNING / ERRORE)
  * dimensioni archivi
  * durata del backup
  * spazio disco totale/usato/libero
* semplificare tutto tramite una **GUI di installazione** che:
  * scarica e posiziona i file giusti
  * prepara la struttura delle cartelle
  * configura l’attività pianificata di Windows
  * offre un pulsante **“Test mail”**

---

## 2. Componenti del sistema

I file principali sono:

* `install-AdHoc-Backup-GUI.ps1`  
  GUI/installer: scarica e installa gli script, prepara i tool (7-Zip e rclone) e crea la Scheduled Task.

* `AdHoc-Backup.ps1`  
  **Motore di backup**: legge `backup.conf`, esegue backup file e SQL, comprime con 7-Zip, invia con rclone, pulisce e manda la mail di report.

* `backup.conf`  
  File di **configurazione utente**: definisce cosa salvare, dove salvare, retention, parametri rclone e parametri SMTP.

* `send-mail.ps1`  
  Si occupa di **costruire l’HTML** del report (usando `report_template.html`) e inviare la mail via SMTP/TLS.

* `report_template.html`  
  Template HTML del report: contiene segnaposto (placeholder) che `send-mail.ps1` sostituisce con i dati reali del backup.

---

## 3. Esecuzione rapida (one-liner)

Per lanciare l’installer **senza scaricare nulla a mano**:

    powershell
    irm "https://gitea.poloinformatico.it/Mattia/Backup-AdHoc/raw/branch/main/install-AdHoc-Backup-GUI.ps1" | iex

### 3.1 Cosa fa questo comando

* `irm` = alias di `Invoke-RestMethod`  
  Scarica il contenuto del file PowerShell da Gitea **come testo**.
* `|` = pipe  
  Passa il testo scaricato al comando successivo.
* `iex` = alias di `Invoke-Expression`  
  Esegue il testo come script PowerShell in memoria.

**Nota importante**

L’errore:

> Impossibile trovare un parametro posizionale che accetta l'argomento 'iex'

si verifica se **manca la pipe** `|`.  
La forma corretta è sempre:

    powershell
    irm "URL" | iex

### 3.2 Come usarlo in pratica

1. Apri **PowerShell** come **Amministratore** (consigliato, per creare attività pianificate e scrivere in `C:\polo`).
2. Copia e incolla il comando:

       powershell
       irm "https://gitea.poloinformatico.it/Mattia/Backup-AdHoc/raw/branch/main/install-AdHoc-Backup-GUI.ps1" | iex

3. Premi **Invio**.  
   Dopo pochi secondi si apre la **finestra GUI “Installer AdHoc Backup”**.

Da qui prosegui con la configurazione grafica descritta nei capitoli successivi.

---

## 4. Struttura delle cartelle e layout standard

L’installer GUI si aspetta e/o prepara un layout tipo.

### 4.1 Cartella di installazione degli script

Esempio predefinito:

* `C:\polo\scripts\`
  * `AdHoc-Backup.ps1`
  * `send-mail.ps1`
  * `backup.conf` (se non spostato in `bin\conf`)
  * `bin\`
    * `conf\`
      * `backup.conf`
      * `rclone.conf`
      * `report_template.html`
    * `RClone\`
      * `rclone.exe`
    * `7Zip\`
      * `7zr.exe` (o `7z.exe` se presente)

### 4.2 Cartella radice dei backup

Definita in `backup.conf`, es.:

* `C:\Backups_AdHoc\`
  * `Bin\` (eventuali tool portabili usati da qui)
  * `logs\`
    * `backup_yyyy-MM-dd_HHmmss.log`
  * `out\`  
    Archivi temporanei prima di upload/spostamento.
  * `_sql_stage\`  
    File `.bak` e script SQL temporanei.
  * `Files\`  
    Archivi file, se `KeepLocalArchives=true`.
  * `Databases\`  
    Archivi SQL, se `KeepLocalArchives=true`.

---

## 5. L’installer GUI – `install-AdHoc-Backup-GUI.ps1`

### 5.1 Cosa fa in sintesi

L’installer:

1. Mostra una **finestra WinForms** con:
   * percorso di installazione
   * URL dei file da scaricare
   * opzioni di schedulazione
   * opzioni di log/output
   * area di configurazione di `backup.conf`
   * pulsante per **Test mail**
   * pulsante per **Installa**
2. Scarica e posiziona:
   * `AdHoc-Backup.ps1`
   * `backup.conf`
   * `send-mail.ps1`
   * `report_template.html`
3. Prepara il layout:
   * `bin\conf`
   * `bin\RClone`
   * `bin\7Zip`
4. Installa automaticamente, se mancanti:
   * `rclone.exe` (portabile)
   * `7zr.exe` (versione minimale di 7-Zip)
5. Crea una **attività pianificata** (Scheduled Task) per eseguire il backup a orario/frequenza desiderati.
6. **Opzionale**: esegue subito il backup alla chiusura della GUI se selezioni l’apposita checkbox.

### 5.2 Campi principali della GUI

*(I nomi possono variare leggermente, ma il concetto resta lo stesso.)*

#### 5.2.1 Cartella di installazione

* Label: “Cartella di installazione”
* TextBox: percorso (default es. `C:\polo\scripts`)
* Pulsante: “Scegli…” per aprire un `FolderBrowserDialog`

Qui verranno salvati gli script (`AdHoc-Backup.ps1`, `send-mail.ps1`, ecc.).

#### 5.2.2 URL script / config / template

* URL script AdHoc-Backup.ps1
* URL backup.conf
* URL send-mail.ps1
* URL report_template.html

Sono precompilati con le URL raw di Gitea.  
Puoi cambiarli se vuoi puntare ad un tuo fork/branch.

#### 5.2.3 Opzioni generali

* **“Crea attività pianificata senza output (quiet)”**  
  Se spuntata, la Scheduled Task esegue `AdHoc-Backup.ps1` con parametro `-Quiet` (niente log su console, solo su file).

* **“Eseguire il backup subito dopo l’installazione (alla chiusura)”**  
  Se spuntata:
  * alla chiusura della GUI l’installer lancia immediatamente `AdHoc-Backup.ps1` con la config scelta;
  * se non spuntata, non parte nessun backup automatico alla chiusura.

#### 5.2.4 Schedulazione (Utilità di pianificazione)

* Checkbox **“Crea attività pianificata”**
  * se disabilitata, l’installer **non** crea alcun job nel Task Scheduler.
* Combobox **“Frequenza”**
  * valori: “Giornaliero”, “Settimanale”.
* Combobox **“Giorno”**
  * attivo solo se scegli “Settimanale”.
  * valori: “Lunedì (MON)”, “Martedì (TUE)”, ecc.
* Campo **“Ora”**
  * `DateTimePicker` solo ora/minuti (es. default 23:00).
* Campo **“Nome attività”**
  * default per es.: `Backup_AdHoc`.

Internamente la GUI usa `New-ScheduledTaskAction/Trigger/Principal` e `Register-ScheduledTask` per creare l’attività con privilegi elevati e, se richiesto, con argomenti `-Config` e `-Quiet`.

#### 5.2.5 Parametri extra per AdHoc-Backup.ps1

* TextBox per specificare argomenti aggiuntivi da passare allo script, ad es.:

      -Quiet
      -Config "C:\percorso\altro.conf"

Questi argomenti vengono aggiunti alla stringa della Scheduled Task.

#### 5.2.6 Area di configurazione `backup.conf`

Nella parte centrale/bassa la GUI:

* legge `backup.conf` usando un parser che:
  * mantiene intatti **commenti, spazi, tab, ordine delle righe**;
  * memorizza i soli **valori** associati alle chiavi.
* genera controlli (TextBox / CheckBox) per i parametri principali (es. `BackupRoot`, `ArchiveSources`, `EnableSqlBackup`, ecc.).

Quando salvi:

* riscrive **solo i valori** nel file, lasciando la formattazione esistente invariata.

Questo ti permette di modificare la config senza “rovinare” il file.

#### 5.2.7 Pulsante “Test mail”

* Rilegge la config (in particolare le variabili `Mail*`).
* Costruisce un body di test.
* richiama `send-mail.ps1` per verificare:
  * connessione SMTP (`MailSmtpHost`, `MailSmtpPort`);
  * credenziali (`MailUser`, `MailPassword`);
  * correttezza di mittente/destinatari.

#### 5.2.8 Pulsanti finali

* **“Installa”**
  * scarica i file dagli URL indicati;
  * prepara le cartelle `bin`, `conf`, `RClone`, `7Zip`;
  * installa rclone/7zr se mancanti;
  * salva `backup.conf` (se modificato);
  * crea o aggiorna la Scheduled Task (se abilitata).

* **“Chiudi”**
  * chiude la GUI;
  * se la checkbox “Eseguire il backup subito dopo l’installazione” è spuntata:
    * lancia immediatamente `AdHoc-Backup.ps1` con il `backup.conf` configurato.

---

## 6. La configurazione – `backup.conf`

`backup.conf` è un file testo `CHIAVE=valore` con commenti `# ...`.

Lo script:

* ignora righe vuote o che iniziano per `#` / `;`;
* espande variabili di ambiente (es. `%COMPUTERNAME%`);
* gestisce le liste separate da `|`.

### 6.1 Sezione base e retention

Parametri principali:

* `BackupRoot=`  
  Cartella radice dei backup (`logs`, `out`, `Files`, `Databases`, `_sql_stage`, ecc.).

* `LocalRetentionDaysFiles=`  
  Giorni di retention per gli archivi file in `Files\`.

* `LocalRetentionDaysDb=`  
  Giorni di retention per gli archivi DB in `Databases\`.

* `RemoteRetentionDays=`  
  Giorni dopo i quali rclone elimina i file **sul remoto** (via `rclone delete --min-age`).

* `KeepLocalArchives=` (`true` / `false`)  
  * `true`: a fine job gli archivi in `out\` vengono **spostati** in `Files\` / `Databases\`.
  * `false`: gli archivi in `out\` vengono eliminati (dopo l’upload).

* `EnableFileBackup=` (`true` / `false`)  
  Abilita/disabilita il backup delle sorgenti file/folder.

* `EnableRcloneUpload=` (`true` / `false`)  
  Abilita/disabilita l’upload verso lo storage remoto.

### 6.2 Sorgenti file

* `ArchiveSources=`  
  Lista di cartelle o share da includere, separate da `|`.

Esempio:

    ArchiveSources=C:\Zucchetti\ahr90|C:\Zucchetti\NetSetup

Lo script:

* rimuove eventuali virgolette;
* ignora percorsi inesistenti (loggando un WARN);
* deduplica i percorsi.

### 6.3 Backup SQL Server

Parametri principali:

* `EnableSqlBackup=` (`true` / `false`)  
  Attiva o meno la parte SQL.

* `SqlInstance=`  
  Istanza SQL Server, es.:
  * `localhost`
  * `.\SQLEXPRESS`
  * `localhost\SQLEXPRESS2022`
  * `192.168.1.10,1433` (server remoto su porta esplicita)

* `SqlUseWindowsAuth=` (`true` / `false`)  
  * `true`: usa Windows Authentication (utente con cui gira il processo).
  * `false`: usa utente/password SQL esplicitati.

* `SqlUser=`, `SqlPassword=`  
  Utilizzati solo se `SqlUseWindowsAuth=false`.

* `DbInclude=`  
  Lista di database da includere esplicitamente (separati da `|`).  

  Se vuoto, lo script:

  1. chiede a SQL l’elenco dei DB utente online (`sys.databases` con `state=0` e `database_id>4`);
  2. li filtra usando `DbExclude`.

* `DbExclude=`  
  Lista di DB da escludere (default include `master|model|msdb|tempdb`).

* `SqlCompressStage=` (`true` / `false`)  
  Se `true`:
  * comprime `_sql_stage\` in un archivio `SQL_HOST_DATASTAMP.7z` nella cartella `out\`;
  * eventuali `.bak` possono essere rimossi (vedi sotto).

* `SqlDropBakAfterZip=` (`true` / `false`)  
  Se `true`:
  * dopo la compressione, elimina i `.bak` da `_sql_stage\` (riduce lo spazio occupato dalla staging).

### 6.4 7-Zip

* `SevenZipCompressionLevel=` (0–9)
  * 0 = store (niente compressione);
  * 3 = compromesso veloce;
  * 7–9 = compressione più forte ma lenta, sconsigliata per DB molto grandi.

Lo script usa `7zr.exe` o `7z.exe` e gestisce automaticamente i codici di ritorno:

* `ExitCode=0` → OK
* `ExitCode=1` → WARNING (non blocca il job, ma segna un warning e l’esito diventa “COMPLETATO CON WARNING”)
* altri codici → errore (solleva eccezione).

### 6.5 rclone

Parametri principali:

* `RcloneRemoteDest=`  
  Percorso remoto in formato `REMOTE:percorso`, es.:

      RcloneRemoteDest=dropbox:/Backups_AdHoc/%COMPUTERNAME%

  Dove:

  * `REMOTE` è il nome configurato in `rclone.conf`;
  * `%COMPUTERNAME%` viene espansa con il nome del server.

* `RcloneBwl=`  
  Limitazione di banda, es. `10M` per 10 MB/s. Vuoto = nessun limite.

* `RcloneExtraArgs=`  
  Lista di argomenti rclone extra, separati da `|`, ad esempio:

      --s3-chunk-size=64M|--s3-upload-concurrency=4|--fast-list

Lo script usa:

* `rclone copyto` per caricare ogni singolo archivio;
* `rclone delete` + `rclone rmdirs` per applicare la retention sul remoto.

Se manca `rclone.conf`, viene aperta una PowerShell con `rclone config --config <percorso>` per configurare almeno un remote.  
In questo caso lo script si ferma dopo aver lanciato la configurazione, con un messaggio chiaro.

### 6.6 Email

Parametri:

* `MailEnabled=` (`true` / `false`)
* `MailSmtpHost=`
* `MailSmtpPort=` (es. 587)
* `MailUseAuth=` (`true` / `false`)
* `MailUser=`
* `MailPassword=`
* `MailFrom=`
* `MailTo=` (uno o più destinatari separati da `|`)
* `MailSubjectPref=`  
  Prefisso per l’oggetto, es.: `[BACKUP ADHOC]`.

`send-mail.ps1` usa queste variabili per costruire la connessione SMTP con TLS e inviare la mail di report.

---

## 7. Il motore di backup – `AdHoc-Backup.ps1`

### 7.1 Avvio e parametri

Lo script accetta:

* `-Config`  
  Percorso del file `backup.conf` da usare.
* `-Quiet`  
  Non stampa nulla su console, scrive solo sul file log.

Ricerca il file di configurazione in questa priorità:

1. se passi `-Config`, usa quello (se esiste, altrimenti errore);
2. se trova `.\bin\conf\backup.conf` (layout installer), usa quello;
3. altrimenti cerca `backup.conf` nella stessa cartella dello script.

### 7.2 Lettura config e variabili script

La funzione `Load-Config`:

1. legge riga per riga `backup.conf`;
2. popola una serie di variabili di **scope script**, ad esempio:
   * `$BackupRoot`
   * `$ArchiveSources`
   * `$EnableFileBackup`
   * `$EnableSqlBackup`
   * `$SqlInstance`, `$SqlUseWindowsAuth`, `$SqlUser`, `$SqlPassword`
   * `$DbInclude`, `$DbExclude`
   * `$SqlCompressStage`, `$SqlDropBakAfterZip`
   * `$SevenZipCompressionLevel`
   * `$EnableRcloneUpload`
   * `$RcloneRemoteDest`, `$RcloneBwl`, `$RcloneExtraArgs`
   * `$KeepLocalArchives`
   * `$LocalRetentionDaysFiles`, `$LocalRetentionDaysDb`, `$RemoteRetentionDays`
   * `$MailEnabled`, `$MailSmtpHost`, `$MailSmtpPort`, `$MailUseAuth`
   * `$MailUser`, `$MailPassword`, `$MailFrom`, `$MailTo`, `$MailSubjectPref`

Se manca un parametro obbligatorio (es. `BackupRoot`, `SqlInstance` con SQL attivo, credenziali quando richieste), lo script solleva un errore e termina in modo controllato.

### 7.3 Inizializzazione percorsi e log

Lo script costruisce:

* `$Paths` (oggetto ordinato con Root/Bin/Logs/Out/SqlStage/Files/Databases)
* `$Files` (percorsi di `SevenZipExe`, `SevenZip7zr`, `RcloneExe`, `RcloneConf`, file log)

Crea (se mancanti) tutte le cartelle:

* root backup
* `Bin`, `Bin\7Zip`, `Bin\RClone`
* `logs`, `out`, `_sql_stage`, `Files`, `Databases`

Genera un log file, ad esempio:

    C:\Backups_AdHoc\logs\backup_2025-11-19_090224.log

e definisce una funzione di logging che scrive su:

* console (a meno che `-Quiet`);
* file log.

### 7.4 Gestione 7-Zip

* `Ensure-7Zip`:
  * controlla se esistono `7z.exe` o `7zr.exe` (prima prova nel layout GUI, poi in `BackupRoot\Bin\7Zip`);
  * se assente, scarica `7zr.exe` da 7-Zip e lo salva nella cartella corretta.

* `Invoke-7ZipArchive`:
  * costruisce gli argomenti corretti (in base a 7z/7zr);
  * usa parametri non interattivi (`-y`, `-bd`, ecc.);
  * controlla `$LASTEXITCODE`:
    * `0` → log “OK”;
    * `1` → log “WARNING”, non blocca il job;
    * altri valori → solleva eccezione.

### 7.5 Gestione rclone

* `Ensure-Rclone`:
  * se `rclone.exe` non esiste, scarica lo zip ufficiale dal sito rclone;
  * lo estrae, trova `rclone.exe`, lo copia in `Bin\RClone`;
  * pulisce le cartelle temporanee.

* `Ensure-RcloneConfigOrLaunch`:
  * se manca `rclone.conf`:
    * apre una PowerShell con `rclone config --config <percorso>`;
    * mostra istruzioni chiare nel log;
    * termina il job con un errore esplicito.

* `Invoke-RcloneCopyTo`:
  * esegue `rclone copyto` con:
    * `--config rclone.conf`;
    * opzioni standard (`--transfers`, `--checkers`, `--retries`, ecc.);
    * eventuale `--bwlimit` derivato da `RcloneBwl`;
    * argomenti extra da `RcloneExtraArgs`.

* `Apply-RemoteRetention`:
  * se `RemoteRetentionDays >= 0` e upload abilitato:
    * esegue `rclone delete` con `--min-age`;
    * esegue `rclone rmdirs` per eliminare cartelle vuote.

### 7.6 Backup SQL Server

Funzioni principali:

* `Resolve-Sqlcmd`  
  Cerca `sqlcmd.exe` nel PATH e in percorsi standard di installazione SQL Server.

* `Build-SqlcmdArgs` / `Log-SqlcmdArgsSafe`  
  Preparano gli argomenti per `sqlcmd`, mascherando la password nella versione loggata.

* `Get-OnlineUserDatabases`  
  Recupera l’elenco dei DB utente online (`sys.databases`), escludendo i system DB (master, model, msdb, tempdb).

* `Backup-SqlDatabases`:

  1. Assicura l’esistenza di `_sql_stage\` e tenta di assegnare permessi `Modify` a `Everyone`, per evitare problemi quando SQL scrive i `.bak` con account di servizio.
  2. Trova `sqlcmd.exe`; se assente → errore.
  3. Determina `dbList` in base a `DbInclude`/`DbExclude`.
  4. Per ogni DB:
     * produce script `.sql` di backup;
     * lancia `sqlcmd` per eseguire il `BACKUP DATABASE` su un `.bak` in `_sql_stage\`;
     * verifica l’esistenza del file `.bak`.
  5. Se `SqlCompressStage=true`:
     * comprime `_sql_stage\` in `SQL_HOST_DATASTAMP.7z` dentro `out\`;
     * se `SqlDropBakAfterZip=true`, cancella i `.bak`.
  6. Ritorna il percorso dell’archivio SQL oppure `null` se non creato.

### 7.7 Archiviazione file/folder

* `Archive-FileSources`:
  * normalizza e verifica tutte le sorgenti di `ArchiveSources`;
  * crea un archivio tipo `FILES_HOST_DATASTAMP.7z` in `out\`;
  * ritorna il percorso dell’archivio o `null` se nessuna sorgente è valida.

### 7.8 Gestione cartella `out\` e copie locali

* `Get-OutFiles`  
  Restituisce tutti i file presenti in `out\`.

* `Move-OutFiles-ToStores`  
  Sposta gli archivi:
  * quelli con nome che inizia per `FILES_` in `Files\`;
  * gli altri (SQL) in `Databases\`.

* `Delete-OutFiles` / `Empty-OutFolder`  
  Eliminano i file e/o eventuali sottocartelle in `out\`.

### 7.9 Retention locale

* `Apply-LocalArchivesRetention`  
  Per ogni file in `Files\` e `Databases\` più vecchio di `LocalRetentionDaysFiles`/`LocalRetentionDaysDb`:

  * prova a cancellarlo;
  * logga sia successi che errori.

* `Apply-GenericRetention`  
  Applica retention generica su:

  * `logs\`
  * `_sql_stage\`

  cancellando file più vecchi di `RetentionDays`.

### 7.10 Flusso MAIN (riassunto)

In modo semplificato:

1. Crea tutte le cartelle necessarie.
2. Scrive nel log i parametri principali (root, retention, ecc.).
3. Inizia a costruire una stringa di **riepilogo** con:
   * hostname
   * data/ora di start
   * dettagli che verranno aggiunti via via.
4. Prepara i tool:
   * se servono archivi (`EnableFileBackup` o SQL compresso), chiama `Ensure-7Zip`;
   * se `EnableRcloneUpload=true`, chiama `Ensure-Rclone` e `Ensure-RcloneConfigOrLaunch`.
5. Se `EnableSqlBackup=true`:
   * esegue `Backup-SqlDatabases`;
   * aggiunge al riepilogo il percorso dell’archivio SQL (se presente).
6. Se `EnableFileBackup=true`:
   * esegue `Archive-FileSources`;
   * aggiunge al riepilogo il percorso dell’archivio file.
7. Determina i file effettivamente presenti in `out\`:
   * se nessuno → warning.
8. Se upload abilitato e ci sono file in `out\`:
   * per ogni file costruisce il percorso remoto:
     
         <RcloneRemoteDest>/<DATASTAMP>/<NOMEARCHIVIO>
     
   * chiama `Invoke-RcloneCopyTo` per inviarlo;
   * aggiorna il riepilogo con la destinazione.
9. Copie locali:
   * se `KeepLocalArchives=true`:
     * `Move-OutFiles-ToStores` e `Empty-OutFolder`;
   * se `false`:
     * `Delete-OutFiles` e `Empty-OutFolder`.
10. Retention:
    * se upload abilitato → `Apply-RemoteRetention`;
    * sempre → `Apply-LocalArchivesRetention` + `Apply-GenericRetention`.
11. Determina l’esito finale:
    * se sono stati registrati warning → `ESITO: COMPLETATO CON WARNING`;
    * se nessun errore/warning → `ESITO: COMPLETATO`.
12. Report mail:
    * se `send-mail.ps1` esiste:
      * viene “dot-sourced” ( `. .\send-mail.ps1` );
      * viene chiamata la funzione che invia la mail passando:
        * `Subject = MailSubjectPref + <testo>` (es. include host ed esito);
        * `Body = riepilogo + log sintetico`.
    * se succede un errore generale:
      * il `catch` imposta `ESITO: FALLITO`;
      * logga l’errore;
      * tenta comunque di inviare un’email di fallimento.

---

## 8. Invio mail e template – `send-mail.ps1` + `report_template.html`

### 8.1 Parametri e funzioni principali

`send-mail.ps1` viene eseguito dal motore di backup con:

* `-Subject` → oggetto della mail (prefisso da `MailSubjectPref` + esito/hostname);
* `-Body` → testo con riepilogo + estratto del log.

Funzioni principali:

* `Format-Bytes` / `Format-Duration`  
  Utility per formato dimensione e durata in forma leggibile.

* `Get-StatusInfo`  
  Analizza la stringa `Body` cercando `ESITO: ...` e restituisce:
  * stato (OK/WARNING/FAIL) e
  * colore da usare nel template (verde/giallo/rosso).

* `Build-ReportHtml`  
  Costruisce l’HTML finale del report:
  1. Cerca `report_template.html` in:
     * `$script:InstallerConfDir` (quando eseguito tramite installer GUI),
     * `$InstallerConfDir`,
     * `bin\conf` vicino allo script,
     * `C:\polo\scripts\bin\conf`.
  2. Se non trova il template:
     * genera una versione HTML di fallback (semplice ma leggibile) e **non blocca** il job.
  3. Se trova il template:
     * lo legge in UTF-8;
     * sostituisce i placeholder con:
       * stato e colore (`XXXSTATUSXXX`, `XXXBGCOLORXXX`, ecc.);
       * host, versione script;
       * data/ora di inizio/fine, durata;
       * dimensioni totali/SQL/FILES;
       * spazio disco totale/usato/libero;
       * destinazione rclone;
       * dettaglio del log formattato con `<br>` al posto dei newline.

* `Send-ReportMail`  
  Si occupa di inviare realmente la mail:

  1. Se `MailEnabled=false` → esce loggando che la mail è disabilitata.
  2. Recupera i parametri `Mail*` (host, porta, credenziali, mittente, destinatari).
  3. Crea un `SmtpClient`:
     * abilita SSL/TLS;
     * imposta eventuali credenziali (`MailUser` / `MailPassword`);
     * imposta `From` e `To`.
  4. Imposta `Body` HTML (quello generato da `Build-ReportHtml`) e l’oggetto.
  5. Invia e logga il risultato.

Alla fine del file:

* viene chiamato `Send-ReportMail -Subject $Subject -Body $Body`.

---

## 9. Modalità d’uso consigliata (end-to-end)

### 9.1 Prima installazione

1. Apri **PowerShell come Administrator**.
2. Lancia l’installer GUI con:

       powershell
       irm "https://gitea.poloinformatico.it/Mattia/Backup-AdHoc/raw/branch/main/install-AdHoc-Backup-GUI.ps1" | iex

3. Nella GUI:
   * verifica la **cartella di installazione** (es. `C:\polo\scripts`);
   * lascia gli URL di default, a meno che tu non voglia prendere i file da un tuo branch.
4. Configura la **schedulazione**:
   * spunta “Crea attività pianificata”;
   * imposta “Giornaliero” o “Settimanale”;
   * scegli l’orario (es. 23:00) e il giorno (se settimanale);
   * eventualmente modifica il nome dell’attività.
5. Compila la sezione `backup.conf`:
   * imposta `BackupRoot` (es. `C:\Backups_AdHoc`);
   * imposta `ArchiveSources` con le cartelle da salvare;
   * configura SQL (istanza, autenticazione, DB da includere/escludere);
   * imposta `RcloneRemoteDest` e, se necessario, `RcloneBwl`/`RcloneExtraArgs`;
   * configura la parte mail (SMTP, credenziali, mittente/destinatari).
6. (Opzionale) Spunta “Eseguire il backup subito dopo l’installazione” per fare un test completo.
7. Premi **“Installa”**:
   * l’installer scarica gli script;
   * prepara layout e tool;
   * crea la Scheduled Task se richiesto.
8. Premi **“Chiudi”**:
   * se avevi spuntato l’opzione, parte il backup immediato.

### 9.2 Verifica dopo il primo run

* Controlla il **log** in `C:\Backups_AdHoc\logs\`.
* Verifica che:
  * siano presenti archivi in `Files\` / `Databases\` (se `KeepLocalArchives=true`);
  * i file siano arrivati sul remoto (rclone);
  * sia arrivata la **mail di report** all’indirizzo/i impostati in `MailTo`.

### 9.3 Esecuzione manuale (senza GUI)

Una volta installato, puoi sempre testare o lanciare il backup manualmente.

Da PowerShell:

    cd C:\polo\scripts
    .\AdHoc-Backup.ps1 -Config "C:\polo\scripts\bin\conf\backup.conf"

Oppure in modalità silenziosa:

    cd C:\polo\scripts
    .\AdHoc-Backup.ps1 -Config "C:\polo\scripts\bin\conf\backup.conf" -Quiet

---

## 10. Troubleshooting rapido

* **Errore: “File di configurazione non trovato. Ho creato un template…”**
  * Lo script non trova `backup.conf` → ne crea uno base.
  * Compila il template generato e riesegui il backup.

* **Errore SQL: `sqlcmd.exe non trovato`**
  * Installa i client tools di SQL Server oppure aggiungi `sqlcmd.exe` al PATH di sistema.
  * Verifica i permessi di scrittura su `_sql_stage\` (account del servizio SQL).

* **Errore rclone: `rclone.conf assente`**
  * Lo script apre una PowerShell con `rclone config`.
  * Configura almeno un remote con il nome usato in `RcloneRemoteDest`.
  * Riesegui il backup dopo aver completato la configurazione.

* **Mail non arrivano**
  * Verifica `MailEnabled=true` in `backup.conf`.
  * Controlla `MailSmtpHost` / `MailSmtpPort` / `MailUseAuth` / `MailUser` / `MailPassword`.
  * Verifica che `MailFrom` e `MailTo` siano corretti.
  * Usa il pulsante **“Test mail”** della GUI per fare prove rapide.

* **Spazio disco che si riempie troppo**
  * Controlla:
    * `LocalRetentionDaysFiles`
    * `LocalRetentionDaysDb`
    * `RetentionDays` (per log e `_sql_stage`)
  * Riduci i valori se vuoi conservare meno storico, oppure aumenta lo spazio a disposizione.

* **Backup troppo lenti o banda saturata**
  * Aumenta o diminuisci `SevenZipCompressionLevel` a seconda delle esigenze.
  * Usa `RcloneBwl` per limitare la banda, es.:

        RcloneBwl=10M

  * Valuta di schedulare il backup in orari notturni tramite la GUI.

---