Varnish Controller


Agents are required to have unique names in the Varnish Controller system. The names must be alphanumeric but can also include a dash (-).

Each Varnish should have a corresponding agent running if it should be included in the Varnish Controller system. Running multiple agents toward the same Varnish is not supported and can result in unpredicted behavior.

Restarting an agent will not affect the Varnish instance as long as the Varnish instance has not been manually changed with regard to loaded VCL.

Agents will start by waiting for connection towards NATS, once connected it will continue.


# Ubuntu/Debian
sudo apt install varnish-controller-agent

# CentOS/RedHat
sudo yum install varnish-controller-agent

Varnish Interaction

Agents must be able to communicate with Varnish on the Varnish administration port. The default port is 6082. That means that Varnish must be started with -T :6082 for example. The agent must also be able to read the Varnish secret file (defaults to /etc/varnish/secret).

Since the agent is responsible for reading/writing VCL files to disk and loading them into Varnish, Varnish must be able to read the files as well. This is not a problem when running on the same server, as long as permissions are set correctly. But when running in a container environment, they both need to be able to read the same shared directory.

See the containers for more information on running in containers.

Setting the Agent Name

To identify the agents in the Varnish Controller, the agent name is used. Agents are required to have unique names in the Varnish Controller system. The names must be alphanumeric but can also include a dash (-). Set the agent name as an argument -agent-name agent01 or environment variable VARNISH_CONTROLLER_AGENT_NAME=agent01.

Read Only

An agent can be started in read-only mode using the -read-only flag. This makes the agent not usable in Varnish Controller with regard to deployments, but it will read information from Varnish and present it to Varnish Controller. It will read loaded VCLs, Varnish version, etc. and present via the REST API.

The agent must be restarted without the -read-only flag in order to be used for deployment via Varnish Controller.

Advanced Configuration

There are some configuration parameters that could be tuned to change how the agent operates. These might not be self-explanatory and are described below.

Note: Do not change these parameters if you are not sure about the implications.

Load From Disk (-load-from-disk)

Load previous deployments (if any) from disk, even if NATS or Brainz is not reachable. The agent saves manifest files containing the deployments (VCLs) to disk. These are then loaded into the agent and Varnish if this option is turned on (by default true).

Default VCL (-default-vcl <vcl_file>)

The default VCL is the VCL that will be loaded into Varnish if no other VCL has been loaded in the system. This VCL can be replaced with any other VCL and can be an error page of some kind. Default is a synth 503.

The default VCL can be viewed:

varnish-controller-agent -default-vcl-show

Heartbeat Rate (-hb-rate <duration>)

The heartbeat rate is the rate of heartbeats being sent by the agent to brainz to tell brainz of its presence and state. The lower heartbeat the faster response time for changes. Note that brainz might require some extra configuration if this value is changed to identify an agent that is down based on missed heartbeats.

NATS Max Wait (-nats-max-wait <duration>)

Max time to wait for reconnection attempt to the NATS server.

NATS Reconnect Time (-nats-reconnect-time <duration>)

Time between each reconnect to NATS server upon lost connection.

NATS Timeout (-nats-timeout <duration>)

Timeout for sending a message on the NATS message-bus.

Root VCL (-root-vcl <vcl_file>)

This should usually not be modified. The default is a template used to handle multiple domains. This VCL is only used when running shared/cloud deployments with shared Varnish instances between multiple domains.

The default root VCL can be viewed:

varnish-controller-agent -root-vcl-show

Static Tags (-tags tag1,tag2)

Starts the agent with pre-defined tags that will be marked static in the database. If someone removes a static tag it will be automatically added again if the agent has it defined at startup.

If multiple agents are started with the same tag names, only one instance of the tag will be created. Hence, it is safe to start multiple agents with same tag names.

Agent Stats Filter (-agent-stats-filter string)

This is a comma-separated string of statistics that will be sampled by the agent. These are the same names as the output from varnishstat -j. Anything other than the specified statistics will be discarded.

Example configuration:

./agent -agent-stats-filter MAIN.client_req,MAIN.cache_hit

VCLGroup Stats Filter (-vclgroup-stats-filter string)

This is almost the same as -agent-stats-filter except that this filters out statistics for VCLGroups (loaded VCLs). It can only filter out parts of the VCL that are presented by varnishstat for VCL backends. The filter names take the last part of the statistics name after the loaded VCL name.

As an example the varnishstat output VBE.vg1_129621b78f1ea3696eb116cbae3abc85bf89ef4ae0d6b642b873c9c978537117_1.happy shows both VBE and the VCL name (which will be different depending on both content and reloads). Hence, we only specify the last part as filter. In this example happy as the statistics that we want to gather.

Example configuration:

./agent -vclgroup-stats-filter req,conn,happy

Varnish External IP (--varnish-ext-ip string)

Specify what the external IP address for the Varnish Cache instance is. This is not used by the Varnish Controller itself. It is presented via the Varnish Controller API for each agent. If this is not specified, the agent will try to lookup the outbound IP address (ipv4 only) and set that as the external IP address for Varnish Cache. The automatic lookup may present the wrong external IP address, especially for virtual environments or if Varnish Cache is not running on the same server as the agent. The external IP address is presented via the API to help out configuring load balancers towards the Varnish Cache servers. This option could be anything such as a IPv4, IPv6 or hostname.

Stats Interval (-stats-interval <duration>)

Specify how often Varnish statistics should be gathered from the Varnish instance.