Varnish Controller


Brainz will start by waiting for database connection. Once a connection is established, it will wait for connection towards NATS.

Brainz can be scaled out with multiple instances. All instances need access to the same database in order to operate in the same cluster. Multiple brainz instances will all act as active and the message handling will be spread among them.


# Ubuntu/Debian
sudo apt install varnish-controller-brainz

# CentOS/RedHat
sudo yum install varnish-controller-brainz

System Administrator

A system administrator user is required in order to use the system. This user is a special user with full system permissions and can only be created using the brainz binary.

See authentication chapter for details about creating an system administrator account.


When the installation is done you need to add your license file. Brainz will by default look for the license file named varnish-controller.lic in the /var/lib/varnish-controller/varnish-controller-brainz/ directory. If you want to change where Brainz looks for the license file, edit the systemd service file and add a command line parameter -license or add the VARNISH_CONTROLLER_LICENSE environment variable.

For details about the license, see the license chapter.

PostgreSQL Interaction

Brainz is started with user, password and database for PostreSQL.

varnish-controller-brainz -db-server localhost:5432 -db-user varnish-controller -db-pass mypassword -db-name varnish-controller

These can be configured in the systemd service file as environment variables (or as environment variables in containers).

Advanced Configuration

There are some configuration parameters that can be tuned to change how the brainz process operates. These might not be self-explanatory and are described below.

Note: Do not change these parameters if you are not sure about the implications.

Deployment Throttle

  • Arg: -deployment-throttle <duration>

This is mainly for handling large numbers of API requests that trigger changes to the deployed VCLGroups. When there is a flood of requests the deployment algorithm will wait this number of seconds before it will decide where things will be deployed. This is to avoid too many re-configurations due to a high number of fast changes. (default 1s)

Deployment Update

  • Arg: -deployment-update <duration>

This is the time between each periodic deployment configuration verification. A deployment configuration is basically the algorithm that checks where things should be deployed and verifies that they are. This just makes sure that things are correct in the system. In normal operation this wouldn’t trigger any changes to the system. (default 10s)

Heartbeat Timeout

  • Arg: -hb-timeout <duration>

This is the maximum time since last heartbeat from an agent. If this is reached and no heartbeats have been received during this time, the agent is considered down. Any VCLGroup deployed to this agent will be moved to any other matching agent if one exists. It is important that this value is in correlation with the agent heartbeat rate. An agent heartbeat rate set to higher than this value will mark the agent as down. (default 10s)

Tick Rate

  • Arg: -tick-rate <duration>

The brainz process has a main loop that handles a lot of different tasks, such as removal of old database entries, checking deployments, down agents, updating states of deployments, etc. This is the interval for which these checks will run. (default 2s)

Mod Admin User

  • Arg: -mod-admin-user <bool>

This will tell brainz to update or create a system administrator. When specifying the two environment variables VARNISH_CONTROLLER_SYSTEM_ADMIN_USER and VARNISH_CONTROLLER_SYSTEM_ADMIN_PASS the user given by the environment variables will automatically be created/updated. If these two environment variables aren’t set, brainz will ask for interactive input of username and password.

Max Key Age

  • Arg: -max-key-age <duration>

The max key age is the maximum age the current JWT signing key can have before a new key is generated. The previous keys will be kept until there are no signed JWTs with these keys remaining. All new JWTs will be signed with the latest generated key. Both the access token and refresh token consist of a JWT that is signed with these keys. (default 24h0m0s)

MMDB Database CSV

  • Arg: -mmdb-file-csv <file/url>

GeoIP database file as CSV for geolocation validation and ensuring correctness of location naming. This should be the corresponding CSV version of the GeoIP MMDB file added to the router. This is only necessary if the router is in use and the routing decision ‘Geolocation’ will be used. The argument to this flag can either be a file path or an URL. in case this is a URL, ‘Last-Modified’ header must to be set.

MMDB File CSV Watcher

  • Arg: -mmdb-file-csv-watcher <duration>

How often to check for a new or updated GeoIP CSV file during runtime.(default 24h0m0s)

Compile Timeout

  • Arg: -compile-timeout <duration>

When a VCLGroup is deployed OR validated its given VCL files will be compiled. This is a process that can take some time depending on the size of the VCL files. This setting should be set larger than the maximum time it takes to compile used VCL files. If this is set to low, timeout will occur between both agent and brainz and also for the REST API calls for functions that compile the VCL files. This should also be configured with the same value for api-gw. (default 1m0s)

Deploy Retry Time

  • Arg: -deploy-retry-time <duration>

The deploy retry time is multiplied with number of current retries for a previously failed deployment to an agent. Hence, the first retry attempt will be performed after the configured deploy-retry-time and if that attempt also fails, the next attempt will be performed after twice as long time. The maximum time to wait for a retry will be the deploy-retry-max configured time.

Note that deployments will not be made at the exact interval configured here. Rather it will mark the VCLGroup for deployment and brainz will take it into account during the next deployment verification that happens at least every 10sec. If a retry should be made faster, a deploy or a reload can be triggered via the API. A deploy or reload of the VCLGroup will also reset the retry counter and the back-off algorithm described here, will be reset. (default 10s)

Deploy Retry Max

  • Arg: -deploy-retry-max <duration>

Maximum time between each retry of a previously failed deployment to an agent. When the deploy-retry-time multiplied with the number of retries reaches a delay longer than deploy-retry-max, the deploy-retry-max value will be used. Meaning that from now on, each deploy attempt will be made every deploy-retry-max (until successful deployment). (default 5m0s)


  • Arg: -quit

When this argument is provided, brainz will automatically exit after performing tasks such as -mod-admin-user for administrator user creation. This is suitable as a one shot invocation to create the first system administrator account without the further need of exposing system administrator credentials when starting brainz.

Using Help

  • Arg: --help

The varnish-controller-brainz provides a full list of parameters with --help and then exit.