SLD-Filebackups-py | Projects

Funzionalità

Backup selettivo: definisci i percorsi da salvare in un file JSON, ciascuno con il proprio flag di attivazione/disattivazione; nessuna necessità di toccare il codice per aggiungere o rimuovere voci.
Backup delle cartelle: le directory vengono archiviate come .tar.gz (viene preservato solo il nome della cartella come root dell'archivio, senza esporre percorsi assoluti).
Backup dei singoli file: i singoli file vengono compressi come .gz.
Logica salta-se-esiste: se esiste già un backup per la data odierna, viene saltato automaticamente, rendendo lo script sicuro da eseguire più volte al giorno.
Auto-rotazione: dopo ogni esecuzione, i vecchi archivi oltre la soglia di conservazione configurata vengono eliminati automaticamente per ciascuna sottocartella.
Modalità simulazione (Dry-run): visualizza in anteprima quali file verrebbero rimossi dalla rotazione, senza cancellare nulla.
Logging strutturato: invia sempre l'output a console (ottimo per monitorare cron); opzionalmente scrive su un file di log persistente.
Supporto multi-ambiente: passa tra le configurazioni local, local2 e prod in un unico file (o crea un ambiente personalizzato).
Gestione sicura degli errori: voci JSON non valide, percorsi mancanti, cartelle vuote e permessi insufficienti vengono gestiti e registrati senza bloccare l'intera esecuzione.

Struttura del Progetto

📁 backups_script/
├── 🐍 script.py           # Entry point e parser argomenti CLI
├── 🐍 functions.py        # Logica principale: backup, rotazione, controlli
├── 🐍 constants.py        # Stato condiviso: percorsi, configurazione, timestamp
├── 🐍 logger.py           # Configurazione logging (console + file opzionale)
├── 🐍 init.py             # Selettore ambiente (local / prod)
├── 🧰 config.json         # Configurazione runtime
├── 🧰 dir_backups.json    # Lista dichiarativa dei percorsi di backup
└── ⭐ LICENSE             # GNU GPL v3

Responsabilità dei Moduli

File	Ruolo
init.py	Definisce ROOT_DIR_APP e ROOT_DIR_BACKUPS in base all'ambiente selezionato. Viene importato per primo da tutti i moduli.
constants.py	Costruisce tutti i percorsi derivati, carica config.json e dir_backups.json in memoria, acquisisce data e ora corrente.
logger.py	Legge config.json e configura il logger Python con uno StreamHandler su console e un FileHandler opzionale su disco.
functions.py	Contiene la logica di business: default_backup_dir(), check_existing_folders(), backups_now(), autorotate_backups(), show_enabled().
script.py	Inizializza il logging, analizza gli argomenti della riga di comando ed esegue le funzioni appropriate. Senza flag, esegue backup completo + rotazione.

Come Funziona

script.py chiama setup_logger(), che legge config.json e imposta il logging.
default_backup_dir() assicura che la cartella radice di backup e la sottocartella con il nome dell'host esistano su disco.
check_existing_folders() legge dir_backups.json, filtra le voci abilitate (flag == 1), verifica che ciascun percorso esista e lo classifica come "folder" o "file". Cartelle vuote o illeggibili vengono escluse.
backups_now() itera sui percorsi verificati:
- Per le cartelle: crea un archivio #NOME_AAAA-MM-GG.tar.gz usando il modulo standard tarfile di Python.
- Per i singoli file: crea una copia compressa #NOME_AAAA-MM-GG.gz usando gzip + shutil.copyfileobj.
- Se l'archivio per oggi esiste già, la voce viene saltata automaticamente.
autorotate_backups() scansiona ogni sottocartella della directory di backup dell'host, ordina i file .gz per data di modifica (dal più recente) ed elimina quelli oltre il limite di keep_backups.

Installazione

Nessuna dipendenza esterna da installare. Lo script utilizza esclusivamente la libreria standard di Python 3.

git clone https://gitea.sld-server.org/sld-admin/sld-filebackups-py.git
cd sld-filebackups-py

Successivamente configura l'ambiente e i percorsi in init.py e dir_backups.json.

Configurazione

config.json:

{
  "keep_backups": 7,
  "logs": false,
  "logs_path": "/home/backups/logs"
}

Parametro	Tipo	Predefinito	Descrizione
`keep_backups`	Intero	7	Quanti archivi recenti conservare per sottocartella. Quelli più vecchi vengono rimossi dalla rotazione.
`logs`	Booleano	false	Se true, viene scritto un file backup.log in logs_path oltre all'output da terminale.
`logs_path`	Stringa	~/backups/logs	Cartella dove verrà creato il file di log. Creata automaticamente se inesistente.

dir_backups.json:

Questa è la lista dichiarativa di tutti gli elementi da includere nel backup. Ogni voce è un array JSON con tre valori:

[
    [ "/percorso/assoluto/alla/cartella",  1, "BackupDocumenti" ],
    [ "/percorso/assoluto/al/file.conf",  1, "BackupConfig"     ],
    [ "/percorso/disabilitato",           0, "VecchioBackup"    ]
]

Indice	Tipo	Descrizione
0	`Stringa`	Percorso assoluto del file o della cartella da salvare.
1	`Intero`	`1` = abilitato (incluso nel backup). `0` = disabilitato (ignorato).
2	`Stringa`	Identificatore univoco usato come nome della sottocartella e prefisso dell'archivio.

Ambiente (init.py)

env = "local"   # Seleziona tra: "local", "local2", "prod"

Ambiente	ROOT_DIR_APP	ROOT_DIR_BACKUPS
local	/home/sld-admin/Scrivania/backups_script/	###ROOT_DIR_APP###/backups/Daily_File_Backups/
local2	/home/simo-positive/Desktop/backups_script/	###ROOT_DIR_APP###/backups/Daily_File_Backups/
prod	/opt/sld-backups/	/home/backups/backups_root/Daily_File_Backups/

Utilizzo da Riga di Comando

# Backup completo + auto-rotazione (predefinito, nessun flag)
python3 script.py

# Mostra i percorsi abilitati e disabilitati
python3 script.py --show

# Verifica se i percorsi dichiarati esistono su disco e stampa un report
python3 script.py --check

# Esegui il backup con output di debug dettagliato
python3 script.py --debug

# Esegui solo il passaggio di rotazione (nessun nuovo backup creato)
python3 script.py --rotate

# Simula la rotazione senza eliminare alcun file reale
python3 script.py --rotate --dry

Riferimento Parametri CLI

Flag	Forma estesa	Descrizione
-s	--show	Stampa i percorsi abilitati e disabilitati definiti in `dir_backups.json`.
-d	--debug	Esegue il backup con output di debug dettagliato.
-c	--check	Esegue `check_existing_folders()` e mostra lo stato di ogni percorso.
-r	--rotate	Esegue unicamente `autorotate_backups()`. Combinabile con `--dry`.
	--dry	Modalità simulazione per `--rotate`: registra i candidati all'eliminazione senza cancellare nulla.

Esecuzione Automatica con Cron

Per eseguire un backup completo ogni giorno alle 02:00 di notte:

crontab -e

0 2 * * * /usr/bin/python3 /opt/sld-backups/script.py >> /home/backups/logs/cron.log 2>&1

Requisiti

Python 3.6+
Nessuna libreria esterna — utilizza esclusivamente i moduli standard:
- tarfile, gzip, shutil — archiviazione e compressione
- logging — output strutturato
- argparse — gestione argomenti CLI
- pathlib — gestione percorsi
- socket — rilevamento hostname
- json — caricamento configurazioni

Licenza

GNU General Public License v3.0 — consulta il file LICENSE per i dettagli completi.