How do I create a retention policy? - Object Storage Service

Creates a retention policy.

Usage notes

To create a retention policy, you must have the oss:InitiateBucketWorm permission. For more information, see Attach a custom policy to a RAM user.
Object Storage Service (OSS) supports the Write Once Read Many (WORM) feature that prevents an object from being deleted or overwritten for a specific period of time. You can configure a time-based retention policy for buckets. This policy has a protection period ranging from 1 day to 70 years.
If a retention policy is not locked within 24 hours after it is created, the retention policy becomes invalid. After a retention policy configured for a bucket is locked, you can read objects from or upload objects to the bucket. You cannot delete the retention policy or objects in the bucket within the retention period. You can delete the objects only after the retention period expires. For more information about retention policies, see Retention policies.
You cannot enable versioning and configure retention policies for a bucket at the same time. If versioning is enabled for a bucket, you cannot configure retention policies for the bucket. For more information about versioning, see Overview.

Command syntax

ossutil api initiate-bucket-worm --bucket value --initiate-worm-configuration value [flags]

Parameter	Type	Description
--bucket	string	The name of the bucket.
--initiate-worm-configuration	string	The request body.

Note

The initiate-bucket-worm command is the equivalent of the InitiateBucketWorm operation. For more information about the API operation, see InitiateBucketWorm.

--initiate-worm-configuration

The --initiate-worm-configuration option supports XML and JSON formats.

XML format:

<InitiateWormConfiguration>
  <RetentionPeriodInDays>integer</RetentionPeriodInDays>
</InitiateWormConfiguration>

JSON format:
```
{
  "RetentionPeriodInDays": integer
}
```

Note

For more information, see Command-line options.

Examples

Create a retention policy for the examplebucket bucket.

Use an XML configuration file (initiate-worm-configuration.xml in this example)

<?xml version="1.0" encoding="UTF-8"?>
<InitiateWormConfiguration>
  <RetentionPeriodInDays>365</RetentionPeriodInDays>
</InitiateWormConfiguration>

Sample command:

ossutil api initiate-bucket-worm --bucket examplebucket --initiate-worm-configuration file://initiate-worm-configuration.xml

Use a JSON configuration file (initiate-worm-configuration.json in this example)

{
        "RetentionPeriodInDays": "365"
}

Sample command:

ossutil api initiate-bucket-worm --bucket examplebucket --initiate-worm-configuration file://initiate-worm-configuration.json

Use JSON parameters in the command line

ossutil api initiate-bucket-worm --bucket examplebucket --initiate-worm-configuration "{\"RetentionPeriodInDays\":\"365\"}"