Object Storage Service:PutBucketWebsite

Usage notes

Static websites consist of static content, including client-side scripts such as JavaScript. OSS does not support server-side processing such as PHP, JSP, or ASP.NET.

• PutBucketWebsite requires the oss:PutBucketWebsite permission. Grant a custom access policy to a RAM user.

• Features

  Configures the default homepage, default 404 page, and redirection rules (RoutingRule). Redirection rules support 3xx redirects and mirroring-based back-to-origin.

• Access static websites using custom domain names

  To access a static website using a custom domain name, add a CNAME record. Bind a custom domain name.

• Index and error pages

  You can specify an index page and an error page. Both must be objects in the bucket.

• Anonymous access to the root domain

  After static website hosting is configured, OSS returns the index page for anonymous requests to the root domain. Signed requests to the root domain return the result of the GetBucket (ListObjects) operation.

Request syntax

PUT /?website HTTP/1.1
Date: GMT Date
Content-Length: ContentLength
Content-Type: application/xml
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue

<?xml version="1.0" encoding="UTF-8"?>
<WebsiteConfiguration>
    <IndexDocument>
        <Suffix>index.html</Suffix>
    </IndexDocument>
    <ErrorDocument>
        <Key>errorDocument.html</Key>
        <HttpStatus>404</HttpStatus>
    </ErrorDocument>
</WebsiteConfiguration>

Request headers

DescribeRegions uses only common request headers. For more information, see Common request headers.

Request parameters

• Contents of WebsiteConfiguration

  Name	Type	Required	Description
  WebsiteConfiguration	Container	Yes	The root node. Parent node: None

• IndexDocument content

  Name	Type	Required	Description
  IndexDocument	Container	Conditional You must specify at least one of the following containers: IndexDocument, ErrorDocument, and RoutingRules.	The container for the default homepage. Parent node: WebsiteConfiguration
  Suffix	String	Conditional This parameter is required if you specify the parent node IndexDocument.	The default homepage. OSS returns this page for requests to URLs ending with a forward slash (/). Parent node: IndexDocument
  SupportSubDir	String	No	Whether to redirect requests for a subdirectory to the index page in that subdirectory. Valid values: true: Redirects requests to the index page in the subdirectory. false (default): Does not redirect requests to the index page in the subdirectory. Instead, requests are redirected to the index page in the root directory. For example, the default homepage is index.html and a request is sent to bucket.oss-cn-hangzhou.aliyuncs.com/subdir/. If you set SupportSubDir to false, the request is redirected to bucket.oss-cn-hangzhou.aliyuncs.com/index.html. If you set SupportSubDir to true, the request is redirected to bucket.oss-cn-hangzhou.aliyuncs.com/subdir/index.html. Parent node: IndexDocument
  Type	Enumeration	No	The operation to perform when the default homepage is set, the name of the accessed Object does not end with a forward slash (/), and the Object does not exist. This operation takes effect only when SupportSubDir is set to true and is applied after RoutingRule and before ErrorFile. For example, the default homepage is index.html, a request is sent for the file path bucket.oss-cn-hangzhou.aliyuncs.com/abc, and the object abc does not exist. The actions for different values of Type are as follows: 0 (default): Checks whether abc/index.html exists. The path is in the format of Object + / + Homepage. If the object exists, OSS returns a 302 redirect to the URL-encoded path /abc/. The path is in the format of / + Object + /. If the object does not exist, OSS returns a 404 error and then checks for an error page. 1: Returns a 404 error with the NoSuchKey error code and then checks for an error page. 2: Checks whether abc/index.html exists. If the object exists, its content is returned. If the object does not exist, OSS returns a 404 error and then checks for an error page. Parent node: IndexDocument

• Error document content

  Name	Type	Required	Description
  ErrorDocument	Container	Conditional You must specify at least one of the following containers: IndexDocument, ErrorDocument, and RoutingRules.	The container for the 404 error page. Parent node: WebsiteConfiguration
  Key	String	Conditional This parameter is required if you specify the parent node ErrorDocument.	The error page. Returned when a requested object does not exist. Parent node: ErrorDocument
  HttpStatus	String	No	The HTTP status code to return with the error page. Valid values: 200, 404 (default) Parent node: ErrorDocument

