Bak&Rest monitora cartelle configurate su Windows, registra i file creati, modificati, cancellati o spostati e prepara il backup successivo tramite tray app.

Per il dettaglio delle scelte tecniche, dei problemi risolti e delle decisioni prese durante la messa a punto, leggere anche DOCUMENTAZIONE_TECNICA.md.

Componenti

BakRestWatchdog: servizio Windows di monitoraggio.
BakRestTray: tray app che eseguira' il backup e lo spegnimento.
BakRestConfig: GUI di configurazione.

Configurazione

Alla prima esecuzione viene creato un file TOML modificabile in:

%PROGRAMDATA%\BakRest\config.toml

Per creare o trovare il file di configurazione:

python -m bakrest.config_cli init
python -m bakrest.config_cli path
python -m bakrest.config_cli show

Se il servizio gira come LocalSystem, imposta l'utente a cui devono riferirsi i percorsi nel tab Monitoraggio, campo Utente percorsi, oppure nel TOML:

[watch]
target_user = "pettirosso"
include_dirs = [
  "%USERPROFILE%\\Documents",
  "%USERPROFILE%\\Desktop",
]

Con target_user = "pettirosso", %USERPROFILE% viene espanso come C:\Users\pettirosso anche se il servizio gira come SYSTEM.

In sviluppo si puo' usare un percorso diverso:

$env:BAKREST_CONFIG="C:\devel\bak&rest\config\config.toml"
python -m bakrest.watchdog_runner

Avvio watchdog in console per test

python -m pip install -e .
python -m bakrest.watchdog_runner

Il watchdog usa il journal USN NTFS per distinguere modifiche reali da eventi rumorosi generati da navigazione, anteprime o metadati. La lettura del journal puo' richiedere privilegi elevati: il servizio eseguito come LocalSystem e' il percorso consigliato. Se USN non e' disponibile o non e' leggibile, il servizio registra un warning e usa un fallback conservativo.

Se nel log compare:

USN journal unavailable for \\.\D:: [WinError 1179] Il journal delle modifiche al volume non e' attivo.

abilita il journal USN sul volume da PowerShell/CMD amministratore:

fsutil usn createjournal m=134217728 a=33554432 D:

Poi riavvia il servizio. Per verificare:

fsutil usn queryjournal D:

Nella configurazione, per cartelle utente puoi usare token portabili come %DOCUMENTS%, %DOWNLOADS%, %PICTURES%, %MUSIC%, %VIDEOS%, %FAVORITES%. Con target_user = "utente" vengono espansi sotto C:\Users\utente.

Avvio tray app per test

python -m pip install -e .
python -m bakrest.tray_app

La tray app legge lo stato prodotto dal servizio e offre il comando Backup e spegni. Se il backup fallisce, lo spegnimento non viene eseguito.

Il servizio Windows non controlla il server di backup: resta dedicato al solo watchdog dei file. La raggiungibilita' dello slave viene controllata dal notifier schedulato.

Quando il notifier rileva che il server di backup non e' raggiungibile, mostra una finestra con:

Accendi il server di backup o verifica che sia connesso alla rete

Il notifier puo' essere eseguito da Task Scheduler con:

python -m bakrest.server_notifier

Azione Task Scheduler consigliata:

Programma: C:\Python314\python.exe
Argomenti: -m bakrest.server_notifier
Avvia in: C:\devel\bak&rest

Schedulazione consigliata: all'accesso dell'utente e poi ogni 30 minuti. Il notifier mostra l'avviso una sola volta mentre il server resta non raggiungibile, poi si resetta quando il server torna raggiungibile.

Backup senza GUI per Task Scheduler

Lo stesso entry point della tray puo' eseguire il backup senza mostrare icone o finestre:

python -m bakrest.tray_app --nogui

Per testare senza spegnere il PC:

python -m bakrest.tray_app --nogui --no-shutdown

In alternativa si puo' chiamare direttamente il modulo dedicato:

python -m bakrest.backup_nogui

