Use put-bucket-referer to configure hotlink protection - Object Storage Service

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

Usage notes

By default, an Alibaba Cloud account has permission to configure a Referer whitelist or blacklist. To run this command as a RAM user or Security Token Service (STS) user, 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.

This command corresponds to the PutBucketReferer API operation. For the full list of request parameters, see PutBucketReferer. For supported global flags, see Global command-line options.

--referer-configuration

Pass the configuration as an XML or JSON string, or as a file path prefixed with file://. When you use file://, ossutil reads the configuration from the specified file.

The configuration supports the following fields:

Field	Parent element	Type	Description
`AllowEmptyReferer`	`RefererConfiguration`	boolean	Whether to allow requests with an empty Referer field. Set to `true` to allow or `false` to deny.
`AllowTruncateQueryString`	`RefererConfiguration`	boolean	Whether to truncate the query string before matching the URL against the Referer list.
`TruncatePath`	`RefererConfiguration`	boolean	Whether to truncate the URL path before matching against the Referer list.
`Referer`	`RefererList`	string	A Referer value to allow (whitelist entry). Supports `*` and `?` wildcards. Multiple entries are allowed.
`Referer`	`RefererBlacklist`	string	A Referer value to deny (blacklist entry). Supports `*` and `?` wildcards. Multiple entries are allowed.

XML format

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

JSON format

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

Examples

The following examples configure a Referer whitelist and blacklist for a bucket named examplebucket. The configuration:

Blocks requests with an empty Referer field (AllowEmptyReferer: false)
Truncates query strings and URL paths before matching (AllowTruncateQueryString: true, TruncatePath: true)

Use an XML configuration file

referer-configuration.xml

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

Command

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

Use a JSON configuration file

referer-configuration.json

{
    "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"
        ]
    }
}

Command

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

Pass the configuration inline as a JSON string

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\"]}}"