Overview
You can use this document to learn how to create and manage custom CDN EdgeRules.
StackPath offers custom delivery rules with every CDN site. You can use EdgeRules to customize the behavior of the StackPath CDN.
Note:
EdgeRules only occur on CDN requests. If you use both a CDN and a WAF, then the EdgeRule response is added before the request is processed by the StackPath WAF. With this workflow, every CDN EdgeRule will work in conjunction with the WAF.
Note:
To use predefined EdgeRules, see Create, Manage, and Validate Predefined EdgeRules .
Review available condition types
Before you create a custom EdgeRule, review the available conditions that you can use to create a rule. After you configure a condition, you must select a rule type to create the triggering action.
In short, you can use this section to learn how to construct a rule.
URL
A URL condition will trigger a rule when the request URL matches the applied filters. This condition also includes any specified file-paths or file types. You can use wildcards, regex, or simple direct match.
| Target | Condition | Pattern | Example Match |
|---|---|---|---|
| All Requests | Matches | * | http://www.example.com/ https://www.example.com/blog/01 |
| Only HTTP Requests | Matches | wildcard: http://* | http://www.example.com/index.html |
| Only HTTPS Requests | Matches | wildcard: https://* | https://www.example.com/index.html |
| Exact URL Detection | Matches | https://example.com/wp-admin/ User "Matches" from the dropdown |
https://www.example.com/wp-admin/ |
| http://examples.com/pages/* (where * can be anything) | Matches Regular Expression | /http://example.com/[^/]+// | http://www.example.com/pages/blog/ |
| https://example.com/pages/*/article (where * can be anything) | Matches Regular Expression | /https://example.com/pages/[^\/]+/article/ | https://example.com/pages/vacations/article/ |
Header
A Header condition will trigger a rule when the request headers sent to the CDN matches the specified header. With a Header condition, wildcards, regex, or a simple match are available.
| Target | Condition | Pattern | Example Match |
|---|---|---|---|
| Any User Agent | Matches | User-Agent: * | All User Agents |
| Specific User Agents (example: mobile) | Matches Regular Expression | /User-Agent: *(iPhone|Android).*/ | iPhone and Android User Agents |
HTTP Method
An HTTP Method condition will trigger a rule when the selected HTTP method is used in the request. You can select multiple methods. All common HTTP methods are accepted.
Status Code
A Status Code condition will trigger a rule when the CDN receives the specified status code from the origin.
Cookie
A Cookie condition will trigger a rule based on the selected response cookie.
| Target | Matching Condition | Pattern | Example Match |
|---|---|---|---|
| Match if any cookie exists | Matches | * | cookie: foo=bar |
| match any cookies with a name starting with "wp" | Matches | wp* | Cookie: wp-value=1; id=123 |
| match when there is no cookie with a name starting with "wp" | Matches | !wp* | Cookie: fake-wp-value=1; id=123 no cookie at all |
| Match if the cookie name is wp and value is 1 | Matches | wp=1 | Cookie: wp=1 |
| match any cookies with a name starting with "wp" and with a value of 1 | Matches | wp*=1 | Cookie: wp-value=1; id=123 Cookie: wp-any=1; id=123 |
More examples for cookie matching can be found here: https://support.stackpath.com/hc/en-us/articles/360035190332-EdgeRules-Bypass-Cache-Using-a-Cookie-
Review available rule types
When you create a condition, you must apply a rule that will trigger the response.
Header Rules
- Add Response Header
- The header will be added to the response (CDN to End User)
- Key-Value, for example:
Key: X-XSS-Protection: Value: 1; mode:block
- Add Header to CDN
- This will add a header as a request to the CDN (User to CDN)
- Possible input value: Key-Value, for example:
Key: X-Mobile Value: Ture
- Add Header to Origin
- Add Header from CDN to your origin server
- Possible input value: Key-Value, for example:
Key: X-Mobile: Value: True
- Modify Header
- Modify the value of an existing header
- Possible input value: Regex, for example:
regex:(?i)x-amz*.*
- Remove Header
- Remove an existing response header
- Possible input value: Name = value, for example:
User-Agent: new agent
Caching Rules
- Cache
- Configure the Caching TTL for a selected Filter
- Do Not Cache
- Bypass cache for the configured filter
- Never Expire
- The resource (matched condition) will be cached indefinitely
Redirect Rules
Force a 301 redirect when the conditions are met.
Possible input value: Full HTTP address (e.g. https://www.example.com)
URL Signing
URL Signing allows you to protect your CDN assets by ensuring only authorized end users are able to access them and to set an expiration time on a given URL.
URL Filters
It's possible to use wildcards, regex and globbing in your Custom EdgeRules to create patterns that match specific URLs allowing you to create a CDN configuration to your specific requirements.
Here are some examples of options for these filters:
| Pattern | Description | Example Matches |
wildcard: http://* |
Only HTTP requests | http://abcdef12.stackpathcdn.com/index.html |
wildcard: https://* |
Only HTTPs requests | https://abcdef12.stackpathcdn.com/index.html |
wildcard: *://foo.com/* |
HTTP/HTTPs request for foo.com HostName | http://foo.com/index.html, https://foo.com/static/js/anydirORfile |
wildcard: *://*.html |
Any request for HTML files | http://abcdef12.stackpathcdn.com/index.html, https://example.com/index.html |
wildcard: !*://*.txt |
Any request except TXT files |
http://abcdef12.stackpathcdn.com/index.html, https://example.com/static/img/index.jpg |
wildcard: *://.html,*://*.js |
Any HTML file or JS files | http://abcdef12.stackpathcdn.com/index.html, https://example.com/static/js/jquery.js |
wildcard: !*://*.txt,!*://*.jpg |
Any request except TXT and JPG files | http://abcdef12.stackpathcdn.com/index.html, https://example.com/static/img/index.jpg |
wildcard: *://abcdef12.stackpathcdn.com/static/*.html |
Any request for HTML file under Directory (recursive) "static" | http://abcdef12.stackpathcdn.com/static/index.html http://abcdef12.stackpathcdn.com/static/foo.html http://abcdef12.stackpathcdn.com/static/2/index.html http://abcdef12.stackpathcdn.com/static/2/st/index.html |
glob: *://abcdef12.stackpathcdn.com/static/*.html |
Any request for HTML file under Directory (one level) "static" | http://abcdef12.stackpathcdn.com/static/index.html, https://abcdef12.stackpathcdn.com/static/foo.html |
regex: /.*\d/index.html/ |
HTTP/HTTPs request for index.html under directory of Numbers | http://abcdef12.stackpathcdn.com/static/1/index.html, https://abcdef12.stackpathcdn.com/static/20/100/index.html |
When applying URL filters, do note that if the protocol is specified in a pattern it will be ignored once the file has been cached by the CDN.
For example, patternhttp://example.com/jquery.js, then any requests tohttps://example.com/jquery.jswill be proxied. However, once a request tohttp://example.com/jquery.jshas been made,jquery.jswill be cached and a cached response will be returned for subsequent requests tohttps://example.com/jquery.js.
Variables
Variables allow for dynamic rules to be made without needing new rules for every possible permutation of a request or response. Use Variables for advanced fine-tuning of the delivery of your content over the StackPath CDN Network.
Available Variables:
| General Expansion Variables | |
| %server.ip% | The Server IP |
| %server.fqdn% | The Server Host Name |
| %server.name% | The Server Name |
| %server.pop% | The Server Pop |
| %server.region% | The Server Region |
| %server.platform% | The Server Platform Name |
| %server.epoch% | The Server Time |
| %client.ip% | The Client IP |
| %client.request.protocol% | The protocol of the request (http/https) |
| %client.request.host% | hostname in the Host header of the request |
| %client.request.fullurl% | Full URL of request (including protocol and host name) |
| %client.request.fullfilepath% | Full File Path from request (without qs param) |
| %client.request.params% | Query Parameters from request (with leading ?) |
| %client.request.pathonly% | Only Path (without filename) from request |
| %client.request.filename% | Only filename from request |
| %client.geoip.areaCode% | The telephone area code |
| %client.geoip.city% | The city or town name |
| %client.geoip.continentCode% | The two-character code for the continent |
| %client.geoip.countryCode% | The two-character ISO-3166-1 country code |
| %client.geoip.countryCode3% | The three-character country code |
| %client.geoip.countryName% | The country name |
| %client.geoip.dmaCode% | Designated Market Area code |
| %client.geoip.latitude% | The latitude |
| %client.geoip.longitude% | The longitude |
| %client.geoip.postalCode% | The postal code |
| %client.geoip.regionCode% | A two character ISO-3166-2 or FIPS 1-=4 code for state/region |
| %client.geoip.regionName% | The region name |
| %client.geoip.timeZone% | The time zone is generated from IANA time zone database (e.g., America/New_York) |
| %query.separator% | The query separator character |
| %function.random(min, max)% | Random Number Generator |
| Request Receipt Expansion Variables | |
| %delivery.firstByteDuration% | Time duration of first byte |
| %delivery.contentTransferDuration% | Duration in milliseconds of the download. Ex: 57 |
| %delivery.bytesFromCache% | The Bytes from the cache for the delivery |
| %delivery.contentBytesServed% | Total Content Bytes served |
| %delivery.sendResult% | success | abort, where success means the CDN successfully delivered a response to the client, regardless of the HTTP status code. |
| %delivery.totalBytesServed% | Total bytes downloaded to the client. Ex: 5140 |
| %delivery.cacheHit% | Whether or not there was a cache hit |
| %delivery.firstByteServed% | The Time for the first byte served |
| %delivery.lastByteServed% | The Time for the last byte served |
| %delivery.attemptedBytesServed% | Number of bytes that the CDN attempted to download. Ex: 5140 |
| %delivery.filesize% | On-disk size of the requested asset. Ex: 125554 |
| %client.request.params% | Query Parameters from request (with leading ?) |
| %client.request.headers.range.value% | Value of the Range header in the client request if it exists. Ex: bytes=5000-9999 |
| %client.request.host% | The hostname in the Host header of the request |
| %client.request.filename% | Only filename from request |
| %client.request.endTime% | Unix timestamp marking the end of the request. Ex: 1392413133 |
| %client.request.method% | The client request method |
| %client.request.fullUrl% | Full URL of request (including protocol and host name) |
| %client.request.protocol% | The protocol of the request (http/https) |
| %client.request.pathOnly% | Only Path (without filename) from request |
| %client.request.fullFilePath% | Full File Path from request (without qs param) |
| %client.request.http.version% | The HTTP Version for the client request |
| %client.request.startTime% | Unix timestamp marking the beginning of the request. Ex: 1392413033 |
| %client.geoip.countryCode3 | The three-character country code |
| %client.geoip.timeZone% | The time zone taken from IANA time zone database (eg America/New_York) |
| %client.geoip.regionName% | The region name |
| %client.geoip.city% | The city or town name |
| %client.geoip.countryCode% | The two-character ISO-3166-1 country code |
| %client.geoip.areaCode% | The telephone area code |
| %client.geoip.postalCode% | The postal code |
| %client.geoip.regionCode% | A two character ISO-3166-2 or FIPS 1-=4 code for state/region |
| %client.geoip.dmaCode% | The Designated Market Area code |
| %client.geoip.continentCode% | The two-character code for the continent |
| %client.geoip.countryName% | The country name |
| %client.geoip.latitude% | The latitude |
| %client.geoip.longitude% | The longitude |
| %client.ip% | IP in dot-notation of the client. Ex: 10.10.5.104 |
| %client.response.headers% | The response headers from the client |
| %origin.request.params% | The parameters for the origin request |
| %origin.request.ip% | The IP address for the origin request |
| %origin.request.host% | Origin host name and port for requests that resulted in an origin pull. Example: myorigin.com:8000 |
| %origin.request.hostOnly% | The host name for the origin request |
| %origin.request.pathOnly% | Only the File path for the origin request |
| %origin.request.port% | The port for the origin request |
| %origin.request.filename% | The filename for the origin request |
| %origin.request.fullFilePath% | The Full File Path for the origin request |
| %origin.request.protocol% | The protocol of the origin request |
| %origin.request.fullUrl% | The Full url for the origin request |
| %origin.response.firstByteDuration% | The first bite duration for the origin response |
Create custom EdgeRules
- In the StackPath Control Portal, in the left-side navigation menu, click Sites.
- Locate and select the desired site.
- This action will refresh the portal.
- In the left-side navigation menu, click EdgeRules.
- Scroll down to Delivery Rules, and then click Add Delivery Rule.
- In Rule Name, enter a descriptive name.
- Use the If / Then feature to create conditions and triggers for your EdgeRules.
- Conditions are requirements that trigger the EdgeRule to activate.
- You can add multiple conditions for a single rule.
- The rule will only trigger if all conditions are met.
- To learn the different parts of the conditions and triggers, see Review available conditions.
- Click Save Rule.
Use curl to validate EdgeRules
Most custom EdgeRules will apply an external change, such as a visible response header or redirect. As a result, to troubleshoot, you can use Curl requests in a terminal or within a browser with network tools.
You can use the -I option to display configured headers to verify if rules are triggered correctly.
The following example verifies that a configured header executes when the rule is triggered. Note that the example uses the -A option to specify if an iPhone has connected.
EdgeRule in the portal:
Validation from the command line:
Use browsers to validate EdgeRules
Most custom EdgeRules will apply an external change, such as a visible response header or redirect. As a result, to troubleshoot, you can use Curl requests in a terminal or within a browser with network tools.
You can also use browsers to verify the behavior of an EdgeRule.
The following example verifies that a configured header executes when the rule is triggered.
EdgeRule in the portal:
Validation from the browser:
