Apache mod_cache: Managing CacheQuickHandler and CacheLock in Apache 2.4

In Apache HTTP Server 2.4, mod_cache provides RFC 2616 compliant HTTP caching. Two key directives in the documentation govern request phase handling and backend concurrency: CacheQuickHandler and CacheLock. Understanding their documented behaviors allows administrators to choose when to bypass standard processing phases and when to serialize backend revalidations to protect origin servers.

CacheQuickHandler: Quick Handler vs Normal Handler Phase

Under the default mode of operation, mod_cache runs inside the server’s quick handler phase. The documentation states that this phase short-circuits the majority of server processing and represents the most performant mode of operation for a typical server, acting as if a caching proxy server were bolted to the front of the web server.

Because running in the quick handler phase avoids the majority of server processing, it bypasses subsequent request handling phases. When content requires per-request processing or is subject to authorization, this mode prevents those checks from running on cached requests.

When an administrator sets CacheQuickHandler off, the cache operates as a normal handler. In normal handler mode, the request is subject to the full sequence of server request handling phases, allowing authentication and authorization checks to execute.

Controlling Filter Placement with the CACHE Filter

When CacheQuickHandler off is configured, administrators can insert the CACHE filter at a chosen location in the output filter chain. This allows caching unpersonalized or uncompressed content prior to downstream transformations.

For example, the documentation illustrates placing the CACHE filter before server-side includes and compression:

# Run cache as a normal handler
CacheQuickHandler off

# Cache content before mod_include and mod_deflate
AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html

In this sequence, content is cached before mod_include parses tags or applies personalization and before mod_deflate applies compression. The documentation notes that if the CACHE filter is specified more than once in the filter chain, the last instance applies. Additionally, if the location of the CACHE filter in the filter chain is changed, the administrator may need to flush the cache to maintain consistent data.

CacheLock: Mitigating the Thundering Herd During Revalidation

When a cached entry becomes stale, mod_cache sends a conditional request to the backend server to confirm whether the cached entry is still fresh and receive an updated entity if not. A small but finite amount of time elapses between when an entry becomes stale and when the revalidation completes.

The CacheLock directive addresses this window:

• When CacheLock is suitably configured and active, a lock is acquired during revalidation.
• During the lifetime of the lock, the second and subsequent incoming requests return stale cached data instead of contacting the backend, keeping the thundering herd at bay.
• Under RFC 2616, responses returning stale data while an existing stale entry is refreshed include a Warning HTTP header with a 110 response code.

CacheLock Configuration, Timeouts, and Client Overrides

Apache documentation provides directives to configure lock storage and maximum lock duration:

<IfModule mod_cache.c>
    CacheLock on
    CacheLockPath "/tmp/mod_cache-lock"
    CacheLockMaxAge 5
</IfModule>

The CacheLockPath directive specifies the path where lock files are located. CacheLockMaxAge sets the maximum age for a lock in seconds and defaults to 5 seconds. Once this maximum age is reached, the lock is removed, allowing a new request to create a lock if refreshing has not completed.

Documented operational boundaries include:

• Locks are hints: Locks are used as hints to enable the cache to be more gentle on backend servers.
• Client override: If a client sends a request with a Cache-Control header forcing a reload (such as no-cache), any active lock is ignored, the client’s request is honored immediately, and the cached entry is refreshed.
• Stale on error: By default in mod_cache, when an attempt to refresh stale data returns an HTTP status code of 500 or above, the cache returns stale data accompanied by a Warning HTTP header with a 111 response code (governed by CacheStaleOnError, which defaults to on).

Operational Roles: CacheQuickHandler vs CacheLock

CacheQuickHandler and CacheLock govern distinct stages of cache handling in mod_cache:

• CacheQuickHandler controls the server execution phase (quick handler vs normal handler). Running as a quick handler provides maximum performance but avoids authorization and filter manipulation; disabling it routes requests through standard authentication, authorization, and custom CACHE filter positions.
• CacheLock manages concurrent backend revalidation when cached entries become stale. When configured, it serves stale data with a 110 Warning header to concurrent requests during the lock window, while respecting client reload overrides.

Research Method and Limitations

This technical explainer was prepared solely using the provided public documentation excerpts from the Apache HTTP Server Version 2.4 mod_cache manual and public tutorial coverage from DigitalOcean. Competing coverage from DigitalOcean was unavailable in detail because the retrieved excerpt contained only general site portal text. In addition, the supplied Apache documentation contains truncated sections, omitting full directive syntax tables, directive-scope details, and explicit default settings for directives such as CacheLock and CacheLockPath. No live server benchmarks, performance tests, or hands-on environments were evaluated.

Source references

• httpd.apache.org documentation