v0.5.6

Changed

• Structured exit codes — categorised non-zero exits (config / lock / storage / VM / tool / CLI / dependency) let monitoring distinguish why a run failed without parsing logs. Symmetric with vmrestore.

Fixed

• Retention not enforced for skipped or excluded VMs — Retention was wired only to the post-backup success path, so any VM that was skipped (SKIP_OFFLINE_UNCHANGED_BACKUPS=true) or excluded (policy=never) accumulated period directories indefinitely with no rotation. The same code path also created the period directory via mkdir -p before deciding whether the backup would run, leaving an empty stub on disk every time a VM was skipped, excluded, or failed before first write. Combined effect on production: VMs at RETENTION_WEEKS=4 carrying 8+ weekly directories, including pure stubs that no later session would ever clean up. Retention is now invoked from the skip and exclude paths via the new run_retention_for_unbacked_vm wrapper, which orders stub cleanup before retention so the period count is correct before the limit check runs. Excluded VMs (policy=never) have stubs removed but their populated periods are preserved by the policy short-circuit. Failed-path retention remains intentionally suppressed; failed-path stubs are reaped on the next non-failed session.

Added

• Stub-aware retention pipeline for unbacked VMs — A new run_retention_for_unbacked_vm wrapper in modules/retention_module.sh runs stub cleanup → retention → orphan retention in that order whenever a VM is skipped or excluded, so the on-disk period count is correct before the limit check fires. Stub cleanup is performed by the new _remove_empty_period_dirs helper, which removes pure stub directories (zero *.data, no .archives/) and is anchored to BACKUP_PATH with a path-shape regex guard, deliberately bypassing _remove_period's keep-last, replication, and protected-period guards (all inappropriate for empty directories). Stub deletions in SQLite go through a new UPDATE-only library function sqlite_mark_chain_deleted_if_exists (in lib/sqlite_module.sh) to avoid injecting phantom active-then-deleted chain_health rows when a pure stub never had a row to begin with.

Changed

• retention_events audit attribution — Field 12 (triggered_by) no longer carries hardcoded function-name literals; it now records the high-level event that drove the prune, with new enum values skipped, excluded, and orphan_dir joining the existing post_backup, prune, and orphan_retention. The action column also gains remove_stub for the new stub-cleanup path. Internally, _remove_period, _remove_orphan_period, _remove_archive_chain, _remove_archives_in_period, _remove_vm_all, run_retention_for_vm, and run_orphan_retention_for_vm all gain a new trigger parameter so the originating event propagates through the call chain into the audit row — making it possible to attribute retention activity to skipped-VM and excluded-VM sessions for the first time.

v0.5.5

Added

• Configurable backup-destination space thresholds — Four new optional vmbackup.conf settings (DISK_ABORT_PCT, DISK_WARN_PCT, DISK_ABORT_GB, DISK_WARN_GB) let check_disk_space() be tuned per instance. Percent and absolute thresholds are evaluated together so either can fire independently; setting any threshold to 0 disables it. Defaults (20%/30% and 10 GB/50 GB) preserve previous behaviour.
• Disk-space snapshot per session (schema v2.1) — sessions table gains disk_free_bytes and disk_total_bytes columns, populated by sqlite_session_end() from a df capture against BACKUP_PATH. Migration from v2.0 is automatic, idempotent and additive.
• --status reporting command — Seven report modes: sessions, VM history, failures, replication, chains, storage, policies. Terminal tables by default, --csv for export, --days N for time window, --all-instances to span every config instance. Sessions output is job-type-aware (backup / prune / replicate-only / mixed) and scoped to the active CONFIG_INSTANCE by default. The storage report includes per-VM size trends and a destination-growth projection that names the configured DISK_ABORT_PCT threshold.
• Post-upgrade config advisory in postinst — On dpkg upgrade, lists .dpkg-dist files awaiting merge with per-file diff -u commands and points custom config instances at config/template/vmbackup.conf for new variables. Visible only on upgrade.
• vmbackup --config-prune-removed — Cleanup helper that comments out configuration variables removed in the running release. Idempotent; supports --dry-run. Operates on default/ and all custom instances; skips template/. Per-name allowlist keyed to release version, designed to be extended by future config-pruning ENHs.

