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

PUT Bucket website

Description

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, go to Hosting Websites on Amazon S3 in the Amazon Simple Storage Service Developer Guide.

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.

Requests

Syntax

PUT /?website HTTP/1.1
Host: bucketname.s3.amazonaws.com
Date: date
Content-Length: ContentLength
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
		4))

<WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <!-- website configuration information. -->
</WebsiteConfiguration>

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For more information, see Common Request Headers.

Request Elements

You can use a website configuration to redirect all requests to the website endpoint of a bucket, or you can add routing rules that redirect only specific requests.

  • 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 send to another website, you don't need to provide index document name for the bucket.

    Name Description Required
    WebsiteConfiguration

    The root element for the website configuration

    Type: Container

    Ancestors: None

    Yes
    RedirectAllRequestsTo

    Describes the redirect behavior for every request to this bucket's website endpoint. If this element is present, no other siblings are allowed.

    Type: Container

    Ancestors: WebsiteConfiguration

    Yes
    HostName

    Name of the host where requests will be redirected.

    Type: String

    Ancestors: RedirectAllRequestsTo

    Yes
    Protocol

    Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.

    Type: String

    Ancestors: RedirectAllRequestsTo

    No
  • 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.

    Name Description Required
    WebsiteConfiguration

    Container for the request

    Type: Container

    Ancestors: None

    Yes
    IndexDocument

    Container for the Suffix element.

    Type: Container

    Ancestors: WebsiteConfiguration

    Yes
    Suffix

    A suffix that is appended to a request that is for a directory on the website endpoint (e.g., if the suffix is index.html and you make a request to samplebucket/images/, the data that is returned will be for the object with the key name images/index.html)

    The suffix must not be empty and must not include a slash character.

    Type: String

    Ancestors: WebsiteConfiguration.IndexDocument

    Yes
    ErrorDocument

    Container for the Key element

    Type: Container

    Ancestors: WebsiteConfiguration

    No
    Key

    The object key name to use when a 4XX class error occurs. This key identifies the page that is returned when such an error occurs.

    Type: String

    Ancestors: WebsiteConfiguration.ErrorDocument

    Condition: Required when ErrorDocument is specified.

    Conditional
    RoutingRules

    Container for a collection of RoutingRule elements.

    Type: Container

    Ancestors: WebsiteConfiguration

    No
    RoutingRule

    Container for one routing rule that identifies a condition and a redirect that applies when the condition is met.

    Type: String

    Ancestors: WebsiteConfiguration.RoutingRules

    Condition: In a RoutingRules container, there must be at least one of RoutingRule element.

    Yes
    Condition

    A container for describing a condition that must be met for the specified redirect to apply. For example:

    • If request is for pages in the /docs folder, redirect to the /documents folder.

    • If request results in HTTP error 4xx, redirect request to another host where you might process the error.

    Type: Container

    Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule

    No
    KeyPrefixEquals

    The object key name prefix when the redirect is applied. For example, to redirect requests for ExamplePage.html, the key prefix will be ExamplePage.html. To redirect request for all pages with the prefix docs/, the key prefix will be /docs, which identifies all objects in the docs/ folder.

    Type: String

    Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Condition

    Condition: Required when the parent element Condition is specified and sibling HttpErrorCodeReturnedEquals is not specified. If both conditions are specified, both must be true for the redirect to be applied.

    Conditional
    HttpErrorCodeReturnedEquals

    The HTTP error code when the redirect is applied. In the event of an error, if the error code equals this value, then the specified redirect is applied.

    Type: String

    Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Condition

    Condition: Required when parent element Condition is specified and sibling KeyPrefixEquals is not specified. If both are specified, then both must be true for the redirect to be applied.

    Conditional
    Redirect

    Container for redirect information. You can redirect requests to another host, to another page, or with another protocol. In the event of an error, you can specify a different error code to return.

    Type: String

    Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule

    Yes
    Protocol

    The protocol to use in the redirect request.

    Type: String

    Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Redirect

    Valid Values: http, https

    Condition: Not required if one of the siblings is present

    No
    HostName

    The host name to use in the redirect request.

    Type: String

    Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Redirect

    Condition: Not required if one of the siblings is present

    No
    ReplaceKeyPrefixWith

    The object key prefix to use in the redirect request. For example, to redirect requests for all pages with prefix docs/ (objects in the docs/ folder) to documents/, you can set a condition block with KeyPrefixEquals set to docs/ and in the Redirect set ReplaceKeyPrefixWith to /documents.

    Type: String

    Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Redirect

    Condition: Not required if one of the siblings is present. Can be present only if ReplaceKeyWith is not provided.

    No
    ReplaceKeyWith

    The specific object key to use in the redirect request. For example, redirect request to error.html.

    Type: String

    Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Redirect

    Condition: Not required if one of the sibling is present. Can be present only if ReplaceKeyPrefixWith is not provided.

    No
    HttpRedirectCode

    The HTTP redirect code to use on the response.

    Type: String

    Ancestors: WebsiteConfiguration.RoutingRules.RoutingRule.Redirect

    Condition: Not required if one of the siblings is present.

    No

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This implementation of the operation does not return response elements.

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>

Amazon S3 returns the following 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.

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>

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. For more information, go to Hosting Websites on Amazon S3 in the Amazon Simple Storage Service Developer Guide.

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>