Retention periods and policies

ECS provides the ability to prevent data from being modified or deleted within a specified retention period.

You can specify retention by using retention periods and retention policies that are defined in the metadata that is associated with objects and buckets. The retention periods and retention policies are checked each time a request to modify an object is made. Retention periods are supported on all ECS object protocols (S3, Swift, Atmos, and CAS).

NOTE: For detailed information about setting retention on object interfaces, including CAS retention and CAS advanced retention, see the ECS Data Access Guide, available from
Retention Periods You can assign retention periods at the object level or the bucket level. Each time a user requests to modify or delete an object, an expiration time is calculated. The object expiration time equals the object creation time plus the retention period. When you assign a retention period for a bucket, the object expiration time is calculated based on the retention period set on the object and the retention period set on the bucket, whichever is the longest. When you apply a retention period to a bucket, the retention period for all objects in a bucket can be changed at any time, and can override the value written to the object by an object client by setting it to a longer period. You can specify that an object is retained indefinitely.
Auto-Commit Period Auto-commit period is the time interval in which the updates through NFS are allowed for objects under retention. This attribute enables NFS files that are written to ECS to be WORM compliant. The interval is calculated from the last modification time. The auto-commit value must be less than or equal to the retention value with a maximum of 1 day. A value of 0 indicates no auto-commit period.
Retention Policies Retention policies are associated with a namespace. Any policy that is associated with the namespace can be assigned to an object belonging to the namespace. A retention policy has an associated retention period. When you change the retention period that is associated with a policy, the retention period automatically changes for objects that have that policy that is assigned. You can apply a retention policy to an object. When a user attempts to modify or delete an object, the retention policy is retrieved. The retention period in the retention policy is used with object retention period and bucket retention period to verify whether the request is allowed. For example, you could define a retention policy for each of the following document types, and each policy could have an appropriate retention period. When a user requests to modify or delete the legal document four years after it was created, the larger of the bucket retention period or the object retention period is used to verify whether the operation can be performed. In this case, the request is not allowed, and the document cannot be modified or deleted for one more year.
  • Email - six months
  • Financial - three years
  • Legal - five years

ECS Management REST API retention policy methods

The retention policy creation and configuration tasks that can be performed in the ECS Portal can also be performed using the ECS Management REST API. The following table describes the ECS Management REST API methods that relate to retention policies:

ECS Management REST API method Description
PUT /object/bucket/{bucketName}/retention The retention value for a bucket that defines a mandatory retention period which is applied to every object within a bucket. If the retention value is one year, an object from the bucket cannot be modified or deleted for one year.
GET /object/bucket/{bucketName}/retention Returns the retention period that is set for a specified bucket.
POST /object/namespaces/namespace/{namespace}/retention The retention setting for namespaces that acts like a policy, where each policy is a <name>: <retention period> pair. You can define several retention policies for a namespace and you can assign a policy, by name, to an object within the namespace. This allows you to change the retention period for a set of objects that have the same policy assigned, by changing the corresponding policy.
PUT /object/namespaces/namespace/{namespace}/retention/{class} Updates the period for a retention class that is associated with a namespace.
GET /object/namespaces/namespace/{namespace}/retention Returns the retention classes that are defined for a namespace.

For information about how to access the ECS Management REST API, see the ECS Data Access Guide, available from