Origin Path Rewrite: How it works, usage notes, and configuration examples - CDN

Alibaba Cloud CDN supports URL rewrite. A rewrite affects only the URL used for origin fetch requests and does not impact internal CDN routing or the cache key.

How it works

Origin Path Rewrite rules let you modify the request path to match the actual resource location on your origin server. This ensures that POPs can accurately retrieve resources or pass specific query strings to the origin.

If the Flag is set to None or break, only the resource path in the URL is rewritten.
If the Flag is set to enhance break, both the resource path and the query string can be rewritten.

Usage notes

You can configure up to 50 Origin Path Rewrite rules for a single domain name.
Rules are applied from top to bottom. Their order affects the final rewrite result.
When you configure Origin Path Rewrite rules, they may conflict with the Ignore Parameters feature on the Domain Names > Optimization tab. Avoid configuration conflicts.
If you configure both Origin Path Rewrite and conditional origin rules, the Origin Path Rewrite rule might alter the origin fetch URL path. This can cause the request path received by the origin server to differ from the expected path, resulting in a 404 error. To troubleshoot, temporarily disable the Origin Path Rewrite rule to see if the request works as expected. If you need to use both features, adjust your rule priorities and conditions to prevent unintentional path rewrites.

Access URL Rewrite and Origin Path Rewrite differences

Feature

Affected object

Client experience

Application scenario

Rewrite access URLs

Affects the URL that the client accesses. It also changes the URL that the DCDN node uses for origin fetches.

If the execution rule is `redirect`, the client sends a new access request using the redirected URL.
If the execution rule is `break`, the URL that the client sees is the same as the actual access URL. There is no change.

Commonly used to migrate or map URLs from an old domain name to a new one. It is also used to provide different URLs for mobile and PC clients.

Example: When a client accesses old.example.com/hello, the access URL is rewritten to new.example.com/hello.

Rewrite Origin Fetch Path

Affects the URL that the DCDN node uses for origin fetches. The URL that the client accesses does not change.

The URL that the client sees is the same as the actual access URL. There is no change.

Commonly used to hide the real URL structure of the origin server to protect its information. It is also used for URL mapping to make the DCDN node fetch content from different origin server folders.

Example: When a client accesses cdn.example.com/hello, the origin fetch URL is rewritten to origin.example.com/source/hello.

Access URL Rewrite diagram

The client sends a request to a DCDN node. The request URL is old.example.com/hello.
After the DCDN node receives the request, it applies the URL rewrite rule. The DCDN node includes the new URL, new.example.com/hello, in the Location header of the 302 response that is sent to the client.
After the client receives the 302 response, it sends a request to the new URL.
The DCDN node checks its cache. If the cache contains the content for the rewritten URL, the node returns the content directly to the client. If not, the DCDN node sends a request to the origin server using the rewritten URL, new.example.com/hello.
The origin server receives the request and returns the response content to the DCDN node.
The DCDN node caches the response content and returns it to the client.

Origin Path Rewrite diagram

The client sends a request to a DCDN node. The request URL is cdn.example.com/files/hello.txt.
After the DCDN node receives the request, it checks its cache. If the cache contains the content for the request URL, the node returns the content directly to the client. If not, the DCDN node applies the origin fetch URL rewrite rule. It rewrites the origin fetch URL to origin.example.com/secret/files/hello.txt and sends a request to the origin server.
After the origin server receives the request, it returns the response content to the DCDN node.
The DCDN node caches the response content and returns it to the client.

Configure origin path rewrite

Log on to the CDN console.
In the left navigation pane, click Domain Names.
On the Domain Names page, find the target domain name and click Manage in the Actions column.
In the left-side navigation pane for the domain name, click Origin Fetch.
Click the Origin Path Rewrite tab.

Click Add. Configure Path to Be Rewritten, Target Path, and Flag.

Parameter	Example	Description
Path to Be Rewritten	^/hello$	A URL path that starts with a forward slash (/) and does not include `http://` or a domain name. You must use a PCRE (Perl Compatible Regular Expressions) pattern.
Target Path	/hello/test	A URL path that starts with a forward slash (/) and does not include `http://` or a domain name. PCRE is supported.
Flag	None	If you configure multiple rules, after this rule is matched and executed, subsequent matching rules are also executed sequentially.
	break	If you configure multiple rules and the request URL matches this rule, no subsequent rules are evaluated. Only the resource path of the URL is modified, not the URL parameters. Therefore, this does not affect the rewriting of URL parameters by the Origin Path Rewrite feature.
	enhance break	If you configure multiple rules and the request URL matches this rule, no subsequent rules are evaluated. Similar to `break`, but this flag also rewrites the query string. This may conflict with the rewrite origin fetch parameters feature. If you use both features, ensure your configurations do not conflict.