• RoutingRules|RoutingRule|RuleNumber

  Name	Type	Required	Description
  RoutingRules	Container	Conditional You must specify at least one of the following containers: IndexDocument, ErrorDocument, and RoutingRules.	The container for redirection rules. Parent node: WebsiteConfiguration
  RoutingRule	Container	No	A redirection rule or a mirroring-based back-to-origin rule. Maximum: 20 rules. Parent node: RoutingRules
  RuleNumber	Positive integer	Conditional This parameter is required if you specify the parent node RoutingRule.	The sequence number. OSS matches rules in ascending order and stops at the first match. Parent node: RoutingRule

• Content of Condition in RoutingRule

  Name	Type	Required	Description
  Condition	Container	Conditional This parameter is required if you specify the parent node RoutingRule.	The match conditions. All conditions must be met for the rule to execute. Parent node: RoutingRule
  KeyPrefixEquals	String	No	The object key must have this prefix for the rule to apply. Parent node: Condition
  HttpErrorCodeReturnedEquals	HTTP status code	No	The HTTP status code returned for the requested object that triggers this rule. For mirroring-based back-to-origin, set to 404. Parent node: Condition
  IncludeHeader	Container	No	The request must include the specified header and value for the rule to apply. You can specify up to 10 headers. Parent node: Condition
  Key	String	Yes	This rule applies only if the request contains the specified header and its value exactly matches the value specified for Equals. Parent node: IncludeHeader
  Equals	String	No	The value of the request header. The rule applies only if the request includes the header specified by Key and its value matches this value. Parent node: IncludeHeader
  KeySuffixEquals	String	No	The object key must have this suffix for the rule to apply. The default value is empty, which means no suffix is matched. Parent node: Condition

