Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

PutBucketWebsite

Sets the configuration of the website that is specified in the website subresource. To configure a bucket as a website, you can add this subresource on the bucket with website configuration information such as the file name of the index document and any redirect rules. For more information, see Hosting Websites on Amazon S3.

This PUT operation requires the S3:PutBucketWebsite permission. By default, only the bucket owner can configure the website attached to a bucket; however, bucket owners can allow other users to set the website configuration by writing a bucket policy that grants them the S3:PutBucketWebsite permission.

To redirect all website requests sent to the bucket's website endpoint, you add a website configuration with the following elements. Because all requests are sent to another website, you don't need to provide index document name for the bucket.

  • WebsiteConfiguration

  • RedirectAllRequestsTo

  • HostName

  • Protocol

If you want granular control over redirects, you can use the following elements to add routing rules that describe conditions for redirecting requests and information about the redirect destination. In this case, the website configuration must provide an index document for the bucket, because some requests might not be redirected.

  • WebsiteConfiguration

  • IndexDocument

  • Suffix

  • ErrorDocument

  • Key

  • RoutingRules

  • RoutingRule

  • Condition

  • HttpErrorCodeReturnedEquals

  • KeyPrefixEquals

  • Redirect

  • Protocol

  • HostName

  • ReplaceKeyPrefixWith

  • ReplaceKeyWith

  • HttpRedirectCode

Request Syntax

PUT /?website HTTP/1.1 Host: Bucket.s3.amazonaws.com Content-MD5: ContentMD5 <?xml version="1.0" encoding="UTF-8"?> <WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <ErrorDocument> <Key>string</Key> </ErrorDocument> <IndexDocument> <Suffix>string</Suffix> </IndexDocument> <RedirectAllRequestsTo> <HostName>string</HostName> <Protocol>string</Protocol> </RedirectAllRequestsTo> <RoutingRules> <RoutingRule> <Condition> <HttpErrorCodeReturnedEquals>string</HttpErrorCodeReturnedEquals> <KeyPrefixEquals>string</KeyPrefixEquals> </Condition> <Redirect> <HostName>string</HostName> <HttpRedirectCode>string</HttpRedirectCode> <Protocol>string</Protocol> <ReplaceKeyPrefixWith>string</ReplaceKeyPrefixWith> <ReplaceKeyWith>string</ReplaceKeyWith> </Redirect> </RoutingRule> </RoutingRules> </WebsiteConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket

The bucket name.

Content-MD5

The base64-encoded 128-bit MD5 digest of the data. You must use this header as a message integrity check to verify that the request body was not corrupted in transit. For more information, see RFC 1864.

Request Body

The request accepts the following data in XML format.

WebsiteConfiguration

Root level tag for the WebsiteConfiguration parameters.

Required: Yes

ErrorDocument

The name of the error document for the website.

Type: ErrorDocument data type

Required: No

IndexDocument

The name of the index document for the website.

Type: IndexDocument data type

Required: No

RedirectAllRequestsTo

The redirect behavior for every request to this bucket's website endpoint.

Important

If you specify this property, you can't specify any other property.

Type: RedirectAllRequestsTo data type

Required: No

RoutingRules

Rules that define when a redirect is applied and the redirect behavior.

Type: Array of RoutingRule data types

Required: No

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples

Example 1: Configure bucket as a website (add website configuration)

The following request configures a bucket example.com as a website. The configuration in the request specifies index.html as the index document. It also specifies the optional error document, SomeErrorDocument.html.

PUT ?website HTTP/1.1 Host: example.com.s3.amazonaws.com Content-Length: 256 Date: Thu, 27 Jan 2011 12:00:00 GMT Authorization: signatureValue <WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'> <IndexDocument> <Suffix>index.html</Suffix> </IndexDocument> <ErrorDocument> <Key>SomeErrorDocument.html</Key> </ErrorDocument> </WebsiteConfiguration>

Sample Response

HTTP/1.1 200 OK x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo x-amz-request-id: 80CD4368BD211111 Date: Thu, 27 Jan 2011 00:00:00 GMT Content-Length: 0 Server: AmazonS3

Example 2: Configure bucket as a website but redirect all requests

