Docs

Torch Object Storage

Back-to-origin rules

Configuring redirection rules

When you set up a redirect-based back-to-origin (redirection) rule and the requested object does not exist in the bucket, TOS returns a redirect address to the requester. The requester can then use this address to access the object or its metadata. This topic explains how to configure redirection rules.

Background information

A redirection action can be triggered by one of the following two operations:

Triggering via GetObject: When the requested object does not exist in the bucket, TOS returns a redirect address to the requester. The requester can then use this address to access the object.

Triggering via HeadObject: When the metadata of the requested object does not exist in the bucket, TOS returns a redirect address to the requester. The requester can then use this address to obtain the metadata.

Notes

Scenario	Category	Description
Triggering via GetObject	Object size	The requested object can be up to 300 GiB in size.
Triggering via GetObject		Back-to-origin condition	A redirection action is only triggered when the GetObject request results in an HTTP status code of 404.
Triggering via HeadObject	Restrictions	You cannot retrieve objects that are symlinks via HeadObject requests. When you retrieve object metadata via HeadObject requests, the option Whether to pull file from the origin server becomes invalid. In this scenario, fetching objects from the origin server and writing them to TOS is not supported.
Triggering via HeadObject		Back-to-origin condition	A redirection action is only triggered when the option Whether to support HeadObject is enabled for the redirection rule and the HeadObject request results in an HTTP status code of 404.

Steps

In the left navigation pane, click Buckets. In the Buckets list, click the bucket you want to manage.

In the left navigation pane, select Basic configurations > Back-to-Origin rules. On the Back-to-Origin rules page, click Create rule.

On the Create Back-to-Origin Rule page, configure the following parameters:

Parameter	Description
Back-to-Origin method	Select Redirection.
Back-to-Origin condition	Configure the desired trigger conditions. A redirection action will only be triggered when all configured conditions are met simultaneously. The fields are described as follows: HTTP Status Code: Selected by default and only supports HTTP status code 404. Filename prefix: Select this option and enter the desired prefix. Filename suffix: Select this option and enter the desired suffix. tip For example, if you set the filename prefix to test and the filename suffix to object.png, and then you attempt to access an object in the bucket that matches the pattern test***object.png, the object does not exist in the bucket and an HTTP 404 status code is returned. In this case, TOS provides the back-to-origin address configured in the rule, allowing you to access the object. After checking the box(es) for Filename prefix or/and Filename suffix, you must enter the corresponding information for the condition to take effect. If you leave the field(s) blank, the condition will not be matched. To match all suffixes under a specific prefix, enable only the Filename prefix condition. Alternatively, enable the Filename suffix condition without entering a value.
Specify the domain	Specify which domain names are allowed to access the origin server. Accessing the origin server via any other domain name will not trigger redirection actions. warning You can specify a maximum of 20 domain names. The domain names must be accessible to the bucket. We recommend using the custom domain associated with the bucket.
Back-to-Origin type	Set the origin server type for back-to-origin. The fields are described as follows: Select back to source private bucket if the origin server is a private bucket from TOS or another cloud provider. Do not select back to source private bucket if the origin server is a public bucket from TOS or another cloud provider.
Back-to-Origin address	Configure the address to which TOS will redirect when the back-to-origin conditions are met. There are three configuration options: Add prefix and suffix, Redirect to fixed address, and Replace filename prefix. Common configuration items (applicable to all three options) Protocol (Required): The options are http and https. The default is https. Domain name (Required): It must be in domain format. IP addresses are not supported. Add prefix and suffix When the back-to-origin rule is triggered, the request is redirected to an object to which a prefix and/or suffix has been added. Prefix/Suffix (Optional): If configured, this prefix or suffix is added to the object name for the request sent to the origin server. The object name returned to the client is unaffected by the prefix and remains unchanged. For example, if a client requests the object aaa.txt and the prefix is set to bbb, the requested object from the origin server will be bbbaaa.txt. However, the object returned to the client will still be aaa.txt. Redirect to fixed address When the back-to-origin rule is triggered, all requests are redirected to a fixed file address. Replace filename prefix When the back-to-origin rule is triggered, the request is redirected to an object with the filename prefix replaced. Prefix (Optional): To replace a prefix, first specify the Filename prefix in the Back-to-Origin condition section. Then, the new prefix will replace the specified filename prefix. Replacing a prefix is typically considered truncation. However, if you do not specify a prefix before replacing it, filling in this field is the same as adding a prefix. The object name returned to the client is unaffected by the prefix and remains unchanged. For example, if a client requests the object aaa.txt, and the Filename prefix in the Back-to-Origin condition section is set to aa and the Prefix is set to bb, the requested object from the origin server will be bba.txt. However, the client will still receive aaa.txt. tip You can add only one redirect address. If you select Redirect to fixed address, TOS will not fetch objects. After completing the settings, refer to the File Obtaining Address from Origin Server section below Back-to-Origin address to verify that the address is configured correctly. If you select "back to source private bucket" as the Back-to-Origin type, you must enter the service provider information for your source bucket in the Back-to-Origin address section. The fields are described as follows: If the service provider is Volcano Engine, click Click to Authorize to grant TOS access to your private bucket. Then, select the source bucket, which must be a bucket under the current account. When the service provider is Baidu Cloud or Other S3 storage protocols, fill in the AccessKey (AK), SecretKey (SK), Source Region, Source bucket, and Back-to-Origin address to access the service provider.
Whether to support HeadObject	Select whether to trigger redirection actions via HeadObject requests. This option is disabled by default. Disabled (Default): Only GetObject requests can trigger redirection actions. Enabled: Both GetObject and HeadObject requests can trigger redirection actions.
Whether to carry request parameter for back-to-origin	Select whether to forward the query string from the request to the origin server. This option is enabled by default. warning Enabling this option will only transmit parameters defined by AWS Signature Version 4 if your origin server is a private bucket. Note that this feature does not support forwarding all query string parameters from the request.
Whether to pull file from the origin server	When enabled, TOS first redirects to the origin server address, then fetches the object asynchronously in the background and writes it to TOS. This option is enabled by default. warning The option Whether to pull file from the origin server only applies to scenarios where the redirection action is triggered by a GetObject request. This option is invalid when the redirection action is triggered by a HeadObject request.
Whether to carry request parameter for file pull	Select whether to forward the query string from the request to the origin server. This option is disabled by default.
Whether to redirect based on the origin server for async pull	Select whether to redirect the request based on the 3XX status code of the origin server. A request can only be redirected three times. This option is disabled by default.
HTTP Header Delivery Rules (client side to source)	Select the rule for passing response headers when TOS accesses the specified origin server. The options are as follows: Transparently Transmit All HTTP Headers (Default): When selected, all parameters are passed through, except Host, Content-Length, Date, and Authorization. Transparently Transmit Specified HTTP Headers: Define the specific headers that are allowed to be passed through. You can add a maximum of 10 headers. Transparently Transmit No HTTP Headers: When selected, all parameters are blocked from being passed through. Not Transparently Transmit Specified HTTP Headers: Define the specific headers prohibited from being passed through. You can add a maximum of 10 headers.
Add specified HTTP headers (client side to source)	Specify the key and value for the HTTP header. This key and value will then be added to the header and passed through to the origin server. warning You can specify a maximum of 10 HTTP headers. Content-Length, Date, Range, and Authorization are not supported.
Support custom metadata	When fetching an object from a specified origin server, you can save the response headers (SourceHeader) from the origin as custom metadata for the object. TOS automatically prefixes the metadata key with x-tos-meta- and appends the suffix you set (MetaDataSuffix), forming the final metadata key. Click Add metadata and configure the following: Enter the origin response header (SourceHeader) in the left input box. Enter the metadata key suffix (MetaDataSuffix) in the right input box. You can add or remove multiple mapping groups. Each rule supports up to ten mappings. For example, if SourceHeader is content-language and MetaDataSuffix is language, the final metadata key is x-tos-meta-language.

Click Submit.

After creating a redirection rule, you can view it in the rules list.

Other operations

Edit a back-to-origin rule: Click Edit in the Actions column of the rule you want to modify.

Delete a back-to-origin rule: Click Delete in the Actions column of the rule you want to remove, and confirm the deletion by clicking Delete in the box that appears.

Move a back-to-origin rule up/down: In the Actions column of the rule you want to move, click ... > Up or ... > Down.

Last updated: 2026.08.04 18:26:47