• Redirect configuration

  Name	Type	Required	Description
  Redirect	Container	Conditional This parameter is required if you specify the parent node RoutingRule.	The action to perform when the rule is matched. Parent node: RoutingRule
  RedirectType	String	Conditional This parameter is required if you specify the parent node Redirect.	The redirect type. Valid values: Mirror: mirroring-based back-to-origin. External: external redirect. OSS returns a 3xx redirect to another address. AliCDN: Alibaba Cloud CDN redirect. This type is used for Alibaba Cloud CDN. Unlike an external redirect, OSS adds an extra header to the request. After Alibaba Cloud CDN detects this header, it redirects the request to the specified address and returns the retrieved data to the user, instead of returning a 3xx redirect request to the user. Parent node: Redirect
  PassQueryString	Boolean	No	Whether to include the query string from the original request in the redirect or back-to-origin request. For example, a user sends a request with the query string ?a=b&c=d. If you set PassQueryString to true and the rule specifies a 302 redirect, the Location header in the response includes the query string, such as Location:example.com?a=b&c=d. If the rule specifies mirroring-based back-to-origin, the back-to-origin request also includes the query string. Valid values: true, false (default) Parent node: Redirect
  MirrorURL	String	Conditional This parameter is required if RedirectType is set to Mirror.	The origin server address for mirroring-based back-to-origin. Takes effect only when RedirectType is Mirror. The address must start with http:// or https:// and end with a forward slash (/). OSS appends the object name to this address to create the back-to-origin URL. For example, if the requested object is myobject and you set this parameter to http://example.com/, the back-to-origin URL is http://example.com/myobject. If you set this parameter to http://example.com/dir1/, the back-to-origin URL is http://example.com/dir1/myobject. Parent node: Redirect
  MirrorPassQueryString	Boolean	No	Same as PassQueryString but with higher priority. Takes effect only when RedirectType is Mirror. Default value: false Parent node: Redirect
  MirrorFollowRedirect	Boolean	No	Whether to follow 3xx redirects from the origin server. Takes effect only when RedirectType is Mirror. For example, the origin server returns a 302 redirect with a Location header. If you set this parameter to true, OSS sends a new request to the address specified in the Location header. A maximum of 10 redirects are followed. If the number of redirects exceeds 10, the back-to-origin request fails. If you set this parameter to false, OSS returns the 302 redirect and passes through the Location header to the client. Default value: true Parent node: Redirect
  MirrorCheckMd5	Boolean	No	Whether to verify the MD5 hash of the response body from the origin server. Takes effect only when RedirectType is Mirror. When MirrorCheckMd5 is true and the origin response includes a Content-Md5 header, OSS verifies the pulled data against the header value. Mismatched data is not saved. Default value: false Parent node: Redirect
  MirrorHeaders	Container	No	Headers to include in the back-to-origin request. Takes effect only when RedirectType is Mirror. Parent node: Redirect
  PassAll	Boolean	No	Whether to pass through all request headers to the origin server, except for the following headers. Takes effect only when RedirectType is Mirror. Headers such as content-length, authorization2, authorization, range, and date Headers that start with oss-, x-oss-, or x-drs- Default value: false Parent node: MirrorHeaders
  Pass	String	No	The specified headers to pass through to the origin server. Takes effect only when RedirectType is Mirror. Each header can be up to 1,024 bytes in length and can contain only digits (0-9), letters (a-z, A-Z), and hyphens (-). You can specify up to 10 headers. Parent node: MirrorHeaders
  Remove	String	No	The specified headers to prohibit from being passed through to the origin server. Takes effect only when RedirectType is Mirror. Each header has a maximum length of 1024 bytes and uses the same character set as Pass. You can specify up to 10 headers. This parameter is typically used with PassAll. Parent node: MirrorHeaders
  Set	Container	No	Sets a header to include in the back-to-origin request, regardless of whether the original request contained it. Takes effect only when RedirectType is Mirror. You can assign this container to a maximum of 10 groups. Parent node: MirrorHeaders
  Key	String	Conditional This parameter is required if you specify the parent node Set.	The key of the header to set. The key can be up to 1,024 bytes in length and can contain only digits (0-9), letters (a-z, A-Z), and hyphens (-). Takes effect only when RedirectType is Mirror. Parent node: Set
  Value	String	Conditional This parameter is required if you specify the parent node Set.	The value of the header to set. The value can be up to 1,024 bytes in length and cannot contain \r\n. Takes effect only when RedirectType is Mirror. Parent node: Set
  Protocol	String	No	The protocol to use for the redirect. Takes effect only when RedirectType is External or AliCDN. For example, if the requested object is test, you set the redirect destination to example.com, and you set Protocol to https, the Location header is https://example.com/test. Valid values: http, https. Parent node: Redirect
  HostName	String	No	The domain name to use for the redirect. The domain name must be valid. For example, if the requested object is test, you set Protocol to https, and you set HostName to example.com, the Location header is https://example.com/test. Parent node: Redirect
  ReplaceKeyPrefixWith	String	No	The string to replace the object key prefix with during the redirect. If the prefix is empty, this string is inserted at the beginning of the object key. Note You can specify either ReplaceKeyWith or ReplaceKeyPrefixWith, but not both. For example, if the requested object is abc/test.txt, you set KeyPrefixEquals to abc/, and you set ReplaceKeyPrefixWith to def/, the Location header is http://example.com/def/test.txt. Parent node: Redirect
  EnableReplacePrefix	Boolean	No	If this parameter is set to true, the object prefix is replaced with the value of ReplaceKeyPrefixWith. If this parameter is not specified or is empty, the object prefix is truncated. Note You cannot set this parameter to true if the ReplaceKeyWith parameter is not empty. Default value: false Parent node: Redirect
  ReplaceKeyWith	String	No	Replaces the entire object key during redirect. Use the ${key} variable to reference the original object key. For example, if the requested object is test and you set ReplaceKeyWith to prefix/${key}.suffix, the Location header is http://example.com/prefix/test.suffix. Parent node: Redirect
  HttpRedirectCode	HTTP status code	No	The HTTP status code to return for the redirect. Takes effect only when RedirectType is External or AliCDN. Valid values: 301 (default), 302, 307. Parent node: Redirect

Response headers

The response contains only common response headers. For more information, see Common response headers.

Examples

