| Table of Contents |
|---|
...
- Retention – Specifies a fixed period of time ("retention period") during which the object remains locked. During this period, the object is WORM-protected and can not be overwritten or deleted. After the period expires, the lock goes away automatically.
- Legal hold – When applied, the object stays locked indefinitely. A legal hold does not expire; it must be explicitly removed.
------------------------------- NEW PAGE
Retention
Retention
Retention Periods
A retention period is used to set the fixed amount of time that the object needs to remain locked. Until that time expires, the object version cannot be changed or deleted.
...
In a deviation from S3, Gateway will always use the maximum of either the bucket default retention duration, or the duration specified in a per-object request.
------------------------------- NEW PAGE
Legal Hold
A legal hold prevents an object version from being overwritten or deleted until the legal hold is removed.
...
| Info | ||
|---|---|---|
| ||
| Setting a legal hold on an object version does not affect the retention mode or retention period for that object version. |
------------------------------- NEW PAGE
Prerequisites
...
Prerequisites
While object locking is implemented fully from Gateway 7.6 onwards, in order to use this feature, you need to be running Swarm Storage 12.0 or above because it relies on the Swarm lifepoints feature to prevent the deletion of locked objects until a certain date has passed.
...
| Info | ||
|---|---|---|
| ||
While the administrator has the ability to disable versioning at the cluster level via SNMP, this does not pass via Gateway so it cannot protect against disabling object locking in the cluster. |
------------------------------- NEW PAGE
Metadata Headers related to Object Locking
...
The purpose of appending the "later lifepoints" to the lock lifepoint is to allow Swarm to act on them as it normally would have once the lock lifepoint has expired naturally, without any intervention from Gateway. For legal hold there must always be a Gateway intervention to remove the lock, so the original lifepoints just get reinstated at that time.
------------------------------- NEW PAGE
How to Enable Object Locking
How to Enable Object Locking
Object locking can only be set using API calls. It is not yet available in the user interface.
...
The request to enable object locking can fail with the following errors:
412 Precondition Failedwill be displayed if the Swarm cluster does not yet support all the features necessary to perform the operation.412 Precondition Failedwill be displayed if the bucket does not have versioning enabled.403 Forbiddenif the user does not have thePutBucketObjectLockingpermission.
...
PUT /<bucket>?objectlock=(use an empty query argument)
The "=" is optional.
------------------------------- NEW PAGE
How to Check Object Locking Status
- To query the object locking status of a bucket:
GET /<bucket>?objectlock
This returns the following response headers:x-object-lock-meta-status: ENABLEDAnd the response body says:
x-object-lock-meta-default: <GOVERNANCE|COMPLIANCE>[:<duration>]Object locking is enabled on bucket <bucket> with default mode <mode> [ and default duration <duration> ]
If the bucket does not have object locking enabled, then no response headers are present and the response body says:Object locking disabled
------------------------------- NEW PAGE
REST API Changes
...
REST API Changes
Object locking introduces the following new REST calls:
...
For S3, see the Amazon documentation website.
------------------------------- NEW PAGE
How to Lock an Object at Creation Time
...
If both headers are omitted from the request, and there are no defaults at the bucket level, then the object gets written as a normal unlocked object, despite being written to a bucket that has object locking enabled.
------------------------------- NEW PAGE
Managing Retention on an Existing ObjectManaging Retention on an Existing Object
Enabling and disabling retention on an object requires that the user has the PutObjectRetention permission.
...
Both S3 and SCSP also allow retrieving object lock information using regular object HEAD and GET requests.
Assuming the user has the GetObjectRetention permission, the information is returned in the form of the above response headers. The response body is not affected.
------------------------------- NEW PAGE
Managing Legal Hold on an Existing Object
...
Both S3 and SCSP also allow retrieving legal hold information using regular object HEAD and GET requests. Assuming the user has the GetObjectLegalHold permission, the information is returned in the form of the above response headers. The response body is not affected.
------------------------------- NEW PAGE
Combined Retention and Legal HoldCombined Retention and Legal Hold
An object can be both under one of the retention modes AND legal hold at the same time.
...
- To query:
GET /<bucket>/<object>?version=<uuid>&objectlock[=<locktype>]When querying the object lock status without specifying the lock type, there will be response headers for both retention and the legal hold, and the response body contains both status texts, separated by a new line.
The user needs both theGetObjectRetentionand theGetObjectLegalHoldpermissions for this request.
You can also query lock status for one specific lock type, either "legal-hold" or "retention". In this case only the corresponding permission is required. - To delete:
DELETE /<bucket>/<object>?version=<uuid>&objectlock=<locktype>Using SCSP you can remove either the retention or legal hold using DELETE and specifying the appropriate query argumentobjectlock=<locktype>, locktype being "legal-hold" or "retention". When the locktype is "retention", this can only be done for locks that are in governance mode.
...
Differences Between S3 and Swarm's Implementation of Object Locking
In S3, a DELETE request would result in a delete marker, shadowing the locked object version. Swarm's implementation deviates from that logic – it rejects any DELETE requests for undeletable objects with a 403 Forbidden error.
When Gateway gets a 403 Forbidden error from Swarm, it checks if the object is locked. If it is, Gateway simulates the S3 behavior creating a new (unlocked) object version, immediately followed by a DELETE, thus creating a delete marker.
For SCSP, you can use a configuration flag to pick the desired behavior:
...
[object_locking]scspDeleteUsesS3Logic=true
...
New Policy Actions Related to Object Locking
...
PutBucketObjectLocking: to enable/disable object locking on a bucketGetBucketObjectLocking: to query bucket object locking statusPutObjectRetention: to set or extend object retentionGetObjectRetention: to query object retentionBypassGovernanceRetention: to shorten/remove a retention in governance modePutObjectLegalHold: to set/remove a legal holdGetObjectLegalHold: to query legal hold
...
Interactions with Existing Swarm Functionality
...