Tenant Cloud Storage Cloud Object Storage Console Guide

Setting Origin-Pull

Last Updated At: 2025-10-16 09:15:14

Overview

You can set origin-pull rules for buckets in the COS console. When the object you request does not exist in the bucket or a specific request needs to be redirected, you can use the origin-pull rules to access the corresponding data from COS. Setting the origin-pull is mainly used for scenes such as hot migration of data and redirection of specific requests. You can set it according to your actual needs.

Description

  • Buckets in the Financial Cloud region do not support origin-pull settings.

Origin-Pull Rules

Trigger Condition

  • In asynchronous and synchronous origin-pull modes, origin-pull is triggered only when the request returns a 404 error.
  • In redirection mode, users can customize HTTP status codes from 400 to 599 to trigger origin-pull.

Accessing Origin Server

  • In asynchronous and synchronous origin-pull modes, you can set whether to pass through the QueryString and Header information of accessing COS to the origin server and whether to carry additional Header information when adding a request to the origin server. The redirection mode only supports setting whether the QueryString is passed through.
  • If the GET range is specified in the GET operation, COS will send an asynchronous request without range in addition to the original request to obtain the complete object data and store it in COS.

Response and Storage

  • Support the origin server in returning data in chunked encode.

  • If the origin server returns a 404 status code, it will be passed through to COS and returned to the user. If 3XX Following Policy is enabled when the origin server returns a 3XX status code, it will pull data from another source server. If the origin server returns a status code other than 2XX, COS will return 424.

  • The files returned from the origin-pull are stored in COS with the same file name as used when requesting the origin server. For example, if the file example.jpg requested by a user is not in the storage bucket, COS will trigger the origin-pull mechanism to the origin-pull address http://origin.com/example.jpg set by the user to pull the file and name it example.jpg in the bucket.

  • New objects stored in COS contain the following metadata, with the data content following the origin server values:

    cache-control
content-disposition
content-encoding
content-type
expires
x-cos-meta-*

Directions

  1. Log in to the COS bucket console.

  2. In the left sidebar, click Bucket List to enter the bucket list page.

  3. Click the name of the bucket for which you want to set origin-pull to go to the bucket details page.

  4. In the left sidebar, select Basic Configuration > Origin-pull Settings and click Add an Origin-Pull Rule.

  5. Configure the following information in the pop-up.

    • Origin-pull Endpoint: Supports filling in domain or IP address. The correct example address is as follows:
    abc.example.com
