Configure a Referer whitelist or blacklist for an OSS bucket. - Object Storage Service

Configures a Referer whitelist or blacklist for an Object Storage Service (OSS) bucket. You can specify whether to allow a request whose Referer field is empty and whether to truncate the query string in the URL.

Usage notes

By default, an Alibaba Cloud account has the permissions to configure a Referer whitelist or blacklist for an OSS bucket. To configure a Referer whitelist or blacklist for an OSS bucket by using a RAM user or Security Token Service (STS), you must have the oss:PutBucketReferer permission. For more information, see Attach a custom policy to a RAM user.

Command syntax

ossutil api put-bucket-referer --bucket value --referer-configuration value [flags]

Parameter	Type	Description
--bucket	string	The name of the bucket.
--referer-configuration	string	The container that stores the hotlink protection configurations.

Note

The put-bucket-referer command corresponds to the PutBucketReferer operation. For more information about the parameters in the PutBucketReferer operation, see PutBucketReferer.

--referer-configuration

The --referer-configuration option supports both the XML and JSON formats. If the value of the option contains the file:// prefix, ossutil reads configurations from a configuration file.

XML format:

<RefererConfiguration>
  <TruncatePath>boolean</TruncatePath>
  <RefererList>
    <Referer>string</Referer>
  </RefererList>
  <RefererBlacklist>
    <Referer>string</Referer>
  </RefererBlacklist>
  <AllowEmptyReferer>boolean</AllowEmptyReferer>
  <AllowTruncateQueryString>boolean</AllowTruncateQueryString>
</RefererConfiguration>

JSON format:

{
  "AllowEmptyReferer": boolean,
  "AllowTruncateQueryString": boolean,
  "TruncatePath": boolean,
  "RefererList": {
    "Referer": ["string", ...]
  },
  "RefererBlacklist": {
    "Referer": ["string", ...]
  }
}

Note

For more information about supported global command-line options, see Global command-line options.

Examples

The following examples shows how to configure a Referer whitelist or blacklist for a bucket named examplebucket:

Create a configuration file named referer-configuration.xml and add the following code to the configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<RefererConfiguration>
    <AllowEmptyReferer>false</AllowEmptyReferer>
    <AllowTruncateQueryString>true</AllowTruncateQueryString>
    <TruncatePath>true</TruncatePath>
    <RefererList>
        <Referer>http://www.aliyun.com</Referer>
        <Referer>https://www.aliyun.com</Referer>
        <Referer>http://www.*.com</Referer>
        <Referer>https://www.?.aliyuncs.com</Referer>
    </RefererList>
    <RefererBlacklist>
        <Referer>http://www.refuse.com</Referer>
        <Referer>https://*.hack.com</Referer>
        <Referer>http://ban.*.com</Referer>
        <Referer>https://www.?.deny.com</Referer>
    </RefererBlacklist>
</RefererConfiguration>

Sample command:

ossutil api put-bucket-referer --bucket examplebucket --referer-configuration file://referer-configuration.xml

Create a configuration file named referer-configuration.json and add the following code to the configuration file:

{
    "AllowEmptyReferer": "false",
    "AllowTruncateQueryString": "true",
    "TruncatePath": "true",
    "RefererList": {
        "Referer": [
            "http://www.aliyun.com",
            "https://www.aliyun.com",
            "http://www.*.com",
            "https://www.?.aliyuncs.com"
        ]
    },
    "RefererBlacklist": {
        "Referer": [
            "http://www.refuse.com",
            "https://*.hack.com",
            "http://ban.*.com",
            "https://www.?.deny.com"
        ]
    }
}

Sample command:

ossutil api put-bucket-referer --bucket examplebucket --referer-configuration file://referer-configuration.json

Configure parameters in the following command in the JSON format:

ossutil api put-bucket-referer --bucket examplebucket --referer-configuration "{\"AllowEmptyReferer\":\"false\",\"AllowTruncateQueryString\":\"true\",\"TruncatePath\":\"true\",\"RefererList\":{\"Referer\":[\"http://www.aliyun.com\",\"https://www.aliyun.com\",\"http://www.*.com\",\"https://www.?.aliyuncs.com\"]},\"RefererBlacklist\":{\"Referer\":[\"http://www.refuse.com\",\"https://*.hack.com\",\"http://ban.*.com\",\"https://www.?.deny.com\"]}}"