DCDN rules engine-Edge Security Acceleration(ESA)-阿里云帮助中心

The rules engine lets you use a graphical interface to configure rules. These rules use parameters from user requests to determine when a configuration applies, giving you more flexible and precise control over how DCDN configuration policies are executed.

Background

The Alibaba Cloud DCDN console provides basic features, such as configuring time-to-live (TTL) and rewriting back-to-origin parameters. While these features cover most use cases, they may not meet all requirements. For example, you might need to route requests that contain the path /example to a specific origin. To handle such scenarios, you can combine basic features with the rules engine for more flexible configurations. Additionally, Alibaba Cloud DCDN 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 up to 50 rules per domain name.
Each rule can contain up to 20 sub-rules.
When you configure rules in the console or with OpenAPI, you cannot use regular expression-related operators, including regular expression match and regular expression mismatch. However, you can view existing configurations. To use these operators, submit a ticket or use ESA.
When you configure rules in the console or with OpenAPI, you can reference each rule up to five times across all features for a single domain name.
Rules can be nested up to three levels deep. Each level supports independent logical relationships.

Rule syntax

A rule consists of one or more conditional expressions that are connected by logical operators. The following sections describe the syntax.

Logical operators

Performs a logical judgment on conditions within the same level (including nested condition sets), supporting and and or.

and: The logical AND operator. A match is successful only if all conditions are true.
or: A logical OR operator that results in a successful match if at least one condition is true.

Conditional expression parameters

A basic conditional expression consists of the following parameters:

Parameter	Domain configuration functioncondition and its corresponding configuration parameters	Description	Required
Conditional match	match	Specifies the matching criteria.	Yes
Logical operator	logic	The logical judgment parameter for the conditional matching expression, whose value can be `and` or `or`.	Yes
Criteria	criteria	An array that contains the conditional expressions to be evaluated.	Yes
Match type	MatchType	Specifies the type of information in a client request to evaluate.	Yes
Match object	MatchObject	Refines the match type. For example, if the match type is client IP address, you can specify `POP connection IP` or `XFF IP` as the match object.	No
Match operator	MatchOperator	Specifies the comparison to perform.	Yes
Match value	MatchValue	The value to compare against the information from the client request.	Yes
Negate condition	negate	Specifies whether to negate the result of the conditional expression. Valid values: `true` and `false`.	Yes
Case sensitivity	caseSensitive	Specifies whether the match value is case-sensitive.	No
Rule name	name	The name of the rule.	Yes
Status	status	The status of the rule.	Yes

Conditional expressions

Match type	Domain configuration feature'sconditionparameters	Description	Match object	Match operator	Value	Case sensitivity	Nginx variable
Protocol	scheme	The protocol of the client request, such as HTTP or HTTPS.	Not applicable	equal to not equal to	http https	Not applicable	$scheme
Request method	method	The method of the client request, such as GET or PUT.	Not applicable	equal to not equal to	get put post delete head	Not applicable	$request_method
URI	uri	The path in the client request URL, which does not include request parameters. For example: `/favicon.ico`.	Not applicable	contains any does not contain any	The `?` and `` wildcards are supported. For example, `//my_path/*`. Multiple values are also supported.	Case-sensitive Case-insensitive	$raw_uri or $uri
File name	basename	The name of the file requested by the client. For example: `name1`.	Not applicable	contains any does not contain any	Supports wildcards `?` and `*`. You can enter multiple values.	Case-sensitive Case-insensitive	-
File extension	extension	The file extension of the file requested by the client is identified from right to left up to the first period (.). For example: `.mp4`.	Not applicable	contains any does not contain any	Supports wildcards `?` and `*`. You can enter multiple values.	Case-sensitive Case-insensitive	-
Hostname	hostname	The hostname from the client request. If a host is present in the request URL, it is used. Otherwise, the host from the `Host` request header is used.	Not applicable	contains any does not contain any	The host of the request. Multiple values are supported.	Case-sensitive Case-insensitive	$host or $http_host
Client IP address	clientip	The IP address of the client. The value can be an IPv4 address, such as `1.1.X.X`, an IPv6 address, such as `240e:95c:3004:2:3:0:0:XXX`, or a network segment, such as `20.209.XXX.XXX/31`.	POP connection IP XFF IP Note For more information about POP connection IP and XFF IP, see IP address verification modes.	contains any does not contain any	Supports IPv6 addresses, such as 240e:XXX:3004:2:3:0:0:3f7, and CIDR blocks, such as 120.209.XXX.XXX/31. Multiple values are supported.	Not applicable	$remote_addr
Client IP version	clientipVer	The IP version of the client address: IPv4 or IPv6.	POP connection IP XFF IP Note For more information about POP connection IP and XFF IP, see IP address verification modes.	equal to not equal to	v4 v6	Not applicable	-
Internet service provider (ISP)	geolocation	The ISP to which the client IP address belongs.	POP connection IP XFF IP Note For more information about POP connection IP and XFF IP, see IP address verification modes.	contains any does not contain any	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. Multiple values are supported.	Not applicable	$ip_isp_id
IP geolocation	geolocation	The geographical location of the client IP address.	POP connection IP XFF IP Note For more information about POP connection IP and XFF IP, see IP address verification modes.	contains any does not contain any	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. Multiple values are supported.	Not applicable	$ip_country_id
Request parameter	querystring	A parameter in the request URL.	Enter the parameter name.	exists not exists contains any does not contain any greater than greater than or equal to less than less than or equal to	You can use the `?` and `*` wildcards and enter multiple values.	Case-sensitive Case-insensitive	$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.	exists not exists contains any does not contain any greater than greater than or equal to less than less than or equal to	Multiple values are supported.	Case-sensitive Ignore case	$http_{name}
Cookie	cookie	The cookie in the client request.	Enter the cookie name.	exists not exists contains any does not contain any greater than greater than or equal to less than less than or equal to	Supports wildcards `?` and `*`. You can enter multiple values.	Case-sensitive Case-insensitive	$cookie_{name}
User-Agent	useragent	The User-Agent header in the client request.	Not applicable	contains any does not contain any	You can select a value from the drop-down list or enter a UA value directly, such as `Chrome/25`. The input supports the wildcards `?` and `*`, and you can enter multiple values (You can configure a maximum of 32 UAs. If you exceed this number, the configured UAs will not take effect).	Case-sensitive Case-insensitive	$http_user_agent
Range bucket	range	Matches a specified percentage of client requests.	Not applicable	equal to not equal to	Enter a percentage value.	Not applicable	-
Time	time	The time when the client request occurs. The time is in the UTC+8 time zone. For example, `09:10~14:22`.	Not applicable	contains any does not contain any	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	If the preceding variables do not meet your requirements, you can use Nginx variables. For more information, see the official Nginx documentation.	Select a variable from the drop-down list or enter a variable name. Concatenation is supported, such as `$region:$isp`.	exists not exists contains any does not contain any greater than greater than or equal to less than less than or equal to	Multiple values are supported.	Not applicable	${name}

