What is VCL?

VCL stands for Varnish Configuration Language and is the domain-specific language used by Varnish to control request handling, routing, caching, and several other things.

At first glance, VCL looks a lot like a normal, top-down programming language with subroutines, if-statements and function calls. However, it is impossible to execute VCL outside of Varnish. Instead, you write code that is run inside Varnish at specific stages of the request-handling process. This lets you define advanced logic that extends the default behavior of Varnish.

The locations where the VCL is run are actually different states of the Varnish finite state machine. Even though you can accomplish a lot by configuring just a few states, understanding the state machine is necessary to leverage the full potential of Varnish.

VCL is one of the most compelling Varnish features. It is often the main reason why users choose Varnish over competing web acceleration products. The level of flexibility that VCL offers is unparalleled in the industry.

Through a set of pre-defined subroutines and other language constructs in the VCL file, the behavior of Varnish can be extended. This can range from request and response header manipulation, to backend selection, overriding state transitions in the finite state machine, and many more other actions.

When the varnishd runtime process is started, the VCL file is processed, the VCL code is translated into C code, the C code is then compiled to a shared object, and eventually this shared object is linked to the server process, where its code is executed.

Here’s some sample code to give you an idea of what VCL looks like:

vcl 4.1;

backend default {
	.host = "backend.example.com";
	.port = "80";
}

sub vcl_recv {
	if(req.url ~ "^/admin(/.*)?") {
		return(pass);
	}
}

This VCL snippet will instruct Varnish not to serve objects from cache if the URL is /admin or if the URL starts with /admin/. When a backend connection is made, Varnish will connect to the backend.example.com hostname on the conventional HTTP port, which is 80.

Note that the DNS resolution of the hostname is done when the VCL configuration is loaded and not on every backend connection.

In addition to standard VCL, there’s also a rich ecosystem of VMODs, or Varnish modules. These modules allow users to integrate with third-party C libraries, and add extra functionality to Varnish. A VMOD exposes its functionality through a set of functions and objects, which further enrich the VCL language.

Here’s a VCL snippet that features the cookie VMOD:

vcl 4.1;
import cookie;

backend default {
	.host = "backend.example.com";
	.port = "80";
}

sub vcl_recv {
	cookie.parse(req.http.cookie);
	cookie.keep("language");
	set req.http.cookie = cookie.get_string();
	return(hash);
}

sub vcl_hash {
	hash_data(cookie.get("language"));
}

This VCL snippet will use the cookie VMOD to remove all incoming cookies except the language cookie. It will force a cache lookup, even when cookies are present. The value of the language cookie will be used as a cache variation to create a cache object per URL per language.

As you can see this VMOD adds additional functionality to Varnish and exposes this functionality using a VCL API.

We’ll discuss VCL in much more detail in the dedicated VCL chapter.