abc.example.com:8080
202.96.128.86
202.96.128.86:8080

    • Backup origin-pull Endpoint: Supports setting the backup origin-pull address. The input format can refer to the configuration items description of Origin-pull Endpoint.

    • Origin-pull mode: You can choose the origin-pull mode according to your actual needs.

      • Synchronous origin-pull: When a request is made to find a file in COS, and it does not exist, COS will search for the file from the specified origin server, return the file to the user, and upload it to the bucket.
      • Redirection: When a specified error is reported when requesting access to a bucket, COS will return the redirection address to the user and will not save the origin server's files. The user side requests access to resources from the origin server through the redirection address.

    • Origin-pull conditions: You can select the conditions to trigger the origin-pull as required. Triggering the origin-pull requires all configured origin-pull conditions to be met at the same time.

      • HTTP status code 404: When asynchronous or synchronous origin-pull is selected, origin-pull is triggered when the HTTP status code is 404. This option is required and cannot be canceled. When you select the redirection origin-pull mode, you can enter an HTTP status code from 400 to 599.
      • File name prefix: When the requested file name prefix matches, the origin-pull rules can be triggered. For example, if you set the file name prefix to prefix, then visit https://examplebucket-1250000000.cos.city.yfm4.fsphere.cn/prefix123.jpg, and when the returned HTTP status code is 404, the origin-pull rules are triggered.

    • Origin-pull protocol: The HTTP protocol used by COS to access the origin server you specify. The options are Force HTTPS, Force HTTP, and Follow Request Protocol.

      • If you select Force HTTPS/HTTP, COS will access your origin server using the HTTPS/HTTP protocol.
      • If you select Follow Request Protocol, COS will access your origin server using the protocol you requested COS to use.

    • Request parameter: Whether to pass through the queryString request parameters carried when accessing COS to the origin server.

    • Request header: You can choose to pass through all request headers or pass through specified request headers. If you choose to pass through all request headers, it is recommended that you configure it to prohibit pass-through of the host header. One-click configuration is supported here.

    • Pass through specified request headers: When selecting pass through specified request header, you need to set this item. Here, you can add the header information that you want to be passed through to the origin server. If you select the redirection origin-pull type, do not set this item.

    • Prohibit pass through specified request headers: Here you can add header information in the request that you do not want to be passed through to the origin server. If you select the redirection origin-pull type, do not set this item.

    • Add request headers: You can add additional request headers when origin-pull to the origin server. If you select the redirection origin-pull type, do not set this item.

    • Origin-pull path: You can choose whether to set a specific file or file path to jump to. The configuration items are described as follows:

      • Specify file: When the origin-pull rule is triggered, all will jump to a fixed file.
      • Specify prefix/specify suffix: When the origin-pull rule is triggered, it will be redirected to the file path with the specified prefix and suffix. For example, if test is specified as the prefix, visiting https://examplebucket-1250000000.cos.city.yfm4.fsphere.cn/path/prefix123.jpg will trigger the origin-pull rule, and the page will be redirected to <origin-pull address>/test/path/prefix123.jpg; For example, if .jpg is specified as the suffix, visiting https://examplebucket-1250000000.cos.city.yfm4.fsphere.cn/path/prefix123 will trigger the origin-pull rule, and the page will be redirected to <origin-pull address>/path/prefix123.jpg;

      Note

      The configurations of specifying a prefix and specifying a suffix can take effect at the same time.

  • 3xx following policy: Synchronous origin-pull mode is visible. After it is enabled, when the origin server returns a 3XX redirection status code, COS's default processing policy is to follow 3XX and pull data from another source server again. If you select Disable, no resources will be pulled.
  • Redirect Code: Redirection mode is visible. 301, 302, 307 are optional.
  • Rule priority: The order of rule execution is determined by priority. Higher priority rules are matched first. Priorities must be unique.
  1. Confirm that the configured origin-pull rules are correct and click OK.
    After you add the rules, the system will assign the highest priority to your new rule; COS will origin-pull according to the highest priority rule; in addition, you can also click the modify button on the rule list page to adjust the priority.

Example

Background
The user with APPID 1250000000 creates a bucket named examplebucket-1250000000 and enables CDN to accelerate access to the domain:

examplebucket-1250000000.cos.city.yfm4.fsphere.cn

Set the bucket origin-pull address to:

abc.example.com

Store the picture picture.jpg at the origin server http://abc.example.com.
Client's first visit (with synchronous origin-pull disabled):

http://examplebucket-1250000000.cos.city.yfm4.fsphere.cn/picture.jpg

When COS finds that it cannot hit the object, it returns a 302 HTTP status code to the client and redirects to the following address:

http://abc.example.com/picture.jpg

Client's first visit (with synchronous origin-pull enabled):

http://examplebucket-1250000000.cos.city.yfm4.fsphere.cn/picture.jpg

When COS finds that it cannot hit the object, it returns a 200 HTTP status code to the client and redirects to the following address:

http://abc.example.com/picture.jpg

At this point, the object is provided to the client by the origin server to ensure access. At the same time, COS copies picture.jpg from the origin server and saves it to the root directory of the bucket example.
Second visit:

http://examplebucket-1250000000.cos.city.yfm4.fsphere.cn/picture.jpg

COS directly hits the picture.jpg object in the root directory and returns it to the client.