The rules engine provides a graphical user interface to configure conditional rules. These rules analyze user request parameters to determine if a specific configuration applies, giving you flexible and precise control over the application of CDN configuration policies.
Background
The Alibaba Cloud CDN console provides basic features, such as configuring cache expiration times and back-to-origin parameter rewrites, to meet most common needs. For special requirements, such as routing requests that contain the path /example to a specific origin server, you can use the rules engine to create custom configurations. In addition, Alibaba Cloud CDN provides the EdgeScript feature, which supports highly flexible customization and lets you configure granular policies similar to those of third-party CDN providers like Fastly and CloudFront.
Capabilities | Basic features | Basic features and rules engine | EdgeScript |
Feature implementation | General-purpose configurations | Lets you create conditional filtering rules using a graphical interface. It supports multiple match types, such as URI, Header, Cookie, and Query String, and AND/OR logical combinations. | Supports highly flexible customization and is suitable for advanced scenarios that require custom scripting. |
Scenarios | General-purpose scenarios | Advanced custom scenarios | Fully custom scenarios |
Ease of use | High | Medium | Low |
Configuration flexibility | Low | Medium | High |
Complex logic and EdgeScript
The rule engine supports basic AND/OR logical combinations, making it suitable for most conditional filtering scenarios. However, the following scenarios can help you decide whether to use EdgeScript:
Complex regular expression matching: The regular expression operator in the rule engine is disabled by default. You must submit a ticket to enable it. For frequent regular expression matching, EdgeScript is more convenient because it provides native support.
Precise multi-dimensional combinations: Configuring complex evaluations that combine multiple criteria, such as matching both the client IP and User-Agent with regular expressions (for example, blocking requests from a specific IP range where the User-Agent contains a specific keyword), is cumbersome in the rule engine. EdgeScript lets you flexibly combine multiple conditions using script logic.
Precise access control for specific URIs: Use the rule engine directly to block requests for a specific URI based on the Referer or an IP whitelist. You do not need EdgeScript.
Limitations
You can create a maximum of 50 rule conditions per domain name.
Each rule condition can contain a maximum of 20 sub-rules.
You cannot use regular expression match or regular expression mismatch operators when configuring rule conditions in the console or using OpenAPI. However, you can view existing configurations that use these operators. To use these operators, use ESA.
A rule condition can be referenced a maximum of five times across all features within a single domain name.
You can nest rule conditions up to three levels deep, and each level can have its own independent logical relationships.
If a feature, such as setting the cache expiration time or modifying outgoing request headers, references a rule condition, the condition's priority determines the execution order, not the feature's configuration order.
The preceding limits (50 rule conditions, 20 sub-rules, 3 levels of nesting, and 5 references) are hard limits and cannot be increased upon request.
Each condition can have a maximum of 32 match values for match types such as client IP, URI, file extension, filename, and User-Agent. If you have a large client IP allowlist, consolidate multiple IP addresses into CIDR blocks (for example,
120.209.XXX.X/24) to conserve the match value quota.You can configure a maximum of 32 User-Agent match values. Values beyond this limit are ignored. To match a large number of User-Agents, use a wildcard (
*) to consolidate similar values (for example,*Chrome*matches all Chrome browser versions) or use EdgeScript for more flexible matching logic.
Feature priority and execution logic
When you configure the rule engine, consider the following feature priorities and execution logic:
Referer hotlink protection takes precedence over the rule engine: When a request includes a Referer header, the system first evaluates it against the Referer blacklist and whitelist. If the request matches the whitelist, it is allowed to proceed, bypassing the rule engine. If the request does not match the whitelist, the system blocks it immediately. If the Referer header is empty, the request bypasses this logic and is evaluated by the rule engine.
Execution order for features using rule conditions: When features such as Cache Expiration or Modify Outbound Request Header use rule conditions, the system executes them based on the priority of their associated rule conditions, not the configuration order of the features. For example, if Cache Expiration and Back-to-Origin Parameter Rewrite use rule conditions with different priorities, the system executes them in order of rule condition priority, from highest to lowest.
Troubleshoot conflicts between URL authentication and caching: If you encounter unexpected behavior after configuring URL authentication, such as requests being accessible without authentication parameters or valid links being incorrectly blocked, check the following in order:
Check if a WAF whitelist is configured. A WAF whitelist might bypass the CDN URL authentication logic, allowing requests to proceed directly.
Verify that the Ignore URL Parameters feature is not stripping authentication parameters, such as
auth_key. This could cause authentication to be skipped on a cache hit.Confirm that the Cache Key Rule does not ignore the authentication parameter. If it does, requests with different authentication parameters might receive the same cached content, effectively bypassing authentication.
Rule condition syntax
A rule condition combines one or more conditional expressions by using logical operators. The following sections describe the syntax.
Logical operators
Logical operators evaluate conditions at the same level, including nested condition sets. The supported operators are and and or.
and: The logical AND operator. A match is successful only if all conditions are true.or: The logical OR operator. A match is successful if at least one condition is true. For example, you can configure multiple rule conditions for the same response header to add the header under different circumstances. Example: If the URI contains/path-aor the URI contains/path-b, the system adds the response header.
Parameters of a conditional expression
A conditional expression, the most granular unit of a rule, includes the following parameters:
Parameter | condition function parameter | Description | Required |
Conditional match | match | Specifies the conditional match expression. | Yes |
Logical operator | logic | Specifies the logical operator for the conditional match expression. Valid values are | Yes |
Criteria | criteria | Specifies the array of conditional expressions to be evaluated. | Yes |
Match type | MatchType | Specifies the type of information in a client request to match. | Yes |
Match object | MatchObject | Further refines the match type. For example, a client IP address can be specified as a POP connection IP or an XFF IP. | No |
Match operator | MatchOperator | Specifies the comparison to perform. | Yes |
Match value | MatchValue | The value to compare against data from the client request. | Yes |
Negate condition | negate | Specifies whether to negate the result of the conditional expression. Valid values are true and false. | Yes |
Case sensitivity | caseSensitive | Specifies whether the match value is case-sensitive. | No |
Rule condition name | name | Specifies the name of the rule condition. | Yes |
Status | status | Specifies the status of the rule condition. | Yes |
Conditional expression configuration
Match type | condition function parameter | Description | Match object | Match operator | Match value | Case sensitivity | Nginx variable |
Protocol | scheme | The protocol used by the client request, such as HTTP or HTTPS. | Not applicable |
|
| Not applicable | $scheme |
Request method | method | The request method used by the client request, such as GET or PUT. | Not applicable |
|
| Not applicable | $request_method |
URI (path) | uri | The path in the client request URL, excluding any request parameters. For example: | Not applicable |
| The wildcards |
| $raw_uri or $uri |
File name | basename | The name of the file requested by the client. For example: name1. | Not applicable |
| The wildcards |
| - |
File extension | extension | The file extension of the file requested by the client. The system identifies the extension as the substring from the last dot (.) to the end of the filename. For example: | Not applicable |
| The wildcards |
| - |
Hostname | hostname | The hostname from the client request. Matching order: host in the request URL > host in the | Not applicable |
| The host from the client request. You can enter multiple values. |
| $host or $http_host |
Client IP address | clientip | The IP address of the client. IPv4 (for example, |
Note For more information about POP connection IP and XFF IP, see IP address verification mode. |
| IPv6 addresses, such as 240e:XXX:3004:2:3:0:0:3f7, and CIDR blocks, such as 120.209.XXX.XXX/31, are supported. You can enter multiple values. | Not applicable | $remote_addr |
Client IP version | clientipVer | The IP version of the client address: IPv4 or IPv6. |
Note For more information about POP connection IP and XFF IP, see IP address verification mode. |
|
| Not applicable | - |
Internet service provider (ISP) | geolocation | The ISP to which the client IP address belongs. |
Note For more information about POP connection IP and XFF IP, see IP address verification mode. |
| You can select an ISP from the drop-down list or enter characters to filter the options. Fuzzy search by ID or name is supported. You can enter multiple values. | Not applicable | $ip_isp_id |
IP geolocation | geolocation | The geographical location of the client IP address. |
Note For more information about POP connection IP and XFF IP, see IP address verification mode. |
| You can select a location from the drop-down list or enter characters to filter the options. Fuzzy search by ID or name is supported. You can enter multiple values. | Not applicable | $ip_country_id |
Request parameter | querystring | A parameter in the request URL. | Enter the parameter name. |
| The wildcards |
| $arg_{name} |
Request header | header | A header in the client request. | You can enter a parameter name or select a parameter from the drop-down list. |
| You can enter multiple values. |
| $http_{name} |
Cookie | cookie | The cookie in the client request. | Enter the cookie name. |
| The wildcards |
| $cookie_{name} |
User-Agent | useragent | The | Not applicable |
| You can select a value from the drop-down list or enter a User-Agent value, such as |
| $http_user_agent |
Range bucket | range | Matches a specified percentage of client requests. | Not applicable |
| Enter a percentage value. | Not applicable | - |
Time | time | The time when the client request occurs. The time is in UTC+8. For example, 09:10~14:22. | Not applicable |
| Enter a time range, such as 09:10~14:22, which represents the period from 09:10 to 14:22. | Not applicable | - |
Nginx var | ngxvar | Use Nginx variables if the preceding variables do not meet your requirements. For a list of supported variables, see the official Nginx documentation. | You can select a variable from the drop-down list or enter a variable name. Concatenation is supported, such as |
| You can enter multiple values. | Not applicable | ${name} |
Common configuration notes for conditional expressions
URI (path) match starting point: For URI matching, the value is the path portion that starts with the first
/after the domain name. The value does not include the domain name or request parameters. For the requesthttps://example.com/path/file.html?key=value, the value to be matched is/path/file.html. The match value must start with/.File extension match format: When you configure a file extension match, the match value must include a dot (
.). For example, to match.txtfiles, enter.txt, nottxt. Otherwise, the match may fail.Wildcard usage examples: URI and file extension matches support the wildcards
?(matches a single character) and*(matches zero or more characters). Common examples:/*.pdf: Matches all PDF files in the root directory./api/*/data: Matches thedatapath in any subdirectory under/api/..??: Matches all two-character file extensions, such as.jsand.ts.
IP address verification mode
The rules engine provides two IP address verification modes. The selected mode affects how CDN nodes identify the client IP address:
POP connection IP: This mode matches the IP address that a client uses to connect to a CDN node. If a proxy server is used between the client and the CDN node, the POP connection IP is the IP address of the proxy server.
XFF IP: This mode matches the leftmost IP address in the
x-forwarded-forrequest header. The XFF IP is always the real IP address of the client, regardless of whether a proxy server is used between the client and the CDN node.
The choice of verification mode depends on whether a client request passes through a proxy server before it reaches a CDN node.
Note that the location on a CDN node where a feature takes effect also affects the IP address verification mode. For features related to origin settings that take effect on L2 nodes, the L1 nodes that a request passes through are considered intermediate proxy servers.
Example: Assume that the real client IP address is 10.10.10.10 and the proxy server IP address is 192.168.0.1.
Without a proxy server:
The value of the
x-forwarded-forrequest header is10.10.10.10.The real IP address of the client (the leftmost IP in the x-forwarded-for request header) = The IP address used to establish the connection between the client and the CDN node =
10.10.10.10.
With a proxy server:
The value of the
x-forwarded-forrequest header is10.10.10.10,192.168.0.1.The real client IP address (the leftmost IP address in the
x-forwarded-forrequest header) is10.10.10.10.Client-to-CDN node connection IP = Proxy server IP =
192.168.0.1.The real client IP address (the first IP address from the left in the x-forwarded-for request header) ≠ the IP address of the client connection to the CDN node.
Some internet service providers (ISPs) in specific regions may assign private IP addresses to end-users. As a result, nodes may receive a user's private IP address.
Private IP addresses fall into three ranges:
Class A private IP address: 10.0.0.0 to 10.255.255.255, subnet mask: 10.0.0.0/8
Class B private IP address: 172.16.0.0 to 172.31.255.255, subnet mask: 172.16.0.0/12
Class C private IP address: 192.168.0.0 to 192.168.255.255, subnet mask: 192.168.0.0/16
Match operators (matchOperator)
Operator | condition function parameter | Description |
equal to |
| The condition is met only when the variable exactly equals or does not equal the specified match value. |
not equal to |
| |
exists |
| The condition is met depending on whether the specified variable exists in the request. |
not exists |
| |
contains any |
| The condition is met if the variable contains (or does not contain) any of the specified match values. A maximum of 32 match values are supported. Two types of containment matching are supported:
|
does not contain any |
| |
greater than |
| That is, |
less than |
| That is, |
greater than or equal to |
| That is, |
less than or equal to |
| That is, |
regular expression match |
| Matches the variable against a regular expression. Note If you configure rules in the console or by using OpenAPI, you cannot use these regular expression operators. However, you can view existing configurations. To use regular expression-related match operators, submit a ticket or use Edge Security Acceleration (ESA). |
regular expression mismatch |
|
Wildcards
Wildcard | Description | Path matching example |
| Matches any single character. |
|
| Matches zero or more characters. |
|
Features that support rule conditions
Category | Feature |
Basic configuration | |
Cache settings | |
Origin settings | |
Access control | |
Performance optimization | |
Video settings | |
Traffic throttling |
Configuration management
Managing actions: The Rules Engine page is for defining rule conditions only. To manage an action (such as cache expiration, URL rewrite, or throttling), go to the settings page for that feature. For example, if a cache expiration setting references a rule condition, go to Cache settings > Cache expiration to view or modify it.
Remote Authentication: The remote authentication feature cannot reference rule conditions, meaning you cannot use the Rule Engine to control when it is triggered.
Authentication timeout limit: The Remote Authentication Timeout can be set to a maximum of 3000 milliseconds (3 seconds). The default value is 500 milliseconds. This is the highest value that the system supports.
Advanced use cases
You can implement the following advanced configurations with the Rule Engine:
Differentiated throttling policies: If you want to throttle some requests but not others (for example, throttle URLs that include signing parameters but do not throttle other URLs), or if you want a fallback throttling policy, create rule conditions in the Rules Engine to differentiate between requests. Then, in the Single-request throttling settings, reference different rule conditions and configure different throttling values.
IP-based canary release for origin fetch: To implement a canary release based on client IP addresses or to route requests from specific IPs to different origins, create IP-based match conditions in the Rule Engine. Then, in the Conditional origin settings, reference these conditions to specify different origin addresses.
Recommendation for mixed-origin architectures: If you use both WAF and OSS as origins, do not configure them as multiple primary origins. Instead, use the Rule Engine to create match conditions based on URL paths. Then, in the Conditional origin settings, you can dynamically route requests to the appropriate origin for each path. This approach helps prevent conflicts.
Procedure
-
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 navigation bar for the specified domain name, click Rules Engine.
Click Add Rule.
On the Add Rule page, set Rule Name and Rule Content.
Click Submit to complete the configuration.
Typical configuration scenarios
The following sections describe how to implement two common configuration scenarios.
Scenario 1: IP allowlist and redirect
Goal: Allow only specific IP addresses to access your site and redirect all other traffic to a maintenance page.
Implementation:
In the Rules Engine, create a rule condition. Set the Match Type to Client IP, the Match Operator to Does not contain any of, and enter your allowlisted IP addresses as the Match Value.
In Cache Configuration > URL Rewrite, reference this rule condition to redirect matched requests (from non-allowlisted IP addresses) to your specified maintenance page URL, such as an HTML page hosted on an OSS origin.
Notes:
If requests from IP addresses not on the allowlist return a 403 error instead of being redirected, check whether you have configured multiple OSS origins, which can cause an origin conflict. We recommend that each CDN domain has only one primary OSS origin.
Ensure the maintenance page URL is publicly accessible and not blocked by other access control rules.
Scenario 2: Referer protection and file extension matching
Goal: Apply Referer hotlink protection to most files, while exempting specific file extensions from the check.
Implementation:
In the Rules Engine, create a rule condition. Set the Match Type to File Extension, the Match Operator to Does not contain any of, and enter the file extensions you want to exempt (such as
.pdf) as the Match Value.In Access Control > Referer Hotlink Protection, reference this rule condition. This applies your Referer allowlist or denylist to all requests except those for the exempted file extensions.
FAQ
Origin Host rules and the rule limit
Yes. Any rule applied to a domain name counts toward the advanced conditional rule limit. You can create up to 50 rule conditions per domain name, and each condition can contain up to 20 sub-conditions.
Defining actions for rule engine conditions
You use the rule engine to define conditions. These conditions take effect only when you link them to other features, such as Cache Expiration Time, origin parameter rewriting, or URL Rewrite. You configure the action in the associated feature's settings. For example, you can create a rule condition to define matching logic, then reference that rule in the Cache Expiration Time settings to apply a cache policy only to matching requests.
Controlling downloads with URL authentication and rules
When Type A authentication is enabled, you can use the rule engine to control behavior by matching request parameters. We recommend configuring a URL Contains condition to match a specific business parameter name or value, such as download=1.
Do not match on the authentication parameters themselves, as this can interfere with the authentication process. However, you can safely match on other business parameters like download.
Ensure the final generated URL includes the parameter specified in your rule (for example, http://.../video.mp4?auth_key=...&download=1) to trigger the corresponding response header configuration and control the download.
Configuring a 301 redirect rule
You can implement a domain redirect by creating a URL rewrite rule. Configure a URI match condition in the rule engine and use it with the URL Rewrite feature to redirect traffic from www.example.com to shop.example.com.
Redirecting a subdomain to a top-level domain
You can do this by configuring a URL rewrite in CDN. Follow these steps:
In the rule engine, create a rule condition. Set the Match Type to URI (path), the Match Operator to Regular Expression Match, and the Match Value to
^/(.*)$. To use the Regular Expression Match operator, you must either use DCDN or submit a ticket to enable it.In the URL Rewrite feature, set the Target Path to
https://top-level-domain.com/$1, where$1is the path captured by the regular expression.
For example, this forces a redirect from sub.wetqt.com/any/path to https://wetqt.com/any/path.
Disabling cache for a specific path with rules
You can use one of the following methods depending on your matching requirements:
By file extension: In your cache configuration, set the cache expiration time to 0 for file extensions that you do not want to cache. For files you want to cache, set an appropriate cache duration (such as 4 hours) and ensure that settings to ignore origin cache control are disabled.
By path: Because the CDN console does not support regular expression matching on the full URL, you must use a URI path match in the rule engine. Set the Match Type to URI (path) and the Match Operator to Contains any of or Does not contain any of. You can use the wildcards
?and*in the Match Value field. For example, a value of/*/no-cache/*can match paths like/api/no-cache/data.
Path matching and the starting /
Yes. When you use a path match (not a regular expression match) in the rule engine, it matches the path segment starting from the first / after the domain name. For example, for the URL https://example.com/a.html, the path to match is /a.html.
CDN does not natively support regular expression matching on the full URL including the protocol and domain, such as ^https?://([^/]+)/path.
Troubleshooting filename matching for response headers
When you configure a filename match in the rule engine, note that basename and file extension are two distinct match types:
Basename: Matches the part of the filename without the extension. For example,
script(not.js).File extension: Matches the file's suffix. For example,
.jsor.css.
If you include the file extension in a basename match (for example, script.js), the match will fail. For the match to succeed, remove the extension and enter only the basename, such as script.
Configuring rules to match static resources
You can match static resources by using a file extension match in the rule engine. Follow these steps:
Set the Match Type to File Extension.
Set the Match Operator to Contains any of.
In the Match Value field, enter
.js,.css. Use commas to separate multiple extensions.
This configuration will match all requests for .js and .css files. You can add more extensions, such as .js,.css,.png,.jpg.