Restic Retention Flags¶
Backup policies use Restic retention flags to decide which snapshots to keep and which to remove. When a policy runs, Restic evaluates every flag and keeps a snapshot if any flag matches it — so the flags combine rather than compete.
Understanding these flags matters because retention is what controls both how far back you can restore and how much backup storage you pay for.
How the portal uses them¶
Retention is set on the Frequency & retention policy (required) step of the add-policy wizard, under Admin → Backups → Policies. (Inside that step, the section is headed "Configure frequency & retention policy" — but the wizard's own step name, shown in the stepper at the top, is "Frequency & retention policy (required)".) You have two options:
- Enter a count per period. Under Choose number of Snapshots to Keep per each period, fill in
Hourly, Daily, Weekly, Monthly and Yearly. The portal turns these into the
flag string for you, always writing all five flags together — a period you leave at
0becomes--keep-<period> 0, which keeps nothing for that period. - Use custom retention flags. Enable this to write the flag string yourself, using any of the
flags below, including
--keep-last.
Existing policies show the resulting string in the Retention flags column of the policy list,
so you can always see exactly what a policy will keep — for example
--keep-hourly 0 --keep-daily 1 --keep-weekly 0 --keep-monthly 0 --keep-yearly 0.
Note
--keep-last is not among the per-period fields. If you want to keep a fixed number of the most
recent snapshots regardless of when they were taken, you must use custom retention flags.
Retention flags¶
Each flag takes a count, written as n below.
| Flag | Keeps |
|---|---|
--keep-last n |
The n most recent snapshots, regardless of when they were taken. |
--keep-hourly n |
The most recent snapshot from each of the last n hours that have snapshots. |
--keep-daily n |
The most recent snapshot from each of the last n days that have snapshots. |
--keep-weekly n |
The most recent snapshot from each of the last n weeks that have snapshots. |
--keep-monthly n |
The most recent snapshot from each of the last n months that have snapshots. |
--keep-yearly n |
The most recent snapshot from each of the last n years that have snapshots. |
Note
The counts refer to periods that contain snapshots, not to calendar periods. If a VM was
powered off for three days, --keep-daily 7 still keeps seven daily snapshots — they will
just span more than seven calendar days.
Example¶
This keeps:
- The newest snapshot from each of the last 7 days that have snapshots, and
- The newest snapshot from each of the last 5 weeks that have snapshots.
A snapshot that satisfies either rule is kept. In practice this gives you daily granularity for the past week and weekly granularity for roughly the past month, while everything older is removed.
Choosing a retention policy¶
- Start from your recovery requirement, not from storage. Decide how far back you need to restore and at what granularity, then express that as flags.
- Combine granularities so that recent backups are dense and older ones are sparse — the example above is a reasonable default for most workloads.
- Set at least one flag. A policy with no retention flags never removes anything, and backup storage grows without limit.
Warning
Removing a flag from an existing policy can delete snapshots the next time it runs. Check what a change will remove before you save it.