Command line

The Artifact Firewall is the varnish-artifact-firewall binary. The Docker image runs it as its entrypoint, and a command that names the binary runs it without the entrypoint’s banner:

docker run --rm varnish/artifact-firewall varnish-artifact-firewall -version

Options

Configuration file

The firewall reads one YAML file, named by -config or else by the ARTIFACT_FIREWALL_CONFIG environment variable, set to /etc/varnish-artifact-firewall/default.yaml in the image. The file holds these top-level sections:

• firewall: the firewall itself.
• license: the license.
• otel: OpenTelemetry.
• config_watch: reloading the file when it changes.

An unknown key stops the firewall at startup.

-schema prints the file’s JSON Schema, for an editor or a CI job to check a configuration before the firewall reads it:

docker run --rm varnish/artifact-firewall varnish-artifact-firewall -schema > config.schema.json

An editor that uses yaml-language-server reads it from a comment at the top of the file, with a path relative to the file:

# yaml-language-server: $schema=config.schema.json

The schema refuses an empty value, such as api_address:, although the firewall accepts one and keeps the default. Write api_address: "" to turn the admin API off.

Environment variables

• ARTIFACT_FIREWALL_CONFIG: the configuration file, when -config is not given.
• ARTIFACT_FIREWALL_CONFIG_WATCH: on or off, which overrides config_watch.enabled. Any other value is ignored with a warning.

Settings for a secret hold the name of an environment variable, not the secret itself: auth.token_env and github_app.private_key_env for a ruleset source, and redirects.signing.key_env.

Signals

• SIGHUP reloads the configuration file, rebuilds the rules, and reopens the log files, so that a rotation tool can rename a log file and then signal. In Docker, send it with docker kill --signal=HUP <container>.
• SIGTERM and SIGINT shut the firewall down.

config_watch

config_watch:
  enabled: true
  interval: 15

With enabled, the default, the firewall checks its configuration file’s contents every interval seconds, 15 by default, and reloads it when they changed. SIGHUP applies a change at once. The watcher follows the symbolic link swapped by Kubernetes when it updates a mounted ConfigMap, and leaves a file modified in the last 250 milliseconds for its next check, so a file that is still being written is not read.

Reloading the configuration

A reload applies the whole file or none of it. A file that does not parse or validate is refused, and so is a change to one of these, which needs a restart:

• address, port, api_address, deployment, work_dir, storage, redirects, maven, pypi, log_output and audit_log_output in the firewall section
• the otel and license sections
• the rulesets entries with git or http, added, removed, edited or reordered

A refused reload is logged at ERROR, naming the settings, and again at WARN every five minutes for as long as the running configuration differs from the file:

level=ERROR msg="failed to reload configuration" err="configuration changes not allowed for fields: [firewall.port]"

Everything else applies without dropping a connection, including registries and the rulesets entries with a path. A request is handled under the old configuration or the new one, never a mix of both. A reload fetches no Git or HTTP ruleset source, and applies mode only when its value in the file changed, so it does not undo a mode set through /api/mode. It logs the names of the changed firewall settings:

level=INFO msg="configuration reloaded" fields=[default_quarantine_days] field_count=1

SIGHUP also rebuilds the rules, from the ruleset files and from the last fetch of each remote source. That is how an edited ruleset file at a local path is applied, since the watcher looks at the configuration file only. Rulesets that load as they were leave the rules alone, as on a SIGHUP from log rotation. A rebuild that changes the rules sends the webhook, and so does a reload that changes preserve_manifest, registries, mode or default_quarantine_days.

A firewall bundled with the Virtual Registry is part of the Supervisor’s process and configuration, and none of this applies to it.