Run the referrer command to configure hotlink protection - Object Storage Service

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

To create or modify hotlink protection configurations, you must have the oss:PutBucketReferer permission. To query hotlink protection configurations, you must have the oss:GetBucketReferer permission. To delete hotlink protection configurations, you must have the oss:DeleteBucketReferer permission. For more information, see Attach a custom policy to a RAM user.

This topic provides sample command lines that 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 command reference.
For more information about hotlink protection, see Hotlink protection.

Create or modify hotlink protection configurations

If hotlink protection is not configured for a bucket, you can run the following referer command to configure hotlink protection for the bucket. If hotlink protection is configured for a bucket, you can run the following referer command to overwrite the existing hotlink protection configurations of the bucket.

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 and options in the syntax.

Parameter/Option	Description
bucketname	The name of the bucket for which you want to create or modify hotlink protection configurations.
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 represent 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 represent 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 to allow requests with an empty Referer field. If you do not specify this parameter, requests with an empty Referer field are allowed. HTTP or HTTPS requests that include the empty Referer field or do not include the Referer field are allowed. If you specify this parameter, requests with an empty Referer field 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 to allow access to objects in the bucket from URLs that contain www.aliyun.com and to deny access to objects in the examplebucket bucket by entering objects URLs in the address bar of 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 to allow access to objects in the bucket from URLs that contain www.aliyun.com and by entering objects URLs in the address bar of a browser.
```
./ossutil64 referer --method put oss://examplebucket http://www.aliyun.com https://www.aliyun.com
```
The following sample output indicates 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 syntax.

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 in which you want to store the hotlink protection configurations of the bucket. Example: `localfile.txt`. If this parameter is not specified, the hotlink protection configurations are displayed to the screen.

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
```
  The following sample output indicates that 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
```
  The following sample output indicates that only HTTP or HTTPS requests whose Referer headers match *www.aliyun.com are allowed to access the examplebucket bucket, and requests with an empty Referer field 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
```
In the syntax, 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
```
The following sample output indicates that 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, 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 that is located in the China (Hangzhou) region and owned by another Alibaba Cloud account:

./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 Common options.