Varnish Administration Console


Registering to the VAC

Varnish-agent is able to register itself on startup to a VAC instance, to do so, you need to add -z to the Varnish-agent command line.

For non-systemd systems

Depending on your distribution, the file to edit should be

/etc/default/varnish-agent for Debian / Ubuntu install [non-systemd]

/etc/sysconfig/varnish-agent for Red Hat Enterprise [non-systemd]

this can be done by editing the DAEMON_OPTS line:

# replace "vac_server" with the IP or hostname of the VAC
DAEMON_OPTS="-z http://vac_server/api/rest/register"

Since version 3.6.0 VAC supports registering a Varnish instance and adding it directly into a group.

Note that registering against a given group will require authentication.

Use either a groupID or a groupName for telling what group to register to.

# replace "vac_server" with the IP or hostname of the VAC
# replace "groupID" with the groupId where the Varnish instance should be added.
DAEMON_OPTS="-z http://<vac_user>:<vac_password>@vac_server/api/v1/register?groupID=<group_ID>"


# replace "vac_server" with the IP or hostname of the VAC
# replace "groupName" with the name of the group where the Varnish instance should be added.
DAEMON_OPTS="-z http://<vac_user>:<vac_password>@vac_server/api/v1/register?groupName=<group_Name>"

This will need the VAC credentials in order to work.

The VAC will use the IP that issued the request as the node IP. If you have a proxy between the VAC and the agent (or that IP is wrong), please use the hostname parameter:

# replace "hostname" with the IP or hostname the VAC should use
# to contact the node
DAEMON_OPTS="-z http://vac_server/api/rest/register?hostname=agent_hostname"

A caveat for the hostname registration is that the VAC machine needs to be able to resolve the agent_hostname, otherwise the registration will fail.

For systemd systems

systemctl edit varnish-agent

The following is a snippet of the full service file.

--- cut ---
ExecStart=/usr/bin/varnish-agent -z http://vac_server/api/rest/register
--- cut ---

You can also use hostname and the groupID query parameters in here.

After editing the service file, you’ll need to restart the varnish-agent service:

systemctl daemon-reload
systemctl start varnish-agent

Switch varnishd 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 init file of varnish, 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.

Optional: change the login/password

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.


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.