- Print
- DarkLight
Enable Object Lock with the Native API
- Print
- DarkLight
You can configure default bucket retention settings using the Backblaze B2 Cloud Storage Native API. For more information, see Object Lock.
Call the b2_update_bucket
operation using the defaultRetention
parameter as in the following example:
"defaultRetention": { "mode": "compliance", "period": { "duration": 7, "unit": "days" } }
The default retention mode
must be either "compliance"
or "governance"
. The default retention period
is specified as a duration
(which must be a positive integer) and a unit
of time (either "days"
or "years"
).
To disable default bucket retention, use the same parameter with mode
set to null
:
"defaultRetention": { "mode": null }
To access a bucket's Object Lock and default retention settings, the client must have the readBucketRetentions
application key capability. In that case, the responses of API calls that return bucket information (for example, b2_list_buckets
) include a fileLockConfiguration
field that includes an isClientAuthorizedToRead
Boolean value that is set to true
and a value
field that contains the actual bucket Object Lock settings.
"fileLockConfiguration": { "isClientAuthorizedToRead": true, "value": { "defaultRetention": { "mode": "governance", "period": { "duration": 2, "unit": "years" } }, "isFileLockEnabled": true } }
If default bucket retention is disabled, then mode
and period
will both be null
.
"fileLockConfiguration": { "isClientAuthorizedToRead": true, "value": { "defaultRetention": { "mode": null, "period": null }, "isFileLockEnabled": true } }
If the bucket is not Object Lock-enabled, then isFileLockEnabled
will be set to false
.
"fileLockConfiguration": { "isClientAuthorizedToRead": true, "value": { "defaultRetention": { "mode": null, "period": null }, "isFileLockEnabled": false } }
If the client does not have readBucketRetentions
application key capability, then isClientAuthorizedToRead
will be false
and value
will be null
.
"fileLockConfiguration": { "isClientAuthorizedToRead": false, "value": null }
Enable Object Lock on File Upload
You can enable Object Lock retention settings (or override default bucket retention settings) and legal hold protections for Backblaze B2 files when uploading or copying. Permissions to configure individual file retention settings and legal hold protections are determined by the writeFileRetentions
and writeFileLegalHolds
application key capabilities, respectively.
To enable Object Lock retention settings for a predetermined period of time when calling b2_upload_file
, use the following headers:
X-Bz-File-Retention-Mode
for Object Lock retention mode. Valid values aregovernance
andcompliance
.X-Bz-File-Retention-Retain-Until-Timestamp
for Object Lock retention timestamp in the future, after which the intended Object Lock expires. This header value must be specified as a base 10 number of milliseconds since midnight, January 1, 1970 UTC.
To enable Object Lock legal hold protections for a file when calling b2_upload_file
, use the following header:
X-Bz-File-Legal-Hold
for specifying the legal hold status of the file being uploaded. Valid values areon
andoff
.
Enable Object Lock for the Destination File
To enable Object Lock retention settings or legal hold protections for the destination file when calling b2_copy_file
or when starting a large file upload ( b2_start_large_file
), use the fileRetention
and/or legalHold
JSON parameters, e.g.:
"fileRetention": { "mode": "compliance", "retainUntilTimestamp": 1628942493000 }, "legalHold": "on"
fileRetention
has two fields: mode
(which must be either "compliance"
or "governance"
to enable retention) and retainUntilTimestamp
(which must be a future timestamp, specified as a base 10 number of milliseconds since midnight, January 1, 1970 UTC). Valid values for legalHold
are "on"
and "off"
.
Configure Object Lock After File Upload
To configure Object Lock retention settings for Backblaze B2 files after upload, call b2_update_file_retention
with the fileName
, fileId
, and fileRetention
parameters. Updating file retention settings requires the writeFileRetentions
application key capability.
{ "fileName": "example.txt", "fileId": "4_zb2f6f21365e1d29f6c59018f_f10076875fe98d4af_d20210514_m223128_c002_v0001108_t0050", "fileRetention": { "mode": "governance", "retainUntilTimestamp": 1628942493000 } }
fileRetention
has two fields: mode
(which must be either "compliance"
or "governance"
to enable retention) and retainUntilTimestamp
(which must be a future timestamp, specified as a base 10 number of milliseconds since midnight, January 1, 1970 UTC).
To shorten or remove an existing governance mode retention setting, the bypassGovernance
parameter must also be specified and set to true
, and the client must have the bypassGovernance
application key capability.
To remove an existing governance mode retention setting, the mode
should be set to null
as in the following example.
{ "fileName": "example.txt", "fileId": "4_zb2f6f21365e1d29f6c59018f_f10076875fe89ea3c_d20210514_m223128_c002_v0001108_t0050", "fileRetention": { "mode": null }, "bypassGovernance": true }
After enabling Object Lock on a bucket containing files with metadata over the lower 2,048 byte limit, API requests to b2_update_file_retention
and b2_update_file_legal_hold
will be rejected. This is because setting file retention or legal hold on a file adds additional headers when the file is downloaded, for example, with b2_download_file_by_name
. In such cases, you can use b2_copy_file
with a REPLACE metadataDirective
to copy the file, give it less metadata, and also specify the fileRetention
and legalHold
parameters. The original file can then be deleted with b2_delete_file_version
.
Configure Legal Hold After File Upload
To enable or disable Object Lock legal hold for Backblaze B2 files after upload, call b2_update_file_legal_hold
with the fileName
, fileId
, and legalHold
parameters. Updating legal hold settings requires the writeFileLegalHolds
application key capability.
{ "fileName": "example.txt", "fileId": "4_zb2f6f21365e1d29f6c59018f_f10076875fe89ea3c_d20210514_m223128_c002_v0001108_t0050", "legalHold": "on" }
Valid values for legalHold
are "on"
and "off"
.
After enabling Object Lock on a bucket containing files with metadata over the lower 2,048 byte limit, API requests to b2_update_file_retention
and b2_update_file_legal_hold
will be rejected. This is because setting file retention or legal hold on a file adds additional headers when the file is downloaded, for example, with b2_download_file_by_name
. In such cases, you can use b2_copy_file
with a REPLACE metadataDirective
to copy the file, give it less metadata, and also specify the fileRetention
and legalHold
parameters. The original file can then be deleted with b2_delete_file_version
.
Enable Object Lock on an Existing Bucket
To enable Object Lock on an existing S3 Compatible bucket, call b2_update_bucket
and set the fileLockEnabled
parameter to true:
{ "accountId": "12f634bf3cbz", "bucketId": "e1256f0973908bfc71ed0c1z", "fileLockEnabled": true }
Once Object Lock is enabled on a bucket, a fileLockEnabled
parameter value of false will not be accepted.
Access File Retention and Legal Hold Settings
To access individual file retention and legal hold settings when listing, uploading, or copying B2 files (e.g., calling b2_list_file_names
, b2_get_file_info
, b2_upload_file
, etc.), the client must have the readFileRetentions
and readFileLegalHolds
application key capabilities, respectively.
If the client has those capabilities, then the responses for such API calls will include fileRetention
and legalHold
fields which include an isClientAuthorizedToRead
Boolean set to true
and a value
field which contains the actual value of the setting, e.g.:
"fileRetention": { "isClientAuthorizedToRead": true, "value": { "mode": "governance", "retainUntilTimestamp": 1628942493000 } } "legalHold": { "isClientAuthorizedToRead": true, "value": "off" }
If the client does not have the readFileRetentions
and/or readFileLegalHolds
application key capability, then isClientAuthorizedToRead
will be false
and value
will be null
for the respective field as in the example below.
"fileRetention": { "isClientAuthorizedToRead": false, "value": null }
Legal Hold
After enabling Object Lock on a bucket containing files with metadata over the lower 2,048 byte limit, API requests to b2_update_file_retention
and b2_update_file_legal_hold
will be rejected. This is because setting file retention or legal hold on a file adds additional headers when the file is downloaded, for example, with b2_download_file_by_name
. In such cases, you can use b2_copy_file
with a REPLACE metadataDirective
to copy the file, give it less metadata, and also specify the fileRetention
and legalHold
parameters. The original file can then be deleted with b2_delete_file_version
.
v2
or later in b2_list_file_names
and b2_list_file_versions
in order to view legal hold and retention settingsTimestamp
If you customize the upload timestamp, then the Object Lock retention calculation (for retention set via the bucket default retention) will be based on the customized upload timestamp. Otherwise, this calculation will be based on the current date and time. For more information about custom upload timestamps, see b2_upload_file
and b2_start_large_file
.