IP address verification modes

The rules engine provides two IP address verification modes. The selected mode affects how /DCDN points of presence (POPs) identify the client IP address:

POP connection IP: 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-for request 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 reaching a /DCDN POP.

Note that the execution location of the feature that references rule conditions on DCDN nodes also affects the selection of the "IP address verification mode" (for features related to origin settings that take effect on L2 nodes, the L1 nodes that a user request passes through are equivalent to intermediate proxy servers).

Example: Assume the client's real IP address is 10.10.10.10 and the proxy server's IP address is 192.168.0.1.

Without a proxy server:
- The value of the x-forwarded-for request header is 10.10.10.10.
- The real client IP (the first IP from the left in the x-forwarded-for request header) = The IP address that the client uses to connect to the DCDN node = 10.10.10.10.
With a proxy server:
- The value of the x-forwarded-for request header in the user request is 10.10.10.10,192.168.0.1.
- The real client IP (the leftmost IP address in the x-forwarded-for request header) is 10.10.10.10.
- Client-to-DCDN node connection IP = proxy server IP = 192.168.0.1.
- The originating client's IP address is not the same as the /DCDN POP connection IP.

Some ISPs in specific regions may assign private IP addresses to clients. As a result, /DCDN POPs may receive requests from private IP addresses.

Note

The following are the three ranges of private IP addresses:

Class A: 10.0.0.0 to 10.255.255.255, with the subnet mask 10.0.0.0/8
Class B: 172.16.0.0 to 172.31.255.255, with the subnet mask 172.16.0.0/12
Class C: 192.168.0.0 to 192.168.255.255, with the subnet mask 192.168.0.0/16

Match operators

Operator	Domain name configuration function's condition configuration parameters	Description
equal to	The `matchOperator` parameter is set to `equals`.	The condition is met only if the variable exactly matches the match value.
not equal to	The `matchOperator` parameter is set to `equals`, and the `negate` parameter is set to `true`.
exists	The `matchOperator` parameter is set to `exists`.	The condition is met if the variable exists (or does not exist).
not exists	The `matchOperator` parameter is set to `exists`, and the `negate` parameter is set to `true`.
contains any	The `matchOperator` parameter is set to `contains`.	The condition is met if the variable contains (or does not contain) any of the specified match values. You can specify up to 32 match values. Two types of containment matching are supported: Exact match: The variable must be an exact match for the specified value. For example, if the value is `a`, the variable must also be `a`. Wildcard matching: You can use `` as a wildcard. Supported patterns include `a`, `a`, and `a*`, which match abc, bca, and bcabc, respectively.
does not contain any	The `matchOperator` parameter is set to `contains`, and the `negate` parameter is set to `true`.
greater than	The `matchOperator` parameter is set to `gt`.	That is, `>`
less than	The `matchOperator` parameter is set to `lt`.	That is, `<`
greater than or equal to	The `matchOperator` parameter is set to `ge`.	That is, `>=`
less than or equal to	The `matchOperator` parameter is set to `le`.	That is `<=`
regular expression match	The `matchOperator` parameter is set to `regex`.	The system uses the match value as a regular expression to evaluate the variable. Note You cannot configure rules with regular expression operators, including `regular expression match` and `regular expression mismatch`, in the console or by calling API operations. You can only view existing rules that use these operators. To create or modify rules with regular expression operators, submit a ticket or use Edge Security Acceleration (ESA).
regular expression mismatch	The `matchOperator` parameter is set to `regex`, and the `negate` parameter is set to `true`.

Wildcards

Wildcard	Description
`?`	Matches a single character.
`*`	Matches zero or more characters.

Features supporting rule conditions

Feature category	Feature name
origin fetch configuration	Specify the origin host
	Modify incoming request headers
	origin HTTP request headers (New)
	origin HTTP response headers
cache configuration	Configure time-to-live
	Modify outgoing response headers
	custom cache key

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.