Lifecycle Rules
Lifecycle rules instruct the B2 service to automatically hide and/or delete old files. You can set up rules to do things like delete old versions of files 30 days after a newer version was uploaded.
A bucket can have up to 100 lifecycle rules. Each rule has a
fileNamePrefix
that specifies which files in the bucket
it applies to. Any file whose name starts with the prefix is
subject to the rule. A prefix of the empty string, ""
,
means that the rule applies to all files in the bucket.
WARNING:
This means that a lifecycle rule with fileNamePrefix
of the empty string could
potentially delete ALL files in a bucket, so please tread carefully.
You're not allowed to create two rules that both apply to the same files.
For example, a rule with a file name prefix of photos/
and a rule with a file name prefix of photos/kittens/
would both apply to a file named photos/kittens/fluffy.jpg
,
so you're not allowed to have both rules at the same time.
Each lifecycle rule specifies two things: daysFromUploadingToHiding
and daysFromHidingToDeleting
. Either can be null
, which
means that part of the rule doesn't apply. Setting both to null
is
not allowed, because the rule would do nothing.
Setting either daysFromUploadingToHiding
or
daysFromHidingToDeleting
to 0 is not allowed. When either is set,
it must be a positive number.
The most commonly used setting is daysFromHidingToDeleting
, which
says how long to keep file versions that are not the current version.
A file version counts as hidden when explicitly hidden with
b2_hide_file
, or when a newer file
with the same name is uploaded. When a rule with this setting applies,
the file will be deleted the given number of days after it is hidden.
For example, if you are backing up your files to B2 using the B2 command-line tool,
or another software package that uploads files when they change, B2 will keep
old versions of the file. This is very helpful, because it means the old versions
are there if the original file is accidentally deleted. On the other hand,
keeping them forever can clutter things up. For an application like this, you
might want a lifecycle rule that keeps old versions in the backup/
folder for 30 days, and then deletes them:
{ "daysFromHidingToDeleting": 30, "daysFromUploadingToHiding": null, "fileNamePrefix": "backup/" }
The daysFromUploadingToHiding
setting is less frequently used.
It causes files to be hidden automatically after the given number of days.
This can be useful for things like server log files that can be deleted
after a while. This rule will keep files in the logs/
folder
for 7 days, and then hide them. They will then be deleted one day after
hiding.
{ "daysFromHidingToDeleting": 1, "daysFromUploadingToHiding": 7, "fileNamePrefix": "logs/" }
Every lifecycle rule includes an implicit rule: When the oldest version of a file is a hide marker, the marker is deleted, independent of its age.
The API calls related to lifecycle rules are:
b2_create_bucket
- creates a new bucketb2_update_bucket
- changes the settings on a bucket
When you create a new bucket, you can specify the lifecycle rules. Later, you can change the rules on a bucket by updating it.
When Things Happen
Lifecycle rules are applied once a day. The smallest number of days you can set in a rule is 1. Rules will be applied at the next daily run after that number of days has passed.
As an example, suppose you upload the first version of file.txt
on May 2.
Then you upload a new version of file.txt
on May 9 at 06:00. At this point
there are two versions, the May 2 version and the May 9 version. The May 2 version is
hidden by the May 9 version, so it became hidden at the time the May 9 version was uploaded.
Suppose there's a lifecycle rule to delete files one day after they are hidden. If the lifecycle rules get applied at 01:00 on May 10, nothing will happen yet. It has been 19 hours since the May 2 version was hidden. Because it hasn't been a full day, nothing will happen.
The next day, on May 11, when the lifecycle get applied something will happen. If it runs at 01:00, it's now been 43 hours since the May 2 version was hidden, so the rule now applies and the old version will be deleted.
File Lock
Lifecycle rules potentially delete specific versions of files. However, if the file version to which the rule applies has File Lock enabled, the deletion will not occur.
Setting Lifecycle Rules on the Web
The "Buckets" page for your account on the Backblaze web site has options for common lifecycle rule settings:
Keep all versions of the file (default) removes all lifecycle rules from the bucket, and keeps all versions of all files until you explicitly delete them.
Keep only the last version of the file deletes prior versions of a file one day after uploading a new version or hiding the file. The rule looks like this:
{ "daysFromHidingToDeleting": 1, "daysFromUploadingToHiding": null, "fileNamePrefix": "" }
Keep prior versions for this number of days lets you pick a number of days, and deletes prior versions of a file that many days after uploading a new version or hiding the file. The rule looks like this if you pick 30 days:
{ "daysFromHidingToDeleting": 30, "daysFromUploadingToHiding": null, "fileNamePrefix": "" }