Click OK to apply the rule.
You can also click Modify or Delete in the rule list on the Origin Path Rewrite tab to manage existing rules.

Configuration examples

Example 1: Flag set to None

Path to Be Rewritten	^/hello$
Target Path	/index.html
Flag	None
Result	Original request: `http://example.com/hello` Origin fetch request after rewrite: `http://example.com/index.html` The request is then matched against subsequent rules in the Origin Path Rewrite list.

Example 2: Flag set to break

Path to Be Rewritten	^/hello.jpg$
Target Path	/image/hello.jpg
Flag	break
Result	Original request: `http://example.com/hello.jpg` Origin fetch request after rewrite: `http://example.com/image/hello.jpg` No subsequent rules in the Origin Path Rewrite list are evaluated.

Example 3: Flag set to enhance break

Path to Be Rewritten	^/hello.jpg?code=123$
Target Path	/image/hello.jpg?code=321
Flag	enhance break
Result	Original request: `http://example.com/hello.jpg?code=123` Origin fetch request after rewrite: `http://example.com/image/hello.jpg?code=321` No subsequent rules in the Origin Path Rewrite list are evaluated.

Example 4: Prefixing variable paths in the root directory

For example, you can rewrite a URL path like /xxx, where xxx is a variable filename (e.g., /hello.jpg or /hello.html), to /image/xxx. This inserts the /image prefix into the path for any file in the root directory.

Path to Be Rewritten	^(.)$ Note* `^` matches the start of the string. `(.)` is a capturing group, where `.` matches any single character except for a newline character, and `` matches the preceding character or group zero or more times. You can use $1 in the Target Path to reference the content captured by this group. `$` matches the end of the string. Therefore, `^(.)$` matches the entire string from start to end and captures all characters, except for newline characters, into a group. For example, for the string `"hello world"`, `^(.)$` matches the entire string and captures `"hello world"` into the first group.
Target Path	/image$1 Note `/image` matches the string `"/image"`. `$1` references the content of the first capture group, `$2` references the content of the second capture group, and so on. Therefore, `/image$1` means that the string `"/image"` is immediately followed by the content of the first capture group. For example, if the content of the first capture group is `"abc"`, `/image$1` matches the string `"/imageabc"`. Note that `$1` references the content of the capture group, not the literal string `"$1"`. To match the literal string `"$1"`, you must use an escape character, such as `"\$1"`.
Flag	break
Result	Original request: `http://example.com/hello.jpg` Origin fetch request after rewrite: `http://example.com/image/hello.jpg` Original request: `http://example.com/hello.html` Origin fetch request after rewrite: `http://example.com/image/hello.html` No subsequent rules in the Origin Path Rewrite list are evaluated.

Example 5: Prefixing paths under a specific directory

For example, you can rewrite a URL that contains /live/xxx, where xxx represents any filename (e.g., hello.jpg or hello.html), to /image/live/xxx. This inserts the /image prefix into the path for any file under the /live directory.

Path to Be Rewritten	^/live/(.*)$
Target Path	/image/live/$1
Flag	break
Result	Original request: `http://example.com/live/hello.jpg` Origin fetch request after rewrite: `http://example.com/image/live/hello.jpg` Original request: `http://example.com/live/hello.html` Origin fetch request after rewrite: `http://example.com/image/live/hello.html` No subsequent rules in the Origin Path Rewrite list are evaluated.

Example 6: Chaining rules with the None flag
Consider two enabled rewrite rules. Rule 1 rewrites ^/image_01.png$ to /image_02.png with the Flag set to None. Rule 2 rewrites ^(.*)$ to /image$1 with the Flag set to None.
Result:
- Original request: http://example.com/image_01.png
- Origin fetch request after rewrite: http://example.com/image/image_02.png
  Note
  The request first matches Rule 1 and is rewritten to http://example.com/image_02.png. Because the Flag is set to None, the rewritten path is then evaluated against Rule 2, which also matches. The path is rewritten a second time, resulting in the final path: http://example.com/image/image_02.png.
Example 7: Halting rule evaluation with break
Consider two enabled rewrite rules. Rule 1 rewrites ^/image_01.png$ to /image_02.png with the Flag set to break. Rule 2 rewrites ^(.*)$ to /image$1 with the Flag set to None. When a request matches Rule 1, processing stops, and subsequent rules are not evaluated because the Flag is set to break.
Result:
- Original request: http://example.com/image_01.png
- Origin fetch request after rewrite: http://example.com/image_02.png
  Note
  The request first matches Rule 1 and is rewritten to http://example.com/image_02.png. Because the Flag for Rule 1 is set to break, processing stops and no subsequent rules are evaluated.