The Varnish Users Guide on Varnish Cache

Achieving a high hitrate

Mon, 16 Mar 2026 00:00:00 +0000

Now that Varnish is up and running you can access your web application through Varnish. Unless your application is specifically written to work behind a web accelerator you’ll probably need to do some changes to either the configuration or the application in order to get a high hitrate in Varnish.

Varnish will not cache your data unless it’s absolutely sure it is safe to do so. So, for you to understand how Varnish decides if and how to cache a page, we’ll guide you through a couple of tools that you should find useful to understand what is happening in your Varnish setup.

ACLs

Mon, 16 Mar 2026 00:00:00 +0000

You create a named access control list with the acl keyword. You can match the IP address of the client against an ACL with the match operator.:

# Who is allowed to purge....
acl local {
 "localhost";
 "192.168.1.0"/24; /* and everyone on the local network */
 ! "192.168.1.23"; /* except for the dialin router */
}

sub vcl_recv {
 if (req.method == "PURGE") {
 if (client.ip ~ local) {
 return(purge);
 } else {
 return(synth(403, "Access denied."));
 }
 }
}

Adding WebSockets support

Mon, 16 Mar 2026 00:00:00 +0000

WebSockets is a technology for creating a bidirectional stream-based channel over HTTP.

To run WebSockets through Varnish you need to pipe the request and copy the Upgrade and Connection headers as follows:

sub vcl_recv {
 if (req.http.upgrade ~ "(?i)websocket") {
 return (pipe);
 }
}

sub vcl_pipe {
 if (req.http.upgrade) {
 set bereq.http.upgrade = req.http.upgrade;
 set bereq.http.connection = req.http.connection;
 }
}

Altering the backend response

Mon, 16 Mar 2026 00:00:00 +0000

Here we override the TTL of a object coming from the backend if it matches certain criteria:

sub vcl_backend_response {
 if (bereq.url ~ "\.(png|gif|jpg)$") {
 unset beresp.http.set-cookie;
 set beresp.ttl = 1h;
 }
}

We also remove any Set-Cookie headers in order to avoid creation of a hit-for-miss object. See VCL Actions.

Backend servers

Mon, 16 Mar 2026 00:00:00 +0000

Varnish has a concept of “backend” or “origin” servers. A backend server is the server providing the content Varnish will accelerate.

Our first task is to tell Varnish where it can find its backends. Start your favorite text editor and open the relevant VCL file.

Somewhere in the top there will be a section that looks a bit like this.:

Built-in VCL

Mon, 16 Mar 2026 00:00:00 +0000

Whenever a VCL program is loaded, the built-in VCL is appended to it. The vcl built-in subs (VCL Steps) have a special property, they can appear multiple times and the result is concatenation of all built-in subroutines.

For example, let’s take the following snippet:

sub vcl_recv {
 # loaded code for vcl_recv
}

The effective VCL that is supplied to the compiler looks like:

sub vcl_recv {
 # loaded code for vcl_recv
 # built-in code for vcl_recv
}

This is how it is guaranteed that all Varnish Processing States have at least one return (<action>).

CLI - bossing Varnish around

Mon, 16 Mar 2026 00:00:00 +0000

Once varnishd is started, you can control it using the varnishadm program and the command line interface:

varnishadm help

If you want to run varnishadm from a remote system, we recommend you use ssh into the system where varnishd runs. (But see also: Local and remote CLI connections)

You can SSH into the varnishd computer and run varnishadm:

Compression

Mon, 16 Mar 2026 00:00:00 +0000

In Varnish 3.0 we introduced native support for compression, using gzip encoding. Before 3.0, Varnish would never compress objects.

In Varnish 4.0 compression defaults to “on”, meaning that it tries to be smart and do the sensible thing.

If you don’t want Varnish tampering with the encoding you can disable compression all together by setting the parameter http_gzip_support to false. Please see man varnishd for details.

Content composition with Edge Side Includes

Mon, 16 Mar 2026 00:00:00 +0000

Varnish can create web pages by assembling different pages, called fragments, together into one page. These fragments can have individual cache policies. If you have a web site with a list showing the five most popular articles on your site, this list can probably be cached as a fragment and included in all the other pages.

Device detection

Mon, 16 Mar 2026 00:00:00 +0000

Device detection is figuring out what kind of content to serve to a client based on the User-Agent string supplied in a request.

Use cases for this are for example to send size reduced files to mobile clients with small screens and on high latency networks, or to provide a streaming video codec that the client understands.

Grace mode and keep

