Use the website command to manage static website hosting and back-to-origin rules - Object Storage Service

Use the website command to manage static website hosting and back-to-origin configurations for an OSS bucket. Supported operations: add or update, query, and delete.

For background on these features, see Static website hosting overview and Back-to-origin overview.

Usage notes

For ossutil 1.6.16 and later, use ossutil as the binary name directly. For earlier versions, update the binary name based on your operating system. See ossutil command reference.
Running website --method put on a bucket that already has website configurations replaces all existing configurations.
If an object requested from OSS does not exist and no back-to-origin rules are configured, OSS returns a 404 error. Configure back-to-origin rules with a valid origin to serve the missing content from an external source.

Prerequisites

Before you begin, make sure you have:

An OSS bucket
The appropriate RAM permission for the operation you want to perform: For instructions on granting permissions, see Attach a custom policy to a RAM user.
Operation Required permission
Add or update configurations oss:PutBucketWebsite
Query configurations oss:GetBucketWebsite
Delete configurations oss:DeleteBucketWebsite

Operation	Required permission
Add or update configurations	`oss:PutBucketWebsite`
Query configurations	`oss:GetBucketWebsite`
Delete configurations	`oss:DeleteBucketWebsite`

Add or update website configurations

Running this command on a bucket with no existing configurations adds new configurations. Running it on a bucket that already has configurations replaces them entirely.

Syntax

ossutil website --method put oss://<bucket-name> <local-xml-file>

Parameter	Description
`<bucket-name>`	Name of the bucket to configure
`<local-xml-file>`	Path to a local XML file containing the website configurations

Examples

All configurations are defined in a local XML file with the root element <WebsiteConfiguration>. Start with the minimal configuration, then add routing rules as needed.

Minimal configuration — sets the index document and error document only:

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

Full configuration — includes routing rules for back-to-origin redirects. The following example defines two routing rules:

Rule 1: Mirror-based back-to-origin — when a request for an object with prefix abc/ returns a 404 error, fetch the object from http://example.com/.
Rule 2: AliCDN redirect — when a request for an object with prefix abc/ returns a 404 error and the host header matches a specific value, issue an HTTP 301 redirect via AliCDN.

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

For a full list of routing rule parameters, see Back-to-origin rules overview.

Run the following command to apply the configuration to examplebucket:

ossutil website --method put oss://examplebucket localfile.xml

Expected output:

0.299514(s) elapsed

Query website configurations

Syntax

ossutil website --method get oss://<bucket-name> [<local-xml-file>]

Parameter	Description
`<bucket-name>`	Name of the bucket to query
`<local-xml-file>`	(Optional) Path to a local file where the configurations are saved. If omitted, the configurations are printed to the terminal.

Examples

Save the configurations to a file:

ossutil website --method get oss://examplebucket localfile.xml

Expected output:

0.212407(s) elapsed

Print the configurations to the terminal:

ossutil website --method get oss://examplebucket

Expected output:

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

The GET response includes additional system-default fields (such as SupportSubDir, MirrorIsExpressTunnel, and EnableReplacePrefix) that OSS adds automatically. These fields are not required in the PUT configuration file.

Delete website configurations

Syntax

ossutil website --method delete oss://<bucket-name>

Example

ossutil website --method delete oss://examplebucket

Expected output:

0.212409(s) elapsed

Common options

To operate on a bucket in a different region or under a different Alibaba Cloud account, add the following options:

Option	Description
`-e <endpoint>`	Endpoint of the region where the bucket is located
`-i <AccessKey-ID>`	AccessKey ID of the target account
`-k <AccessKey-secret>`	AccessKey secret of the target account

Example — add configurations to testbucket in the China (Hangzhou) region under a different account:

ossutil website --method put oss://testbucket localfile.xml -e oss-cn-hangzhou.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret

For the full list of common options, see Common options.

What's next

Static website hosting overview — learn how static website hosting works and how to configure it in the console
Back-to-origin overview — understand back-to-origin rules and when to use them
Back-to-origin rules overview — full parameter reference for routing rules