-
Notifications
You must be signed in to change notification settings - Fork 0
Features and Interface
BackupCheckup reads Home Assistant's native backup inventory and distinguishes regular automatic and manual backups from small technical app-update snapshots. It evaluates:
- date and age of the newest regular backup,
- automatic or manual origin,
- reported completeness and failed components,
- size and change compared with a backup of matching origin and scope,
- available storage agents and copies of the newest backup,
- native backup-manager and automatic-schedule state,
- locally observed automatic successes and failures.
Refresh backup data only reloads the lightweight inventory. It does not download or fully scan a backup.
sensor.backup_checkup_status reports the highest-priority current problem, such as no backup, stale, incomplete, storage error, or integrity failure. Every simultaneous cause remains available in attributes and dedicated binary sensors.
sensor.backup_checkup_recommendation turns the primary state into a useful next action, such as creating a backup, checking the schedule, repairing storage, reviewing backup contents, or replacing a failed recovery point.
The deterministic Health Score ranges from 0 to 100 and explains every deduction through these attributes:
-
deductions: deductions actually applied, -
component_deductions: applied deduction by cause group, -
raw_deductions: every detected candidate, -
suppressed_correlated_deductions: related symptoms not counted twice, -
score_version: calculation-model version.
Related symptoms are correlation-aware. A storage outage can cause a storage error, missing location, and insufficient redundancy at the same time; only the strongest deduction in that cause group affects the score. Independent problems can still combine.
| Condition | Typical deduction |
|---|---|
| No backup | 100 |
| Corrupt or unreadable backup | 60 |
| Backup manager unavailable | 50 |
| Stored checksum changed | 40 |
| Stale backup | 20 / 25 / 35 depending on severity |
| Incomplete backup | 25 |
| Latest automatic backup failed | 20 |
| Storage error | 20 |
| Suspicious size | 15 |
| Insufficient redundancy | 15–25 |
| Automatic backup overdue | 15 |
| Integrity warning | 11 |
| Schedule missing or overdue | 10 |
| Observed success rate below 95 / 80 / 60% | 5 / 12 / 20 |
| Consecutive automatic failures | 5 each, maximum 15 |
BackupCheckup uses only backups inside the configured analytics window. Sizes are compared only when origin and backup scope match, preventing a manual partial backup from being compared with a complete automatic backup.
It calculates size trend, average comparable size, longest observed gap, automatic success rate, and consecutive automatic failures. This is a bounded local observation history, not unlimited long-term statistics.
Check backup protection is the central non-destructive verification. It selects the newest regular backup, prefers an available local copy, and otherwise uses another reachable native storage agent.
The structural phase:
- checks expected size and free temporary storage,
- downloads the selected copy,
- calculates SHA-256,
- decrypts protected backups with credentials supplied by Home Assistant,
- validates metadata, paths, and archive boundaries,
- completely reads all nested archives and regular files,
- optionally checks the included SQLite database,
- stores only bounded evidence and removes temporary data.
Valid proves structural readability, not the availability of every external dependency. Valid with warnings means the archive was completely readable but a non-blocking inconsistency was detected. Aborted means a configured safety limit stopped the check and does not prove corruption.
The older Verify latest backup action and button remain as compatibility aliases for the same protected pipeline.
Deep verification temporarily extracts the included Home Assistant database and runs SQLite PRAGMA integrity_check. This requires additional time and temporary space. The production database is never opened or modified.
When enabled, BackupCheckup synchronizes Home Assistant Repairs for important conditions such as missing, stale, incomplete, or non-redundant backups, storage failures, integrity problems, and failed temporary cleanup. Resolving a problem removes the corresponding Repair.
Localized messages are sent to selected Companion App targets when an active problem group first appears or changes. An unchanged condition is not resent at every poll. An optional recovery message is sent when all previously reported problems are resolved.
The optional activity journal shows steps such as inventory refresh, download, extraction, database checking, status changes, notifications, and runner stages. It stores fixed action, outcome, and error codes instead of backup names, paths, tokens, or passwords.
The bounded journal can remain memory-only or be persisted for 1–30 days. Administrators can filter, export, and clear it.
The optional panel contains four sections:
- Overview: Health Score, status, recommendation, newest backup, storage, and active problems
- Recovery: Recovery Score, evidence level, risks, inventory comparison, protection check, runner, preparedness, and emergency plan
- Settings: every integration option for administrators
- Live log: filterable activity events and export
The panel is an additional interface. Monitoring continues when it is disabled.
Open Settings → Devices & services → BackupCheckup → three-dot menu → Download diagnostics. The sanitized report contains configuration, counts, states, and verification evidence. Backup names and IDs, contents, passwords, and selected notification entity IDs are excluded.