Varnish Controller


A VCL is a configuration for a Varnish server written in the Varnish Configuration Language. This is not a new concept but in Varnish Controller we distinguish between a MainVCL and an Includes. The reason for this is how we handle deployments to Varnish servers. Both types are described below.


The main VCL is either the only VCL used or can have include statements that reference the Includes. The reason for dividing VCL files into these categories is that the MainVCL is the one loaded by the agent into Varnish. If the main VCL includes other VCL files, we also need to know about these.

NOTE: The naming here is important. Varnish will look for the same name of the included file as the name of the VCL in Varnish Controller. That means that a statement like this include "my.vcl"; only works if the Includes includes a VCL named my.vcl.


Includes are files that are referenced by an VCL, either as include statements in the MainVCL as VCL files or as other type of files used by for example vmods.

Binary files could be used as Includes but they require base64 encoding when being uploaded to Varnish Controller. Uploading a base64 encoded (RFC 4648) binary file will mark the file as encoded=true.

Included files will end up in the same directory as the MainVCL.

Drafts and Rollbacks

Since version 2.0.0 we have implemented drafts and rollbacks for your VCLs and files, which also applies to the MainVCL and Includes. With these new features it is possible to prepare deployments and roll back within seconds if you made a mistake.


The draft version can be accessed with the API when retrieving a single VCL or file. The UI and CLI have built-in features to show the difference between your original and changed draft. The draft feature is intended to be short lived. To prepare changes for deployment, keep in mind that the draft column can be overwritten by a rollback. We only keep track of one draft version.


When deploying a draft to your VCLGroup a snapshot is created of your VCLs and files that are currently deployed to that VCLGroup. On a rollback the VCLs and deployed files will become the draft version. The source data is overwritten with that of the previously created snapshot, resulting in all agents rolling back in a couple of seconds. We keep track of one snapshot per VCLGroup, and you can only roll back your most recent deployment.

The VCL and file state indicate if there are pending changes, if the file is new and never deployed or if the file is rolled back. If you want to have a longer history of VCL and file changes we recommend using version control software.