Use ossutil to configure retention policies to prevent OSS data from being modified or deleted within a specific period of time - Object Storage Service

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.

Usage notes

To create a retention policy, you must have the oss:InitiateBucketWorm permission. To lock a retention policy, you must have the oss:CompleteBucketWorm permission. To extend the retention period of a retention policy, you must have the oss:ExtendBucketWorm permission. To query a retention policy, you must have the oss:GetBucketWorm permission. To delete an unlocked retention policy, you must have the oss:AbortBucketWorm permission. For more information, see Attach a custom policy to a RAM user.
For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you need to update the binary name based on the operating system. For more information, see ossutil command reference.
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.

Create a retention policy.

Command syntax

ossutil worm init oss://BucketName days

The following table describes the preceding parameters.

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:
```
ossutil worm init oss://examplebucket 180
```
If a similar output is displayed, the retention policy is created.
```
init success,worm id is 581D8A7FFA064C80827CAB4076A93A78
```

Lock the retention policy.

Command syntax

ossutil worm complete oss://BucketName WormId

The following table describes the preceding parameters.

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:
```
ossutil 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

ossutil 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:
```
ossutil 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
```
ossutil 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:
```
ossutil 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
```
ossutil worm abort oss://BucketName
```
Examples
Run the following command to delete the retention policy that is configured for a bucket named examplebucket:
```
ossutil 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 specify the endpoint of the region in which the bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to specify the AccessKey ID of the specified account, and add the -k option 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:

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

For more information about common options, see Common options.