Mon, 16 Mar 2026 00:00:00 +0000

Sometimes you want Varnish to serve content that is somewhat stale instead of waiting for a fresh object from the backend. For example, if you run a news site, serving a main page that is a few seconds old is not a problem if this gives your site faster load times.

Hashing

Mon, 16 Mar 2026 00:00:00 +0000

Internally, when Varnish stores content in the cache indexed by a hash key used to find the object again. In the default setup this key is calculated based on URL, the Host: header, or if there is none, the IP address of the server:

sub vcl_hash {
 hash_data(req.url);
 if (req.http.host) {
 hash_data(req.http.host);
 } else {
 hash_data(server.ip);
 }
 return (lookup);
}

As you can see it first hashes req.url and then req.http.host if it exists. It is worth pointing out that Varnish doesn’t lowercase the hostname or the URL before hashing it so in theory having “Varnish.org/” and “varnish.org/” would result in different cache entries. Browsers however, tend to lowercase hostnames.

Logging in Varnish

Mon, 16 Mar 2026 00:00:00 +0000

One of the really nice features in Varnish is the way logging works. Instead of logging to a normal log file Varnish logs to a shared memory segment, called the VSL - the Varnish Shared Log. When the end of the segment is reached we start over, overwriting old data.

This is much, much faster than logging to a file and it doesn’t require disk space. Besides it gives you much, much more information when you need it.

Manipulating request headers in VCL

Mon, 16 Mar 2026 00:00:00 +0000

Lets say we want to remove the cookie for all objects in the /images directory of our web server:

sub vcl_recv {
 if (req.url ~ "^/images") {
 unset req.http.cookie;
 }
}

Now, when the request is handled to the backend server there will be no cookie header. The interesting line is the one with the if-statement. It matches the URL, taken from the request object, and matches it against the regular expression. Note the match operator. If it matches the Cookie: header of the request is unset (deleted).

Parameters

Mon, 16 Mar 2026 00:00:00 +0000

Varnish Cache comes with a set of parameters that affects behaviour and performance. Parameters are set either though command line arguments to varnishd or at runtime through varnishadm using the param.set CLI command.

We don’t recommend that you tweak parameters unless you’re sure of what you’re doing. We’ve worked hard to make the defaults sane and Varnish should be able to handle most workloads with the default settings.

Purging and banning

Mon, 16 Mar 2026 00:00:00 +0000

One of the most effective ways of increasing your hit ratio is to increase the time-to-live (ttl) of your objects. But, as you’re aware of, in this twitterific day of age, serving content that is outdated is bad for business.

The solution is to notify Varnish when there is fresh content available. This can be done through three mechanisms. HTTP purging, banning and forced cache misses. First, lets look at HTTP purging.

Reporting and statistics

Mon, 16 Mar 2026 00:00:00 +0000

This section covers how to find out what Varnish is doing, from the detailed per HTTP request blow-by-blow logrecords to the global summary statistics counters.

Request and response VCL objects

Mon, 16 Mar 2026 00:00:00 +0000

In VCL, there several important objects that you need to be aware of. These objects can be accessed and manipulated using VCL.

req: The request object. When Varnish has received the request the req object is created and populated. Most of the work you do in vcl_recv you do on or with the req object.
bereq: The backend request object. Varnish constructs this before sending it to the backend. It is based on the req object.

beresp: The backend response object. It contains the headers of the object coming from the backend. If you want to modify the response coming from the server you modify this object in vcl_backend_response.
resp: The HTTP response right before it is delivered to the client. It is typically modified in vcl_deliver.
obj: The object as it is stored in cache. Read only.

Required command line arguments

Mon, 16 Mar 2026 00:00:00 +0000

There only one command line argument you have to provide when starting Varnish, which is ‘-b’ for where the backend server can be contacted.

‘-a’ is another argument which is likely to require adjustment.

If you have installed Varnish through using a provided operating system bound package, you will find the startup options here:

Security first

Mon, 16 Mar 2026 00:00:00 +0000

If you are the only person involved in running Varnish, or if all the people involved are trusted to the same degree, you can skip this chapter. We have protected Varnish as well as we can from anything which can come in through an HTTP socket.

If parts of your web infrastructure are outsourced or otherwise partitioned along administrative lines, you need to think about security.

Separate VCL files

Mon, 16 Mar 2026 00:00:00 +0000

Having multiple different vhosts in the same Varnish is a very typical use-case, and from Varnish 5.0 it is possible to have a separate VCL files for separate vhosts or any other distinct subset of requests.

