Advanced Caching
smoxy provides a CDN caching layer that stores copies of your. This guide covers all caching configuration options available on your site, including TTL, cache key composition, cache tags, and stale cache behavior.
Cache TTL (Time-to-Live)
The cache TTL controls how long smoxy caches your content before requesting a fresh copy from your origin server.
Minimum
300 seconds (5 minutes)
Maximum
604,800 seconds (7 days)
Default
604,800 seconds (7 days)
Cache Key
The cache key determines how smoxy identifies unique cached responses. Two requests with the same cache key return the same cached content. Understanding the cache key is essential for avoiding stale or incorrect content being served.
Components
URI
Always included
—
The request path is always part of the cache key
Host
host_vary_enabled
Derived from config
Include the request hostname in the cache key
Cookie
cookie_vary_enabled
Enabled
Vary the cache based on specific cookie values
Host Vary
When host vary is enabled, requests to different hostnames on the same site produce separate cache entries. This is important if multiple hostnames on the same site serve different content for the same path.
Example: With host vary enabled, www.example.com/about and shop.example.com/about are cached separately.
Cookie Vary
When cookie vary is enabled, smoxy includes specific cookie values in the cache key. This is useful for serving different content based on user preferences like language or region.
Configure which cookies to vary on by specifying cookie parameter names — a comma-separated list of cookie names.
Example: If you set cookie vary params to language, a visitor with language=en and a visitor with language=de receive separately cached responses.
Cookie name rules: Only alphanumeric characters, hyphens, and underscores are allowed in cookie names.
Excluded Query Parameters
By default, the full query string is part of the cache key. You can exclude specific query parameters that should not affect caching — typically tracking parameters that don't change the page content.
Configure a comma-separated list of parameter names to exclude.
Common exclusions: utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid
Parameter name rules: Only alphanumeric characters and hyphens are allowed.
Cache Tags
Cache tags allow you to group cached content and purge it selectively. Your origin server sends cache tag values in HTTP response headers, and smoxy uses these to associate cached content with tags. When you purge a tag, all cached content associated with that tag is invalidated.
Configuration
You can configure up to 4 cache tag headers. Each header has a name and a separator character.
Header name
The HTTP response header that contains tag values
Separator
The character that separates multiple tags within the header (single character)
Header name rules: Only alphanumeric characters and hyphens are allowed.
Defaults
smoxy comes preconfigured with two cache tag headers:
x-cache-tags
, (comma)
x-cache-tags: product-123,category-shoes
xkey
(space)
xkey: product-123 category-shoes
These defaults cover the most common cache tagging conventions. You can modify or add additional headers as needed.
Cache Tag Ignore List
You can configure a list of tag patterns to ignore. Tags matching these patterns are not stored, which can reduce cache metadata overhead for tags you never intend to purge.
Enter a comma-separated list of tag names or patterns.
Allowed characters: Alphanumeric, parentheses, braces, brackets, hyphens, underscores, periods, forward slashes, and asterisks.
Cache Control Header
When enabled, smoxy respects the Cache-Control header from your origin server's response. This allows your origin to control caching behavior on a per-response basis.
cache_control_header_enabled
Disabled
When disabled, smoxy uses the configured TTL for all cacheable responses regardless of the origin's Cache-Control header.
Important Considerations
TTL trade-off: A longer TTL means less origin traffic but slower content updates. A shorter TTL means fresher content but more origin requests. Choose based on how frequently your content changes.
Cookie vary carefully: Only vary on cookies that actually affect the response content. Varying on session IDs or tracking cookies effectively disables caching since every visitor gets a unique cache entry.
Exclude tracking parameters: Marketing parameters like UTM tags don't change your page content. Excluding them from the cache key significantly improves your cache hit rate.
Cache tags require origin cooperation: Your origin server must send the configured tag headers in its responses. smoxy reads these headers and stores the association — it does not generate tags automatically.
Last updated
Was this helpful?