Installation

Installing VHA-Agent

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

On all platform, the package is named varnish-plus-ha and can be installed via the usual package manager:

on debian/ubuntu platform:

apt-get install varnish-plus-ha

on RHEL platforms:

yum install varnish-plus-ha

Configuration

Cluster

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 = 1.2.3.4
bravo = [1:2::3]:45
charlie = https://5.6.7.8:90
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.

If you have multiple Points of Presence, you can group them in sections:

[europe]
europe1 = 1.1.1.1
europe3 = 1.1.1.2

[asia]
asia1 = 2.2.2.1

[america]
america1 = 3.3.3.1
america2 = 3.3.3.2

Daemon configuration

Next, we need to secure replication by setting a secret token in the vha-agent command line. One easy way is to use systemctl edit vha-agent to create an override like this (replace YOURTOKEN by your own token):

[Service]
ExecStart=
ExecStart=/usr/bin/vha-agent -D -P /run/vha-agent/vha-agent.pid -N /etc/varnish/nodes.conf -s /var/lib/vha-agent/vha-status -T YOURTOKEN

You can then restart the vha-agent service.

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=YOURLENGTH

VHA also relies on Debug log records, but those are masked by default for production usage, so you must add the following to your varnishd command:

-p vsl_mask=+Debug

Including the VCL

VHA requires some VCL to be included in your own configuration. This VCL file, bundled in the varnish-plus-ha package) must be included at the top of your VCL, right after the vcl 4.X; statement:

vcl 4.0;
include "vha_40.vcl";

Or if you are using the 4.1 VCL version:

vcl 4.1;
include "vha_41.vcl";

Setting the token

The last thing is to set the same secret token as for vha-agent, by a simple call in vcl_init:

sub vcl_init {
	vha_opts.set("token", "YOURTOKEN");
}

Note that if you need to also replicate requests with a body, you need to set a second option:

sub vcl_init {
	vha_opts.set("token", "YOURTOKEN");
	vha_opts.set("replicate_body", "yes");
}

Starting replication and checking it works

You can now restart Varnish (the vsl_mask change requires it) 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.