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 bucket
b2_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.

Lifecycle Rules and Replica Files

Lifecycle rules apply to replica files in the same manner as they apply to source files. When replicating files between buckets with different lifecycle rules, be aware of the effect that the different lifecycle rules will have on your files.

Example 1:

You have a source bucket with lifecycle rules that will hide files after 30 days and then delete them five days later.
You have a destination bucket with lifecycle rules that will hide files after 10 days and then delete them one day later.

In this situation, you might have a file in the source bucket which is 15 days old. If you replicate that file to the destination bucket, the file will become hidden. Specifically, the file will become hidden the next time the system applies the lifecycle rules. Lifecycle rules are applied once per day.

Example 2:

You have a source bucket with lifecycle rules that will hide files after 10 days and then delete them one day later.
You have a destination bucket with lifecycle rules that will hide files after 30 days and then delete them five days later.

In this situation, you might have a file in the source bucket which reaches an age of 11 days. Due to the source bucket's lifecycle rules, this file will become hidden after 10 days and then deleted on the 11th day. However, if you replicate that file to the destination bucket before it is deleted, the file will remain visible in the destination bucket until it is 30 days old, even though the original file was already deleted from the source bucket.

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.

NOTE: Lifecycle rules are based on the upload timestamp of the file/object. When migrating from other cloud providers, you can maintain existing lifecycle rules by customizing the upload timestamp to set the timestamp in the past.
For more information about custom upload timestamps, see b2_upload_file and b2_start_large_file.
To use custom upload timestamps, please contact Backblaze support to have the feature enabled on your account.

Object Lock

Lifecycle rules potentially delete specific versions of files. However, if the file version to which the rule applies has Object Lock enabled, the deletion will not occur.

Existing File Replication

When a replication rule is configured to include existing files, the replica files are created with the same upload timestamp as their source file. This has several ramifications:

Backblaze does not guarantee any ordering of individual file version replications. While replication of existing files is ongoing, it is possible that a filename-based query will have different results between the source and destination buckets. This situation is temporary, and both buckets will provide the same response once the existing files have finished replicating. Consider disabling lifecycle rules in the destination bucket if this will be an issue.
Existing files will be replicated to the destination bucket regardless of the destination bucket's lifecycle rule configuration. It is possible that some newly created file replicas will be hidden or deleted when lifecycle rules are next applied (typically every 24 hours).
Replica files are created with the same upload timestamp as their source file. If the destination bucket has a default object lock retention period set, the retention period is calculated based on the timestamp inherited from the source file.

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": ""
    }