Configuration: HTTP cache

This page documents the cache directive for configuring Ferron’s in-memory HTTP response cache. The cache stores complete GET response representations, serves HEAD from cached GET metadata, follows standard HTTP caching semantics by default, and understands a subset of LiteSpeed Cache response headers for LSCache-aware applications.

The cache applies to final HTTP responses produced by static file serving, reverse proxying, and other response stages.

cache

{
    cache {
        max_entries 2048
    }
}

example.com {
    cache {
        max_response_size 1048576
        litespeed_override_cache_control false
        vary Accept-Encoding Accept-Language
        ignore Set-Cookie
    }

    location /admin {
        cache false
    }
}

At HTTP host scope, cache can be written either as a block or as a boolean flag. Block form enables caching for that scope and configures nested directives. Boolean form is useful when you want to enable or disable inherited caching without changing any nested settings.

Global cache block

Use the global cache { ... } block to configure shared cache capacity.

Configuration example:

{
    cache {
        max_entries 4096
    }
}

HTTP host cache block

Use the HTTP host cache { ... } block to enable caching and tune how responses are stored for that host or matching location.

Configuration example:

example.com {
    cache {
        max_response_size 2097152
        litespeed_override_cache_control
        emit_litespeed_headers
        vary Accept-Encoding Accept-Language
        ignore Set-Cookie
    }
}

Boolean cache form

Behavior

Cache eligibility

• Only GET and HEAD requests perform cache lookups.
• HEAD requests reuse cached GET representations and return only headers.
• Non-GET responses are not stored, but they may still trigger LSCache-compatible purge headers.
• Responses with Vary: * are never stored.
• Built-in error responses generated after the main HTTP pipeline are not currently stored.

PURGE method cache invalidation

When the purge_method subdirective is enabled, Ferron accepts the PURGE HTTP method for cache invalidation. A PURGE request to a specific URL removes all cached entries (both public and private) matching that URL, causing subsequent requests to fetch fresh content.

Security:

PURGE requests must be either:

• Authenticated via HTTP basic authentication (the basic_auth directive), or
• Originating from an IP address matching the purge_allowed_ips list.

If neither condition is met, Ferron returns a 403 Forbidden response. This ensures that cache purging is never accidentally left unsecured.

Example using trusted IP list:

example.com {
    cache {
        purge_method
        purge_allowed_ips "127.0.0.1" "10.0.0.0/8"
    }
}

Example using basic authentication:

example.com {
    cache {
        purge_method
    }
    basic_auth {
        users {
            user "$argon2id$..."
        }
    }
}

Example request:

PURGE /blog/post-123 HTTP/1.1
Host: example.com

Public and private cache behavior

• Public responses containing Set-Cookie are not stored.
• Private responses are partitioned by client context. Ferron currently uses the client IP address, the authenticated username when available, and detected private cookies.
• If Ferron cannot determine a narrower private cookie set, it falls back to all request cookies for the private cache key.

LSCache-compatible response headers

When the cache module is enabled, Ferron understands the following response headers from upstream applications and origin handlers:

Observability

Metrics

The cache module emits the following metrics:

Logs

• DEBUG — logged when Ferron skips cache storage because X-LiteSpeed-Vary: value=... is not supported yet.
• DEBUG — logged when Ferron skips cache storage because the response body exceeds cache.max_response_size.
• DEBUG — logged when Ferron performs a purge through X-LiteSpeed-Purge.
• DEBUG — logged when Ferron performs a purge through PURGE HTTP method.
• DEBUG — logged when Ferron receives an LSCache stale purge marker and falls back to a hard purge.

Structured logs

Best practices

The following best-practice checks are reported by ferron doctor for directives on this page.

• litespeed_override_cache_control — This makes LiteSpeed cache headers override standard HTTP cache policy. Enable only for applications that require LiteSpeed-compatible semantics.
• purge_method without access control — Cache purging enabled without purge_allowed_ips or basic_auth in the same scope allows unauthenticated cache invalidation.
• purge_allowed_ips with wildcard — Allowing every source address for cache purging should be restricted to trusted operators or internal networks.