Varnish `varnishadm` quick reference

This is a concise guide to common varnishadm tasks: connecting, inspecting state, managing VCLs, backends, bans, parameters, and the child process. Commands are broadly compatible with Varnish 6–7, but minor differences exist by version.

Connect

Local default instance (root):

varnishadm

Specific instance name (systemd multi-instance setups):

varnishadm -n <instance_name>

Remote or explicit socket with shared secret:

varnishadm -T 127.0.0.1:6082 -S /etc/varnish/secret

Run a single command non-interactively:

varnishadm -T 127.0.0.1:6082 -S /etc/varnish/secret vcl.list

Quick health checks

help                 # List available CLI commands
ping                 # Round-trip check to the child
status               # Child process state (running / stopped)

VCL management

List loaded VCLs (use -j for JSON):

vcl.list
vcl.list -j

Load a new VCL and give it a name:

vcl.load site_20251021 /etc/varnish/site.vcl

Activate a loaded VCL:

vcl.use site_20251021

Show a VCL’s source (helpful when debugging):

vcl.show site_20251021

Change a VCL’s state (temperature):

vcl.state site_20251021 warm   # warm | cold | auto

Discard an old, unused VCL:

vcl.discard site_20250901

Create or point a label at a VCL (blue/green style):

vcl.label live site_20251021
vcl.use live

Backend control

List backends and health (use -j for JSON):

backend.list
backend.list -j

Force backend health (overrides probes until set back to auto):

backend.set_health default healthy   # healthy | sick | auto

Cache invalidation (bans)

Bans mark cached objects for eviction on next lookup. Prefer targeted expressions.

See current bans:

ban.list
ban.list -j

Purge a single URL on a single host:

ban 'req.http.host == "www.example.com" && req.url == "/path/to/page"'

Purge a path prefix for a host:

ban 'req.http.host == "www.example.com" && req.url ~ "^/assets/"'

Purge by extension across a host:

ban 'req.http.host == "www.example.com" && req.url ~ "\.(css|js|png|jpg)$"'

Purge everything for a host (use with care):

ban 'req.http.host == "www.example.com"'

Purge everything (rarely appropriate outside emergencies):

ban 'req.url ~ "."'

Tip: quote the entire ban expression in the shell to avoid regex or ampersand parsing issues.

Parameters

Show all parameters (use -j for JSON):

param.show
param.show -j

Show a specific parameter, with description:

param.show thread_pools

Change a parameter at runtime:

param.set thread_pool_min 100

Reset a parameter to default:

param.reset thread_pool_min

Changes here are volatile; persist via your service/unit configuration for restarts.

Child (worker) process control

start   # Start the child if stopped
stop    # Stop the child (cache goes offline; CLI stays up)
status  # Check current child state

Storage and object visibility

List storage backends and usage:

storage.list
storage.list -j

Panic diagnostics

Show last panic (if any):

panic.show

Clear recorded panic:

panic.clear

Practical patterns

Atomic VCL rollouts:

vcl.load site_YYYYMMDDHH /etc/varnish/site.vcl
Optional sanity check: vcl.show site_YYYYMMDDHH
vcl.use site_YYYYMMDDHH
After a soak period: vcl.discard site_OLD

Blue/green with labels:

vcl.load site_green /etc/varnish/site-green.vcl
vcl.label live site_green (instant switch)
Keep previous VCL loaded for quick rollback, then discard later

Targeted purge after deploy:

ban 'req.http.host == "www.example.com" && req.url ~ "^/(assets|static)/"'

JSON-friendly outputs

Many list commands accept -j for scripting:

vcl.list -j
backend.list -j
ban.list -j
param.show -j
storage.list -j

Pipe to jq or similar for automation.

Troubleshooting checklist

status and ping to verify the child is alive.
backend.list to confirm health states match expectations.
ban.list to ensure bans aren’t piling up excessively.
panic.show if the child is crashing or stopped unexpectedly.
param.show for thread pools and timeout tuning during load.

Notes

Access typically requires the shared secret (-S) and admin socket (-T). On many distros the secret is /etc/varnish/secret and the admin port is 6082.
Some commands and flags vary slightly by Varnish version; use help to confirm availability in your build.
For metrics and logs, use companion tools (varnishstat, varnishlog, varnishncsa), not varnishadm.

Varnish varnishadm quick reference