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
Important note: in a VAC environment, you shouldn’t reload Varnish
systemctl reload varnish as it will conflict with the global state the VAC
ensures, and any non-VAC changes will eventually be deleted.
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.
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
ExecStart=/usr/bin/varnish-agent -z http://<vac_user>:<vac_password>@vac_server/api/v1/register?groupName=<group_Name>
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>
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
ExecStart=/usr/bin/varnish-agent -z http://<vac_user>:<vac_password>@vac_server/api/v1/register?hostname=<agent_ip>
varnish-agent saves the current VCL to
will want varnishd to boot directly on it, instead of the usual
The change is done in the varnish unit file, by simply changing
*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.
While deploying large VCL files the agent may be marked as down (red) in the VAC User Interface. This is because the agent cannot, during deployment, fetch varnishd status from varnish and VAC will consider the agent as down. As soon as the agent has deployed the VCL, it will be marked as up (green) again. The time the deployment takes depends on the time it takes to compile the VCL by varnishd.
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
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.