Varnish Controller


NATS is the message-bus used for communication between the Agent, Brainz, and API-GW. NATS can and should be clustered since it is a vital part of the Varnish Controller setup. To secure communication over NATS, TLS can be used.


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

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

Message Size

Varnish Controller NATS package comes with a configuration file for NATS. The default message size is increased to support larger file uploads. This can be configured in /etc/varnish/nats.conf.

max_payload: 104857600
max_pending: 104857600


NATS can be clustered with multiple servers. In a clustered setup, at least two servers are required as an argument to each client. If there are more NATS servers will be spread to the clients by NATS itself. That means that it’s always enough to give two servers as an argument to clients.

To activate NATS clustering the NATS servers need to know about each other.

Example configuration:

# Port 4222 is the port clients connect to. The same port can be used
# if the NATS servers are located on different hosts.
# -cluster specifies the host:port that other servers will use to join the cluster.
# host1:
nats-server -p 4222 -cluster nats://

# -routes specifies the another NATS servers cluster URL which is the URL this
# nats-server connects in order to join the cluster.
# host2:
nats-server -p 4222 -cluster nats:// -routes nats://host1:4248

# For each other server added to the cluster, it's setup in the same manner.
# Note that the `routes` could point to either Host1 or Host2.
# It will join the same cluster and still get information about the other
# server over the NATS gossip protocol.
# host3:
nats-server -p 4222 -cluster nats:// -routes nats://host2:4248

Clients can use this cluster to connect to (giving at least 2 servers):

# <name> is either 'brainz', 'agent' or 'api-gw'
varnish-controller-<name> -nats-server host1:4222,host2:4222

Detailed clustering information can be found here.


NATS can be configured with a port for monitoring. Specifying -m <port> to the nats-server will open a port that can be accessed in order to get various message-bus related information.

Detailed monitoring information can be found here.

Configure NATS With TLS

The NATS server can be started with TLS certificates and authentication with user, password, and token, such as:

nats-server --tls --tlscert server-crt.pem --tlskey server-key.pem --user test --pass test --token mytoken

It can also be configured (preferred) in nats.conf (default /etc/varnish/nats.conf).

Example configuration for having TLS between nats-servers and clients:

port: 4221
tls {
  cert_file: "/path/to/client-cert.pem"
  key_file:  "/path/to/client-key.pem"
  # CA File required if self-signed certificates are used
  ca_file: "/path/to/ca.pem"
  verify_and_map: false

# Cluster configuration
cluster {
  port: 5221
  tls {
    cert_file: "/path/to/client-cert.pem"
    key_file:  "/path/to/client-key.pem"
    ca_file: "/path/to/ca.pem"
    verify: true
  routes = [
    # The other nats-server

Detailed TLS information including how to create self-signed certs can be found here.

Varnish Controller Configuration NATS TLS

If NATS is running with TLS the Varnish Controller processes must also be configured with TLS for NATS.

All the Varnish Controller binaries have the same arguments with regard to NATS TLS:

  • nats-server - Comma separated list of servers in the form of user:pass@host:port.
  • nats-token - If token has been configured for the NATS server.
  • nats-insecure-tls - Do not perform TLS server name verification (insecure, do not use in production).
  • nats-client-key - Client TLS key
  • nats-client-cert - Client TLS cert
  • nats-ca - CA file


varnish-controller-<name> -nats-server user:pass@,user:pass@ -nats-token mysecrettoken -nats-client-key server.key -nats-client-cert server.crt

Note that these parameters can be set in a configuration file or as environment variables.