Installation

In order to install VHA6 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 platforms, the package is named varnish-plus-ha and can be installed via the usual package manager:

• Debian/Ubuntu:

sudo apt-get install varnish-plus-ha varnish-broadcaster

• RHEL/CentOS:

sudo yum install varnish-plus-ha varnish-broadcaster

Note that VHA6 requires the Varnish Broadcaster.

Configuration

Disable vha-agent

VHA6 retired the use of the vha-agent in favor of the Varnish Broadcaster. The vha-agent service should be disabled to avoid conflicts:

sudo systemctl stop vha-agent
sudo systemctl disable vha-agent

If upgrading, remove the legacy VHA VCL include: vha_40.vcl or vha_41.vcl. Also remove all vha_opts.set() calls.

Setup the cluster

Create a /etc/varnish/nodes.conf describing the VHA6 cluster. Each host in the cluster needs a single entry. The entry name is the hostname. The entry value is the routable address and port for that host. This file should be identical across the whole cluster.

Example:

alpha = 1.2.3.4
bravo = [1:2::3]:45
charlie = https://5.6.7.8:90
delta = http://[1::2]

If upgrading, your original nodes.conf can be re-used.

Its very important that the names in your nodes.conf match up exactly with the hostnames of the nodes. The nodes.conf node name should be the fully qualified domain name of the node. VHA6 will fallback to the public interface when the nodes.conf node name does not match up exactly with the hostname of the node.

If using groups, please make sure to set the corresponding VHA6 broadcaster_group setting. This is done in vcl_init.

Next, make sure the broadcaster is enabled and running:

sudo systemctl enable broadcaster
sudo systemctl start broadcaster

Varnish configuration

Add the following configuration to the top of your VCL:

include "vha6/vha_auto.vcl";

sub vcl_init {
    vha6_opts.set("token", "secret123");
    call vha6_token_init;
}

Change the token value of secret123 to a unique secret value. This value should be identical across your cluster.

Disabling VHA6

To disable VHA6 on a single node, replace the vha6/vha_auto.vcl include with:

include "vha6/vha_disable.vcl";

This will gracefully opt the node out of the VHA6 architecture while allowing other nodes to operate.

To permanently disable VHA6 across an entire architecture, disable each node as described above and then remove all VHA6 VCL from the configuration.

Using VHA6 with VCL 4.0

VHA6 requires using vcl 4.1 in your parent VCL. If your VCL is using 4.0, replace the vha6/vha_auto.vcl include with:

include "vha6/vha_auto_legacy_40.vcl";

Using VHA6 with VCL labels

The VHA6 configuration needs to be applied to the parent VCL and all labels which want to replicate objects.

Using VHA6 with Total Encryption

When using Total Encryption, include Total Encryption before VHA6:

include "total-encryption/random_key.vcl";
include "vha6/vha_auto.vcl";

This applies to both random_key and secret_key encryption.

If you are using the same secret key across your entire cluster, you can skip decryption during VHA6 transactions by putting the secret_key include after VHA6:

include "vha6/vha_auto.vcl";
include "total-encryption/secret_key.vcl";

If using header encryption, please contact support for VHA6 usage.

Using VHA6 with req.* bans

Note: If using 6.0.5 or later, this is not needed.

If using 6.0.4 or earlier, add the following line to vcl_init to allow req.* bans to update into cache:

vha6_opts.set("force_update", "true");

If using obj.* bans, force_update can be left as the default.