Extend the WORM retention period of a bucket using ossutil extend-bucket-worm - Object Storage Service

Extend the retention period of a locked Write Once, Read Many (WORM) retention policy on a bucket using ossutil.

Prerequisites

Before you begin, ensure that you have:

The oss:ExtendBucketWorm permission. For more information, see Attach a custom policy to a RAM user

Usage notes

A time-based retention policy is in the InProgress state for 24 hours after it is created. Within this window, the retention policy protects the data in the bucket:
- If the policy is not locked, the bucket owner and authorized users can delete it.
- If the policy is locked, it cannot be deleted, and its retention period can only be extended — not shortened.
After 24 hours, an unlocked policy becomes invalid.
If a bucket contains objects within the retention period, you cannot delete the bucket or its retention policy.
If a bucket is deleted, its retention policy is also deleted. Only the bucket owner can delete a bucket when it is empty.

Command syntax

ossutil api extend-bucket-worm --bucket <value> --worm-id <value> --extend-worm-configuration <value> [flags]

Parameter	Type	Description
`--bucket`	string	The name of the bucket.
`--worm-id`	string	The ID of the retention policy.
`--extend-worm-configuration`	string	The new retention period configuration. Accepts XML or JSON format. Use the `file://` prefix to read the configuration from a file.

For all available flags, see Command-line options.

--extend-worm-configuration format

XML format:

<ExtendWormConfiguration>
  <RetentionPeriodInDays>integer</RetentionPeriodInDays>
</ExtendWormConfiguration>

JSON format:

{
  "RetentionPeriodInDays": integer
}

Examples

The following examples extend the retention period of objects protected by policy 123 in examplebucket to 366 days.

Using an XML configuration file

Create a configuration file named extend-worm-configuration.xml:

   <?xml version="1.0" encoding="UTF-8"?>
   <ExtendWormConfiguration>
     <RetentionPeriodInDays>366</RetentionPeriodInDays>
   </ExtendWormConfiguration>

Run the command:

   ossutil api extend-bucket-worm --bucket examplebucket --worm-id 123 --extend-worm-configuration file://extend-worm-configuration.xml

Using a JSON configuration file

Create a configuration file named extend-worm-configuration.json:
```
   {
     "RetentionPeriodInDays": "366"
   }
```

Run the command:

   ossutil api extend-bucket-worm --bucket examplebucket --worm-id 123 --extend-worm-configuration file://extend-worm-configuration.json

Using inline JSON

ossutil api extend-bucket-worm --bucket examplebucket --worm-id 123 --extend-worm-configuration "{\"RetentionPeriodInDays\":\"366\"}"