Installing VHA-Agent involves:

  • Installing and configuring VHA-Agent on a Varnish server.
  • Integrating VHA-specific VCL for the peer Varnish server.

After a successful installation, VHA-Agent will notify the peer Varnish server about successful object insertions, and the peer Varnish will replicate these insertions by issuing requests to the origin Varnish.

Note: this page applies to VHA 2.1, available in the Varnish Enterprise 4.1 repositories.

VHA 4.1 installation instructions

Installing VHA-Agent via Varnish Enterprise

In order to install VHA-Agent on either Debian/Ubuntu or Redhat Enterprise, access to Varnish Enterprise is required. Please get in touch via for more information on Varnish Enterprise.

Debian / Ubuntu install

If you are installing on Debian or Ubuntu, use the prebuilt packages:

Add the Varnish Enterprise repository for VHA-Agent.

Update and install:

apt-get update
apt-get install varnish-plus-ha

Redhat Enterprise Linux install

Currently only RPMs for RHEL6 and RHEL7 and compatible derivatives are available.

Add the VHA-Agent yum repository as per Varnish Enterprise instruction.


yum update
yum install varnish-plus-ha


This section explains how to quickly configure VHA using a token to secure replication, it’s very straightforward but know that all the omitted details and options are available in the vha-agent(1) and vha-generate-vcl(1) man pages.

Note: the Cluster and Daemon configuration sections are to be followed on the node sending the replication requests, while the Varnish configuration is to be done on the node receiving them. However, in a normal setup, nodes usually assume both roles.


The first requirement is to describe the Varnish nodes that will need to be replicated. This is done in /etc/varnish/nodes.conf, with every line specifying the hostname (as returned by the hostname command) and address of the node, like so:

alpha =
bravo = [1:2::3]:45
charlie =
delta = http://[1::2]

The address is an IP (no domain name), but you can add details about the protocol (HTTP or HTTPS) as well as the port.

Important: the current, local node must be present in this file.

Daemon configuration

systemd platforms

The default unit file specify the token value “TOKEN” to secure replication requests, so we need to change it to a string of your own choosing.

Create (or edit) /etc/systemd/system/vha-agent and override the unit (replace “TOKEN” with your secret):

ExecStart=/usr/bin/vha-agent -P /run/vha-agent/ -N /etc/varnish/nodes.conf -s /var/lib/vha-agent/vha-status -T TOKEN


The parameters file holds two variables of importance that must be changed: ENABLE and DAEMON_OPTS. This file is located:

  • on Debian: /etc/default/vha-agent.
  • on RHEL6: /etc/sysconfig/vha-agent.params.

ENABLE has to be set to 1 to allow vha-agent to be started.

Make the following changes to DAEMON_OPTS:

  • NAME needs to be replaced with the hostname of the current node (same name as in nodes.conf).
  • TOKEN has to be replaced with a secret string that will be the same for all nodes.

Varnish configuration

VHA relies on Varnish logs to perform replication, and as a result some aspects of the request needed for replication might be truncated. It’s usually a problem with URLs. The default Varnish configuration should prevent that in most cases but if you need to replicate requests with very long URLs you may add the following to your varnishd command:

-p vsl_reclen=LENGTH

The program vha-generate-vcl is used to generate the VHA-specific VCL that will be called vha.vcl:

# on Centos 6 and/or python 2.6, please install the "python-argparse" first
vha-generate-vcl --token TOKEN > /etc/varnish/vha.vcl

where TOKEN is the same secret token value you chose in the daemon configuration section.

Finally, you need to include vha.vcl at the top of your own VCL:

include "vha.vcl";

Starting replication and checking it works

You can now restart Varnish (if you changed vsl_reclen) and start the vha-agent daemon using systemctl or service, depending on your Linux distribution.

To verify that replication is correctly happening, you can monitor the /var/lib/vha-agent/vha-status file where vha-agent will write status information every minute.