Varnish Agent

Latest is 6.1.0

Installation

The varnish-agent is present in the Varnish enterprise and is installed like any other package:

# Debian/Ubuntu
sudo apt install varnish-agent
# RedHat/CentOS
sudo yum install varnish-agent
sudo systemctl start varnish-agent
sudo systemctl enable varnish-agent

Configuration

Important note: in a VAC environment, you shouldn’t reload Varnish via systemctl reload varnish as it will conflict with the global state the VAC ensures, and any non-VAC changes will eventually be deleted.

Auto-registration

The agent must be told to register itself to the VAC server when starting. This is done by giving it an extra argument at startup (via an override file).

sudo systemctl edit varnish-agent

Add the following configuration:

[Service]
ExecStart=
ExecStart=/usr/bin/varnish-agent -z http://vac_hostname/api/rest/register

Reload and restart:

# update systemd, and restart the agent
sudo systemctl daemon-reload
sudo systemctl restart varnish-agent

The node should now be visible in the VAC web UI and can be added to a group.

Specifying a group

The agent can also automatically assign a group to the node upon registration.

This is done by adding a querystring to the registraction URL, either groupName:

ExecStart=/usr/bin/varnish-agent -z http://<vac_user>:<vac_password>@vac_server/api/v1/register?groupName=<group_Name>

or groupID if you prefer to specify the group hash:

ExecStart=/usr/bin/varnish-agent -z http://<vac_user>:<vac_password>@vac_server/api/v1/register?groupID=<group_ID>

Specifying a hostname

The VAC needs to be able to connect to the agent to communicate with it, and so it needs its IP address. Usually it uses the IP used to register, but if you are behind a NAT for example, the VAC won’t see the right IP, and you may need to override it. This is done using the hostname parameter:

ExecStart=/usr/bin/varnish-agent -z http://<vac_user>:<vac_password>@vac_server/api/v1/register?hostname=<agent_ip>

Switch to boot.vcl

varnish-agent saves the current VCL to /var/lib/varnish-agent/boot.vcl so will want varnishd to boot directly on it, instead of the usual default.vcl.

The change is done in the varnish unit file, by simply changing /etc/varnish/default.vcl to /var/lib/varnish-agent/boot.vcl.

*Note that the VAC has a consistency job running every two minutes, making sure the VCL is as it should be, but pointing to boot.vcl ensures you have the right configuration from the get-go. *

Calls to Varnish-agent must be authorized via BasicAuth, demanding a login and password specified in /etc/varnish/agent_secret. This information randomly generated at install time and passed to the VAC when registering, but if you wish to issue calls to the agent via another mean, you can use this file to learn or change the credentials.

A restart of the agent is necessary for the information to be updated.

Debugging

When the Varnish-agent can not be reached the VAC will constantly log about it. If you do not want the agent to log when the it is down, there is a flag agent_log in in var/opt/vac/log which is true by default. By setting it to false we just get the state of the agent changes from up to down.

Varnish-agent must be able to send HTTP requests to the VAC to register, if it can’t it may be a firewall issue or another network problem.

To access counters, and operate Varnish, Varnish-agent need read access to either the Varnish secret file or the the shared memory log, other wise you’ll be missing features and the daemon will log about it. The default packaging takes care of this, but if you are experiencing issues, check your permissions and know that you can use the -u switch to run as a specific user.