This guide presents the steps required for configuring and using the S3 Object Locking feature using curl and the aws AWS CLI.
Table of Contents | ||||
---|---|---|---|---|
|
...
Make sure you have a Swarm 14.0+ cluster with a search feed pointing to an Elasticsearch 7+ cluster; also make sure to issue the requests in this guide through a Content Gateway 7.6 +or higher.
Create a tenant, a domain in that tenant and a bucket, using either the Content UI or the Content Gateway’s Management API, as follows:
Create a tenant.
Code Block curl -XPUT -i -u caringoadmin:caringo "http://192.168.8.109:9090/_admin/manage/tenants/example.tenant.com"
Create a domain within that tenant.
Code Block curl -XPUT -i -u caringoadmin:caringo "http://192.168.8.109:9090/_admin/manage/tenants/example.tenant.com/domains/locking.example.com"
Create a bucket in the domain.
Code Block curl -XPUT -i -u caringoadmin:caringo "http://192.168.8.109:9090/_admin/manage/tenants/example.tenant.com/domains/locking.example.com/buckets/b1"
Enable versioning at the cluster-level. You can do that through the swarmctl utility available in our support bundle https://support.cloud.datacore.com/tools/swarm-support-tools.tgz, by running the following command from within the dist/ folder.
Code Block ./swarmctl -C policy.versioning -V "allowed" -d <IP of any Swarm node>
Enable versioning for the newly created domain.
Code Block curl -XCOPY -i -H "Policy-Versioning: enabled" -u caringoadmin:caringo "http://192.168.8.109:9090?domain=locking.example.com&preserve"
Enable versioning for the newly created bucket.
Code Block curl -XCOPY -i -H "Policy-Versioning: enabled" -u caringoadmin:caringo "http://192.168.8.109:9090/b1?domain=locking.example.com&preserve"
In order to use the S3 API, create a an S3 token for the user that’s going to manage object locking on the bucket. In the following examples, that role will be played by someuser. Write down the token UUID outputted by the request below which will be your S3 AWS_ACCESS_KEY_ID and the secret that you’ve configured for this token, which will be your S3 AWS_SECRET_ACCESS_KEY.
Code Block curl -H "x-user-secret-key-meta: somesecret" -H "x-user-token-expires-meta: +365" -H 'x-owner-meta: someuser' -XPOST "http://192.168.8.109:9090/.TOKEN/?domain=locking.example.com" -u caringoadmin:caringo
The user that will manage object locking on the bucket needs to be either the bucket’s owner , or an a user with admin-level permissions for that bucket. The following requests grants grant all privileges on the bucket to someuser, which is the user that we’re going to employ in the next steps.
Code Block curl -XPUT -u caringoadmin:caringo -H "Content-Type: application/json+policy" "http://192.168.8.109:9090/b1?domain=locking.example.com&policy" --data-binary '{ "Version": "2008-10-17", "Id": "Unnamed Policy", "Statement": [ { "Sid": "1: Custom", "Effect": "Allow", "Principal": { "user": [ "someuser" ], "group": [] }, "Action": [ "*" ], "Resource": "*" } ] }'
...
A. Enabling object locking on the bucket and all subsequently created objects
In this case, the object locking parameters that you will apply through the following request will be automatically applied to all the objects that you write onwards, unless you explicitly set the object-locking headers when writing an object. In the latter case, Gateway will always use the maximum of either the bucket default retention duration , or the duration specified in a per-object request.
Enabling object-locking at the bucket - level through SCSP requires the following steps:
Do a PUT
/<bucket>?
objectlock=<defaultmode> [ :<defaultperiod> ] wheredefaultmode
can be either "governance" or "compliance"defaultperiod
is optional; it is a number of years (y) or days (d), eg.1y
or20d
.Code Block curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1?domain=locking.example.com&objectlock=compliance:20d" -u someuser:caringo
(Optional) Check that object-locking was enabled at the bucket - level by issuing a
GET /<bucket>?
objectlock and checking that the following headers exist and that the response body says:Object locking is enabled on bucket
x-object-lock-meta-status: ENABLED
(Optionally)
x-object-lock-meta-default: <GOVERNANCE|COMPLIANCE>[:<duration>]
Code Block curl --location-trusted -i "http://192.168.8.109:9090/b1?domain=locking.example.com&objectlock" -u someuser:caringo HTTP/1.1 200 OK Date: Mon, 25 Oct 2021 06:37:33 GMT Gateway-Request-Id: 55C57E6997420CD2 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp X-Object-Lock-Meta-Status: ENABLED Content-Length: 39 Object locking is enabled on bucket b1
...
Create a new object in the bucket.
Code Block curl --location-trusted -i -XPOST --data-binary 'test' "http://192.168.8.109:9090/b1/file1?domain=locking.example.com" -u someuser:caringo
Make sure the object is locked according to the locking configuration defined at the bucket level, namely that it has the following headers:
X-Object-Lock-Meta-Mode: COMPLIANCE
X-Object-Lock-Meta-Retain-until-date: <current date + 50 days>
Code Block curl --location-trusted -I "http://192.168.8.109:9090/b1/file1?domain=locking.example.com" -u someuser:caringo HTTP/1.1 200 OK Date: Fri, 22 Oct 2021 08:48:16 GMT Gateway-Request-Id: 09EC017DBBD195E6 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Castor-System-CID: e5c51ad561fcc0f361dd7c941a004ce6 Castor-System-Cluster: swarm.demo.internal Castor-System-Created: Fri, 22 Oct 2021 08:46:39 GMT Castor-System-IsVersioned: True Castor-System-Name: file1 Castor-System-Version: 1634892399.199 Content-Type: application/x-www-form-urlencoded Last-Modified: Fri, 22 Oct 2021 08:46:39 GMT X-Last-Modified-By-Meta: someuser@ X-Owner-Meta: someuser ETag: "ba2263c7ff58ebc15526fbafc1076787" Castor-System-Path: /locking.example.com/b1/file1 Castor-System-Domain: locking.example.com Volume: fdd5be4d6b82c11a9c68e89106281fa4 Content-MD5: CY9rzUYh03PK3k6DJie09g== X-Object-Lock-Meta-Mode: COMPLIANCE X-Object-Lock-Meta-Retain-until-date: Thu, 11 Nov 2021 08:46:38 GMT Content-Length: 4
B. Enabling object locking on the bucket without automatically setting it on the objects written afterwards.
For users that want object locking enabled on the bucket, but not automatically applied to all subsequently created objects/versions, the following request needs to be performed.
...
In order to verify that object-locking is not automatically set on a new object (i.e. new objects are unlocked , unless the user explicitly locks them when creating them) do the following:
Create a new object.
Code Block curl --location-trusted -i -XPOST --data-binary 'test' "http://192.168.8.109:9090/b1/file2?domain=locking.example.com" -u someuser:caringo
Check that it does not have the
X-Object-Lock-Meta-Mode
andX-Object-Lock-Meta-Retain-until-date
headers.Code Block curl --location-trusted -I "http://192.168.8.109:9090/b1/file2?domain=locking.example.com" -u someuser:caringo HTTP/1.1 200 OK Date: Fri, 22 Oct 2021 08:56:10 GMT Gateway-Request-Id: 36555A75CE064B5C Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Castor-System-CID: e5c51ad561fcc0f361dd7c941a004ce6 Castor-System-Cluster: swarm.demo.internal Castor-System-Created: Fri, 22 Oct 2021 08:53:31 GMT Castor-System-IsVersioned: True Castor-System-Name: file2 Castor-System-Version: 1634892811.229 Content-Type: application/x-www-form-urlencoded Last-Modified: Fri, 22 Oct 2021 08:53:31 GMT X-Last-Modified-By-Meta: someuser@ X-Owner-Meta: someuser ETag: "321375af02fecb94ca33dee20aa17f0c" Castor-System-Path: /locking.example.com/b1/file2 Castor-System-Domain: locking.example.com Volume: eb4715ce21e9a8a20e0b4397bdc825d5 Content-MD5: CY9rzUYh03PK3k6DJie09g== Content-Length: 4
...
Create the object, making sure to set the aforementioned headers.
Code Block curl --location-trusted -i -XPOST --data-binary 'test' -H "x-object-lock-meta-mode: COMPLIANCE" -H "x-object-lock-meta-retain-until-date: Sat, 23 Oct 2021 08:53:31 GMT" "http://192.168.8.109:9090/b1/file3?domain=locking.example.com" -u someuser:caringo
Make sure that the object has the 2 headers, namely that it is locked.
Code Block curl --location-trusted -I "http://192.168.8.109:9090/b1/file3?domain=locking.example.com" -u someuser:caringo HTTP/1.1 200 OK Date: Fri, 22 Oct 2021 09:04:09 GMT Gateway-Request-Id: DE2913658216FD69 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Castor-System-CID: e5c51ad561fcc0f361dd7c941a004ce6 Castor-System-Cluster: swarm.demo.internal Castor-System-Created: Fri, 22 Oct 2021 09:03:32 GMT Castor-System-IsVersioned: True Castor-System-Name: file3 Castor-System-Version: 1634893412.164 Content-Type: application/x-www-form-urlencoded Last-Modified: Fri, 22 Oct 2021 09:03:32 GMT X-Last-Modified-By-Meta: someuser@ X-Owner-Meta: someuser ETag: "b7bf6149bf811e057f2006b58e6dbbae" Castor-System-Path: /locking.example.com/b1/file3 Castor-System-Domain: locking.example.com Volume: eb4715ce21e9a8a20e0b4397bdc825d5 Content-MD5: CY9rzUYh03PK3k6DJie09g== X-Object-Lock-Meta-Mode: COMPLIANCE X-Object-Lock-Meta-Retain-until-date: Sat, 23 Oct 2021 08:53:31 GMT Content-Length: 4
...
Enabling legal hold on a newly created object , requires setting the x-object-lock-meta-legal-hold: ON
header when writing the object. For this particular use - case, you need to perform the following steps:
Write the object with the aforementioned header.
Code Block curl --location-trusted -i -XPOST --data-binary 'test' -H "x-object-lock-meta-legal-hold: ON" "http://192.168.8.109:9090/b1/file8?domain=locking.example.com" -u someuser:caringo
Check that legal - hold was applied on the object by issuing a HEAD request and confirming the presence of the following headers:
X-Object-Lock-Meta-Legal-Hold: ON
Lifepoint: [] deletable=no
X-Object-Lock-Meta-Original-Lifepoints: <if you've added other lifepoints, they should be in this list>
Code Block curl --location-trusted -I "http://192.168.209.84/b1/file8?domain=locking.example.com" HTTP/1.1 301 Moved Permanently Date: Mon, 25 Oct 2021 07:04:42 GMT Server: CAStor Cluster/14.0.0 Location: http://192.168.209.85:80/b1/file8?domain=locking.example.com&auth=b5bd5c429a3366969d5b57f0e2cba0cb Content-Length: 0 Keep-Alive: timeout=14400 HTTP/1.1 200 OK Castor-System-CID: e5c51ad561fcc0f361dd7c941a004ce6 Castor-System-Cluster: swarm.demo.internal Castor-System-Created: Mon, 25 Oct 2021 07:04:28 GMT Castor-System-IsVersioned: True Castor-System-Name: file8 Castor-System-Version: 1635145468.896 Content-Length: 4 Content-Type: application/x-www-form-urlencoded Last-Modified: Mon, 25 Oct 2021 07:04:28 GMT Lifepoint: [] deletable=no X-Last-Modified-By-Meta: someuser@ X-Object-Lock-Meta-Legal-Hold: ON X-Object-Lock-Meta-Original-Lifepoints: X-Owner-Meta: someuser Etag: "c52c8d4ee80b6a86b74eb95caf449582" Castor-System-Path: /locking.example.com/b1/file8 Castor-System-Domain: locking.example.com Volume: c613440c53abae81420b93211625b54b Content-MD5: CY9rzUYh03PK3k6DJie09g== Date: Mon, 25 Oct 2021 07:04:42 GMT Server: CAStor Cluster/14.0.0 Keep-Alive: timeout=14400
...
List the versions, noting the hash field returned by the listing requests, which is the versionId/etag of that particular version.
Code Block curl --location-trusted -s "http://192.168.8.109:9090/b1?domain=locking.example.com&format=json&versions&name=file2&sort=tmborn:DESC,etag:DESC" -u someuser:caringo [ {"last_modified": "2021-10-25T09:10:45.768000Z", "bytes": 8, "versioned": "true", "name": "file2", "hash": "5823fac0dd0f21e32026c3ff1291c104", "written": "2021-10-25T09:10:45.768000Z", "accessed": "2021-10-25T09:10:45.768000Z", "content_type": "application/x-www-form-urlencoded"}, {"last_modified": "2021-10-22T08:53:31.228000Z", "bytes": 4, "versioned": "true", "name": "file2", "hash": "321375af02fecb94ca33dee20aa17f0c", "written": "2021-10-22T08:53:31.228000Z", "accessed": "2021-10-22T08:53:31.228000Z", "content_type": "application/x-www-form-urlencoded", "version": "321375af02fecb94ca33dee20aa17f0c"} ]
Set your desired lock (governance | compliance) and the retention period on one of the versions. In this example, we will set a governance lock with a retention period of 30 days. This is done through the
?objectlock=governance:30d
query argument.Code Block curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=governance:30d" -u someuser:caringo
Try to remove the governance lock, making sure to set the
x-object-lock-meta-bypass-governance-retention: true
header and the?objectlock=retention
query argument.Code Block curl --location-trusted -i -XDELETE -H "x-object-lock-meta-bypass-governance-retention: true" "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=retention" -u someuser:caringo
Set the version’s locking to compliance with a retention period of 40 days.
Code Block curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=compliance:40d" -u someuser:caringo
Try to reduce the retention period to 30 days, confirming that this is not allowed.
Code Block curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=compliance:30d" -u someuser:caringo HTTP/1.1 403 Forbidden Date: Mon, 25 Oct 2021 11:44:58 GMT Gateway-Request-Id: 3CAEFC561F5AB1D8 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Content-Length: 44 Cannot shorten compliance retention period
Try to increase the retention period to 50 days, which is allowed.
Code Block curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=compliance:50d" -u someuser:caringo
Check the version’s locking status through a GET request that includes the
?objectlock
argument.Code Block curl --location-trusted -i "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock" -u someuser:caringo HTTP/1.1 200 OK Date: Mon, 25 Oct 2021 11:45:13 GMT Gateway-Request-Id: 36EC45858BA0A0F5 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp X-Object-Lock-Meta-Mode: COMPLIANCE X-Object-Lock-Meta-Retain-until-date: Tue, 14 Dec 2021 11:45:09 GMT Content-Length: 72 Object is locked in COMPLIANCE mode until Tue, 14 Dec 2021 11:45:09 GMT
Change the bucket’s locking mode to compliance with a retention period that is less than what we’ve set for the object at step 6 (e.g. 30 days).
Code Block curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1?domain=locking.example.com&objectlock=compliance:30d" -u someuser:caringo
Try to change the version’s locking mode to compliance, without specifying the retention (i.e. use this query argument
?objectlock=compliance
), which means that it should inherit the retention set at the bucket level. Since at the bucket level we have set a retention of 30 days, which is less than the 50 days that the version currently has, this request should fail:Code Block curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock=compliance" -u someuser:caringo HTTP/1.1 403 Forbidden Date: Mon, 25 Oct 2021 12:07:00 GMT Gateway-Request-Id: 85349B63D10C25CF Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Content-Length: 44 Cannot shorten compliance retention period
Change the bucket’s locking mode to compliance with a retention higher than what the object currently has (e.g. 60 days).
Code Block curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1?domain=locking.example.com&objectlock=compliance:60d" -u someuser:caringo
Now change the version’s locking mode to the bucket’s default (use
?objectlock=
).Code Block curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock" -u someuser:caringo
Confirm that the object has a retention period that matches the bucket’s (i.e. 60 days).
Code Block curl --location-trusted -i "http://192.168.8.109:9090/b1/fileA1?domain=locking.example.com&version=18e9adfcfc2b102e05162fe1633118f1&objectlock" -u someuser:caringo HTTP/1.1 200 OK Date: Mon, 25 Oct 2021 12:16:26 GMT Gateway-Request-Id: F7D3C75D4223B42F Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp X-Object-Lock-Meta-Mode: COMPLIANCE X-Object-Lock-Meta-Retain-until-date: Fri, 24 Dec 2021 12:14:30 GMT Content-Length: 72 Object is locked in COMPLIANCE mode until Fri, 24 Dec 2021 12:14:30 GMT
...
List the object’s versions.
Code Block curl --location-trusted -s "http://192.168.8.109:9090/b1?domain=locking.example.com&format=json&versions&name=fileB1&sort=tmborn:DESC,etag:DESC" -u someuser:caringo [ {"last_modified": "2021-10-25T12:30:35.108000Z", "bytes": 4, "versioned": "true", "name": "fileB1", "hash": "fa6665b5a9189306addc007c0c57ad9b", "written": "2021-10-25T12:30:35.108000Z", "accessed": "2021-10-25T12:30:35.108000Z", "content_type": "application/x-www-form-urlencoded"}, {"last_modified": "2021-10-25T12:30:32.920000Z", "bytes": 4, "versioned": "true", "name": "fileB1", "hash": "386afd4ee45aba359c942c95bea61223", "written": "2021-10-25T12:30:32.920000Z", "accessed": "2021-10-25T12:30:32.920000Z", "content_type": "application/x-www-form-urlencoded", "version": "386afd4ee45aba359c942c95bea61223"}
Set legal hold for one of the object’s version using the
?objectlock=legal-hold
query argument on a PUT request.Code Block curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1/fileB1?domain=locking.example.com&version=386afd4ee45aba359c942c95bea61223&objectlock=legal-hold" -u someuser:caringo
Check the version’s locking status through a GET request that uses the
?objectlock
query argument.Code Block curl --location-trusted -i "http://192.168.8.109:9090/b1/fileB1?domain=locking.example.com&version=386afd4ee45aba359c942c95bea61223&objectlock" -u someuser:caringo HTTP/1.1 200 OK Date: Mon, 25 Oct 2021 12:36:20 GMT Gateway-Request-Id: 1EB296F696DEBA57 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp X-Object-Lock-Meta-Legal-Hold: ON Content-Length: 31 Object is locked in legal hold
Remove the version’s legal hold, through a DELETE request that includes the
?objectlock=legal-hold
query argument.Code Block curl --location-trusted -i -XDELETE "http://192.168.8.109:9090/b1/fileB1?domain=locking.example.com&version=386afd4ee45aba359c942c95bea61223&objectlock=legal-hold" -u someuser:caringo
Confirm that the legal hold has been removed.
Code Block curl --location-trusted -i "http://192.168.8.109:9090/b1/fileB1?domain=locking.example.com&version=386afd4ee45aba359c942c95bea61223&objectlock" -u someuser:caringo HTTP/1.1 200 OK Date: Mon, 25 Oct 2021 12:43:09 GMT Gateway-Request-Id: FDC05254168B34A2 Server: CAStor Cluster/14.0.0 Via: 1.1 192.168.8.109 (Cloud Gateway SCSP/7.6.0) Gateway-Protocol: scsp Content-Length: 21 Object is not locked
...
If you want to enable object locking on the bucket and have it applied automatically to all objects written afterwards, then the typical usage scenario is the following (NOTE: You will still be able to set object-locking on a per-object basis and the Gateway will always use the maximum of either the bucket default retention duration , or the duration specified in a per-object request):
Use the
put-object-lock-configuration
S3 API call for enabling locking using the desired mode and retention period.Code Block aws s3api put-object-lock-configuration --endpoint-url=http://locking.example.com:9091 --bucket=b2 --object-lock-configuration '{ "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 50 }}}'
Check the bucket’s locking status using the
get-object-lock-configuration
S3 API call.Code Block aws s3api get-object-lock-configuration --endpoint-url=http://locking.example.com:9091 --bucket=b2 { "ObjectLockConfiguration": { "ObjectLockEnabled": "Enabled", "Rule": { "DefaultRetention": { "Mode": "COMPLIANCE", "Days": 50 } } } }
Create a new object in that bucket using the
put-object
API call.Code Block aws s3api put-object --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileA1 --body test.txt
Check the object’s retention period using the
get-object-retention
S3 API call, making sure it matches the locking settings applied to the bucket. NOTE: This will return the retention settings of the object’s current version. If you need to check the retention settings of a different version, specify that using the--version-id
CLI option.Code Block aws s3api get-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileA1 { "Retention": { "Mode": "COMPLIANCE", "RetainUntilDate": "2021-12-14T13:39:35+00:00" } }
B. Enabling object locking on the bucket without automatically setting it on the objects written afterwards
If you want to enable object locking on the bucket without having it applied automatically to all objects written afterwards, then your typical usage scenario will look like this:
Use the
put-object-lock-configuration
S3 API call for enabling locking without setting a mode or retention period.Code Block aws s3api put-object-lock-configuration --endpoint-url=http://locking.example.com:9091 --bucket=b2 --object-lock-configuration '{ "ObjectLockEnabled": "Enabled" }'
Check the bucket’s locking status using the
get-object-lock-configuration
S3 API call.Code Block aws s3api get-object-lock-configuration --endpoint-url=http://locking.example.com:9091 --bucket=b2 { "ObjectLockConfiguration": { "ObjectLockEnabled": "Enabled" } }
Create a new object in that bucket using the
put-object
API call.Code Block aws s3api put-object --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileB1 --body test.txt
Check the object’s retention period using the
get-object-retention
S3 API call, making sure the object has no retention period set.Code Block aws s3api get-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileB1 { "Retention": {} }
Set a retention period for the current version of this newly written object , using the
put-object-retention
API call.Code Block aws s3api put-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileB1 --retention '{ "Mode": "Compliance", "RetainUntilDate": "2022-01-01T00:00:00" }'
Using the
get-object-retention
S3 API call, confirm that the new retention period is now in place.Code Block aws s3api get-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileB1 { "Retention": { "Mode": "COMPLIANCE", "RetainUntilDate": "2022-01-01T00:00:00+00:00" } }
Alternatively, you can set the object lock mode and retention period at write time, using the
--object-lock-mode
and--object-lock-retain-until-date
Code Block aws s3api put-object --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileC1 --body test.txt --object-lock-mode GOVERNANCE --object-lock-retain-until-date 2021-11-01T00:00:00+00:00
C. Enabling legal-hold on newly written objects
Using the aws AWS CLI, you can set legal-hold while writing an object by setting the --object-lock-legal-hold-status
option to ON:
...
The typical workflow when managing the locking settings of an object’s version using the aws AWS CLI is the following:
List the object’s versions using the
list-object-versions
API call, noting the VersionId of the version for which you want to manage the locking settings.Code Block aws s3api list-object-versions --endpoint-url=http://locking.example.com:9091 --bucket=b2 --prefix fileE1 { "Versions": [ { "ETag": "\"d8e8fca2dc0f896fd7cb4cb0031ba249\"", "Size": 5, "StorageClass": "STANDARD", "Key": "fileE1", "VersionId": "771c0aa2c1d8e944fa75ac8cbf780c34", "IsLatest": true, "LastModified": "2021-10-26T08:40:49.448000+00:00", "Owner": { "DisplayName": "caringoadmin@", "ID": "caringoadmin@" } }, { "ETag": "\"d8e8fca2dc0f896fd7cb4cb0031ba249\"", "Size": 5, "StorageClass": "STANDARD", "Key": "fileE1", "VersionId": "f59bbbb8a093dde1ed2cceb029a92fa2", "IsLatest": false, "LastModified": "2021-10-26T08:40:44.064000+00:00", "Owner": { "DisplayName": "caringoadmin@", "ID": "caringoadmin@" } } ] }
Set a GOVERNANCE locking mode on one of the versions (in this example we will use the 2nd version) with a retention period until 2022-01-01T00:00:00. This can be done using the
put-object-retention
API call.Code Block aws s3api put-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id f59bbbb8a093dde1ed2cceb029a92fa2 --retention '{ "Mode": "Governance", "RetainUntilDate": "2022-01-01T00:00:00" }'
Using the
get-object-retention
API call confirm confirms that the new settings are in place.Code Block aws s3api get-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id f59bbbb8a093dde1ed2cceb029a92fa2 { "Retention": { "Mode": "GOVERNANCE", "RetainUntilDate": "2022-01-01T00:00:00+00:00" } }
Remove the Governance lock using the
put-object-retention
call, with the--bypass-governance-retention
flag set.Code Block aws s3api put-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --bypass-governance-retention --version-id f59bbbb8a093dde1ed2cceb029a92fa2 --retention '{ "Mode": "Governance", "RetainUntilDate": 0 }'
Confirm that the lock has been removed.
Code Block aws s3api get-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id f59bbbb8a093dde1ed2cceb029a92fa2 { "Retention": {} }
Set a Compliance mode object lock with a retention period of 90 days.
Code Block aws s3api put-object-retention --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --bypass-governance-retention --version-id f59bbbb8a093dde1ed2cceb029a92fa2 --retention '{ "Mode": "Compliance", "RetainUntilDate": "2022-03-01T00:00:00+00:00" }'
...
List the versions of an object and choose the version for which you want to apply the legal hold (in these examples we will use the 2nd most recent version.
Code Block aws s3api list-object-versions --endpoint-url=http://locking.example.com:9091 --bucket=b2 --prefix fileE1 | jq '.Versions[].VersionId' "bf427bb54de0520a2b2c5d18e552587e" "a05ab3dac37bebf45dc269c60df77417" "771c0aa2c1d8e944fa75ac8cbf780c34" "f59bbbb8a093dde1ed2cceb029a92fa2"
Enable legal hold on that version using the
put-object-legal-hold
API call.Code Block aws s3api put-object-legal-hold --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id a05ab3dac37bebf45dc269c60df77417 --legal-hold Status=ON
Check the version’s legal hold status using the
get-object-legal-hold
.Code Block aws s3api get-object-legal-hold --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id a05ab3dac37bebf45dc269c60df77417 { "LegalHold": { "Status": "ON" } }
Remove the legal hold lock.
Code Block aws s3api put-object-legal-hold --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id a05ab3dac37bebf45dc269c60df77417 --legal-hold Status=OFF
Confirm that the legal hold lock has been removed.
Code Block aws s3api get-object-legal-hold --endpoint-url=http://locking.example.com:9091 --bucket=b2 --key fileE1 --version-id a05ab3dac37bebf45dc269c60df77417 { "LegalHold": { "Status": "OFF" } }
...