Object Storage Service (OSS) allows you to configure a Referer whitelist for a bucket to prevent your resources in the bucket from unauthorized access. This topic describes how to run the referer command to add, modify, query, or delete hotlink protection configurations for a bucket.

Note
  • 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.
  • For more information about hotlink protection, see Configure hotlink protection in OSS Developer Guide.

Add or modify hotlink protection configurations for a bucket

If hotlink protection is not configured for a bucket, you can run this command to add hotlink protection configurations for the bucket. If hotlink protection is configured for a bucket, the existing hotlink protection configurations for the bucket are overwritten when you run this command.

You can refer to the following command format and examples to add or modify hotlink protection configurations for a bucket:

  • Command syntax
    ./ossutil referer --method put oss://bucketname refererconfig [--disable-empty-referer]

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

    Parameter Description
    bucketname The name of the bucket for which you want to add or modify hotlink protection configurations.
    refererconfig Specifies the domain name or IP address of the origins from which you want to allow requests. Asterisks (*) and question marks (?) are supported as wildcards. Separate multiple Referer configurations with spaces. The following examples show how to configure domain names and IP addresses:
    • If you add www.aliyun.com to the Referer whitelist, requests sent from URLs that start with www.aliyun.com, such as www.aliyun.com/123 and www.aliyun.com.cn are allowed.
    • If you add *www.aliyun.com/ to the Referer whitelist, requests sent from http://www.aliyun.com/ and https://www.aliyun.com/ are allowed.
    • You can use an asterisk (*) as a wildcard to indicate zero or more characters. For example, if you add *.aliyun.com to the Referer whitelist, requests sent from URLs such as help.aliyun.com and www.aliyun.com are allowed.
    • You can use a question mark (?) as a wildcard to indicate a single character.
    • You can add domain names or IP addresses that include a port number, such as www.example.com:8080 and 10.0.0.0:8080, to the Referer whitelist.
    --disable-empty-referer Specifies whether empty Referer is allowed:
    • If you do not add this parameter, the Referer field is allowed to be empty. HTTP or HTTPS requests that contain an empty Referer field or no Referer field are allowed.
    • If you add this parameter, the Referer field is not allowed to be empty. Only HTTP or HTTPS requests that include the Referer field can access the bucket.
  • Examples

    Configure hotlink protection for a bucket named examplebucket. Only HTTP or HTTPS requests that contain *www.aliyun.com in their headers are allowed to access the examplebucket bucket, and the Referer field cannot be empty.

    ./ossutil64 referer --method put oss://examplebucket *www.aliyun.com --disable-empty-referer

    Configure hotlink protection for the bucket named examplebucket. Only HTTP or HTTPS requests that contain www.baidu.com and www.google.com in their headers are allowed to access the examplebucket bucket, and the Referer field is allowed to be empty.

    ./ossutil64 referer --method put oss://examplebucket www.baidu.com  www.google.com

    If a similar output is displayed, hotlink protection configurations are added:

    0.134839(s) elapsed

Query the hotlink protection configurations of a bucket

  • Command syntax
    ./ossutil64 referer --method get oss://bucketname [local_xml_file]

    The following table describes the parameters that you can configure when you run this command to query the hotlink protection configurations of a bucket.

    Parameter Description
    bucketname The name of the bucket of which the hotlink protection configurations you want to query.
    local_xml_file The name of the local file used to store the hotlink protection configurations. Example: localfile.txt. If this parameter is not specified, obtained hotlink protection configurations are displayed without being stored in a local file.
  • Examples
    • Obtain the hotlink protection configurations of the examplebucket bucket and write the obtained configurations to the localfile.txt local file.
      ./ossutil64 referer --method get oss://examplebucket localfile.txt

      If a similar output is displayed, the hotlink protection configurations are obtained:

      0.212407(s) elapsed
    • Obtain the hotlink protection configurations of the examplebucket bucket and display the configuration result without storing the result in a local file.
      ./ossutil64 referer --method get oss://examplebucket

      If a similar output is displayed, only requests that contain *www.aliyun.com in the HTTP or HTTPS headers are allowed to access the examplebucket bucket based on the hotlink protection configurations of the examplebucket bucket, and Referer must not be empty:

      <?xml version="1.0" encoding="UTF-8"?>
        <RefererConfiguration>
            <AllowEmptyReferer>false</AllowEmptyReferer>
            <RefererList>
                <Referer>*www.aliyun.com</Referer>
            </RefererList>
        </RefererConfiguration>
      
      
      0.080482(s) elapsed

Delete the hotlink protection configurations of a bucket

  • Command syntax
    ./ossutil64 referer --method delete oss://bucketname

    bucketname specifies the name of the bucket of which the hotlink protection configurations are to be deleted.

  • Examples

    Delete the hotlink protection configurations for the examplebucket bucket.

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

    If a similar output is displayed, the hotlink protection configurations of 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 multiple 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.

The following command provides an example on how to configure hotlink protection for the testbucket bucket owned by another Alibaba Cloud account in the China (Hangzhou) region:

./ossutil64 referer --method put oss://testbucket www.alibabacloud.com -e oss-cn-hangzhou.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

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