Configuration

Configuration options

Start Varnish Broadcaster with any of the options below. They’ve been pre-configured with default values, except the cfg option which points to the file containing the nodes to broadcast against.

Broadcaster doesn’t have a specific requirement of running in its own VM, but if running on the same node with Varnish and Hitch, it’s worth taking into account Broadcaster’s https configuration to avoid port collision with Hitch.

Arguments that take a duration value, such as -timeout, use Go time Duration format. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”. A combination of units can be used to express a duration, e.g. 1h10m30s.

Option	About	Default	Required
`port`	The port under which Broadcaster is exposed.	8088
`mgmt-port`	Listening port for Broadcaster’s management.	8089
`cfg`	Path to a file containing configured nodes.		X
`a`	Enable async mode. If true, any incoming request will return immediately with a X-Job-Id header.	false
`ttl`	The ttl of a finished invalidation request. When done, every invalidation request is kept in memory for the specified amount of time. This due to status purposes only.	10m
`log`	Set log level. Available options: debug, info, warning, error, quiet.	info
`https-port`	Broadcaster https listening port.	8443
`crt`	CRT file used for HTTPS support.		For HTTPS
`key`	KEY file used for HTTPS support.		For HTTPS
`V`	Show current version and exit.
`host`	Set Broadcaster’s running host.	0.0.0.0
`keep-alive`	Keep-alive duration between Broadcaster and configured nodes.	1m
`keep-alive-disabled`	Disable keep-alive between Broadcaster and the configured nodes.	false
`pid`	Path to a file where Broadcaster writes its pid.	/run/varnish-broadcaster/broadcaster.pid
`proxy-host`	Proxy host for the user interface (deprecated, see `request-proxy-host`)
`request-proxy-host`	Host the UI will send requests towards (Broadcaster external host)
`proxy-port`	Port the UI will send requests towards (Broadcaster external port)
`proxy-proto`	Protocol the UI will send requests with (http or https)	http
`timeout`	Request timeout between Broadcaster and the configured nodes.	10s
`tls-verify`	TLS verification mode towards nodes (AUTO, CLIENT, SERVER, NONE).	AUTO
`confwatch`	Duration between checking for caches configuration file changes. The default is 0s and no check is performed.	0s
`mgmt-host`	Set Broadcaster’s management host, The default is using the same as the ‘-host’ option if not specified.	0.0.0.0
`mgmt-on`	Enables/disables the management interface	true

TLS verification

Varnish Broadcaster handles TLS certificate verification towards nodes in four different ways:

AUTO - The default. If the node in the configuration file is a hostname, it will use it for server name verification. If it’s an IP, it will use the host header from the incoming request. It won’t use local server IP/host in the validation.
CLIENT - Always use the Host header in the incoming request for server name verification.
SERVER - Always use the host/IP in the configuration file.
NONE - Don’t perform any TLS server name verification. This trusts ALL TLS certificates. Note: This is insecure and not recommended in production.

User interface

Varnish Broadcaster’s user interface (UI) can be reached on http://localhost:<mgmt-port>. The UI will, by default, issue requests towards Broadcaster’s listening port (-port), e.g. http://localhost:8088. To change the URL that the UI will perform requests towards, the configuration options -request-proxy-host, -proxy-port and proxy-proto should be used.

Example

-proxy-port 1234 -proxy-proto https -request-proxy-host example.com

This will make the UI send requests towards https://example.com:1234. Make sure that the assembled URL is routed correctly towards Broadcaster’s listening interface.

Logging

All logs from Varnish Broadcaster will be written to stdout. Using systemd, these logs can be seen using journald.

HTTPS support

By default, Broadcaster starts listening on the port, however - if both crt and key options are set, it will automatically switch onto HTTPS and listen to the https-port (default: 8443).

Optional headers

X-Broadcast-Group: Name of the cluster(s) to broadcast against, if not used - the broadcast will be done against all caches. Multiple group names are white-space separated.
X-Broadcast-Random: This header with the value * will tell Broadcaster to only broadcast to one node in each configured group. It will randomly select one. If the selected node is failing, the next one is tried and so forth, until a response from a node. The X-Broadcast-Group have precedence over X-Broadcast-Random. Hence, X-Broadcast-Group: * will override X-Broadcast-Random: *. Multiple groups are white-space separated. Mixing group names and * will use the group names and reject the *.
X-Broadcast-InOrder: By default, all relevant nodes are contacted in parallel. If this option is set to true, broadcaster will treat each relevant cluster one after the other. This is useful for purging multi-layer setup from upstream to downstream.The order is defined by the X-Broadcast-Group, or if it’s empty or *, by the nodes.conf file. Group names are white-space separated.
X-Broadcast-Skip: Blacklisted caches as a whitespace separated list. They will be skipped when processing a group.

See these examples.

Broadcaster’s user agent header

From release 1.2.4, all requests towards backends will include the header X-Broadcaster-Ua which includes the version of Varnish Broadcaster. The value for this header is in the form X-Broadcaster-Ua: Broadcaster/<version> (eg. X-Broadcaster-Ua: Broadcaster/1.2.4).

Header normalization

Broadcaster converts all request headers to canonical format. This converts the first letter and any letter following a hyphen to upper case; the rest are converted to lowercase. The HTTP standard requires all servers to treat the header names in a case-insensitive fashion, so normalization is only problematic if your server doesn’t respect the standard. This means that the header accept-encoding: text will be converted to Accept-Encoding: text.

Configuration file

Varnish Broadcaster requires a file, in which contains the nodes, to broadcast against. The format of the file is similar to the INI format.

Examples

Here are a couple of snippets from a valid configuration file:

There are two clusters (Europe/US), each with its own nodes:

# this is a comment
[Europe]
First = 1.2.3.4:9090
Second = 9.9.9.9:6081
Third = example.com

[US]
Alpha = http://[1::2]
Beta = 8.8.8.8

This configuration has all the nodes available in the local cluster:

alpha = 1.2.3.4
bravo = [1:2::3]:45
charlie = https://5.6.7.8:90
delta = http://[1::2]

Note: A combination of the two configurations is not allowed.

Thus, this configuration is invalid:

alpha = 1.2.3.4
bravo = [1:2::3]:45
[US]
charlie = https://5.6.7.8:90
delta = http://[1::2]

Configuration reload

If Varnish Broadcaster receives a SIGHUP notification, it will trigger a configuration reload from disk. Broadcaster can be started with a -confwatch <duration> flag to specify how often it should look for configuration file changes. When configured and a change has occurred, it will be reloaded automatically. confwatch is off (0s) by default.