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, as well as to modify, query, and delete the hotlink protection configurations.

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.

For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you need to update the binary name based on the operating system. 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, the following referer command configures hotlink protection for the bucket. If hotlink protection is configured for a bucket, the following referer command overwrites 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

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

The following table describes the parameters and options in the command 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. If you specify multiple Referers, separate them 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 are followed by port numbers, 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 the www.aliyun.com domain to reference objects in the bucket and to deny access to objects in the examplebucket bucket by entering object URLs in the address bar of a browser.
```
ossutil 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 the www.aliyun.com domain to reference objects in the bucket and to permit object access by entering object URLs in the address bar of a browser.
```
ossutil referer --method put oss://examplebucket http://www.aliyun.com https://www.aliyun.com
```
The following sample output indicates that hotlink protection is configured for the bucket:
```
0.134839(s) elapsed
```

Query the hotlink protection configurations of a bucket

Command syntax

ossutil 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 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.
```
ossutil 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.
```
ossutil 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 that 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
```
ossutil 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.
```
ossutil 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 specify the endpoint of the region in which the bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to specify the AccessKey ID of the specified account, and add the -k option 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:

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

For more information about common options, see Common options.