CDN:Rules engine

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 request that it be enabled. If you need to use regular expressions frequently, EdgeScript natively supports regular expression matching, which is more convenient.

• 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.

• Granular multi-directory IP access control: EdgeScript lets you grant different IP address ranges access to different directories. For example, you can allow one IP address range to access all directories, allow a specific IP address to access only one directory, and deny all other IP addresses. Use match_re to match IP addresses and URI paths. Use return true to allow the request, and use exit(403) to deny it.

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 total number of times that rule conditions can be referenced for a single domain name (five by default), submit a ticket. Provide the following information in the ticket: the accelerated domain name for which you want to increase the limit, the target number of references, and a description of your business scenario.

  • When adding another accelerated domain name, submit a separate ticket to increase the number of rule-condition references for that domain. The process is the same as for the first 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 configure the IP addresses and conserve match-value capacity.

• 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 User-Agent 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:

  1. Check if a WAF whitelist is configured. A WAF whitelist might bypass the CDN authentication logic and allow requests through directly.

  2. Verify that the Ignore URL Parameters feature is not stripping authentication parameters, such as auth_key) are filtered out by the ignore URL parameters setting, which skips authentication validation for cache hits.

  3. 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.

IP address verification mode

The rules engine provides two IP address verification modes. The selected mode affects how CDN POPs identify the client IP address:

• POP connection IP: This mode matches the IP address that a client uses to connect to a CDN POP. If the traffic between the client and the CDN POP passes through a proxy server, 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. Whether or not a proxy server is used between the client and the CDN POP, the XFF IP is always the client's real IP address.

The choice of verification mode depends on whether a client request passes through a proxy server before it reaches a CDN POP.

Note that the location on a CDN POP where a feature that references a rule condition takes effect also affects which IP address verification mode you must select. For origin-fetch features that take effect on L2 POPs, the L1 POP that the user request passes through is equivalent to an intermediate proxy server.

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

• Without a proxy server:

  • The x-forwarded-for request header value is 10.10.10.10.

  • The client's real IP address (the leftmost IP in the x-forwarded-for request header) = the IP address used to establish the connection between the client and the CDN POP = 10.10.10.10.

• With a proxy server:

  • The x-forwarded-for request header value is 10.10.10.10,192.168.0.1.

  • The client's real IP address (the leftmost IP in the x-forwarded-for request header) = 10.10.10.10.

  • The IP address used to establish the connection between the client and the CDN POP = the IP address of the proxy server = 192.168.0.1.

  • The client's real IP address (the leftmost IP in the x-forwarded-for request header) ≠ the IP address used to establish the connection between the client and the CDN POP.

In specific regions, a small number of Internet service providers (ISPs) may assign private IP addresses to end users. As a result, the CDN node receives the user's private IP address.

Features that support rule conditions