783 lines
26 KiB
Markdown
783 lines
26 KiB
Markdown
# 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.
|
||
|
||
---
|