Every backup in StateWarden carries its own expiration date, stamped at the moment of creation. Retention is therefore not a cleanup task you run later - it is a property of the backup itself, defined by the Backup Policy that produced it. This article explains how retention is configured, what happens when a backup expires, and how to plan retention against your storage quota and compliance obligations.
1. What Retention Means in StateWarden
Retention is configured per Backup Policy through the Retention (Days) field in the policy editor. The default for a new policy is 30 days.
When a backup job starts, the Agent reads the policy's retention value and calculates the expiration date:
Expiration Date = Backup Creation Time + Retention (Days)
The date is attached to the backup record and is sealed: it cannot be changed afterwards. Editing the policy's retention value affects only backups created after the change. This immutability is deliberate - it ensures a restore point lives exactly as long as configured at the time it was taken, which keeps retention auditable.
Two consequences follow from per-backup expiration:
- Deleting a policy does not delete its backups. Each backup keeps its own expiration date independently of the policy that created it. Removing a policy stops future backups; the existing history expires on its original schedule.
- Mixed lifecycles on one device are normal. A daily policy with 30-day retention and a 4-hour policy with 7-day retention can govern the same device without interfering with each other.
For the full policy model - schedules, sources, and Fair Use limits - see Backup Policies & Smart Quota Management.
2. Keep Forever
Setting Retention (Days) to 0 disables expiration: backups created under that policy are kept indefinitely until deleted manually.
Backups triggered manually, outside any policy schedule, default to Keep Forever.
Use Keep Forever selectively - for example, for a quarterly archive or a pre-migration snapshot. Indefinite retention accumulates storage and counts against your Realm's storage quota for as long as the backup exists.
3. What Happens When a Backup Expires
Expiration is a lifecycle transition, not an immediate wipe:
- Expired: Once the expiration date passes, the backup is logically marked as expired. It disappears from the standard backup lists and is no longer available as a restore point.
- Eligible for cleanup: The expired backup becomes eligible for garbage collection. The Driad storage layer reclaims the physical space asynchronously, during its maintenance windows - storage usage does not necessarily drop at the moment a backup expires.
Deduplication and Reference Counting
StateWarden stores backups deduplicated: backup data is split into chunks, and chunks identical across backups are stored only once. Every chunk is reference-counted - the storage layer tracks how many backups still reference it.
A chunk is physically deleted only when the last backup referencing it has expired or been deleted. Practical consequences:
- Expiring or deleting a single old backup may free little or no space, because most of its chunks are typically shared with newer backups of the same volume.
- The space actually freed by an expiration is roughly the amount of data that exists only in that backup. For a daily chain of a slowly changing volume, that is usually just one day's worth of changes.
- A storage usage figure that does not drop right after backups expire is expected behavior, not a malfunction.
4. Expiration vs. Manual Deletion
Both paths end at the same deduplication rule - space is freed only when no remaining backup references the data - but they differ in intent and control.
Expiration is automatic and policy-driven. No administrator action is required; the backup stops being restorable on its stamped date.
Manual deletion is an immediate, deliberate destroy operation performed from the Restore Data view:
- Locate the backup in the Restore Data view and click the delete icon. The action is available only to users whose Realm role includes the backup deletion permission.
- Confirm the PERMANENT DELETION dialog. The action is irreversible: the cryptographic keys associated with that specific snapshot are discarded, and the data cannot be recovered.
- Depending on your Realm's MFA policy, the Dashboard may challenge you for an MFA code before executing the deletion. See Managing MFA and Identity: Tri-State Logic for how the policy gates destructive actions.
Manual deletion is the correct tool for removing a backup before its stamped date - for example, purging a snapshot taken of a compromised or misconfigured system. For everything else, let retention expire backups on schedule.
5. Failed Backups Are Not Restore Points
Only completed backups count as restore points. A failed backup:
- appears in the Restore Data view with a FAILED status, with the failure reason available on the status chip,
- cannot be mounted or restored - its restore actions stay disabled,
- does not extend your recovery history.
This matters for retention planning: your effective point-in-time coverage is the chain of successful backups only. If a device's backups fail for a week, a 30-day retention window still leaves a 7-day gap at the most recent end. Investigate FAILED entries promptly via Events & Logs instead of assuming the schedule is protecting you.
6. Planning Retention
Against the Storage Quota
Longer retention means more restore points kept alive, which means more chunks pinned by reference counting. Two workload properties drive the real cost:
- Change rate (churn): A database volume that rewrites gigabytes daily accumulates far more unique chunks per retained day than a mostly static file server.
- Backup frequency: A 4-hour policy creates six times as many restore points per day as a daily policy, each pinning its own changed data.
Size retention together with your Realm's storage ceiling - see Understanding Quotas and Fair Use for how the storage quota is tracked and what happens as you approach it.
Against Compliance Needs
Define retention periods from your organization's obligations: regulatory minimums, contractual requirements, and internal governance policies. The sealed expiration date supports audit integrity, since a restore point cannot outlive its configured period. This article is not legal advice - confirm the specific periods applicable to your jurisdiction and industry with your compliance officer or legal counsel.
Recommended Starting Points
The values below are starting points, not rules. Adjust them to your change rates, recovery objectives, and obligations:
- Test and lab machines: 7-14 days. Recovery needs are short-lived; long retention wastes quota.
- Endpoints and workstations: 30 days (the default). Covers the typical window in which data loss is noticed.
- File servers: 90 days. Users regularly request restores of files deleted weeks earlier.
- Databases and line-of-business systems: 90-180 days or more, aligned with business and audit cycles.
- Archival milestones (pre-migration, quarter-end): Keep Forever (
0) on a dedicated policy, reviewed periodically.
StateWarden: Resilience Engineered.