All Products
Search
Document Center

Object Storage Service:referer

Last Updated:Dec 20, 2023

You can configure hotlink protection for an Object Storage Service (OSS) bucket to prevent unauthorized access to your resources in the bucket. This topic describes how to run the referer command to configure hotlink protection for a bucket, or modify, query, or delete the hotlink protection configurations of 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 Get started with ossutil.

  • For more information about hotlink protection, see Hotlink protection.

Configure hotlink protection for a bucket or modify the hotlink protection configurations of a bucket

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

You can run the following command to configure hotlink protection for a bucket or modify the hotlink protection configurations of a bucket:

  • Command syntax

    ./ossutil64 referer --method put oss://bucketname refererconfig [--disable-empty-referer]

    The following table describes the parameters in the preceding command.

    Parameter

    Description

    bucketname

    The name of the bucket for which you want to configure hotlink protection or whose hotlink protection configurations you want to modify.

    refererconfig

    The domain names or IP addresses that you want to add to the Referer whitelist. You can use asterisks (*) and question marks (?) as wildcard characters. Separate multiple Referers with spaces. Examples:

    • If you add http://www.aliyun.com to the Referer whitelist, URLs that start with http://www.aliyun.com, such as http://www.aliyun.com/123 and http://www.aliyun.com.cn, can be matched.

    • If you add *www.aliyun.com/ to the Referer whitelist, URLs that contain www.aliyun.com, such as http://www.aliyun.com and https://www.aliyun.com, can be matched.

    • You can use an asterisk (*) as a wildcard character to specify zero or multiple characters. For example, if you add *.aliyun.com to the Referer whitelist, URLs such as https://help.aliyun.com and https://www.aliyun.com can be matched.

    • You can use a question mark (?) as a wildcard character to specify a character.

    • You can add domain names or IP addresses that include a port number, such as https://www.example.com:8080 and https://10.0.0.0:8080, to the Referer whitelist.

    --disable-empty-referer

    Specifies whether empty Referer is allowed.

    • If you do not specify this parameter, empty Referers are allowed. HTTP or HTTPS requests that include the empty Referer field or no Referer field are allowed.

    • If you specify this parameter, empty Referers are not allowed. Only HTTP or HTTPS requests that include the Referer field with a valid value can access the bucket.

  • Examples

    Configure hotlink protection for the examplebucket bucket. Only requests sent from URLs that contain www.aliyun.com are allowed to access data in the examplebucket bucket. You cannot access data in the examplebucket bucket by entering the URLs in a browser.

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

    Configure hotlink protection for the examplebucket bucket. Only requests sent from URLs that contain www.aliyun.com are allowed to access data in the examplebucket bucket. You can also access data in the examplebucket bucket by entering the URLs in a browser.

    ./ossutil64 referer --method put oss://examplebucket http://www.aliyun.com https://www.aliyun.com

    If a similar output is displayed, hotlink protection is configured for the bucket.

    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 in the preceding command.

    Parameter

    Description

    bucketname

    The name of the bucket whose hotlink protection configurations you want to query.

    local_xml_file

    The name of the local file that stores the hotlink protection configurations of the bucket. Example: localfile.txt. If this parameter is not specified, the hotlink protection configurations are displayed.

  • Examples

    • Query the hotlink protection configurations of the examplebucket bucket and store the hotlink protection configurations in the localfile.txt 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
    • Query the hotlink protection configurations of the examplebucket bucket and display the hotlink protection configurations.

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

      If a similar output is displayed, only HTTP or HTTPS requests whose headers match *www.aliyun.com are allowed to access the examplebucket bucket, and empty Referers are not allowed.

      <?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 whose hotlink protection configurations you want to delete.

  • Examples

    Delete the hotlink protection configurations of 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

If you use ossutil to switch to a bucket that is located in another region, add the -e option to the command to specify the endpoint of the region in which the specified bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, you can add the -i option to the command to specify the AccessKey ID of the specified account, and add the -k option to the command to specify the AccessKey secret of the specified account.

The following command provides an example on how to configure hotlink protection for the testbucket bucket of 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 sync command, see View options.