Varnish req.* vs obj.* bans: why req-level bans never leave the list

req.* bans persist on the ban list because the ban lurker thread has no request context and cannot evaluate them asynchronously. The list grows, lookup latency degrades across every request, and the fix is the same in nearly every case: rewrite req-based bans as obj-based bans so the lurker can process them in the background. For the broader failure pattern, see Varnish ban list growing.

What it is and why it matters

A ban is a regex-based cache invalidation rule. When you issue ban('req.url ~ "/product/123"') or ban('obj.http.x-url ~ "/product/123"'), Varnish adds the expression to a linked list. Every cached object is tested against outstanding bans, either by the lurker in the background or by a worker thread at lookup time.

The distinction:

• obj.* bans reference fields stored on the cached object: obj.status, obj.http.*, obj.ttl. The lurker can evaluate these because everything it needs lives in the object itself.
• req.* bans reference fields from the incoming request: req.url, req.http.host, req.http.cookie. The lurker has no access to any request. These bans are evaluated only when a worker thread performs a cache lookup against a specific candidate object.

obj.* bans are processed and removed asynchronously by the lurker. req.* bans stay on the list until every object older than the ban has been tested at lookup time. If objects are long-lived and seldom accessed, req.* bans accumulate indefinitely.

How it works

flowchart LR
    A["Ban added to list"] --> B{"References req.* ?"}
    B -- yes --> C["Lurker skips (no request context)"]
    C --> D["Ban persists on list"]
    D --> E["Worker tests at lookup time"]
    E --> F{"All older objects tested?"}
    F -- no --> D
    F -- yes --> G["Ban removed"]
    B -- no --> H["Lurker walks object heap"]
    H --> I["Evicts matching objects"]
    I --> J["Ban completed and removed"]

The ban lurker runs as a background thread. It wakes on a timer controlled by ban_lurker_sleep (default 0.010 seconds) and, after ban_lurker_batch (default 1000) objects, sleeps for ban_lurker_sleep. It only touches bans and objects older than ban_lurker_age (default 60 seconds). Freshly cached objects are skipped to avoid contention with active lookups.

When the lurker encounters an obj.* ban, it evaluates the expression against each object and evicts matches. Once all objects older than the ban have been tested and none remain matching, the ban is marked completed and eventually removed from the front of the list.

When the lurker encounters a req.* ban, it skips it. There is no req struct in the lurker thread. The ban stays on the list and is tested only when a worker thread performs a cache lookup: the worker evaluates the ban expression against the incoming request and the candidate object. If the object matches, it is not served. The ban remains outstanding for all other objects.

Watermark cleanup and why req.* bans block the list

Ban list cleanup is a watermark mechanism. A ban can only be removed from the front of the list once all objects older than it have been tested. The oldest untested object determines how far the watermark can advance.

For obj.* bans, the lurker does this testing in the background. For req.* bans, it cannot. Testing only happens at lookup time, one object at a time, when a request happens to hit that specific cached object. Objects with long TTLs that are rarely requested may never be tested. The req.* ban hangs above them indefinitely.

A req.* ban near the front of the list also blocks removal of obj.* bans behind it. The lurker may have fully processed an obj.* ban (all objects tested, none matched), but if a req.* ban above it cannot be completed, the watermark cannot advance past it. The completed obj.* ban stays on the list too.

The ban_any_variant change in Varnish 8.0+

In Varnish 8.0, the default value of ban_any_variant changed to 0. During a lookup, only the matching variant of an object is evaluated against the ban list. Variants that are rarely requested may never get tested against req.* bans, accelerating accumulation. Teams upgrading to 8.0+ who rely on req.* bans may see ban lists grow unexpectedly.

Varnish 8.0 also introduced obj.last_hit, allowing operators to ban objects that have not been accessed since a given timestamp. This is useful for cleaning up after req.* bans by evicting untouched objects.

The rewrite pattern

The fix is to rewrite req-based bans as obj-based bans. req.url and req.http.host are request-time data and are not stored on the cached object by default. To ban on them using obj.*, copy the request data into response headers at fetch time in vcl_backend_response:

sub vcl_backend_response {
    set beresp.http.x-url = bereq.url;
    set beresp.http.x-host = bereq.http.host;
}

Then issue bans against the stored headers:

# obj-based ban: the lurker can process this proactively
varnishadm ban 'obj.http.x-url ~ "/product/123"'

The lurker now walks the heap, evaluates obj.http.x-url against each object, evicts matches, and removes the ban once all older objects have been tested.

Strip the helper headers from client responses to avoid leaking internal path data:

sub vcl_deliver {
    unset resp.http.x-url;
    unset resp.http.x-host;
}

A common mistake: issuing ban 'obj.http.url ~ "pattern"' without first setting beresp.http.url in VCL. The ban is added to the list but never matches anything because the header does not exist on stored objects. It stays on the list until the objects it covers expire naturally.

Where this shows up in production

• CMS publishing hooks. A CMS issues a ban on every publish event using req.url. Under heavy publishing activity, bans accumulate faster than objects are accessed at lookup time.
• Per-URL invalidation scripts. An application bans individual URLs on each content change rather than using pattern-based or key-based invalidation. Each ban references req.url and the lurker cannot process it.
• Long-TTL objects with low request rates. Objects cached for hours or days that are rarely accessed. req.* bans covering these objects persist because the objects are never tested at lookup time.
• Post-upgrade accumulation. Teams upgrading to Varnish 8.0+ who rely on req.* bans see ban lists grow due to the ban_any_variant default change.

Common misuses

Signals to watch

To inspect the live ban list and identify whether entries reference req.* or obj.*:

# List all outstanding bans with timestamps and expressions
varnishadm ban.list

# Count bans by type
varnishstat -1 -f MAIN.bans -f MAIN.bans_req -f MAIN.bans_obj -f MAIN.bans_completed

If MAIN.bans_req is nonzero and growing while MAIN.bans_completed is flat, you have req.* bans that the lurker cannot process. Audit your ban expressions and apply the rewrite pattern.

How Netdata helps

Netdata’s Varnish collector reports ban counters at one-second resolution. The key correlations:

• Ban accumulation confirmation. MAIN.bans_req growing with MAIN.bans_completed flat is the signature of req.* ban accumulation. Set an alert on MAIN.bans_req sustained above zero.
• Lurker activity. MAIN.bans_lurker_obj_killed shows whether the lurker is actively evicting objects (working through obj.* bans) or idle (all outstanding bans are req.* and it has nothing to evaluate).
• Latency vs hit rate. Ban list growth with stable hit rate but rising request latency is a ban-list performance problem. Hit rate degrading simultaneously means the bans are evicting too much cache.
• Backend load isolation. When bans accumulate and lookups slow, backend request rate may stay flat while CPU on the Varnish node rises from O(n) ban evaluation overhead. Correlating MAIN.bans with system CPU charts isolates the cause to ban-list growth rather than backend problems.

Related guides

• Varnish ban list growing: O(n) lookups and the lurker falling behind
• Varnish cache hit ratio dropped: hit rate collapse and backend overload
• Varnish cache stampede: a popular object expires and the herd hits the backend
• Varnish grace masking a backend outage: the ticking-clock incident
• Varnish Guru Meditation: reading the XID and tracing the failing request
• Varnish Error 503 Backend fetch failed: what the error page actually means