From 12a2cc4485c8759ee2efbd733c31b2c95c914ccd Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 23 Jan 2026 11:22:31 +0100 Subject: [PATCH] Add README from spec --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f7c89c8 --- /dev/null +++ b/README.md @@ -0,0 +1,57 @@ +# Backup Orchestrator (bckWinRsync) + +## Sommario +- Client Windows PySide6 che manda richieste HTTPS a un Orchestrator FastAPI. +- Server Debian su Proxmox che esegue job `rsync` in pull verso `/srv/backup/current` con storicizzazione (`.history/`) e retention 20 esecuzioni. +- Sicurezza LAN con HTTPS, SSH, logging strutturato, validazione path e protezioni sulle credenziali. + +## Requisiti principali +1. Il client gestisce profili e selezione di cartelle, abilitando “Esegui” solo con almeno una destinazione valida. +2. Il pulsante “Esegui” invia credenziali SSH e percorsi al backend, che crea un job e lo mette in coda. +3. Il job runner server si connette via SSH al client e invoca `rsync --backup --backup-dir=/srv/backup/.history/`, senza `--delete`. +4. Le cancellazioni upstream non si propagano: `/current` mantiene i file attivi e `.history` conserva le versioni precedenti fino a 20 run. +5. Il client mostra log/progress via GUI, notificando il completamento o eventuali errori. +6. `config.json` (vicino all’eseguibile) definisce profili, cartelle, endpoint API, compressione e toggle dello scheduler `schtasks`. Lo scheduler può essere attivato o disattivato per chiamare l’API autonomamente. + +## Non funzionali +- Affidabilità tramite job idempotenti con lock e timeout. +- Performance differenziali con `rsync -a --info=progress2 --compress` opzionale e `--partial`. +- Manutenibilità grazie a separazione chiara tra GUI, orchestratore e runner/logging. +- Sicurezza con token JWT, HTTPS, SSH limitato all’utente `backupsvc`, DPAPI per credenziali e log rotati. + +## Architettura +- **Client PySide6**: profili, scheduler switch, log real-time, polling stato API (`/backup/status/{job_id}`, `/backup/log/{job_id}`). +- **Orchestrator FastAPI + Uvicorn**: espone `/auth/login`, `/profiles`, `/backup/start`, `/backup/status`, `/health`; usa DB (SQLite/Postgres) per job e log. +- **Job Runner (systemd)**: serializza job, invia comandi SSH verso il `sshd` Windows, aggiorna stato job e archivia log/retention. +- **Backup Storage**: `/srv/backup/current` per il dataset attivo, `/srv/backup/.history/` per versioni storiche. + +## API e sicurezza +- Autenticazione via `/auth/login` che restituisce JWT con scadenza, ratelimit e lockout. +- Validazione input (allow-list cartelle, no path traversal) e logging strutturato JSON senza password. +- HTTPS con certificati self-signed o CA interna; SSH consentito solo dall’IP del server verso `backupsvc` con shell limitata. +- Retention 20 run con task di cleanup che elimina `.history` più vecchi. + +## Scheduling e configurazione +- Switch PySide6 gestisce `schtasks` che esegue `BackupClient.exe --auto` con token, se abilitato. +- Configurazione opzionale per credenziali via DPAPI o prompt ogni esecuzione. +- Job runner esegue `rsync` con lock e retry/timeout configurabili. + +## Fasi previste +1. Setup server: Debian, storage `/srv/backup`, rsync, OpenSSH client/server, permessi. +2. Orchestrator: API start/status/log, DB, job queue, retention automatica. +3. Client PySide6: GUI, log, scheduler sincronia, config e packaging. +4. Windows helper: script attivazione OpenSSH/rsync, firewall e permessi. +5. QA/hardening: logging, rate limit, test end-to-end e threat modeling leggero. + +## Checklist sicurezza +- SSH da server solo verso IP autorizzato e `backupsvc`. +- Password SSH mai loggate, prompt o DPAPI. +- HTTPS interno gestito con cert e rotazione log (logrotate). +- Validazione input e cron job cleanup. +- Utente Linux `backupsvc` con directory `700`, log `640`. + +## Deliverable attesi +- Repo server: FastAPI, runner, doc/install, test. +- Repo client: PySide6, config schema, scheduler script, rsync portable. +- Documentazione: manuale utente, runbook admin, threat model, checklist. +- CI: lint/test/build/release pipeline.