How to configure static website hosting and back-to-origin rules by using the website command - Object Storage Service

You can use the static website hosting feature to host your static website in an Object Storage Service (OSS) bucket and use the endpoint of the bucket to access the website. After you configure static website hosting for a bucket, if the data that users request from OSS does not exist, you can configure back-to-origin rules to make sure that the users can still obtain the data. This topic describes how to run the website command to add, modify, query, or delete static website hosting and back-to-origin configurations for a bucket.

Usage notes

To add website-related configurations to or modify the website-related configurations of a bucket, you must have the oss:PutBucketWebsite permission. To query the website-related configurations of a bucket, you must have oss:GetBucketWebsite permission. To delete the website-related configurations of a bucket, you must have the oss:DeleteBucketWebsite permission. For more information, see Attach a custom policy to a RAM user.
This topic provides sample command lines that are based on the 64-bit Linux system. For other systems, replace ./ossutil64 in the commands with the specific binary name. For more information, see ossutil command reference.
After static website hosting is configured for a bucket, a 404 error is returned if the data requested by users from OSS does not exist. However, if you configure back-to-origin rules that contain a valid origin for the bucket, users can obtain the data based on the rules.
For more information about static website hosting, see Overview.
For more information about back-to-origin, see Overview.

Add website-related configurations to or modify the website-related configurations of a bucket

If a bucket has no website-related configurations, new configurations are added for the bucket when you run the website command. If a bucket already has website-related configurations, new website configurations overwrite the existing configurations when you run the website command.

To add or modify website-related configurations, perform the following steps:

Create a local file and add website-related configurations to the file.
Add website-related configurations to a destination bucket.

Command syntax and examples

Command syntax

./ossutil64 website --method put oss://bucketname local_xml_file

The following table describes the parameters in the preceding command.

Parameter	Description
bucketname	The name of the bucket to which you want to add website-related configurations or whose website-related configurations you want to modify.
local_xml_file	The name of the local file that you want to use to configure website rules. Example: `localfile.xml`.

Examples

Create a local file named localfile.xml and configure different website rules in the file.

The following sample code provides an example on how to add complete website-related configurations to a bucket, including static website hosting configurations and back-to-origin configurations. You can add only static website hosting configurations or back-to-origin configurations based on your actual requirements.

Static website hosting configurations
In the following example, the <IndexDocument> field specifies that the default homepage of the static website is index.html. The <ErrorDocument> field specifies that the default 404 page of the static website is error.html.
Back-to-origin configurations
In the following example, the <RoutingRules> field specifies back-to-origin rules. For more information about the parameters that you can configure for back-to-origin rules, see Overview.

<?xml version="1.0" encoding="UTF-8"?>
 <WebsiteConfiguration>
     <IndexDocument>
         <Suffix>index.html</Suffix>
     </IndexDocument>
     <ErrorDocument>
         <Key>error.html</Key>
     </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>
     </RoutingRules>
 </WebsiteConfiguration>

Run the following command to add website-related configurations to the bucket named examplebucket:
```
./ossutil64 website --method put oss://examplebucket localfile.xml
```
If a similar output is displayed, the website-related configurations are added to examplebucket:
```
0.299514(s) elapsed
```

Query website-related configurations

Command syntax

./ossutil64 website --method get oss://bucketname [local_xml_file]

The following table describes the parameters in the preceding command.

Parameter	Description
bucketname	The name of the bucket whose website-related configurations you want to query.
local_xml_file	The name of the local file in which website-related configurations are stored. Example: `localfile.xml`. If this parameter is not specified, the queried website-related configurations are displayed.

Examples

Run the following command to query the website-related configurations of the examplebucket bucket and store the configurations in the localfile.xml local file:
```
./ossutil64 website --method get oss://examplebucket localfile.xml
```
If a similar output is displayed, the website-related configurations of examplebucket are queried and stored in localfile.xml:
```
0.212407(s) elapsed
```

Run the following command to query the website-related configurations of the examplebucket bucket and specify that the configurations are displayed:

./ossutil64 website --method get oss://examplebucket

If a similar output is displayed, the website-related configurations of examplebucket are queried:

<?xml version="1.0" encoding="UTF-8"?>
<WebsiteConfiguration>
  <IndexDocument>
    <Suffix>index.html</Suffix>
    <SupportSubDir>false</SupportSubDir>
    <Type>0</Type>
  </IndexDocument>
  <ErrorDocument>
    <Key>error.html</Key>
  </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>
        <MirrorPassOriginalSlashes>false</MirrorPassOriginalSlashes>
        <MirrorFollowRedirect>true</MirrorFollowRedirect>
        <MirrorIsExpressTunnel>false</MirrorIsExpressTunnel>
        <MirrorUserLastModified>false</MirrorUserLastModified>
        <MirrorCheckMd5>false</MirrorCheckMd5>
        <MirrorSwitchAllErrors>false</MirrorSwitchAllErrors>
        <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>
        <MirrorUsingRole>false</MirrorUsingRole>
        <MirrorAllowHeadObject>false</MirrorAllowHeadObject>
        <EnableReplacePrefix>false</EnableReplacePrefix>
      </Redirect>
    </RoutingRule>
    <RoutingRule>
      <RuleNumber>2</RuleNumber>
      <Condition>
        <IncludeHeader>
          <Key>host</Key>
          <Equals>test.oss-cn-beijing-internal.aliyuncs.com</Equals>
        </IncludeHeader>
        <KeyPrefixEquals>abc/</KeyPrefixEquals>
        <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals>
      </Condition>
      <Redirect>
        <RedirectType>AliCDN</RedirectType>
        <Protocol>http</Protocol>
        <HostName>example.com</HostName>
        <PassQueryString>false</PassQueryString>
        <ReplaceKeyWith>prefix/${key}.suffix</ReplaceKeyWith>
        <EnableReplacePrefix>false</EnableReplacePrefix>
        <HttpRedirectCode>301</HttpRedirectCode>
      </Redirect>
    </RoutingRule>
  </RoutingRules>
</WebsiteConfiguration>

0.157648(s) elapsed

Delete website-related configurations

Command syntax

./ossutil64 website --method delete oss://bucketname

Examples
Run the following command to delete the website-related configurations of the bucket named examplebucket:
```
./ossutil64 website --method delete oss://examplebucket
```
If a similar output is displayed, the website-related configurations of the bucket are deleted:
```
0.212409(s) elapsed
```

Common options

If you use ossutil to switch to a bucket that is located in another region, add the -e option to the command to specify the endpoint of the region in which the specified bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, you can add the -i option to the command to specify the AccessKey ID of the specified account, and add the -k option to the command to specify the AccessKey secret of the specified account.

For example, you can run the following command to add website-related configurations to a bucket named testbucket that is located in the China (Hangzhou) region and owned by another Alibaba Cloud account:

./ossutil64 website --method put oss://testbucket localfile.xml -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

For more information about common options, see Common options.