The following request configures a bucket www.example.com as a website; however, the configuration specifies that all GET requests for the www.example.com bucket's website endpoint will be redirected to host example.com. This redirect can be useful when you want to serve requests for both http://www.example.com and http://example.com, but you want to maintain the website content in only one bucket, in this case example.com.

PUT ?website HTTP/1.1 Host: www.example.com.s3.amazonaws.com Content-Length: length-value Date: Thu, 27 Jan 2011 12:00:00 GMT Authorization: signatureValue <WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'> <RedirectAllRequestsTo> <HostName>example.com</HostName> </RedirectAllRequestsTo> </WebsiteConfiguration>

Example 3: Configure bucket as a website and also specify optional redirection rules

Example 1 is the simplest website configuration. It configures a bucket as a website by providing only an index document and an error document. You can further customize the website configuration by adding routing rules that redirect requests for one or more objects. For example, suppose your bucket contained the following objects:

  • index.html

  • docs/article1.html

  • docs/article2.html

If you decided to rename the folder from docs/ to documents/, you would need to redirect requests for prefix /docs to documents/. For example, a request for docs/article1.html will need to be redirected to documents/article1.html.

In this case, you update the website configuration and add a routing rule as shown in the following request.

PUT ?website HTTP/1.1 Host: www.example.com.s3.amazonaws.com Content-Length: length-value Date: Thu, 27 Jan 2011 12:00:00 GMT Authorization: signatureValue <WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'> <IndexDocument> <Suffix>index.html</Suffix> </IndexDocument> <ErrorDocument> <Key>Error.html</Key> </ErrorDocument> <RoutingRules> <RoutingRule> <Condition> <KeyPrefixEquals>docs/</KeyPrefixEquals> </Condition> <Redirect> <ReplaceKeyPrefixWith>documents/</ReplaceKeyPrefixWith> </Redirect> </RoutingRule> </RoutingRules> </WebsiteConfiguration>

Example 4: Configure bucket as a website and redirect errors

You can use a routing rule to specify a condition that checks for a specific HTTP error code. When a page request results in this error, you can optionally reroute requests. For example, you might route requests to another host and optionally process the error. The routing rule in the following requests redirects requests to an EC2 instance in the event of an HTTP error 404. For illustration, the redirect also inserts a object key prefix report-404/ in the redirect. For example, if you request a page ExamplePage.html and it results in a HTTP 404 error, the request is routed to a page report-404/testPage.html on the specified EC2 instance. If there is no routing rule and the HTTP error 404 occurred, then Error.html would be returned.

PUT ?website HTTP/1.1 Host: www.example.com.s3.amazonaws.com Content-Length: 580 Date: Thu, 27 Jan 2011 12:00:00 GMT Authorization: signatureValue <WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'> <IndexDocument> <Suffix>index.html</Suffix> </IndexDocument> <ErrorDocument> <Key>Error.html</Key> </ErrorDocument> <RoutingRules> <RoutingRule> <Condition> <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals > </Condition> <Redirect> <HostName>ec2-11-22-333-44.compute-1.amazonaws.com</HostName> <ReplaceKeyPrefixWith>report-404/</ReplaceKeyPrefixWith> </Redirect> </RoutingRule> </RoutingRules> </WebsiteConfiguration>

Example 5: Configure a bucket as a website and redirect folder requests to a page

Suppose you have the following pages in your bucket:

  • images/photo1.jpg

  • images/photo2.jpg

  • images/photo3.jpg

Now you want to route requests for all pages with the images/ prefix to go to a single page, errorpage.html. You can add a website configuration to your bucket with the routing rule shown in the following request.

PUT ?website HTTP/1.1 Host: www.example.com.s3.amazonaws.com Content-Length: 481 Date: Thu, 27 Jan 2011 12:00:00 GMT Authorization: signatureValue <WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'> <IndexDocument> <Suffix>index.html</Suffix> </IndexDocument> <ErrorDocument> <Key>Error.html</Key> </ErrorDocument> <RoutingRules> <RoutingRule> <Condition> <KeyPrefixEquals>images/</KeyPrefixEquals> </Condition> <Redirect> <ReplaceKeyWith>errorpage.html</ReplaceKeyWith> </Redirect> </RoutingRule> </RoutingRules> </WebsiteConfiguration>

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: