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.
For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you need to update the binary name based on the operating system. 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

ossutil 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:
```
ossutil 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

ossutil 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:
```
ossutil 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:

ossutil 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

ossutil website --method delete oss://bucketname

Examples
Run the following command to delete the website-related configurations of the bucket named examplebucket:
```
ossutil 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 specify the endpoint of the region in which the bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to specify the AccessKey ID of the specified account, and add the -k option 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:

ossutil 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.