worm (manage retention policies) - Object Storage Service

OSS supports time-based retention policies. After a retention policy is configured for a bucket, objects stored inside the bucket cannot be deleted or modified during the retention period. This topic describes how to use the worm command to manage the retention policies configured for a bucket.

Note

The commands described in this topic are for 64-bit Linux systems. To use the commands in the examples on 64-bit Windows systems, replace ./ossutil64 in the commands with ossutil64.exe.
For more information about retention policies, see Retention policy.

Create and lock a retention policy

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

Create a retention policy.

Command syntax

./ossutil64 worm init oss://BucketName days

The following table describes the parameters that you can configure when you use the worm command to create a retention policy.


Parameter	Description
BucketName	The name of the bucket for which you want to configure the retention policy.
days	The retention period of the retention policy. During the retention period, objects in the bucket cannot be modified or deleted. Unit: days Valid values: 1 to 25550

Examples
You can run the following command to create a retention policy for a bucket named examplebucket and sets the retention period of the policy 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
```

Lock a retention policy.

Command syntax

./ossutil64 worm complete oss://BucketName WormId

The following table describes the parameters that you can configure when you use the worm command to lock a retention policy.


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 when you successfully create a retention policy.

Examples
You can run the following command to lock the retention policy 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 of a retention policy

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

Command syntax

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

Examples
You can run the following command to extend the retention period of the retention policy configured for a bucket named examplebucket to 360 days:
```
./ossutil64 worm extend oss://examplebucket 360 581D8A7FFA064C80827CAB4076A93A78
```
If a similar output is displayed, the retention period of the retention policy is extended to 360 days.
```
0.067810(s) elapsed
```

Query the configurations of a retention policy

You can run the following command to query the configurations of the retention policy configured for a bucket.

Command syntax
```
./ossutil64 worm get oss://BucketName
```
Examples
You can run the following command to query the configurations of the retention policy configured for a bucket named examplebucket:
```
./ossutil64 worm get oss://examplebucket
```
If a similar output is displayed, the configurations of the retention policy are found. 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 policy is locked.

Command syntax
```
./ossutil64 worm abort oss://BucketName
```
Examples
You can run the following command to delete the retention policy 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 a different region, you can use the -e option to specify the endpoint of the region in which the specified bucket resides. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, you can use the -i option to specify the AccessKey ID of the specified account, and use 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:

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

For more information about other common options that apply to the worm command, see Common options.