All Products
Search
Document Center

Object Storage Service:worm (manage retention policies)

Last Updated:Dec 26, 2023

You can configure Object Storage Service (OSS) retention policies that provide the Write Once Read Many (WORM) feature to protect objects in a bucket from being deleted or overwritten within a specific period of time by any user, including the object owner. To achieve that goal, you can run the worm command to configure retention policies for the bucket. Before the specified retention period ends, you can only upload objects to or read objects from the bucket. You can modify or delete objects only after the retention period ends.

Note
  • Sample command lines in this topic are based on the 64-bit Linux system. For other systems, replace ./ossutil64 in the commands with the corresponding binary name. For more information, see Get started with ossutil.

  • For more information about retention policies, see Retention policies.

Create and lock a retention policy

To use a retention policy to protect objects in your bucket, you must create and lock the retention policy.

  1. Create a retention policy.

    • Command syntax

      ./ossutil64 worm init oss://BucketName days

      The following table describes the parameters in the preceding command.

      Parameter

      Description

      BucketName

      The name of the bucket for which you want to configure a retention policy.

      days

      The retention period of objects that you want to configure in the retention policy. During the retention period, objects in the bucket cannot be modified or deleted.

      • Unit: days.

      • Valid values: 1 to 25550.

    • Examples

      Run the following command to create a retention policy for a bucket named examplebucket and set the retention period to 180 days:

      ./ossutil64 worm init oss://examplebucket 180

      If a similar output is displayed, the retention policy is created.

      init success,worm id is 581D8A7FFA064C80827CAB4076A93A78
  2. Lock the retention policy.

    • Command syntax

      ./ossutil64 worm complete oss://BucketName WormId

      The following table describes the parameters in the preceding command.

      Parameter

      Description

      BucketName

      The name of the bucket for which the retention policy you want to lock is configured.

      WormId

      The ID of the retention policy you want to lock. This parameter is returned after you successfully create a retention policy.

    • Examples

      Run the following command to lock the retention policy that is configured for a bucket named examplebucket:

      ./ossutil64 worm complete oss://examplebucket 581D8A7FFA064C80827CAB4076A93A78

      If a similar output is displayed, the retention policy is locked.

      0.073810(s) elapsed

Extend the retention period

After a retention policy is locked, objects in the bucket cannot be modified or deleted during the retention period. If the retention period cannot meet your requirements for data protection, you can run the following command to extend the retention period.

  • Command syntax

    ./ossutil64 worm extend oss://BucketName days WormId
  • Examples

    Run the following command to extend the retention period of objects in a bucket named examplebucket to 360 days:

    ./ossutil64 worm extend oss://examplebucket 360 581D8A7FFA064C80827CAB4076A93A78

    If a similar output is displayed, the retention period is extended to 360 days.

    0.067810(s) elapsed

Query the configurations of retention policies

You can query the configurations of the retention policies that are configured for a bucket.

  • Command syntax

    ./ossutil64 worm get oss://BucketName
  • Examples

    Run the following command to query the configurations of the retention policies that are configured for a bucket named examplebucket:

    ./ossutil64 worm get oss://examplebucket

    If a similar output is displayed, the configurations of a retention policy are queried. The returned results include the ID, status, retention period, and creation time of the retention policy.

    <WormConfiguration>
          <WormId>581D8A7FFA064C80827CAB4076A93A78</WormId>
          <State>Locked</State>
          <RetentionPeriodInDays>360</RetentionPeriodInDays>
          <CreationDate>2021-01-19T03:36:53.000Z</CreationDate>
      </WormConfiguration>

Delete a retention policy

You can delete a retention policy before the retention policy is locked.

  • Command syntax

    ./ossutil64 worm abort oss://BucketName
  • Examples

    Run the following command to delete the retention policy that is configured for a bucket named examplebucket:

    ./ossutil64 worm abort oss://examplebucket

    If a similar output is displayed, the retention policy is deleted.

    0.067810(s) elapsed

Common options

If you use ossutil to switch to a bucket that is located in another region, add the -e option to the command to specify the endpoint of the region in which the specified bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, you can add the -i option to the command to specify the AccessKey ID of the specified account, and add the -k option to the command to specify the AccessKey secret of the specified account.

For example, you can run the following command to create a retention policy for a bucket named test, which is located in the China (Hangzhou) region and is owned by another Alibaba Cloud account:

./ossutil64 worm init oss://test -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

For more information about other common options that you can use for the sync command, see View options.