Removing snapshots according to a policy
Removing snapshots manually is tedious and error-prone, therefore rustic allows
specifying a policy (one or more --keep-*
options) for which snapshots to
keep. You can for example define how many hourly, daily, weekly, monthly and
yearly snapshots to keep, and any other snapshots will be removed.
Warning: If you use an append-only repository with policy-based snapshot removal, some security considerations are important. Please refer to the section below for more information.
Note: You can always use the --dry-run
option of the forget
command,
which instructs rustic to not remove anything but instead just print what
actions would be performed.
The forget
command accepts the following policy options:
--keep-last n
keep then
last (most recent) snapshots.--keep-hourly n
for the lastn
hours which have one or more snapshots, keep only the most recent one for each hour.--keep-daily n
for the lastn
days which have one or more snapshots, keep only the most recent one for each day.--keep-weekly n
for the lastn
weeks which have one or more snapshots, keep only the most recent one for each week.--keep-monthly n
for the lastn
months which have one or more snapshots, keep only the most recent one for each month.--keep-yearly n
for the lastn
years which have one or more snapshots, keep only the most recent one for each year.--keep-tag
keep all snapshots which have all tags specified by this option (can be specified multiple times).--keep-within duration
keep all snapshots having a timestamp within the specified duration of the latest snapshot, whereduration
is a number of years, months, days, and hours. E.g.2y5m7d3h
will keep all snapshots made in the two years, five months, seven days and three hours before the latest (most recent) snapshot.--keep-within-hourly duration
keep all hourly snapshots made within the specified duration of the latest snapshot. Theduration
is specified in the same way as for--keep-within
and the method for determining hourly snapshots is the same as for--keep-hourly
.--keep-within-daily duration
keep all daily snapshots made within the specified duration of the latest snapshot.--keep-within-weekly duration
keep all weekly snapshots made within the specified duration of the latest snapshot.--keep-within-monthly duration
keep all monthly snapshots made within the specified duration of the latest snapshot.--keep-within-yearly duration
keep all yearly snapshots made within the specified duration of the latest snapshot.
Note: All calendar related options (--keep-{hourly,daily,...}
) work on
natural time boundaries and not relative to when you run forget
. Weeks are
Monday 00:00 to Sunday 23:59, days 00:00 to 23:59, hours :00 to :59, etc. They
also only count hours/days/weeks/etc which have one or more snapshots.
Note: All duration related options (--keep-{within,-*}
) ignore snapshots
with a timestamp in the future (relative to when the forget
command is run)
and these snapshots will hence not be removed.
Note: Specifying --keep-tag ''
will match untagged snapshots only.
When forget
is run with a policy, rustic first loads the list of all snapshots
and groups them by their host name and paths. The grouping options can be set
with --group-by
, e.g. using --group-by paths,tags
to instead group snapshots
by paths and tags. The policy is then applied to each group of snapshots
individually. This is a safety feature to prevent accidental removal of
unrelated backup sets. To disable grouping and apply the policy to all snapshots
regardless of their host, paths and tags, use --group-by ''
(that is, an empty
value to --group-by
).
Additionally, you can restrict the policy to only process snapshots which have a
particular hostname with the --host
parameter, or tags with the --tag
option. When multiple tags are specified, only the snapshots which have all the
tags are considered. For example, the following command removes all but the
latest snapshot of all snapshots that have the tag foo
:
rustic forget --tag foo --keep-last 1
This command removes all but the last snapshot of all snapshots that have either
the foo
or bar
tag set:
rustic forget --tag foo --tag bar --keep-last 1
To only keep the last snapshot of all snapshots with both the tag foo
and
bar
set use:
rustic forget --tag foo,bar --keep-last 1
To ensure only untagged snapshots are considered, specify the empty string ‘’ as the tag.
rustic forget --tag '' --keep-last 1
Let’s look at a simple example: Suppose you have only made one backup every Sunday for 12 weeks:
rustic snapshots repository f00c6e2a opened successfully, password is correct ID Time Host Tags Paths
## 0a1f9759 2019-09-01 11:00:00 mopped /home/user/work 46cfe4d5 2019-09-08 11:00:00 mopped /home/user/work f6b1f037 2019-09-15 11:00:00 mopped /home/user/work eb430a5d 2019-09-22 11:00:00 mopped /home/user/work 8cf1cb9a 2019-09-29 11:00:00 mopped /home/user/work 5d33b116 2019-10-06 11:00:00 mopped /home/user/work b9553125 2019-10-13 11:00:00 mopped /home/user/work e1a7b58b 2019-10-20 11:00:00 mopped /home/user/work 8f8018c0 2019-10-27 11:00:00 mopped /home/user/work 59403279 2019-11-03 11:00:00 mopped /home/user/work dfee9fb4 2019-11-10 11:00:00 mopped /home/user/work e1ae2f40 2019-11-17 11:00:00 mopped /home/user/work
12 snapshots
Then forget --keep-daily 4
will keep the last four snapshots, for the last
four Sundays, and remove the other snapshots:
$ rustic forget --keep-daily 4 --dry-run repository f00c6e2a opened successfully, password is correct Applying Policy: keep the last 4 daily snapshots keep 4 snapshots: ID Time Host Tags Reasons Paths
8f8018c0 2019-10-27 11:00:00 mopped daily snapshot /home/user/work 59403279 2019-11-03 11:00:00 mopped daily snapshot /home/user/work dfee9fb4 2019-11-10 11:00:00 mopped daily snapshot /home/user/work e1ae2f40 2019-11-17 11:00:00 mopped daily snapshot /home/user/work
4 snapshots
remove 8 snapshots: ID Time Host Tags Paths
0a1f9759 2019-09-01 11:00:00 mopped /home/user/work 46cfe4d5 2019-09-08 11:00:00 mopped /home/user/work f6b1f037 2019-09-15 11:00:00 mopped /home/user/work eb430a5d 2019-09-22 11:00:00 mopped /home/user/work 8cf1cb9a 2019-09-29 11:00:00 mopped /home/user/work 5d33b116 2019-10-06 11:00:00 mopped /home/user/work b9553125 2019-10-13 11:00:00 mopped /home/user/work e1a7b58b 2019-10-20 11:00:00 mopped /home/user/work
8 snapshots
The processed snapshots are evaluated against all --keep-*
options but a
snapshot only need to match a single option to be kept (the results are ORed).
This means that the most recent snapshot on a Sunday would match both hourly,
daily and weekly --keep-*
options, and possibly more depending on calendar.
For example, suppose you make one backup every day for 100 years. Then
forget --keep-daily 7 --keep-weekly 5 --keep-monthly 12 --keep-yearly 75
would
keep the most recent 7 daily snapshots and 4 last-day-of-the-week ones (since
the 7 dailies already include 1 weekly). Additionally, 12 or 11
last-day-of-the-month snapshots will be kept (depending on whether one of them
ends up being the same as a daily or weekly). And finally 75 or 74
last-day-of-the-year snapshots are kept, depending on whether one of them ends
up being the same as an already kept snapshot. All other snapshots are removed.
You might want to maintain the same policy as in the example above, but have
irregular backups. For example, the 7 snapshots specified with --keep-daily 7
might be spread over a longer period. If what you want is to keep daily
snapshots for the last week, weekly for the last month, monthly for the last
year and yearly for the last 75 years, you can instead specify
forget --keep-within-daily 7d --keep-within-weekly 1m --keep-within-monthly 1y --keep-within-yearly 75y
(note that 1w
is not a recognized duration, so you will have to specify 7d
instead).
For safety reasons, rustic refuses to act on an “empty” policy. For example, if
one were to specify --keep-last 0
to forget all snapshots in the repository,
rustic will respond that no snapshots will be removed. To delete all snapshots,
use --keep-last 1
and then finally remove the last snapshot manually (by
passing the ID to forget
).