Assume that we want to handle varnish.org with one VCL file and varnish-cache.org with another VCL file.

Sizing your cache

Mon, 16 Mar 2026 00:00:00 +0000

Deciding on cache size can be a tricky task. A few things to consider:

How big is your hot data set. For a portal or news site that would be the size of the front page with all the stuff on it, and the size of all the pages and objects linked from the first page.

How expensive is it to generate an object? Sometimes it makes sense to only cache images a little while or not to cache them at all if they are cheap to serve from the backend and you have a limited amount of memory.

Watch the n_lru_nuked counter with varnishstat or some other tool. If you have a lot of LRU activity then your cache is evicting objects due to space constraints and you should consider increasing the size of the cache.

Also, there are additional considerations for specific storage engines (stevedores), see Storage backends for details.

Starting and running Varnish

Mon, 16 Mar 2026 00:00:00 +0000

This section covers starting, running, and stopping Varnish, command line flags and options, and communicating with the running Varnish processes, configuring storage and sockets and, and about securing and protecting Varnish against attacks.

Statistics

Mon, 16 Mar 2026 00:00:00 +0000

Varnish comes with a couple of nifty and very useful statistics generating tools that generates statistics in real time by constantly updating and presenting a specific dataset by aggregating and analyzing logdata from the shared memory logs.

varnishtop

The varnishtop utility reads the shared memory logs and presents a continuously updated list of the most commonly occurring log entries.

Storage backends

Mon, 16 Mar 2026 00:00:00 +0000

Intro

Varnish has pluggable storage backends. It can store data in various backends which can have different performance characteristics. The default configuration is to use the malloc backend with a limited size. For a serious Varnish deployment you probably would want to adjust the storage settings.

All built-in storage backends cache full objects only, so, for example, to support n concurrent cache hits on 1GB sized objects, the storage backend should be configured to provide at least nGB of storage. For uncacheable objects, the rule of thumb is n x transit_buffer.

The Big Varnish Picture

Mon, 16 Mar 2026 00:00:00 +0000

In this section we will cover answers to the questions:

What is in this package called “Varnish”?
what are all the different bits and pieces named?
Will you need a hex-wrench for assembly?

The two main parts of Varnish are the two processes in the varnishd program. The first process is called “the manager”, and its job is to talk to you, the administrator, and make the things you ask for happen.

Troubleshooting Varnish

Mon, 16 Mar 2026 00:00:00 +0000

Sometimes Varnish misbehaves or rather behaves the way you told it to behave but not necessarily the way you want it to behave. In order for you to understand whats going on there are a couple of places you can check. varnishlog, /var/log/syslog, /var/log/messages are all good places where Varnish might leave clues of whats going on. This section will guide you through basic troubleshooting in Varnish.

Using inline C to extend Varnish

Mon, 16 Mar 2026 00:00:00 +0000

(Here there be dragons. Big and mean ones.)

You can use inline C to extend Varnish. Please note that you can seriously mess up Varnish this way. The C code runs within the Varnish Cache process so if your code generates a segfault the cache will crash.

One of the first uses of inline C was logging to syslog.:

Varnish and Website Performance

Mon, 16 Mar 2026 00:00:00 +0000

This section focuses on how to tune the performance of your Varnish server, and how to tune the performance of your website using Varnish.

The section is split in three subsections. The first subsection deals with the various tools and functions of Varnish that you should be aware of. The next subsection focuses on the how to purge content out of your cache. Purging of content is essential in a performance context because it allows you to extend the time-to-live (TTL) of your cached objects. Having a long TTL allows Varnish to keep the content in cache longer, meaning Varnish will make fewer requests to your relatively slower backend.

VCL - Varnish Configuration Language

Mon, 16 Mar 2026 00:00:00 +0000

This section covers how to tell Varnish how to handle your HTTP traffic, using the Varnish Configuration Language (VCL).

Varnish has a great configuration system. Most other systems use configuration directives, where you basically turn on and off lots of switches. We have instead chosen to use a domain specific language called VCL for this.

VCL Examples

Mon, 16 Mar 2026 00:00:00 +0000

These are a short collection of examples that showcase some of the capabilities of the VCL language.

VCL Syntax

Mon, 16 Mar 2026 00:00:00 +0000

VCL has inherited a lot from C and it reads much like simple C or Perl.

Blocks are delimited by curly brackets, statements end with semicolons, and comments may be written as in C, C++ or Perl according to your own preferences.

Note that VCL doesn’t contain any loops or jump statements.