Fixed

• Pre-flight aborts failed silently with no email — check_backup_destination(), check_scratch_path() and check_disk_space() exit before main() reaches its normal email send, so destination/scratch/space failures left no notification (only a journal entry). cleanup_on_exit() now sends a failure report on any non-zero exit once a SQLite session has been registered, gated by _EMAIL_SENT so the existing success/failure path remains the single source of truth on normal runs.
• SKIP_OFFLINE_UNCHANGED_BACKUPS is now honoured — Previously the variable was defined and validated but never read; offline-unchanged VMs were always skipped regardless of the setting. The change-detection call in backup_vm() is now gated by this flag.

Removed

• OFFLINE_CHANGE_DETECTION_THRESHOLD — Was never read by the change-detection code (which uses strict mtime > last_backup). The variable inverted the safe default and would have introduced false negatives if implemented. Existing values in operator configs are inert; run vmbackup --config-prune-removed to clean them up.
• EMAIL_INCLUDE_REPLICATION — Was never read. Hiding replication results from the email is operator-hostile (silent on success, dangerous on failure). The empty-section logic already handles the no-replication case.
• EMAIL_INCLUDE_DISK_SPACE — Was never read; gated a section that was never built. A real disk-usage email section is tracked as ENH-16.

v0.5.4

Fixed

• SQLite session not finalised on normal exit — Sessions could be left permanently "in progress" in the database. Now finalised unconditionally in cleanup_on_exit() with idempotency guard.
• Silent permission failures on backup path — chown/chmod failures now log warnings instead of being silently suppressed with || true.
• Stale lock cleanup could delete active locks — Now validates PID liveness before deletion and uses correct vmbackup-*.lock glob.
• Session PID lock race condition — Replaced non-atomic check-then-write with noclobber pattern.
• Double email on SIGTERM — Added _EMAIL_SENT guard flag.
• virtnbdbackup not confirmed dead before retry — Added pgrep/pkill cleanup and virsh domjobabort before retry.
• Reorder config-instance validation before session lock — --config-instance nonexistent now fails immediately at startup.

Install

wget https://github.com/doutsis/vmbackup/releases/download/v0.5.4/vmbackup_0.5.4_all.deb
sudo dpkg -i vmbackup_0.5.4_all.deb

Full changelog: CHANGELOG.md

v0.5.3

Added

• --run flag required to start backups — explicit mode for all operations
• --vm targeted backup mode — back up specific VMs on demand
• Unknown flag detection and --cancel-replication conflict guards
• Root privilege check with clear error message
• Global session lock to prevent concurrent invocations
• session_type column in SQLite sessions table (schema v2.0)

Changed

• SKIP_OFFLINE_UNCHANGED_BACKUPS default changed to true
• --help output restructured
• Systemd service updated with --run flag
• Documentation rewritten — condensed from ~4,500 to ~2,900 lines

Removed

• Host Configuration Backup feature

Fixed

• RETENTION_ORPHAN_DRY_RUN config setting was being ignored

See CHANGELOG.md for full details.

v0.5.2

See CHANGELOG.md for details.

v0.5.1

Fixed

• chain_health off-by-one — total_checkpoints and restorable_count were 0 after first backup instead of 1
• restore_points counted per-disk instead of per-backup — multi-disk VMs reported 3× the correct count
• csv_ variable name remnants — 25 stale variable names and dead CSV cleanup code removed
• Archived chains missing vmconfig XML and TPM marker — chain archives were incomplete; now self-contained

See CHANGELOG.md for details.

v0.5.0

Initial public release.

Install:

sudo dpkg -i vmbackup_0.5.0_all.deb

See README for configuration and usage.