Use the rules engine's graphical interface to define conditional rules based on request parameters and control exactly when DCDN configuration policies take effect.
Note: When this feature references rule conditions from the Rules Engine, the execution order follows the priority order of the rule conditions configured in the Rules Engine, NOT the priority order of this feature's own configuration.
Background
The Alibaba Cloud DCDN console provides basic features such as configuring time-to-live (TTL) and rewriting back-to-origin parameters. These features cover most use cases but cannot handle all requirements. For example, you might need to route requests containing the path /example to a specific origin. For such scenarios, combine basic features with the rules engine for more flexible configurations. Alibaba Cloud DCDN also offers EdgeRoutine for advanced customization.
|
Configuration capability |
Basic features |
Basic features + rules engine |
EdgeRoutine |
|
Implementation |
General-purpose configurations |
Flexible custom configurations |
Highly flexible custom configurations |
|
Scenarios |
Common use cases |
Advanced custom requirements |
Fully customized requirements |
|
Difficulty |
Low |
Medium |
High |
|
Configuration flexibility |
Low |
Medium |
High |
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.
Among the preceding limits, the maximums of 50 rule conditions, 20 sub-rules, and 3 levels of nesting are hard limits that cannot be increased upon request. The maximum total number of references to rule conditions across all features within a single accelerated domain name, which is 5 by default, can be increased upon request.
To increase the maximum total number of references to rule conditions for a single accelerated domain name, submit a ticket and provide the following information: the accelerated domain name for which you want to increase the limit, the target number of references, and a description of your business scenario.
If you add another accelerated domain name later, you must submit a ticket separately for that domain name to increase the number of references. The process is the same as for the initial request.
No mechanism is available to increase this limit automatically. After you submit a ticket, the request is processed through manual review by the backend team.
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.
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 | Functions for domain name configuration 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 | Functions for domain name configuration 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 DCDN nodes identify the client IP address:
POP connection IP: This mode matches the IP address that a client uses to connect to a DCDN node. If a proxy server is used between the client and the DCDN 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 DCDN node.
The choice of verification mode depends on whether a client request passes through a proxy server before it reaches a DCDN node.
Note that the location on a DCDN 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 DCDN 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-DCDN 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 DCDN 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 supporting rule conditions
|
Feature category |
Feature name |
|
origin fetch configuration |
|
|
origin HTTP request headers (New) |
|
|
origin HTTP response headers |
|
|
cache configuration |
|
Procedure
-
Log on to the DCDN console.
-
In the left-side navigation pane, click Domain Names.
-
On the Domain Names page, find the domain name that you want to manage and click Configure in the Actions column.
-
In the left navigation pane, click Rule Engine.
-
Click Create Rule.
-
On the Create Rule page, set the Rule Name and Rule Content.
-
Click Submit.