http-cache-turbo #
Built-in full-page micro-cache for nginx — Varnish-style page caching without Varnish, served straight from shared memory; must be the last dynamic module loaded. Full write-up: cache pages in nginx with cache-turbo →.
Source: our fork on GitHub
Read more: deep-dive article on deb.myguard.nl
Directives
cache_turbo #
syntax: cache_turbo 1 arg; · context: server, location
Enables cache-turbo in this location and binds it to a shared-memory zone; accepts "off" or an optional "auto" backend-preset shorthand.
cache_turbo_admin #
syntax: cache_turbo_admin 1 arg; · context: location
Turns the location into an admin/control endpoint for the named cache_turbo shared-memory zone.
cache_turbo_auto_vary #
syntax: cache_turbo_auto_vary on | off (on/off flag); · context: server, location
If you both turn on > cache_turbo_auto_vary and add the matching cache_turbo_normalize_vary > bucket (e.g.
cache_turbo_autotune #
syntax: cache_turbo_autotune on | off (on/off flag); · context: server, location
What it will never do is extend the fresh TTL — a client is never told "fresh" about content older than your cache_turbo_valid contract. > Load-adaptation is folded into cache_turbo_autotune on — turning autotune > on enables all three.
cache_turbo_backend #
syntax: cache_turbo_backend 1+ args; · context: server, location
Composes one or more CMS auto-classify presets (generic, wordpress, woocommerce, joomla) by setting bits in backend_presets.
cache_turbo_backend_prefix #
syntax: cache_turbo_backend_prefix 1 arg; · context: server, location
Scoping the location does not help (it routes requests, it does not rewrite r->uri): declare the mount with cache_turbo_backend_prefix /forums/; (see the vhost example in docs/xenforo.md). ### Interactions and safety - Implies cache_turbo_cache_control honor (unless you set it explicitly).
cache_turbo_background_update #
syntax: cache_turbo_background_update on | off (on/off flag); · context: server, location
Boolean directive — set to "on" or "off".
cache_turbo_beta #
syntax: cache_turbo_beta 1 arg (integer); · context: server, location
Repeatable. | | cache_turbo_beta N | server, location | preset (1000) | Refresh eagerness, ×1000 (1000 = 1.0).
cache_turbo_bypass #
syntax: cache_turbo_bypass 1+ args; · context: server, location
Sets a predicate that, when it evaluates true, skips serving from cache and forwards the request to origin.
cache_turbo_bypass_uri #
syntax: cache_turbo_bypass_uri 1+ args; · context: server, location
Add cache_turbo_bypass_uri /api; if you serve it. ‡ edit, submit, delete, protect, unprotect, purge, rollback, revert, watch, unwatch, markpatrolled, mcrundo, mcrrestore — the mutating half of ActionFactory::CORE_ACTIONS.
cache_turbo_cache_control #
syntax: cache_turbo_cache_control 1 arg; · context: server, location
Only active under cache_turbo_cache_control honor. - no-store veto — a targeted no-store/private/max-age=0 refuses the shared store the same way a plain Cache-Control: no-store does.
cache_turbo_key #
syntax: cache_turbo_key 1 arg; · context: server, location
Compiles a complex-value expression used to build the cache key for matching requests.
cache_turbo_l2_negative_ttl #
syntax: cache_turbo_l2_negative_ttl 1 arg; · context: server, location
Changes eviction ORDER only -- never what is served, what is cacheable, or any freshness decision. | | cache_turbo_l2_negative_ttl N | server, location | 0 (off) | Remember for N seconds that an L2 (Redis/memcached) GET missed a key, so the next cold request for it skips the L2 round-trip instead of paying a full RTT to be told "absent" again.
cache_turbo_lock #
syntax: cache_turbo_lock on | off (on/off flag); · context: server, location
Use it with cache_turbo_lock on, not instead of it: min_uses decides what is worth storing, single-flight decides how many requests reach the origin while a key is being filled. ## Zone sizing under LRU pressure The cache zone is a single shared-memory heap with a flat LRU (least-recently-used) eviction list.
cache_turbo_lock_timeout #
syntax: cache_turbo_lock_timeout 1 arg (duration in ms); · context: server, location
Duration in milliseconds; accepts ms / s / m suffixes.
cache_turbo_lock_ttl #
syntax: cache_turbo_lock_ttl 1 arg (duration in seconds); · context: server, location
Higher = refresh sooner/more often. | | cache_turbo_lock_ttl TIME | server, location | preset (5s) | Single-flight window: once one refresh is claimed, others serve stale until it finishes.
cache_turbo_max_size #
syntax: cache_turbo_max_size 1 arg (size (k/m/g)); · context: server, location
Size in bytes; accepts k / m / g suffixes.
cache_turbo_memcached #
syntax: cache_turbo_memcached 1+ args; · context: http, server, location
Selects the memcached L2 backend with host:port plus prefix=/timeout= params; mutually exclusive with cache_turbo_redis.
cache_turbo_min_uses #
syntax: cache_turbo_min_uses 1 arg; · context: server, location
If you want the aggressive TTLs without the admission gate, set cache_turbo_min_uses 1 explicitly; an explicit directive beats the band like any other knob.
cache_turbo_no_store #
syntax: cache_turbo_no_store 1+ args; · context: server, location
Sets a predicate that, when true, prevents the response from being stored in cache.
cache_turbo_normalize_strip #
syntax: cache_turbo_normalize_strip 1+ args; · context: server, location
Appends extra denylist parameter-name patterns to strip when normalizing the cache key's query string.
cache_turbo_normalize_vary #
syntax: cache_turbo_normalize_vary 1+ args; · context: server, location
Selects which Vary buckets (encoding and/or device) are appended to the normalized cache-key arguments.
cache_turbo_preset #
syntax: cache_turbo_preset 1 arg; · context: server, location
Selects a named default-tuning band (micro, conservative, balanced, aggressive) for cache knobs not explicitly overridden.
cache_turbo_purge #
syntax: cache_turbo_purge on | off (on/off flag); · context: server, location
Unset ⇒ inert. | | cache_turbo_purge on | server, location | off | Allow a PURGE <uri> request to drop that URI's entry from L1 (+L2).
cache_turbo_redis #
syntax: cache_turbo_redis 1+ args; · context: http, server, location
Configures the Redis L2 backend from a redis(s):// DSN or host:port, with optional auth/db/TLS/prefix/timeout params.
cache_turbo_require_header #
syntax: cache_turbo_require_header 1 arg; · context: server, location
cache_turbo_require_header inverts the default on a location — from cacheable unless something vetoes it to uncacheable unless the origin affirms it: The response is stored only if it carries that header with an affirmative value — yes, 1, or on, case-insensitive, matched whole.
cache_turbo_scan_resistant #
syntax: cache_turbo_scan_resistant 1 arg; · context: server, location
It is 184 whether or not cache_turbo_scan_resistant is enabled -- the fields exist unconditionally, they are simply never set to a non-zero value when the feature is off.
cache_turbo_stale_mult #
syntax: cache_turbo_stale_mult 1 arg; · context: server, location
Caps backend regens to ~one per cycle. | | cache_turbo_stale_mult N | server, location | preset (4 balanced) | Stale window as a multiple of the fresh TTL: an entry stays serveable as STALE until cache_turbo_valid * N.
cache_turbo_suppress_native #
syntax: cache_turbo_suppress_native on | off (on/off flag); · context: server, location
The default cache key's args component. | | $cache_turbo_active | 1 when cache-turbo is engaged for this request (enabled, cacheable method, main request) and cache_turbo_suppress_native on; else 0.
cache_turbo_tag #
syntax: cache_turbo_tag 1 arg; · context: server, location
Compiles a complex-value expression producing whitespace/comma-separated cache tags recorded against the stored object for later purge.
cache_turbo_test_force_file_buf #
syntax: cache_turbo_test_force_file_buf on | off (on/off flag); · context: server, location
Boolean directive — set to "on" or "off".
cache_turbo_test_restore_alloc_fail #
syntax: cache_turbo_test_restore_alloc_fail on | off (on/off flag); · context: server, location
Boolean directive — set to "on" or "off".
cache_turbo_valid #
syntax: cache_turbo_valid 1+ args; · context: server, location
Sets the fresh-cache TTL, either as the default/200 TTL or per listed HTTP status code(s).
cache_turbo_zone #
syntax: cache_turbo_zone 2 args; · context: http
Declares a named shared-memory zone (name=NNN and size) used to hold cache_turbo's cache state.
Example
load_module modules/ngx_http_cache_turbo_module.so;
http {
# ── http context only ───────────────────────────────────────────────
cache_turbo_zone name=ct 256m; # declare the shm zone (min 8 pages)
# L2 tier — pick AT MOST ONE of the next two (mutually exclusive per block).
# Both also valid at server/location scope; declared here they're inherited.
cache_turbo_redis redis://127.0.0.1:6379/0 prefix=ct: timeout=250ms
tls=off tls_verify=on keepalive=0 keepalive_timeout=60s;
# cache_turbo_memcached 127.0.0.1:11211 prefix=ct: timeout=250ms
# keepalive=0 keepalive_timeout=60s;
server {
listen 80;
server_name example.com;
location / {
# ── turn it on ──────────────────────────────────────────────
cache_turbo ct; # bind zone "ct" (or: off)
cache_turbo_backend wordpress; # wordpress|woocommerce|joomla|xenforo|discourse|phpbb|drupal|mediawiki|magento|shopware6|ghost|wagtail|kirby|typo3|invision|smf|vanilla|punbb|phorum|yabb|mybb|vbulletin (stackable, '|' or spaces); 'none' = off; implies cache_control honor
# ── what is "the same page" ─────────────────────────────────
cache_turbo_key $host$uri$cache_turbo_normalized_args; # the default
cache_turbo_normalize_strip sid sessionid "tmp_*"; # extra args to drop (trailing * = prefix; bare * = all)
cache_turbo_normalize_vary encoding device; # add variant buckets to the key
# ── freshness / staleness ───────────────────────────────────
cache_turbo_preset balanced; # micro|conservative|balanced|aggressive — sets the 4 knobs below
cache_turbo_valid 60s; # 200 TTL; 0 = cache forever
cache_turbo_valid 301 302 308 1h; # repeatable: cache redirects
cache_turbo_valid 404 410 1m; # negative caching
cache_turbo_beta 1000; # refresh eagerness ×1000
cache_turbo_lock_ttl 5s; # single-flight refresh window
cache_turbo_cache_control respect; # respect | honor (take TTL from response CC/Expires) | ignore (discard response CC)
cache_turbo_background_update on;
…