Overview
You can use this document to review the settings in the Cache Handling section.
To access these settings:
- In the StackPath Control Portal, in the left-side navigation, click Sites.
- Locate and select the desired site.
- In the left-side navigation, click CDN.
- Expand Cache Handling.
Review available settings
| Setting | Description |
| Lifetime |
You can use this setting to determine how long assets should be cached in the CDN.
|
| Query string control |
You can use this setting to determine how StackPath will treat URLs that have a query string portion.
|
| Dynamic caching by header |
You can use this setting to extend the variables used to create a cache key by adding a specific request header to delivery specific content. Please note that negative pattern matching is not supported. |
| Gzip compression |
You can use this setting to compress and reduce the size of files.
|
| Content persistence |
You can use this setting to keep assets in cache after its lifetime has expired. This setting is ideal for:
With this setting, when a request is made, the CDN will attempt to fetch a new version of the asset from the origin. If the origin does not respond, then the CDN will deliver the expired asset from the origin. |
| Use vary header |
You can use this setting to allow the CDN to follow your origin’s Vary header during an origin pull request. Vary is an HTTP response header that allows different versions of the same asset to be cached with the same URL. The asset is selected based on the value of the specified request header. The Vary header uses the following syntax:
|
| Canonical header |
You can use this setting to instruct search engine which website's URL is the authoritative source to serve content. This setting allows search engines to produce uniform results, which helps to eliminate duplication versions in search results. This setting is useful for users interested in search engine optimization. |
| URL caching |
You can use this setting to cache URLs without file extensions. By default, the CDN caches static assets. When enabled, you can cache your website's entire asset collection. If your site uses the WAF, then this setting will be disabled. This setting is not compatible with the WAF. Note: |
Lifetime
You can use the Lifetime setting to configure how long assets (image, CSS file, JS file) are saved on the CDN's cache.
The Lifetime setting can reduce the number of calls to your origin server and increase the time assets are served from the CDN's cache.
After the lifetime setting expires, the CDN will fetch the assets from the origin server.
Review the following options:
| Setting | Description |
| Origin Controlled |
With this setting, the CDN will follow the origin headers that instruct the CDN to cache (or not cache) an asset, and for how long. |
| Specify CDN TTL |
With this setting, the CDN caches assets for a custom amount of time, from 30 seconds to 60 days. |
| Never Expire |
With this setting, assets remained cached on the CDN until a manual purge takes place. |
| Do Not Cache |
With this setting, assets are not cached; the CDN will pull assets from the origin server for each request. |
Based on the asset type and use cases, consider the following statements:
- Logos, images, CSS files, and JS files are generally unchanging and can have a longer lifetime.
- Pages that update frequently should have a shorter lifetime.
Query String Behavior
You can use the Query String Behavior setting to determine how StackPath will treat URLs that have a query string portion.
- A query string portion includes a question mark ( ? ), followed by a series of keyword/value pairs represented by "&x=y".
Review the following options:
| Setting | Description |
| Ignore Query String |
This setting ignores all query strings and caches pages with no query strings. With this setting, StackPath will cache https://example.com/file.txt?ver=1 and https://example.com/file.txt?ver=2 identically, based on which is requested first. |
| Cache All Query Strings | This setting caches all query strings separately. |
| Custom |
This setting allows specific query strings to be entered and cached separately. All other query strings not listed will be ignored and cached as the non-query version of the file.
|
Custom query string
Step 1: Add a custom query string
- In the drop-down menu, select Custom.
- In the field that appears, enter the query to cache separately.
- You can enter additional query string parameters in the same field.
- Click Save.
Step 2: Verify the custom query string
- Run a cURL command to an asset with 2 different versions.
- Run the cURL to the URL with -IH "pragma: x-hw-cache-all" appended to the end to display CDN cache keys within the header information.
- StackPath uses cache-key to differentiate cache types. If your rule was set up correctly, then the 2 different file versions will be cached under separate cache keys.
- Review the following example.
- A cURL command has been executed to a file with two different versions, version 2.2 and version 5.2. The X-HW-Cache-Key entry will display information to see if the files were cached separately.
- In the following image, note that X-HW-Cache-Key displays ver=5.2.
- In the following image, note that X-HW-Cache-Key displays ver=2.2.
- This information displayed in X-HW-Cache-Key verifies that the files were cached separately.
gzip compression
You can use the gzip setting to compress and reduce the size of files, which can help website performance because your users will fetch a reduced amount of data.
While gzip supports compression up to level 9, StackPath only supports up to level 6 because higher compression levels offer significantly diminished returns.
At a high level, StackPath:
- Fetches uncompressed assets from the origin,
- Compresses assets in cache, and then
- Serve the assets in a compressed, gzip format to browsers that can handle compressed assets.
Before you begin, consider the following statements:
- Assets already in cache will not be compressed when you enable gzip compression. As a result, you must first purge the host after you enable this feature to ensure that assets are compressed
- To learn how to purge, see How-To Purge files from the StackPath CDN.
- If an asset is not in cache, but needs to be compressed, then the CDN will fetch the asset from the origin and proxy the asset to the user immediately in a compressed format, while at the same time, the CDN will queue the asset for compressed in the background.
- Assets that are already compressed on the origin will be treated as normal assets and will be served to your users without any in-cache processing.