diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..9015b5c --- /dev/null +++ b/readme.md @@ -0,0 +1,782 @@ +# 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 ` 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 `; + * 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: + + // + + * 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 + ` (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 `
` 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. + +---