Command line and signals

The Virtual Registry runs as a single process, varnish-supervisor, which starts and manages Varnish itself. The DEB and RPM packages run it from a systemd unit, and the Docker image runs it as the container entrypoint, so the command line below is what those already do rather than something that has to be typed.

Options

A single dash works as well as two.

--validate is worth running before a reload, since a configuration that fails to load leaves the running one in place but never takes effect:

varnish-supervisor --validate --config /etc/varnish-supervisor/default.yaml
configuration is valid

--defaults prints every setting with its default value and a comment describing it, generated from the same definitions the loader uses, so it never drifts from the software:

varnish-supervisor --defaults

Configuration files

SUPERVISOR_CONFIG names the configuration, and --config sets it. It takes a colon-separated list, and the files are merged in the order given, over the built-in defaults, so a later file overrides an earlier one:

varnish-supervisor --config /etc/orca/base.yaml:/etc/orca/site.yaml

That layering is what keeps a shared base configuration separate from what one deployment changes about it. Decoding is strict, so a key that no longer exists, or was never spelled the way the file spells it, fails the load rather than being ignored.

The packages and the image already point it somewhere:

• DEB and RPM: /etc/varnish-supervisor/default.yaml, passed by the systemd unit.
• The varnish/orca image: /etc/varnish-supervisor/default.yaml, holding the default configuration.

Environment variables

The Supervisor reads two variables of its own:

• SUPERVISOR_CONFIG: the configuration files, as above.
• SUPERVISOR_CONFIG_WATCH: on or off, forcing supervisor.config_watch regardless of what the configuration says. It is the switch to reach for when automatic reloads are themselves the problem. An unrecognised value fails the start rather than being ignored.

Several configuration settings name an environment variable rather than holding a secret themselves, so that the secret stays out of the configuration file: redirects.signing.key_env, remote_auth.password_env, and the firewall’s auth.token_env and private_key_env. Those variables have to be in the process environment:

# Docker
docker run -e REMOTE_AUTH_PASSWORD=... varnish/orca

# Docker Compose
services:
  orca:
    environment:
      - REMOTE_AUTH_PASSWORD=...

# Helm, in values.yaml. extraEnvs also takes a list, which is the form
# that can name a secret instead of holding the value.
extraEnvs:
- name: REMOTE_AUTH_PASSWORD
  valueFrom:
    secretKeyRef:
      name: orca-remote-auth
      key: password

# systemd, in a drop-in from `systemctl edit varnish-supervisor`
[Service]
Environment=REMOTE_AUTH_PASSWORD=...

A secret is better read from a file the platform mounts than written into a unit file or a values file. Under Kubernetes that means a secret projected into the environment, and under systemd an EnvironmentFile= that root alone can read.

Signals

SIGHUP reloads the configuration and reopens the log file. Reopening is what makes external log rotation work: a rotation tool renames the file, then signals, and the Supervisor writes to a fresh one. The systemd unit maps systemctl reload varnish-supervisor to this signal.

A reload applies what it can without interrupting traffic. Where the change reaches the generated VCL, Varnish is switched to the new one atomically and the cache survives. A setting that cannot be changed in a running process is refused, and the running configuration stays as it is.

SIGTERM and SIGINT shut down.