Versions Compared

Old Version 14

changes.mady.by.user Adrian Nedelcu

Saved on

compared with

New Version Current

changes.mady.by.user Anjali Tyagi

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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
minLevel1
maxLevel7

...

  1. 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.

  2. 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:

    1. Create a tenant.

      Code Block
      curl -XPUT -i -u caringoadmin:caringo "http://192.168.8.109:9090/_admin/manage/tenants/example.tenant.com"

    2. 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"

    3. 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"

  3. 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>

  4. 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"

  5. 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"

  6. 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

  7. 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:

  1. Do a PUT /<bucket>?objectlock=<defaultmode> [ :<defaultperiod> ] where

    1. defaultmode can be either "governance" or "compliance"

    2. defaultperiod is optional; it is a number of years (y) or days (d), eg. 1y or 20d.

      Code Block
      curl --location-trusted -i -XPUT "http://192.168.8.109:9090/b1?domain=locking.example.com&objectlock=compliance:20d" -u someuser:caringo

  2. (Optional) Check that object-locking was enabled at the bucket - level by issuing aGET /<bucket>?objectlock and checking that the following headers exist and that the response body says: Object locking is enabled on bucket

    1. x-object-lock-meta-status: ENABLED

    2. (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

...

  1. 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

  2. Make sure the object is locked according to the locking configuration defined at the bucket level, namely that it has the following headers:

    1. X-Object-Lock-Meta-Mode: COMPLIANCE

    2. 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:

  1. 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

  2. Check that it does not have the X-Object-Lock-Meta-Mode and X-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

...

  1. 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

  2. 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:

  1. 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

  2. Check that legal - hold was applied on the object by issuing a HEAD request and confirming the presence of the following headers:

    1. X-Object-Lock-Meta-Legal-Hold: ON

    2. Lifepoint: [] deletable=no

    3. 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

...

  1. 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"}
]

  2. 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

  3. 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

  4. 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

  5. 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

  6. 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

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

  8. 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

  9. 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

  10. 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

  11. 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

  12. 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

...

  1. 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"}

  2. 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

  3. 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

  4. 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

  5. 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):

  1. 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 }}}'

  2. 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
            }
        }
    }
}

  3. 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

  4. 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:

  1. 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" }'

  2. 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"
    }
}

  3. 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

  4. 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": {}
}

  5. 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" }'

  6. 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"
    }
}

  7. 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:

  1. 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@"
            }
        }
    ]
}

  2. 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" }'

  3. 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"
    }
}

  4. 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 }'

  5. 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": {}
}

  6. 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" }'

...

  1. 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"

  2. 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

  3. 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"
    }
}

  4. 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

  5. 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"
    }
}

...