Questo percorso e' pensato per Task Scheduler alla disconnessione dell'utente. Se il server non e' raggiungibile o il backup fallisce, il comando termina con errore e non spegne il PC.

Azione Task Scheduler consigliata in sviluppo:

Programma: C:\Python314\python.exe
Argomenti: -m bakrest.tray_app --nogui
Avvia in: C:\devel\bak&rest

Motore backup Windows

Il default e' robocopy, pensato per copiare verso share SMB su un server Windows:

[backup]
engine = "robocopy"
server_host = "backup-server"
remote_destinations = [
  "\\\\backup-server\\BakRest1",
  "\\\\backup-server\\BakRest2",
]
robocopy_path = "robocopy"

[backup.server_check]
type = "tcp"
port = 445
interval_seconds = 1800

Task Scheduler

Sono disponibili XML importabili in Task Scheduler:

tasks\BakRestBackupOnLogoff.xml
tasks\BakRestServerNotifierEvery30Minutes.xml

Gli XML sono sorgenti di base. Per registrarli su una macchina reale e' consigliato usare lo script PowerShell, che corregge dinamicamente path Python, working directory e codifica:

powershell -ExecutionPolicy Bypass -File .\scripts\Register-BakRestTask.ps1 -Task Notifier

Per il backup al logoff, usare credenziali memorizzate. Questa modalita' e' necessaria perche' al logoff il token interattivo non e' abbastanza affidabile per avviare un processo lungo:

powershell -ExecutionPolicy Bypass -File .\scripts\Register-BakRestTask.ps1 -Task BackupOnLogoff -RunAsStoredCredentials -UserName ".\pettirosso"

Per debug senza spegnimento:

powershell -ExecutionPolicy Bypass -File .\scripts\Register-BakRestTask.ps1 -Task BackupOnLogoff -RunAsStoredCredentials -UserName ".\pettirosso" -NoShutdown

Verifica del task backup:

schtasks /Query /TN "BakRest\BackupOnLogoff" /XML |
  Select-String "UserId|LogonType|Winlogon|7002|Arguments"

Il task di backup usa l'evento System del provider Microsoft-Windows-Winlogon, EventID=7002. Nei test l'evento Security 4647 veniva scritto ma non agganciava il task in modo affidabile, quindi e' stato abbandonato.

Nel task definitivo deve comparire:

<LogonType>Password</LogonType>

Il task notifier usa un trigger al logon e un trigger giornaliero con ripetizione PT30M, quindi avvisa durante la giornata anche se non viene usata la tray app.

La copia ricrea il percorso relativo sotto ogni share. Se una cartella monitorata e' D:\Lavori, il file D:\Lavori\Cliente\a.psd viene copiato in:

\\backup-server\BakRest1\Lavori\Cliente\a.psd
\\backup-server\BakRest2\Lavori\Cliente\a.psd

Il programma non usa opzioni distruttive di robocopy: non usa /MIR e non usa /PURGE. Le cancellazioni sul master non vengono propagate allo slave.

Per una prova senza spegnimento:

Programma: C:\Python314\python.exe
Argomenti: -m bakrest.tray_app --nogui --no-shutdown
Avvia in: C:\devel\bak&rest

Avvio GUI configurazione

python -m pip install -e .
python -m bakrest.config_app

La GUI permette di modificare la configurazione e vedere la coda dei file in attesa di backup. I file in coda restano persistenti anche se il computer viene spento senza eseguire il backup.

Installazione servizio Windows

Da PowerShell avviato come amministratore:

python -m pip install -e .
python -m bakrest.service install
python -m bakrest.service start

Se service.autostart = true, il comando install configura il servizio con avvio automatico. Se e' false, il servizio viene installato con avvio manuale. Il valore puo' essere sempre sovrascritto passando esplicitamente le opzioni di pywin32.

Comandi utili:

python -m bakrest.service stop
python -m bakrest.service remove
python -m bakrest.service debug

Il servizio si chiama BakRestWatchdog.