Azure CDN Rules Engine Match Condition and Feature Details
Applies To: Microsoft Azure
This topic lists detailed descriptions of the available match conditions and features for Azure Content Delivery Network (CDN) Rules Engine.
Syntax
The manner in which special characters will be treated varies according to how a match condition or feature handles text values. A match condition or feature may interpret text in one of the following ways:
- Literal Values
- Wildcard Values
- Regular Expressions
Literal Values
Text that is interpreted as a literal value will treat all special characters, with the exception of the % symbol, as a part of the value that must be matched. In other words, a literal match condition set to \'*'\ will only be satisfied when that exact value (i.e., \'*'\) is found.
A percentage symbol is used to indicate URL encoding (e.g., %20).
Wildcard Values (Special Characters)
Text that is interpreted as a wildcard value will assign additional meaning to special characters. The following table describes how the following set of characters will be interpreted.
| Character | Description |
|---|---|
| \ | A backslash is used to escape any of the characters specified in this table. A backslash must be specified directly before the special character that should be escaped. For example, the following syntax escapes an asterisk: \* |
| % | A percentage symbol is used to indicate URL encoding (e.g., %20). |
| * | An asterisk is a wildcard that represents one or more characters. |
| Space | A space character indicates that a match condition may be satisfied by either of the specified values or patterns. |
| 'value' | A single quote does not have special meaning. However, a set of single quotes is used to indicate that a value should be treated as a literal value. It can be used in the following ways: - It allows a match condition to be satisfied whenever the specified value matches any portion of the comparison value. For example, 'ma' would match any of the following strings:/business/marathon/asset.htm map.gif /business/template.map - It allows a special character to be specified as a literal character. For example, you may specify a literal space character by enclosing a space character within a set of single quotes (i.e., ' ' or 'sample value').- It allows a blank value to be specified. Specify a blank value by specifying a set of single quotes (i.e., ''). Important: - If the specified value does not contain a wildcard, then it will automatically be considered a literal value. This means that it is not necessary to specify a set of single quotes. - If a backslash does not escape another character in this table, then it will be ignored when specified within a set of single quotes. - Another way to specify a special character as a literal character is to escape it using a backslash (i.e., \). |
Regular Expressions
Regular expressions define a pattern that will be searched for within a text value. Regular expression notation defines specific meanings to a variety of symbols. The following table indicates how special characters are treated by match conditions and features that support regular expressions.
| Special Character | Description |
|---|---|
| \ | A backslash escapes the character the follows it. This causes that character to be treated as a literal value instead of taking on its regular expression meaning. For example, the following syntax escapes an asterisk: \* |
| % | The meaning of a percentage symbol depends on its usage.%{HTTPVariable}: This syntax identifies an HTTP variable.%{HTTPVariable%Pattern}: This syntax uses a percentage symbol to identify an HTTP variable and as a delimiter.\%: Escaping a percentage symbol allows it to be used as a literal value or to indicate URL encoding (e.g., \%20). |
| * | An asterisk allows the preceding character to be matched zero or more times. |
| Space | A space character is typically treated as a literal character. |
| 'value' | Single quotes are treated as literal characters. A set of single quotes does not have special meaning. |
Match conditions
A match condition identifies specific types of requests for which a set of features will be performed.
For example, it may be used to filter requests for content at a particular location, requests generated from a particular IP address or country, or by header information.
Always
The Always match condition is designed to apply a default set of features to all requests.
Device
The Device match condition identifies requests made from a mobile device based on its properties. Mobile device detection is achieved through WURFL. WURFL capabilities and their CDN Rules Engine variables are listed below.
Tip
The variables below are supported in the Modify Client Request Header and Modify Client Response Header features.
| Capability | Variable | Description | Sample Value(s) |
|---|---|---|---|
| Brand Name | %{wurfl_cap_brand_name} | A string that indicates the brand name of the device. | Samsung |
| Device OS | %{wurfl_cap_device_os} | A string that indicates the operating system installed on the device. | IOS |
| Device OS Version | %{wurfl_cap_device_os_version} | A string that indicates the version number of the OS installed on the device. | 1.0.1 |
| Dual Orientation | %{wurfl_cap_dual_orientation} | A Boolean that indicates whether the device supports dual orientation. | true |
| HTML Preferred DTD | %{wurfl_cap_html_preferred_dtd} | A string that indicates the mobile device's preferred document type definition (DTD) for HTML content. | none xhtml_basic html5 |
| Image Inlining | %{wurfl_cap_image_inlining} | A Boolean that indicates whether the device supports Base64 encoded images. | false |
| Is Android | %{wurfl_vcap_is_android} | A Boolean that indicates whether the device uses the Android OS. | true |
| Is IOS | %{wurfl_vcap_is_ios} | A Boolean that indicates whether the device uses iOS. | false |
| Is Smart TV | %{wurfl_cap_is_smarttv} | A Boolean that indicates whether the device is a smart TV. | false |
| Is Smartphone | %{wurfl_vcap_is_smartphone} | A Boolean that indicates whether the device is a smartphone. | true |
| Is Tablet | %{wurfl_cap_is_tablet} | A Boolean that indicates whether the device is a tablet. This is an OS-independent description. | true |
| Is Wireless Device | %{wurfl_cap_is_wireless_device} | A Boolean that indicates whether the device is considered a wireless device. | true |
| Marketing Name | %{wurfl_cap_marketing_name} | A string that indicates the device's marketing name. | BlackBerry 8100 Pearl |
| Mobile Browser | %{wurfl_cap_mobile_browser} | A string that indicates the browser used to request content from the device. | Chrome |
| Mobile Browser Version | %{wurfl_cap_mobile_browser_version} | A string that indicates the version of the browser used to request content from the device. | 31 |
| Model Name | %{wurfl_cap_model_name} | A string that indicates the device's model name. | s3 |
| Progressive Download | %{wurfl_cap_progressive_download} | A Boolean that indicates whether the device supports the playback of audio/video while it is still being downloaded. | true |
| Release Date | %{wurfl_cap_release_date} | A string that indicates the year and month on which the device was added to the WURFL database. Format: yyyy_mm |
2013_december |
| Resolution Height | %{wurfl_cap_resolution_height} | An integer that indicates the device's height in pixels. | 768 |
| Resolution Width | %{wurfl_cap_resolution_width} | An integer that indicates the device's width in pixels. | 1024 |
Location
These match conditions are designed to identify requests based on the requester's location.
| Name | Purpose |
|---|---|
| AS Number | Identifies requests that originate from a particular network. |
| Country | Identifies requests that originate from the specified countries. |
Origin
These match conditions are designed to identify requests that point to CDN storage or a customer origin server.
| Name | Purpose |
|---|---|
| CDN Origin | Identifies requests for content stored on CDN storage. |
| Customer Origin | Identifies requests for content stored on a specific customer origin server. |
Request
These match conditions are designed to identify requests based on their properties.
| Name | Purpose |
|---|---|
| Client IP Address | Identifies requests that originate from a particular IP address. |
| Cookie Parameter | Checks the cookies associated with each request for the specified value. |
| Cookie Parameter Regex | Checks the cookies associated with each request for the specified regular expression. |
| Edge Cname | Identifies requests that point to a specific edge CNAME. |
| Referring Domain | Identifies requests that were referred from the specified hostname(s). |
| Request Header Literal | Identifies requests that contain the specified header set to a specified value(s). |
| Request Header Regex | Identifies requests that contain the specified header set to a value that matches the specified regular expression. |
| Request Header Wildcard | Identifies requests that contain the specified header set to a value that matches the specified pattern. |
| Request Method | Identifies requests by their HTTP method. |
| Request Scheme | Identifies requests by their HTTP protocol. |
URL
These match conditions are designed to identify requests based on their URLs.
| Name | Purpose |
|---|---|
| URL Path Directory | Identifies requests by their relative path. |
| URL Path Extension | Identifies requests by their filename extension. |
| URL Path Filename | Identifies requests by their filename. |
| URL Path Literal | Compares a request's relative path to the specified value. |
| URL Path Regex | Compares a request's relative path to the specified regular expression. |
| URL Path Wildcard | Compares a request's relative path to the specified pattern. |
| URL Query Literal | Compares a request's query string to the specified value. |
| URL Query Parameter | Identifies requests that contain the specified query string parameter set to a value that matches a specified pattern. |
| URL Query Regex | Identifies requests that contain the specified query string parameter set to a value that matches a specified regular expression. |
| URL Query Wildcard | Compares the specified value(s) against the request's query string. |
Features
A feature defines the type of action that will be applied to the type of request identified by a set of match conditions.
Access
These features are designed to control access to content.
Note
Token auth is not generally available yet, but will be supported in a future release.
| Name | Purpose |
|---|---|
| Deny Access | Determines whether all requests are rejected with a 403 Forbidden response. |
| Token Auth | Determines whether Token-Based Authentication will be applied to a request. |
| Token Auth Denial Code | Determines the type of response that will be returned to a user when a request is denied due to Token-Based Authentication. |
| Token Auth Ignore URL Case | Determines whether URL comparisons made by Token-Based Authentication will be case-sensitive. |
| Token Auth Parameter | Determines whether the Token-Based Authentication query string parameter should be renamed. |
Caching
These features are designed to customize when and how content is cached.
| Name | Purpose |
|---|---|
| Bandwidth Parameters | Determines whether bandwidth throttling parameters (i.e., ec_rate and ec_prebuf) will be active. |
| Bandwidth Throttling | Throttles the bandwidth for the response provided by our edge servers. |
| Bypass Cache | Determines whether the request can leverage our caching technology. |
| Cache-Control Header Treatment | Controls the generation of Cache-Control headers by the edge server when External Max-Age feature is active. |
| Cache-Key Query String | Determines whether the cache-key will include or exclude query string parameters associated with a request. |
| Cache-Key Rewrite | Rewrites the cache-key associated with a request. |
| Complete Cache Fill | Determines what happens when a request results in a partial cache miss on an edge server. |
| Compress File Types | Defines the file formats that will be compressed on the server. |
| Default Internal Max-Age | Determines the default max-age interval for edge server to origin server cache revalidation. |
| Expires Header Treatment | Controls the generation of Expires headers by an edge server when the External Max-Age feature is active. |
| External Max-Age | Determines the max-age interval for browser to edge server cache revalidation. |
| Force Internal Max-Age | Determines the max-age interval for edge server to origin server cache revalidation. |
| H.264 Support (HTTP Progressive Download) | Determines the types of H.264 file formats that may be used to stream content. |
| Honor No-Cache Request | Determines whether an HTTP client's no-cache requests will be forwarded to the origin server. |
| Ignore Origin No-Cache | Determines whether our CDN will ignore certain directives served from an origin server. |
| Ignore Unsatisfiable Ranges | Determines the response that will be returned to clients when a request generates a 416 Requested Range Not Satisfiable status code. |
| Internal Max-Stale | Controls how long past the normal expiration time a cached asset may be served from an edge server when the edge server is unable to revalidate the cached asset with the origin server. |
| Partial Cache Sharing | Determines whether a request can generate partially cached content. |
| Prevalidate Cached Content | Determines whether cached content will be eligible for early revalidation before its TTL expires. |
| Refresh Zero-Byte Cache Files | Determines how an HTTP client's request for a 0-byte cache asset is handled by our edge servers. |
| Set Cacheable Status Codes | Defines the set of status codes that can result in cached content. |
| Stale Content Delivery on Error | Determines whether expired cached content will be delivered when an error occurs during cache revalidation or when retrieving the requested content from the customer origin server. |
| Stale While Revalidate | Improves performance by allowing our edge servers to serve stale client to the requester while revalidation takes place. |
| Comment | The Comment feature allows a note to be added within a rule. |
Headers
These features are designed to add, modify, or delete headers from the request or response.
| Name | Purpose |
|---|---|
| Age Response Header | Determines whether an Age response header will be included in the response sent to the requester. |
| Debug Cache Response Headers | Determines whether a response may include the X-EC-Debug response header which provides information on the cache policy for the requested asset. |
| Modify Client Request Header | Overwrites, appends, or deletes a header from a request. |
| Modify Client Response Header | Overwrites, appends, or deletes a header from a response. |
| Set Client IP Custom Header | Allows the IP address of the requesting client to be added to the request as a custom request header. |
Logs
These features are designed to customize the data stored in raw log files.
| Name | Purpose |
|---|---|
| Custom Log Field 1 | Determines the format and the content that will be assigned to the custom log field in a raw log file. |
| Log Query String | Determines whether a query string will be stored along with the URL in access logs. |
Optimize
These features determine whether a request will undergo the optimizations provided by Edge Optimizer.
| Name | Purpose |
|---|---|
| Edge Optimizer | Determines whether Edge Optimizer can be applied to a request. |
| Edge Optimizer – Instantiate Configuration | Instantiates or activates the Edge Optimizer configuration associated with a site. |
Origin
These features are designed to control how the CDN communicates with an origin server.
| Name | Purpose |
|---|---|
| Maximum Keep-Alive Requests | Defines the maximum number of requests for a Keep-Alive connection before it is closed. |
| Proxy Special Headers | Defines the set of CDN-specific request headers that will be forwarded from an edge server to an origin server. |
Specialty
These features provide advanced functionality that should only be used by advanced users.
| Name | Purpose |
|---|---|
| Cacheable HTTP Methods | Determines the set of additional HTTP methods that can be cached on our network. |
| Cacheable Request Body Size | Defines the threshold for determining whether a POST response can be cached. |
URL
These features allow a request to be redirected or rewritten to a different URL.
| Name | Purpose |
|---|---|
| Follow Redirects | Determines whether requests can be redirected to the hostname defined in the Location header returned by a customer origin server. |
| URL Redirect | Redirects requests via the Location header. |
| URL Rewrite | Rewrites the request URL. |
Web Application Firewall
The Web Application Firewall feature determines whether a request will be screened by Web Application Firewall.