Advanced Varnish
Provides advanced Varnish cache integration for Drupal with ESI support, per-content-type TTL settings, and comprehensive cache management features.
adv_varnish
Install
composer require 'drupal/adv_varnish:^4.0'
Overview
Advanced Varnish is a comprehensive caching module that provides deep integration between Drupal and Varnish reverse proxy cache servers. It enables efficient page caching for both anonymous and authenticated users through Edge Side Includes (ESI) technology.
The module allows administrators to configure granular cache settings including per-content-type TTL (Time To Live) values, per-block ESI caching with different cache granularity levels (per page, per role, or per user), and sophisticated cache invalidation mechanisms. It includes a built-in cache purger that can invalidate cache by tags, URLs, or completely flush the entire Varnish cache.
A unique feature is the Deflate cache functionality, which gradually invalidates cache through cron runs to prevent cache stampedes during major content updates. The module also provides a plugin system for creating custom User Blocks that can be loaded via ESI for authenticated users, enabling personalized content while maintaining cacheable pages.
Features
- Full Varnish cache integration with configurable server endpoints supporting multiple Varnish servers
- ESI (Edge Side Includes) support for serving dynamic blocks within cached pages
- Per content type TTL configuration allowing different cache lifetimes for different content types
- Per block ESI configuration with three cache granularity levels: Shared (per page), Per User Roles, or Per User ID
- Built-in cache purger supporting purge by cache tag, by URL pattern, or full site cache flush
- Deflate cache feature for gradual cache invalidation during cron runs to prevent cache stampedes
- Cookie-based cache binning for authenticated users with role-based cache segmentation
- UserBlocks plugin system for creating custom ESI-loaded user-specific content blocks
- Grace period configuration for serving stale content when backend is unavailable
- Custom Cache-Control header rules per path pattern for anonymous and authenticated users
- URL exclusion patterns to disable caching for specific paths or domains
- Debug mode with detailed logging and cache debug headers
- Automatic cache tag invalidation integration with Drupal's cache tag system
- Support for preventing cache purge during Drupal maintenance mode
Use Cases
High-traffic news site with personalized content
A news website receives millions of page views daily. By using Advanced Varnish with ESI support, the site can cache the main article content while dynamically loading user-specific elements (like welcome messages, reading history, or subscription status) via ESI. This provides near-instantaneous page loads while still offering personalization.
E-commerce site with shopping cart
An e-commerce site needs to cache product pages but show the shopping cart count for logged-in users. Using the UserBlocks plugin system, a custom plugin can be created to inject the cart count via ESI. The product pages remain fully cached while the cart information is loaded separately per user.
Multi-site deployment with varied content types
A Drupal multisite installation has different content types with varying update frequencies. Using per-content-type TTL settings, news articles can have a 15-minute cache, while landing pages can be cached for 24 hours. This optimizes cache hit rates while ensuring timely content updates.
Gradual cache refresh during content migration
When performing a large content migration or bulk update, the Deflate feature can be used to gradually invalidate the cache over multiple cron runs. This prevents a cache stampede where all pages suddenly become uncached, causing backend overload.
Development and staging environments
Using the 'bypass advanced varnish cache' permission, developers and content editors can be granted the ability to see uncached content during development while production users continue to receive cached pages. The debug mode can also be enabled to inspect cache headers.
Tips
- Always test your Varnish VCL configuration in a staging environment before deploying to production.
- Use the Debug mode during development to see cache headers (X-Adv-Varnish, X-Cache-Debug) in the response.
- The Deflate feature is useful for major content updates - it gradually invalidates cache to prevent backend overload from cache stampedes.
- Consider using different TTL values for different content types based on their update frequency and importance.
- The 'Hashing Noise' and 'Secret' values are auto-generated but can be changed. Changing the Hashing Noise will invalidate all user cache bins.
- When creating custom UserBlocks plugins, remember to include appropriate cache tags so the content is invalidated when relevant entities change.
- The module supports multiple Varnish servers - separate server hosts with spaces in the configuration.
- Use the 'bypass advanced varnish cache' permission sparingly, as users with this permission will always hit the Drupal backend.
Technical Details
Admin Pages 3
/admin/config/development/adv_varnish
Main configuration page for the Advanced Varnish module where you can configure caching behavior, server settings, and various options.
/admin/config/development/adv_varnish/clear_cache
Manually purge Varnish cache by tag, URL, or flush the entire site cache. Only available when the built-in Varnish purger is enabled.
/admin/config/development/adv_varnish/deflate
Gradually invalidate Varnish cache over multiple cron runs to prevent cache stampedes. Only available when the built-in Varnish purger is enabled.
Permissions 2
Hooks 1
hook_adv_varnish_user_blocks_info_alter
Allows modules to alter the UserBlocks plugin definitions.
Troubleshooting 5
Ensure the built-in Varnish purger is enabled and the Varnish server host is correctly configured. Check that the Varnish VCL is configured to accept BAN requests with the X-Varnish-Purge header matching the configured secret. Enable logging in the module settings and check the watchdog logs for purge request details.
Verify that your Varnish VCL is configured to process ESI. The client must send the 'Surrogate-Capability: abc=ESI/1.0' header, and Varnish must be configured to handle ESI includes. Also ensure 'Enable Varnish ESI support' is checked in the module settings.
This typically indicates a VCL configuration issue. Ensure your Varnish VCL varies cache by the X-Bin header and properly handles the ADVBIN cookie. The module uses role-based cache binning, so users with the same roles should see the same cached content.
Enable 'Prevent redirect if cookie is empty after update' in the Redirect settings. This prevents redirect loops for clients (like search engines) that don't support cookies.
If you need cache to be purged during maintenance, uncheck 'Prevent Varnish purge while in Maintenance Mode' in the General settings. Otherwise, this is expected behavior to keep pages cached during deployments.
Security Notes 4
- The 'administer advanced varnish configuration' permission is marked as restricted access and should only be granted to trusted administrators.
- The Varnish secret header (X-Varnish-Purge) should be kept secure and your Varnish VCL should verify this header before accepting BAN requests.
- The cookie hashing uses HMAC-SHA256 with both the configured noise and Drupal's hash salt for security.
- Ensure your Varnish VCL properly validates the secret header to prevent unauthorized cache purging from external sources.