Enabling or disabling versioning for a bucket
You use the HTTP PUT method with the versioning query parameter to enable or disable versioning for a bucket. To enable or disable versioning for a bucket, you need to be the bucket owner.
While versioning is enabled for a bucket, the versioning status of the bucket is Enabled. If you disable versioning for a bucket after it has been enabled, the versioning status changes to Suspended. If versioning has never been enabled for a bucket, the bucket has no explicit versioning status.
To enable or disable versioning for a bucket, you specify the new versioning status in an XML request body.
Request line
Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to enable or disable versioning for a bucket has either of these formats:
- With the bucket name included in the hostname:
PUT /?versioning HTTP/1.1
- With the bucket name following the hostname:
PUT /bucket-name?versioning HTTP/1.1
The versioning query parameter is not case sensitive.
Required headers
Authorization
Specifies user credentials or requests anonymous access.
Content-Length
Specifies the size, in bytes, of the request body.
Date
Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.
The date and time must always be specified using Greenwich Mean Time (GMT).
To specify the date and time, use this format:
DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)
In this format:
DDD
The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).
dd
The two-digit day of the month.
MMM
The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).
yyyy
The four-digit year.
HH
The hour on a 24-hour clock.
mm
The number of minutes.
ss
The number of seconds.
For example:
Thu, 23 Mar 2017 14:27:05 +0000
All S3 compatible requests must include either a
Date
header or anx-amz-date
header. If a request includes both headers, HCP uses the date and time in thex-amz-date
header.Host
Specifies the hostname for the request. The host name identifies either a tenant or a bucket.
For a tenant, use this format:
tenant-name.hcp-domain-name
For a bucket, use this format:
bucket-name.tenant-name.hcp-domain-name
x-amz-date
Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.
For the valid values for this header, see the description of the
Date
header above.
Optional headers
Content-Type
Specifies the Internet media type of the request body. The only valid values are
application/xml
andtext/xml
.
Request body
For the content of a versioning request body, you use XML in this format:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Status>versioning-status</Status> </VersioningConfiguration>
The list below describes the XML elements in a versioning request body. The elements are listed in alphabetical order.
Status
Child of the
VersioningConfiguration
element. Valid values for theStatus
element are:Enabled
Enables versioning for the bucket
Suspended
Disables versioning for the bucket
VersioningConfiguration
Root element. This must be the first element in the versioning request body.
The
VersioningConfiguration
element can optionally include this XML namespace specification:xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
Response headers
The list below describes the headers returned in response to a successful request to enable or disable versioning for a bucket.
Content-length
Specifies the size, in bytes, of the response body. In response to a successful request to store an object, the value of this header is always
0
(zero).Date
The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:
DDD dd MMM yyyy HH:mm:ss GMT
For example:
Fri, 18 Sep 2020 14:27:05 GMT
Location
Specifies the name of the target bucket.
Return codes
The table below describes HTTP status codes that can be returned in response to a request to enable or disable versioning for a bucket.
Code | Meaning | Description |
200 | OK | HCP successfully enabled or disabled versioning for the bucket. |
400 | Bad Request | Possible reasons include that the XML in the versioning request body is malformed or contains an invalid value. |
403 | Forbidden |
Possible reasons include:
|
404 | Not Found | The specified bucket does not exist. |
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
503 | Service Unavailable |
HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator. |
Example: Enabling versioning for a bucket
Here’s a sample PUT request that enables versioning for the finance bucket. The versioning request body is in a file named versioning.xml.
Request body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Status>Enabled</Status> </VersioningConfiguration>
Request with s3curl command line
./s3curl.pl --id=lgreen --put versioning.xml -- -k "https://europe.hcp.example.com/finance?versioning"
Request headers
PUT /finance?versioning HTTP/1.1 Host: europe.hcp.example.com Date: Fri, 07 February 2020 17:19:26 +0000 Authorization: AWS bGdyZWVu:ETdibK607bVlNdxb0aKCttJU33U= Content-Length: 182
Response headers
HTTP/1.1 200 OK Date: Fri, 07 February 2020 17:19:26 GMT Location: /finance Content-Length: 0