WORM and the Hammerspace S3 Interface

Hammerspace shares may be exposed to clients via multiple protocols simultaneously, including SMB, NFS, and S3. Directories and files appear as buckets and objects when exposed via S3.

In AWS S3 API terms, WORM is known as Object Lock. AWS offers a wide variety of configuration options for Object Lock. Hammerspace supports a subset consisting of four Object Lock-related S3 APIs:

PutObjectLockConfiguration — Sets Object Lock policy on a bucket
GetObjectLockConfiguration — Displays Object Lock policy
PutObjectLegalHold — Sets legal hold status on an object
GetObjectLegalHold — Displays legal hold status of an object

Object Lock provides two ways to manage object retention, retention periods and legal holds. Retention periods have a defined expiration date, and legal holds do not.

S3 Object Lock Retention Period

An Object Lock retention period is a policy that applies to an S3 bucket and all objects in that bucket. With Hammerspace, all objects in the bucket are protected against deletion using deny-write and deny-delete objectives, and the Hammerspace attribute WORM_EXPIRE_DATE is set to match the requested policy.

When a retention period is specified, one of two retention modes, Compliance or Governance, must also be specified. Hammerspace only supports the stricter Compliance mode at this time. Attempts to configure Governance mode will return a (501): Not Implemented error.

The following command sets an Object Lock policy on a bucket named s3bucket with a retention period of 30 days using AWS CLI with Windows PowerShell. The {"RequestCharged"} response indicates that the command was executed successfully.

Set a 30-day Object Lock retention period on a bucket

Command:

PS> aws s3api put-object-lock-configuration --bucket s3bucket --object-lock-configuration '{\"ObjectLockEnabled\": \"Enabled\", \"Rule\": { \"DefaultRetention\": { \"Mode\": \"COMPLIANCE\", \"Days\": 30 }}}'

Expected output:

{
    "RequestCharged"; "RequestCharged"
}

The JSON is easier to read when doing the corresponding get operation to view the configuration:

View the Object Lock configuration on a bucket

Command:

PS> aws s3api get-object-lock-configuration --bucket s3bucket

Expected output:

{
    "ObjectLockConfiguration": {
        "ObjectLockEnabled": "Enabled",
        "Rule": {
            "DefaultRetention": {
                "Mode": "COMPLIANCE",
                "Days": 30
            }
        }
    }
}

After setting the bucket policy, the Hammerspace WORM_EXPIRE_DATE attribute reflects the configured retention period:

Verify the WORM_EXPIRE_DATE attribute

Command:

PS> Y:\s3bucket\> hs attribute get WORM_EXPIRE_DATE .

Expected output:

LOCAL_TIME('2025-04-22 12:28:47')

Retention periods are not reciprocal. Enabling a retention period on a bucket sets deny-write and deny-delete objectives on the corresponding directory, but setting the deny-write and deny-delete objectives on a directory will not cause a retention period to be enabled on the corresponding bucket.

S3 Object Lock Legal Hold

Legal hold is a property that applies to individual objects. It is a simple ON/OFF toggle with no concept of an expiration date. The status (ON or OFF) is set using the PutObjectLegalHold API by a bucket owner. The GetObjectLegalHold API displays the current status of an object.

Similar to WORM_EXPIRE_DATE, Hammerspace defines an attribute named LEGAL_HOLD_EXPIRE_DATE. This attribute is not used in conjunction with legal hold, however, since legal hold does not use expiration dates.

Unlike retention period, legal hold is reciprocal. Enabling legal hold on an object will set deny-write and deny-delete objectives on the corresponding file, and setting those objectives on a file will toggle the legal hold status to ON as viewed by GetObjectLegalHold.

The commands shown below set object lock on an object, and verify the status has been set ON.

Set legal hold on an object

Command:

PS> aws s3api put-object-legal-hold --bucket s3bucket --key client42 --legal-hold Status=ON

Expected output:

{
    "RequestCharged": "RequestCharged"
}

Verify the legal hold status of an object

Command:

PS> aws s3api get-object-legal-hold --bucket s3bucket --key client42

Expected output:

{
    "LegalHold": {
        "Status": "ON"
    }
}