• Request example

  PUT /?website HTTP/1.1
  Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  Content-Length: 209
  Date: Thu, 17 Apr 2025 03:21:12 GMT
  Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  
  <?xml version="1.0" encoding="UTF-8"?>
  <WebsiteConfiguration>
    <IndexDocument>
      <Suffix>index.html</Suffix>
        <SupportSubDir>true</SupportSubDir>
        <Type>0</Type>
    </IndexDocument>
    <ErrorDocument>
      <Key>error.html</Key>
      <HttpStatus>404</HttpStatus>
    </ErrorDocument>
  </WebsiteConfiguration>

• Response example

  HTTP/1.1 200 OK
  x-oss-request-id: 534B371674E88A4D8906008B
  Date: Fri, 04 May 2012 03:21:12 GMT
  Content-Length: 0
  Connection: keep-alive
  Server: AliyunOSS

• Complete example

  PUT /?website HTTP/1.1
  Date: Thu, 17 Apr 2025 09:03:18 GMT
  Content-Length: 2064
  Host: test.oss-cn-hangzhou-internal.aliyuncs.com
  Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
  User-Agent: aliyun-sdk-python-test/0.4.0
  
  <WebsiteConfiguration>
    <IndexDocument>
      <Suffix>index.html</Suffix>
      <SupportSubDir>true</SupportSubDir>
      <Type>0</Type>
    </IndexDocument>
    <ErrorDocument>
      <Key>error.html</Key>
      <HttpStatus>404</HttpStatus>
    </ErrorDocument>
    <RoutingRules>
      <RoutingRule>
        <RuleNumber>1</RuleNumber>
        <Condition>
          <KeyPrefixEquals>abc/</KeyPrefixEquals>
          <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
        </Condition>
        <Redirect>
          <RedirectType>Mirror</RedirectType>
          <PassQueryString>true</PassQueryString>
          <MirrorURL>http://example.com/</MirrorURL>   
          <MirrorPassQueryString>true</MirrorPassQueryString>
          <MirrorFollowRedirect>true</MirrorFollowRedirect>
          <MirrorCheckMd5>false</MirrorCheckMd5>
          <MirrorHeaders>
            <PassAll>true</PassAll>
            <Pass>myheader-key1</Pass>
            <Pass>myheader-key2</Pass>
            <Remove>myheader-key3</Remove>
            <Remove>myheader-key4</Remove>
            <Set>
              <Key>myheader-key5</Key>
              <Value>myheader-value5</Value>
            </Set>
          </MirrorHeaders>
        </Redirect>
      </RoutingRule>
      <RoutingRule>
        <RuleNumber>2</RuleNumber>
        <Condition>
          <KeyPrefixEquals>abc/</KeyPrefixEquals>
          <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
          <IncludeHeader>
            <Key>host</Key>
            <Equals>test.oss-cn-beijing-internal.aliyuncs.com</Equals>
          </IncludeHeader>
        </Condition>
        <Redirect>
          <RedirectType>AliCDN</RedirectType>
          <Protocol>http</Protocol>
          <HostName>example.com</HostName>
          <PassQueryString>false</PassQueryString>
          <ReplaceKeyWith>prefix/${key}.suffix</ReplaceKeyWith>
          <HttpRedirectCode>301</HttpRedirectCode>
        </Redirect>
      </RoutingRule>
      <RoutingRule>
        <Condition>
          <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
        </Condition>
        <RuleNumber>3</RuleNumber>
        <Redirect>
          <ReplaceKeyWith>prefix/${key}</ReplaceKeyWith>
          <HttpRedirectCode>302</HttpRedirectCode>
          <EnableReplacePrefix>false</EnableReplacePrefix>
          <PassQueryString>false</PassQueryString>
          <Protocol>http</Protocol>
          <HostName>example.com</HostName>
          <RedirectType>External</RedirectType>
        </Redirect>
      </RoutingRule>
    </RoutingRules>
  </WebsiteConfiguration>
  
  HTTP/1.1 200 OK
  Server: AliyunOSS
  Date: Fri, 27 Jul 2018 09:03:18 GMT
  Content-Length: 0
  Connection: keep-alive
  x-oss-request-id: 5B5ADFD6ED3CC49176CBE29D
  x-oss-server-time: 47

SDK

• Java

• Python

• Go V2

• C++

• PHP V2

• C

• .NET

• Node.js

CLI (ossutil)

ossutil command: put-bucket-website.

Error codes