referer - Object Storage Service - Alibaba Cloud Documentation Center

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

./ossutil64 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 example.aliyundoc.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 example.aliyundoc.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

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