You can use the static website hosting feature to host your static website on 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 your users request from OSS does not exist, you can configure back-to-origin rules to make sure that they 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

  • Sample command lines in this topic are based on the 64-bit Linux system. For other systems, replace ./ossutil64 in the commands with the corresponding binary name. For more information, see ossutil.
  • After static website hosting is configured for a bucket, a 404 error is returned when the data requested by your users from OSS does not exist. However, if you configure back-to-origin rules that contain a valid origin for the bucket, your 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 Manage back-to-origin configurations.

Add or modify website-related configurations

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 ones when you run the website command.

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

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

The following code provides an example on the command syntax to add or modify website-related configurations:

  • Command syntax
    ./ossutil64 website --method put oss://bucketname local_xml_file

    The following table describes the parameters that you can configure when you run this command to add or modify website-related configurations.

    Parameter Description
    bucketname The name of the bucket to which website-related configurations are added or modified.
    local_xml_file The name of the local file in which the website rules are configured. Example: localfile.txt.
  • Examples
    1. Create a file named localfile.txt on the local device and configure different website rules in the file.
      The following code provides an example on how to add complete website-related configurations to a bucket, which includes static website hosting configurations and back-to-origin configurations: You can choose to add only static website hosting configurations or back-to-origin configurations based on your actual requirements.
      • Static website hosting configurations

        In the following sample configuration, the <IndexDocument> field specifies the default homepage of the static website as index.html. The <ErrorDocument> field specifies the default 404 error page of the static website as error.html.

      • Back-to-origin configurations

        In the following sample configuration, the <RoutingRules> field specifies back-to-origin rules. For more information about 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>
    2. You can run the following command to add website-related configurations for the bucket named examplebucket: 
      ./ossutil64 website --method put oss://examplebucket localfile.txt

      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 that you can configure when you run this command to query website-related configurations.

    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 used to store the website-related configurations. Example: localfile.txt. If this parameter is not specified, obtained website-related configurations are displayed without being stored in the local file.
  • Examples
    • You can run the following command to query the website-related configurations for the examplebucket bucket and write the configurations into the localfile.txt local file: 
      ./ossutil64 website --method get oss://examplebucket localfile.txt

      If a similar output is displayed, the website-related configurations for examplebucket are obtained and written into localfile.txt: 

      0.212407(s) elapsed
    • You can run the following command to query the website-related configurations of the examplebucket bucket and specify that the output is displayed without being stored in the local file: 
      ./ossutil64 website --method get oss://examplebucket

      If a similar output is displayed, the website-related configurations are obtained: 

      <?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

    You can run the following command to delete the website-related configurations for the bucket named examplebucket: 

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

    If a similar output is displayed, the website-related configurations for the bucket are deleted: 

    0.212409(s) elapsed

Common options

To use ossutil to manage buckets that are located in different regions, you can use the -e option to use the endpoint of the specified bucket. To use ossutil to manage buckets that are owned by different Alibaba Cloud accounts, you can use the -i option to use the AccessKey ID of the specified account, and use the -k option to use the AccessKey secret of the specified account.

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

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

For more information about other common options that you can use for the website command, see Common options.