SearchA 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 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, these also have to be
included in the Includes for a VCLGroup.
include "my.vcl"; only works if the Includes includes a file 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.
Files uploaded to the controller are required to be base64 encoded (RFC 4648). This is handled
automatically via vcli and the Web UI, but when using the API, this is important.
Included files will end up in the same directory as the MainVCL on each server.
Files is only a meta-data structure that holds a name, label and ID. For each file there can be many
versions. When creating a new file version for a file, the name and label from the File is used
for the new file version. To change name and/or label, the change has to be done on the file itself.
Then next new versions of the file will take this name and label. Hence, to change name or label for
a file it has to be done on the parent File for a version. A new file could be created instead,
but that will get a new version history and a new file id.
File Versions contains the source, version, name, and a label. For Git-managed files, additional metadata such as directory path and the commit hash are included. The version field is automatically incremented for each file, starting at 1. File versions are immutable and cannot be modified once created.
When Git is used to deploy VCLGroups, all matching files are created as file and file versions.
File versions that are either deployed on a VCLGroup or part of a deploy log cannot be removed until the VCLGroup is undeployed/removed and/or the deploy log is removed.
# Create a new file and upload the file 'test.vcl' as the name 'main.vcl'.
vcli file add main.vcl test.vcl
# Create a new version of the previously uploaded file
vcli file new 1 --descr "my second version" --file main.vcl
# Edit the current file
vcli file edit 1
# List versions of the file with ID 1
vcli file versions 1
# Delete version 2 of file with ID 1 (cannot be in use or part of deploy logs)
vcli file version 1 -d 2
# Delete file and all its versions
vcli file delete 1