SearchVarnish 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
# RPM-based
sudo dnf install varnish-controller-brainz
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.
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).
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 <duration>VARNISH_CONTROLLER_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 <duration>VARNISH_CONTROLLER_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)
-hb-timeout <duration>VARNISH_CONTROLLER_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 <duration>VARNISH_CONTROLLER_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 <bool>VARNISH_CONTROLLER_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 <duration>VARNISH_CONTROLLER_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-file-csv <file/url>VARNISH_CONTROLLER_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 <duration>VARNISH_CONTROLLER_MMDB_FILE_CSV_WATCHER=<duration>How often to check for a new or updated GeoIP CSV file during runtime.(default 24h0m0s)
-compile-timeout <duration>VARNISH_CONTROLLER_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 <duration>VARNISH_CONTROLLER_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 <duration>VARNISH_CONTROLLER_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)
-quitVARNISH_CONTROLLER_QUITWhen 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.
--helpThe varnish-controller-brainz provides a full list of parameters with --help and then exit.