The Varnish Reference Manual on Varnish Cache

Shell Tricks

Mon, 16 Mar 2026 00:00:00 +0000

All the varnish programs can be invoked with the single argument --optstring to request their getopt() specification, which simplifies wrapper scripts:

optstring=$(varnishfoo --optstring)

while getopts "$optstring" opt
do
 case $opt in
 n)
 # handle $OPTARG
 ;;
 # handle other options
 *)
 # ignore unneeded options
 ;;
 esac
done

varnishfoo "$@"

# do something with the options

Varnish Command Line Interface

Mon, 16 Mar 2026 00:00:00 +0000

Description

Varnish has a command line interface (CLI) which can control and change most of the operational parameters and the configuration of Varnish, without interrupting the running service.

The CLI can be used for the following tasks:

Configuration

You can upload, change and delete VCL files from the CLI.

Parameters

You can inspect and change the various parameters Varnish has available through the CLI. The individual parameters are documented in the varnishd reference documentation.

Varnish Processing States

Mon, 16 Mar 2026 00:00:00 +0000

Introduction

Varnish processing of client and backend requests is implemented as state machines. Whenever a state is entered, a C function is called, which in turn calls the appropriate Varnish core code functions to process the request or response at this stage. For most states, core code also calls into a state-specific function compiled from VCL, a VCL subroutine (see VCL Steps).

varnish-counters

Mon, 16 Mar 2026 00:00:00 +0000

Varnish counter field definitions

Manual section: 7

LCK – Lock Counters

Counters which track the activity in the different classes of mutex-locks.

varnishadm

Mon, 16 Mar 2026 00:00:00 +0000

Control a running Varnish instance

Manual section: 1

SYNOPSIS

varnishadm [-h] [-n workdir] [-p] [-S secretfile] [-T [address]:port] [-t timeout] [command […]]

DESCRIPTION

The varnishadm utility establishes a CLI connection to varnishd either using -n workdir or using the -T and -S arguments. If -n workdir is given, the location of the secret file and the address:port are looked up in shared memory. If neither is given, varnishadm uses the -n defaults documented for varnishd.

varnishd

Mon, 16 Mar 2026 00:00:00 +0000

HTTP accelerator daemon

Manual section: 1

SYNOPSIS

varnishd
[-a [name=][listen_address[,PROTO|,option=value,…]]
 [-A cfgfile]
 [-b [host[:port]|path]]
 [-C]
 [-d]
 [-E extension]
 [-F]
 [-f config]
 [-h type[,options]]
 [-I clifile]
 [-i identity]
 [-j jail[,jailoptions]]
 [-l vsl]
 [-M address:port]
 [-n workdir]
 [-P file]
 [-p param=value]
 [-r param[,param…]]
 [-S secret-file]
 [-s [name=]kind[,options]]
 [-T address[:port]]
 [-t TTL]
 [-V]
 [-W waiter]

varnishd [-x parameter|vsl|cli|builtin|optstring]

varnishd [-?]

DESCRIPTION

The varnishd daemon accepts HTTP requests from clients, passes them on to a backend server and caches the returned documents to better satisfy future requests for the same document.

varnishhist

Mon, 16 Mar 2026 00:00:00 +0000

Varnish request histogram

Manual section: 1

SYNOPSIS

varnishhist [-B ] [-C] [-d] [-g <request|vxid>] [-h] [-L ] [-n ] [-p ] [-P responsetime] [-P reqbodytime] [-P size] [-P Bereqtime] [-P Beresptime] [-P BerespBodytime] [-P Besize] [-P <[cbE:]tag:[prefix]:field_num[:min:max]>] [-Q ] [-q ] [-r ] [-t <seconds|off>] [-T ] [-V]

DESCRIPTION

The varnishhist utility reads varnishd(1) shared memory logs and presents a continuously updated histogram showing the distribution of the last N requests by their processing. The value of N and the vertical scale are displayed in the top left corner. The horizontal scale is logarithmic. Hits are marked with a pipe character (“|”), and misses are marked with a hash character (“#”).

varnishlog

Mon, 16 Mar 2026 00:00:00 +0000

Display Varnish logs

Manual section: 1

SYNOPSIS

varnishlog [-a] [-A] [-b] [-c] [-C] [-d] [-D] [-E] [-g <session|request|vxid|raw>] [-h] [-i ] [-I <[taglist:]regex>] [-k ] [-L ] [-n ] [-P ] [-Q ] [-q ] [-r ] [-R <limit[/duration]>] [-t <seconds|off>] [-T ] [-u] [-v] [-V] [-w ] [-x ] [-X <[taglist:]regex>]

varnishncsa

Mon, 16 Mar 2026 00:00:00 +0000

Display Varnish logs in Apache / NCSA combined log format

Manual section: 1

SYNOPSIS

varnishncsa [-a] [-b] [-c] [-C] [-d] [-D] [-E] [-F ] [-f ] [-g <request|vxid>] [-h] [-j] [-k ] [-L ] [-n ] [-P ] [-Q ] [-q ] [-r ] [-R <limit[/duration]>] [-t <seconds|off>] [-V] [-w ]

DESCRIPTION

The varnishncsa utility reads varnishd(1) shared memory logs and presents them in the Apache / NCSA “combined” log format.

varnishstat

Mon, 16 Mar 2026 00:00:00 +0000

Varnish Cache statistics

SYNOPSIS

varnishstat [-1] [-c] [-f <glob>] [-h] [-I <glob>] [-j] [-l] [-n <workdir>] [-r] [-t <seconds|off>] [-V] [-X <glob>] [-x]

DESCRIPTION

The varnishstat utility displays statistics from a running varnishd(1) instance.

The following options are available:

CURSES MODE

When neither -1, -j nor -x options are given, the application starts up in curses mode. This shows a continuously updated view of the counter values, along with their description.

varnishtest

Mon, 16 Mar 2026 00:00:00 +0000

Test program for Varnish

Manual section: 1

SYNOPSIS

varnishtest [-hikLlqv] [-b size] [-D name=val] [-j jobs] [-n iter] [-t duration] file [file …]

DESCRIPTION

The varnishtest program is a script driven program used to test the Varnish Cache.

The varnishtest program, when started and given one or more script files, can create a number of threads representing backends, some threads representing clients, and a varnishd process. This is then used to simulate a transaction to provoke a specific behavior.

varnishtop

Mon, 16 Mar 2026 00:00:00 +0000

Varnish log entry ranking

Manual section: 1

SYNOPSIS

varnishtop [-1] [-b] [-c] [-C] [-d] [-E] [-f] [-g <session|request|vxid|raw>] [-h] [-i ] [-I <[taglist:]regex>] [-L ] [-n ] [-p ] [-Q ] [-q ] [-r ] [-t <seconds|off>] [-T ] [-x ] [-X <[taglist:]regex>] [-V]

DESCRIPTION

The varnishtop utility reads varnishd shared memory logs and presents a continuously updated list of the most commonly occurring log entries. With suitable filtering using the -I, -i, -X and -x options, it can be used to display a ranking of requested documents, clients, user agents, or any other information which is recorded in the log.

VCL

Mon, 16 Mar 2026 00:00:00 +0000

Varnish Configuration Language

Manual section: 7

DESCRIPTION

The VCL language is a small domain-specific language designed to be used to describe request handling and document caching policies for Varnish Cache.

When a new configuration is loaded, the varnishd management process translates the VCL code to C and compiles it to a shared object which is then loaded into the server process.

VCL-backends

Mon, 16 Mar 2026 00:00:00 +0000

Configuring Backends

Manual section: 7

Backend definition

A backend declaration creates and initialises a named backend object. A declaration start with the keyword backend followed by the name of the backend. The actual declaration is in curly brackets, in a key/value fashion.:

backend name {
 .attribute1 = value;
 .attribute2 = value;
 [...]
}

If there is a backend named default it will be used unless another backend is explicitly set. If no backend is named default the first backend in the VCL program becomes the default.

VCL-probe

Mon, 16 Mar 2026 00:00:00 +0000

Configuring Backend Health Probes

Manual section: 7

Backend health probes

Varnish can be configured to periodically send a request to test if a backend is answering and thus “healthy”.

Probes can be configured per backend:

backend foo {
 [...]
 .probe = {
 [...]
 }
}

They can be named and shared between backends:

VCL-steps

Mon, 16 Mar 2026 00:00:00 +0000

Built-in subroutines

Manual section: 7

DESCRIPTION

Various built-in subroutines are called during processing of client and backend requests as well as upon vcl.load and vcl.discard.

See Varnish Processing States for a detailed graphical overview of the states and how they relate to core code functions and VCL subroutines.

Built-in subroutines always terminate with a return (<action>), where <action> determines how processing continues in the request processing state machine.

VCL-Variables

Mon, 16 Mar 2026 00:00:00 +0000

The complete album

Manual section: 7

DESCRIPTION

This is a list of all variables in the VCL language.

Variable names take the form scope.variable[.index], for instance:

req.url
beresp.http.date
client.ip

Which operations are possible on each variable is described below, often with the shorthand “backend” which covers the vcl_backend_* {} subroutines and “client” which covers the rest, except vcl_init {} and vcl_fini {}.

VCLI protocol - Scripting the CLI interface

Mon, 16 Mar 2026 00:00:00 +0000

The Varnish CLI has a few bells&whistles when used as an API.

First: vcli.h contains magic numbers.

Second: If you use varnishadm to connect to varnishd for API purposes, use the -p argument to get “pass” mode.

In “pass” mode, or with direct CLI connections (more below), the first line of responses is always exactly 13 bytes long, including the NL, and it contains two numbers: The status code and the count of bytes in the “body” of the response:

VEXT - Varnish Extensions

Mon, 16 Mar 2026 00:00:00 +0000

A Varnish Extension is a shared library, loaded into the worker process during startup, before privileges are dropped for good. This allows a VEXT to do pretty much anything it wants to do in the worker process.

A VEXT can (also) contain a VMOD, and it will work just like any other VMOD, which also means that VMODs can be loaded as VEXTs.

VMOD - Varnish Modules

Mon, 16 Mar 2026 00:00:00 +0000

For all you can do in VCL, there are things you cannot do. Look an IP number up in a database file for instance. VCL provides for inline C code, and there you can do everything, but it is not a convenient or even readable way to solve such problems.

This is where VMODs come into the picture: A VMOD is a shared library with some C functions which can be called from VCL code.

VMOD blob - Utilities for the VCL blob type, encoding and decoding

Mon, 16 Mar 2026 00:00:00 +0000

SYNOPSIS

import blob [as name] [from "path"]

[BLOB decode(ENUM decoding, INT length, STRING encoded)](#blob-decode)

[STRING encode(ENUM encoding, ENUM case, BLOB blob)](#blob-encode)

[STRING transcode(ENUM decoding, ENUM encoding, ENUM case, INT length, STRING encoded)](#blob-transcode)

[BOOL same(BLOB, BLOB)](#blob-same)

[BOOL equal(BLOB, BLOB)](#blob-equal)

[INT length(BLOB)](#blob-length)

[BLOB sub(BLOB, BYTES length, BYTES offset=0)](#blob-sub)

[new xblob = blob.blob(ENUM decoding, STRING encoded)](#blob-blob)

 [BLOB xblob.get()](#xblob-get)

 [STRING xblob.encode(ENUM encoding, ENUM case)](#xblob-encode)

DESCRIPTION

This VMOD provides utility functions and an object for the VCL data type BLOB, which may contain arbitrary data of any length.

VMOD cookie - Varnish Cookie Module

Mon, 16 Mar 2026 00:00:00 +0000

SYNOPSIS

import cookie [as name] [from "path"]

[VOID clean()](#cookie-clean)

[VOID delete(STRING cookiename)](#cookie-delete)

[VOID filter(STRING filterstring)](#cookie-filter)

[VOID filter_re(REGEX expression)](#cookie-filter-re)

[VOID keep(STRING filterstring)](#cookie-keep)

[VOID keep_re(REGEX expression)](#cookie-keep-re)

[STRING format_date(TIME now, DURATION timedelta)](#cookie-format-date)

[STRING get(STRING cookiename)](#cookie-get)

[STRING get_re(REGEX expression)](#cookie-get-re)

[STRING get_string()](#cookie-get-string)

[BOOL isset(STRING cookiename)](#cookie-isset)

[VOID parse(STRING cookieheader)](#cookie-parse)

[VOID set(STRING cookiename, STRING value)](#cookie-set)

DESCRIPTION

Handle HTTP cookies more easily in Varnish VCL.

VMOD directors - Varnish Directors Module

Mon, 16 Mar 2026 00:00:00 +0000

SYNOPSIS

import directors [as name] [from "path"]

[new xround_robin = directors.round_robin()](#directors-round-robin)

 [VOID xround_robin.add_backend(BACKEND)](#xround-robin-add-backend)

 [VOID xround_robin.remove_backend(BACKEND)](#xround-robin-remove-backend)

 [BACKEND xround_robin.backend()](#xround-robin-backend)

[new xfallback = directors.fallback(BOOL sticky=0)](#directors-fallback)

 [VOID xfallback.add_backend(BACKEND)](#xfallback-add-backend)

 [VOID xfallback.remove_backend(BACKEND)](#xfallback-remove-backend)

 [BACKEND xfallback.backend()](#xfallback-backend)

[new xrandom = directors.random()](#directors-random)

 [VOID xrandom.add_backend(BACKEND, REAL)](#xrandom-add-backend)

 [VOID xrandom.remove_backend(BACKEND)](#xrandom-remove-backend)

 [BACKEND xrandom.backend()](#xrandom-backend)

[new xhash = directors.hash()](#directors-hash)

 [VOID xhash.add_backend(BACKEND, REAL weight=1.0)](#xhash-add-backend)

 [VOID xhash.remove_backend(BACKEND)](#xhash-remove-backend)

 [BACKEND xhash.backend(STRING)](#xhash-backend)

[new xshard = directors.shard()](#directors-shard)

 [VOID xshard.set_warmup(REAL probability=0.0)](#xshard-set-warmup)

 [VOID xshard.set_rampup(DURATION duration=0)](#xshard-set-rampup)

 [VOID xshard.associate(BLOB param=0)](#xshard-associate)

 [BOOL xshard.add_backend(BACKEND backend, [STRING ident], [DURATION rampup], [REAL weight])](#xshard-add-backend)

 [BOOL xshard.remove_backend([BACKEND backend], [STRING ident])](#xshard-remove-backend)

 [BOOL xshard.clear()](#xshard-clear)

 [BOOL xshard.reconfigure(INT replicas=67)](#xshard-reconfigure)

 [INT xshard.key(STRING)](#xshard-key)

 [BACKEND xshard.backend([ENUM by], [INT key], [BLOB key_blob], [INT alt], [REAL warmup], [BOOL rampup], [ENUM healthy], [BLOB param], [ENUM resolve])](#xshard-backend)

 [VOID xshard.debug(INT)](#xshard-debug)

[new xshard_param = directors.shard_param()](#directors-shard-param)

 [VOID xshard_param.clear()](#xshard-param-clear)

 [VOID xshard_param.set([ENUM by], [INT key], [BLOB key_blob], [INT alt], [REAL warmup], [BOOL rampup], [ENUM healthy])](#xshard-param-set)

 [STRING xshard_param.get_by()](#xshard-param-get-by)

 [INT xshard_param.get_key()](#xshard-param-get-key)

 [INT xshard_param.get_alt()](#xshard-param-get-alt)

 [REAL xshard_param.get_warmup()](#xshard-param-get-warmup)

 [BOOL xshard_param.get_rampup()](#xshard-param-get-rampup)

 [STRING xshard_param.get_healthy()](#xshard-param-get-healthy)

 [BLOB xshard_param.use()](#xshard-param-use)

[BACKEND lookup(STRING)](#directors-lookup)

DESCRIPTION

vmod_directors enables backend load balancing in Varnish.

VMOD h2 - Module to control the built-in HTTP2 transport

Mon, 16 Mar 2026 00:00:00 +0000

SYNOPSIS

import h2 [as name] [from "path"]

[BOOL is()](#h2-is)

[DURATION rapid_reset([DURATION threshold])](#h2-rapid-reset)

[INT rapid_reset_limit([INT number])](#h2-rapid-reset-limit)

[DURATION rapid_reset_period([DURATION duration])](#h2-rapid-reset-period)

[REAL rapid_reset_budget()](#h2-rapid-reset-budget)

DESCRIPTION

This VMOD contains functions to control the HTTP2 transport built into Varnish-Cache.

VMOD proxy - Varnish Module to extract TLV attributes from PROXYv2

Mon, 16 Mar 2026 00:00:00 +0000

SYNOPSIS

import proxy [as name] [from "path"]

[STRING alpn()](#proxy-alpn)

[STRING authority()](#proxy-authority)

[BOOL is_ssl()](#proxy-is-ssl)

[BOOL client_has_cert_sess()](#proxy-client-has-cert-sess)

[BOOL client_has_cert_conn()](#proxy-client-has-cert-conn)

[INT ssl_verify_result()](#proxy-ssl-verify-result)

[STRING ssl_version()](#proxy-ssl-version)

[STRING client_cert_cn()](#proxy-client-cert-cn)

[STRING ssl_cipher()](#proxy-ssl-cipher)

[STRING cert_sign()](#proxy-cert-sign)

[STRING cert_key()](#proxy-cert-key)

DESCRIPTION

vmod_proxy contains functions to extract proxy-protocol-v2 TLV attributes as described in https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt.

VMOD purge - Varnish Purge Module

Mon, 16 Mar 2026 00:00:00 +0000

SYNOPSIS

import purge [as name] [from "path"]

[INT hard()](#purge-hard)

[INT soft(DURATION ttl, DURATION grace, DURATION keep)](#purge-soft)

DESCRIPTION

vmod_purge contains functions that offer a finer-grained control than return(purge) from vcl_recv{}. The functions can only be called from vcl_hit{} or vcl_miss{} and they should in general be used in both to ensure that all variants of a same object are taken care of.

VMOD std - Varnish Standard Module

Mon, 16 Mar 2026 00:00:00 +0000

SYNOPSIS

import std [as name] [from "path"]

[REAL random(REAL lo, REAL hi)](#std-random)

[REAL round(REAL r)](#std-round)

[VOID collect(HEADER hdr, STRING sep=”, “)](#std-collect)

[STRING querysort(STRING)](#std-querysort)

[STRING toupper(STRING s)](#std-toupper)

[STRING tolower(STRING s)](#std-tolower)

[STRING strstr(STRING s1, STRING s2)](#std-strstr)

[BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname, BOOL noescape, BOOL period)](#std-fnmatch)

[STRING fileread(STRING)](#std-fileread)

[BLOB blobread(STRING)](#std-blobread)

[BOOL file_exists(STRING path)](#std-file-exists)

[BOOL healthy(BACKEND be)](#std-healthy)

[INT port(IP ip)](#std-port)

[DURATION duration([STRING s], [DURATION fallback], [REAL real], [INT integer])](#std-duration)

[BYTES bytes([STRING s], [BYTES fallback], [REAL real], [INT integer])](#std-bytes)

[INT integer([STRING s], [INT fallback], [BOOL bool], [BYTES bytes], [DURATION duration], [REAL real], [TIME time])](#std-integer)

[IP ip(STRING s, [IP fallback], BOOL resolve=1, [STRING p])](#std-ip)

[REAL real([STRING s], [REAL fallback], [INT integer], [BOOL bool], [BYTES bytes], [DURATION duration], [TIME time])](#std-real)

[TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])](#std-time)

[STRING strftime(TIME time, STRING format)](#std-strftime)

[VOID log(STRING s)](#std-log)

[VOID syslog(INT priority, STRING s)](#std-syslog)

[VOID timestamp(STRING s)](#std-timestamp)

[BOOL syntax(REAL)](#std-syntax)

[STRING getenv(STRING name)](#std-getenv)

[BOOL cache_req_body(BYTES size)](#std-cache-req-body)

[VOID late_100_continue(BOOL late)](#std-late-100-continue)

[VOID set_ip_tos(INT tos)](#std-set-ip-tos)

[VOID rollback(HTTP h)](#std-rollback)

[BOOL ban(STRING)](#std-ban)

[STRING ban_error()](#std-ban-error)

[TIME now()](#std-now)

[DURATION timed_call(SUB)](#std-timed-call)

DESCRIPTION

vmod_std contains basic functions which are part and parcel of Varnish, but which for reasons of architecture fit better in a VMOD.

VMOD unix - Utilities for Unix domain sockets

Mon, 16 Mar 2026 00:00:00 +0000

SYNOPSIS

import unix [as name] [from "path"]

[STRING user()](#unix-user)

[STRING group()](#unix-group)

[INT uid()](#unix-uid)

[INT gid()](#unix-gid)

DESCRIPTION

This VMOD provides information about the credentials of the peer process (user and group of the process owner) that is connected to a Varnish listener via a Unix domain socket, if the platform supports it.

VMOD vtc - Utility module for varnishtest

Mon, 16 Mar 2026 00:00:00 +0000

SYNOPSIS

import vtc [as name] [from "path"]

[VOID barrier_sync(STRING addr, DURATION timeout=0)](#vtc-barrier-sync)

[BACKEND no_backend()](#vtc-no-backend)

[STEVEDORE no_stevedore()](#vtc-no-stevedore)

[IP no_ip()](#vtc-no-ip)

[VOID panic(STRING)](#vtc-panic)

[VOID sleep(DURATION)](#vtc-sleep)

[VOID workspace_alloc(ENUM, INT size)](#vtc-workspace-alloc)

[BYTES workspace_reserve(ENUM, INT size)](#vtc-workspace-reserve)

[INT workspace_free(ENUM {client, backend, session, thread})](#vtc-workspace-free)

[VOID workspace_snapshot(ENUM)](#vtc-workspace-snapshot)

[VOID workspace_reset(ENUM)](#vtc-workspace-reset)

[BOOL workspace_overflowed(ENUM)](#vtc-workspace-overflowed)

[VOID workspace_overflow(ENUM)](#vtc-workspace-overflow)

[BLOB workspace_dump(ENUM, ENUM, BYTES off, BYTES len)](#vtc-workspace-dump)

[INT typesize(STRING)](#vtc-typesize)

[BLOB proxy_header(ENUM version, IP client, IP server, STRING authority)](#vtc-proxy-header)

[VOID vsl(INT vxid, STRING tag, ENUM {c, b} side, STRING s)](#vtc-vsl)

[VOID vsl_replay(STRING s)](#vtc-vsl-replay)

DESCRIPTION

The goal for this VMOD is to provide VCL users and VMOD authors means to test corner cases or reach certain conditions with varnishtest.

Vmod_Math

Mon, 16 Mar 2026 00:00:00 +0000

VSL

Mon, 16 Mar 2026 00:00:00 +0000

Varnish Shared Memory Logging

Manual section: 7

OVERVIEW

This document describes the format and content of all the Varnish shared memory logging tags. These tags are used by the varnishlog(1), varnishtop(1), etc. logging tools supplied with Varnish.

VSL tags

BackendClose - Backend connection closed

Logged when a backend connection is closed.
The format is:

%d %s %s [ %s ]
| | | |
| | | +- Optional reason, see SessClose for explanation
| | +------ "close" or "recycle"
| +--------- Backend display name
+------------ Connection file descriptor

BackendOpen - Backend connection opened

Logged when a new backend connection is opened.
The format is:

%d %s %s %s %s %s %s [ %f %ld ]
| | | | | | | | |
| | | | | | | | +--- Connection reuses
| | | | | | | +------ Connection age
| | | | | | +----------- "connect" or "reuse"
| | | | | +-------------- Local port
| | | | +----------------- Local address
| | | +-------------------- Remote port
| | +----------------------- Remote address
| +-------------------------- Backend display name
+----------------------------- Connection file descriptor

Backend_health - Backend health check

The result of a backend health probe.
The format is:

%s %s %s %s %u %u %u %f %f %s
| | | | | | | | | |
| | | | | | | | | +- Probe HTTP response / error information
| | | | | | | | +---- Average response time
| | | | | | | +------- Response time
| | | | | | +---------- Probe window size
| | | | | +------------- Probe threshold level
| | | | +---------------- Number of good probes in window
| | | +------------------- Probe window bits
| | +---------------------- "healthy" or "sick"
| +------------------------- "Back", "Still" or "Went"
+---------------------------- Backend name

Probe window bits are:
```default '-': Could not connect '4': Good IPv4 '6': Good IPv6 'U': Good UNIX 'x': Error Xmit 'X': Good Xmit 'r': Error Recv 'R': Good Recv 'H': Happy ```
When the backend is just created, the window bits for health check slots that haven’t run yet appear as ‘-’ like failures to connect.

Begin - Marks the start of a VXID

The first record of a VXID transaction.
The format is:

%s %d %s [%u]
| | | |
| | | +- Task sub-level
| | +----- Reason
| +-------- Parent vxid
+----------- Type ("sess", "req" or "bereq")

BereqAcct - Backend request accounting

Contains byte counters from backend request processing.
The format is:

%d %d %d %d %d %d
| | | | | |
| | | | | +- Total bytes received
| | | | +---- Body bytes received
| | | +------- Header bytes received
| | +---------- Total bytes transmitted
| +------------- Body bytes transmitted
+---------------- Header bytes transmitted

BereqHeader - Backend request header

HTTP header contents.
The format is:

%s: %s
| |
| +- Header value
+----- Header name

NOTE: HTTP header fields are free form records and not strictly made of 2 fields. Accessing a specific header with the prefix notation helps treating the header value as a single string.

BereqMethod - Backend request method

The HTTP request method used.

BereqProtocol - Backend request protocol

The HTTP protocol version information.

BereqURL - Backend request URL

The HTTP request URL.

BereqUnset - Backend request unset header

HTTP header contents.
The format is:

%s: %s
| |
| +- Header value
+----- Header name

NOTE: HTTP header fields are free form records and not strictly made of 2 fields. Accessing a specific header with the prefix notation helps treating the header value as a single string.

BerespHeader - Backend response header

HTTP header contents.
The format is:

%s: %s
| |
| +- Header value
+----- Header name

NOTE: HTTP header fields are free form records and not strictly made of 2 fields. Accessing a specific header with the prefix notation helps treating the header value as a single string.

BerespProtocol - Backend response protocol

The HTTP protocol version information.

BerespReason - Backend response reason

The HTTP response reason string.

BerespStatus - Backend response status

The HTTP response status code.

BerespUnset - Backend response unset header

HTTP header contents.
The format is:

%s: %s
| |
| +- Header value
+----- Header name

NOTE: HTTP header fields are free form records and not strictly made of 2 fields. Accessing a specific header with the prefix notation helps treating the header value as a single string.

BogoHeader - Bogus HTTP received

Contains the first 20 characters of received HTTP headers we could not make sense of. Applies to both req.http and beresp.http.

CLI - CLI communication

CLI communication between varnishd master and child process.

Debug - Debug messages

Debug messages can normally be ignored, but are sometimes helpful during trouble-shooting. Most debug messages must be explicitly enabled with parameters.
Debug messages may be added, changed or removed without prior notice and shouldn’t be considered stable.
NB: This log record is masked by default.

ESI_xmlerror - ESI parser error or warning message

An error or warning was generated during parsing of an ESI object. The log record describes the problem encountered.

End - Marks the end of a VXID

The last record of a VXID transaction.

Error - Error messages

Error messages are stuff you probably want to know.

ExpBan - Object evicted due to ban

Logs the VXID when an object is banned.

ExpKill - Object expiry event

Logs events related to object expiry. The events are:

EXP_Rearm: Logged when the expiry time of an object changes.
EXP_Inbox; Logged when the expiry thread picks an object from the inbox for processing.
EXP_Kill; Logged when the expiry thread kills an object from the inbox.
EXP_When; Logged when the expiry thread moves an object on the binheap.
EXP_Inspect; Logged when the expiry thread inspects the next object scheduled to expire.
EXP_Expired; Logged when the expiry thread expires an object.
EXP_Removed; Logged when the expiry thread removes an object before expiry.
VBF_Superseded; Logged when an object supersedes another.
LRU_Cand; Logged when an object is evaluated for LRU force expiry.
LRU; Logged when an object is force expired due to LRU.
LRU_Fail; Logged when no suitable candidate object is found for LRU force expiry.
The format is:

EXP_Rearm p=%p E=%f e=%f f=0x%x
EXP_Inbox p=%p e=%f f=0x%x
EXP_Kill p=%p e=%f f=0x%x
EXP_When p=%p e=%f f=0x%x
EXP_Inspect p=%p e=%f f=0x%x
EXP_Expired x=%u t=%f h=%u
EXP_Removed x=%u t=%f h=%u
VBF_Superseded x=%u n=%u
LRU_Cand p=%p f=0x%x r=%d
LRU x=%u
LRU_Fail
<br/>
Legend:
p=%p Objcore pointer
t=%f Remaining TTL (s)
e=%f Expiry time (unix epoch)
E=%f Old expiry time (unix epoch)
f=0x%x Objcore flags
r=%d Objcore refcount
x=%u Object VXID
n=%u New object VXID
h=%u Objcore hits

FetchError - Error while fetching object

Logs the error message of a failed fetch operation.

Fetch_Body - Body fetched from backend

Ready to fetch body from backend.
The format is:

%d %s %s
| | |
| | +---- 'stream' or '-'
| +------- Text description of body fetch mode
+---------- Body fetch mode

Filters - Body filters

List of filters applied to the body

Gzip - G(un)zip performed on object

A Gzip record is emitted for each instance of gzip or gunzip work performed. Worst case, an ESI transaction stored in gzipped objects but delivered gunzipped, will run into many of these.
The format is:

%c %c %c %d %d %d %d %d
| | | | | | | |
| | | | | | | +- Bit length of compressed data
| | | | | | +---- Bit location of 'last' bit
| | | | | +------- Bit location of first deflate block
| | | | +---------- Bytes output
| | | +------------- Bytes input
| | +---------------- 'E': ESI, '-': Plain object
| +------------------- 'F': Fetch, 'D': Deliver
+---------------------- 'G': Gzip, 'U': Gunzip, 'u': Gunzip-test

Examples:
```default U F E 182 159 80 80 1392 G F E 159 173 80 1304 1314 ```

H2RxBody - Received HTTP2 frame body

Binary data

H2RxHdr - Received HTTP2 frame header

Binary data

H2TxBody - Transmitted HTTP2 frame body

Binary data

H2TxHdr - Transmitted HTTP2 frame header

Binary data

Hash - Value added to hash

This value was added to the object lookup hash.
NB: This log record is masked by default.

Hit - Hit object in cache

Object looked up in cache.
The format is:

%u %f %f %f [%u [%u]]
| | | | | |
| | | | | +- Content length
| | | | +----- Fetched so far
| | | +--------- Keep period
| | +------------ Grace period
| +--------------- Remaining TTL
+------------------ VXID of the object

HitMiss - Hit for miss object in cache.

Hit-for-miss object looked up in cache.
The format is:

%u %f
| |
| +- Remaining TTL
+---- VXID of the object

HitPass - Hit for pass object in cache.

Hit-for-pass object looked up in cache.
The format is:

%u %f
| |
| +- Remaining TTL
+---- VXID of the object

HttpGarbage - Unparseable HTTP request

Logs the content of unparseable HTTP requests.

Length - Size of object body

Logs the size of a fetch object body.

Link - Links to a child VXID

Links this VXID to any child VXID it initiates.
The format is:

%s %d %s [%u]
| | | |
| | | +- Child task sub-level
| | +----- Reason
| +-------- Child vxid
+----------- Child type ("sess", "req" or "bereq")

LostHeader - Failed attempt to set HTTP header

Logs the header name of a failed HTTP header operation due to resource exhaustion or configured limits.

Notice - Informational messages about request handling

Informational log messages on events occurred during request handling.
The format is:

%s: %s
| |
| +- Short description of the notice message
+----- Manual page containing the detailed description

See the NOTICE MESSAGES section below or the individual VMOD manual pages for detailed information of notice messages.

ObjHeader - Object header

HTTP header contents.
The format is:

%s: %s
| |
| +- Header value
+----- Header name

NOTE: HTTP header fields are free form records and not strictly made of 2 fields. Accessing a specific header with the prefix notation helps treating the header value as a single string.

ObjProtocol - Object protocol

The HTTP protocol version information.

ObjReason - Object reason

The HTTP response reason string.

ObjStatus - Object status

The HTTP response status code.

ObjUnset - Object unset header

HTTP header contents.
The format is:

%s: %s
| |
| +- Header value
+----- Header name

NOTE: HTTP header fields are free form records and not strictly made of 2 fields. Accessing a specific header with the prefix notation helps treating the header value as a single string.

PipeAcct - Pipe byte counts

Contains byte counters for pipe sessions.
The format is:

%d %d %d %d
| | | |
| | | +------- Piped bytes to client
| | +---------- Piped bytes from client
| +------------- Backend request headers
+---------------- Client request headers

Proxy - PROXY protocol information

PROXY protocol information.
The format is:

%d %s %d %s %d
| | | | |
| | | | +- server port
| | | +---- server ip
| | +------- client port
| +---------- client ip
+------------- PROXY protocol version
<br/>
All fields are "local" for PROXY local connections (command 0x0)

ProxyGarbage - Unparseable PROXY request

A PROXY protocol header was unparseable.

ReqAcct - Request handling byte counts

Contains byte counts for the request handling. The body bytes count includes transmission overhead (ie: chunked encoding). ESI sub-requests show the body bytes this ESI fragment including any subfragments contributed to the top level request. The format is:

%d %d %d %d %d %d
| | | | | |
| | | | | +- Total bytes transmitted
| | | | +---- Body bytes transmitted
| | | +------- Header bytes transmitted
| | +---------- Total bytes received
| +------------- Body bytes received
+---------------- Header bytes received

ReqHeader - Client request header

HTTP header contents.
The format is:

%s: %s
| |
| +- Header value
+----- Header name

NOTE: HTTP header fields are free form records and not strictly made of 2 fields. Accessing a specific header with the prefix notation helps treating the header value as a single string.

ReqMethod - Client request method

The HTTP request method used.

ReqProtocol - Client request protocol

The HTTP protocol version information.

ReqStart - Client request start

Start of request processing. Logs the client address, port number and listener endpoint name (from the -a command-line argument).
The format is:

%s %s %s
| | |
| | +-- Listener name (from -a)
| +----- Client Port number (0 for Unix domain sockets)
+-------- Client IP4/6 address (0.0.0.0 for UDS)

ReqURL - Client request URL

The HTTP request URL.

ReqUnset - Client request unset header

HTTP header contents.
The format is:

%s: %s
| |
| +- Header value
+----- Header name

NOTE: HTTP header fields are free form records and not strictly made of 2 fields. Accessing a specific header with the prefix notation helps treating the header value as a single string.

RespHeader - Client response header

HTTP header contents.
The format is:

%s: %s
| |
| +- Header value
+----- Header name

NOTE: HTTP header fields are free form records and not strictly made of 2 fields. Accessing a specific header with the prefix notation helps treating the header value as a single string.

RespProtocol - Client response protocol

The HTTP protocol version information.

RespReason - Client response reason

The HTTP response reason string.

RespStatus - Client response status

The HTTP response status code.

RespUnset - Client response unset header

HTTP header contents.
The format is:

%s: %s
| |
| +- Header value
+----- Header name

NOTE: HTTP header fields are free form records and not strictly made of 2 fields. Accessing a specific header with the prefix notation helps treating the header value as a single string.

SessClose - Client connection closed

SessClose is the last record for any client connection.
The format is:

%s %f
| |
| +- How long the session was open
+---- Why the connection closed

Explanation of reasons (first column): : * `REM_CLOSE`: Client Closed * `REQ_CLOSE`: Client requested close * `REQ_HTTP10`: Proto < HTTP/1.1 * `RX_BAD`: Received bad req/resp * `RX_BODY`: Failure receiving body * `RX_JUNK`: Received junk data * `RX_OVERFLOW`: Received buffer overflow * `RX_TIMEOUT`: Receive timeout * `RX_CLOSE_IDLE`: timeout_idle reached * `TX_PIPE`: Piped transaction * `TX_ERROR`: Error transaction * `TX_EOF`: EOF transmission * `RESP_CLOSE`: Backend/VCL requested close * `OVERLOAD`: Out of some resource * `PIPE_OVERFLOW`: Session pipe overflow * `RANGE_SHORT`: Insufficient data for range * `REQ_HTTP20`: HTTP2 not accepted * `VCL_FAILURE`: VCL failure * `RAPID_RESET`: HTTP2 rapid reset

SessError - Client connection accept failed

Accepting a client connection has failed.
The format is:

%s %s %s %d %d %s
| | | | | |
| | | | | +- Detailed error message
| | | | +---- Error Number (errno) from accept(2)
| | | +------- File descriptor number
| | +---------- Local TCP port / 0 for UDS
| +------------- Local IPv4/6 address / 0.0.0.0 for UDS
+---------------- Socket name (from -a argument)

SessOpen - Client connection opened

The first record for a client connection, with the socket-endpoints of the connection.
The format is:

%s %d %s %s %s %f %d
| | | | | | |
| | | | | | +- File descriptor number
| | | | | +---- Session start time (unix epoch)
| | | | +------- Local TCP port / 0 for UDS
| | | +---------- Local IPv4/6 address / 0.0.0.0 for UDS
| | +------------- Socket name (from -a argument)
| +---------------- Remote TCP port / 0 for UDS
+------------------- Remote IPv4/6 address / 0.0.0.0 for UDS

Storage - Where object is stored

Type and name of the storage backend the object is stored in.
The format is:

%s %s
| |
| +- Name of storage backend
+---- Type ("malloc", "file", "persistent" etc.)

TTL - TTL set on object

A TTL record is emitted whenever the ttl, grace or keep values for an object is set as well as whether the object is cacheable or not.
The format is:

%s %d %d %d %d [ %d %d %u %u ] %s
| | | | | | | | | |
| | | | | | | | | +- "cacheable" or "uncacheable"
| | | | | | | | +------ Max-Age from Cache-Control header
| | | | | | | +--------- Expires header
| | | | | | +------------ Date header
| | | | | +--------------- Age (incl Age: header value)
| | | | +-------------------- Reference time for TTL
| | | +----------------------- Keep
| | +-------------------------- Grace
| +----------------------------- TTL
+-------------------------------- "RFC", "VCL" or "HFP"

The four optional fields are only present in “RFC” headers.
Examples:
```default RFC 60 10 -1 1312966109 1312966109 1312966109 0 60 cacheable VCL 120 10 0 1312966111 uncacheable HFP 2 0 0 1312966113 uncacheable ```

Timestamp - Timing information

Contains timing information for the Varnish worker threads.
Time stamps are issued by Varnish on certain events, and show the absolute time of the event, the time spent since the start of the work unit, and the time spent since the last timestamp was logged. See the TIMESTAMPS section below for information about the individual time stamps.
The format is:

%s: %f %f %f
| | | |
| | | +- Time since last timestamp
| | +---- Time since start of work unit
| +------- Absolute time of event
+----------- Event label

VCL_Error - VCL execution error message

Logs error messages generated during VCL execution.

VCL_Log - Log statement from VCL

User generated log messages insert from VCL through std.log()

VCL_acl - VCL ACL check results

ACLs with the +log flag emits this record with the result.
The format is:

%s [%s [%s [fixed: %s]]]
| | | |
| | | +- Fix info (see below)
| | +------------ Matching entry (only for MATCH)
| +---------------- Name of the ACL for MATCH or NO_MATCH
+-------------------- MATCH, NO_MATCH or NO_FAM

* Fix info: either contains network/mask for non-canonical entries (see acl +pedantic flag) or `folded` for entries which were the result of a fold operation (see acl +fold flag). * `MATCH` denotes an ACL match * `NO_MATCH` denotes that a checked ACL has not matched * `NO_FAM` denotes a missing address family and should not occur.

VCL_call - VCL method called

Logs the VCL method name when a VCL method is called.

VCL_return - VCL method return value

Logs the VCL method terminating statement.

VCL_trace - VCL trace data

Logs VCL execution trace data.
The format is:

%s %u %u.%u.%u
| | | | |
| | | | +- VCL program line position
| | | +---- VCL program line number
| | +------- VCL program source index
| +---------- VCL trace point index
+------------- VCL configname

NB: This log record is masked by default.

VCL_use - VCL in use

Records the name of the VCL being used.
The format is:

%s [ %s %s ]
| | |
| | +- Name of label used to find it
| +---- "via"
+--------- Name of VCL put in use

VSL - VSL API warnings and error message

Warnings and error messages generated by the VSL API while reading the shared memory log.

VdpAcct - Deliver filter accounting

Contains name of VDP and statistics.
The format is:

%s %d %d
| | |
| | +- Total bytes produced
| +---- Number of calls made
+------- Name of filter

NB: This log record is masked by default.

VfpAcct - Fetch filter accounting

Contains name of VFP and statistics.
The format is:

%s %d %d
| | |
| | +- Total bytes produced
| +---- Number of calls made
+------- Name of filter

NB: This log record is masked by default.

Witness - Lock order witness records

Diagnostic recording of locking order.

WorkThread - Logs thread start/stop events

Logs worker thread creation and termination events.
The format is:

%p %s
| |
| +- [start|end]
+---- Worker struct pointer

NB: This log record is masked by default.

TIMESTAMPS

Timestamps are inserted in the log on completing certain events during the worker thread’s task handling. The timestamps has a label showing which event was completed. The reported fields show the absolute time of the event, the time spent since the start of the task and the time spent since the last timestamp was logged.

vsl-query

Mon, 16 Mar 2026 00:00:00 +0000

Varnish VSL Query Expressions

Manual section: 7

OVERVIEW

The Varnish VSL Query Expressions extracts transactions from the Varnish shared memory log, and perform queries on the transactions before reporting matches.

A transaction is a set of log lines that belongs together, e.g. a client request or a backend request. The API monitors the log, and collects all log records that make up a transaction before reporting on that transaction. Transactions can also be grouped, meaning backend transactions are reported together with the client transaction that initiated it.

VSM: Shared Memory Logging and Statistics

Mon, 16 Mar 2026 00:00:00 +0000

Varnish uses shared memory to export parameters, logging and statistics, because it is faster and much more efficient than regular files.

“Varnish Shared Memory” or VSM, is the overall mechanism maintaining sets of shared memory files, each consisting a chunk of memory identified by a two-part name (class, ident).

The Class indicates what type of data is stored in the chunk, for instance “Arg” for command line arguments useful for establishing an CLI connection to the varnishd, “Stat” for statistics counters (VSC) and “Log” for log records (VSL).

VTC

Mon, 16 Mar 2026 00:00:00 +0000

Varnish Test Case Syntax

Manual section: 7

OVERVIEW

This document describes the syntax used by Varnish Test Cases files (.vtc). A vtc file describe a scenario with different scripted HTTP-talking entities, and generally one or more Varnish instances to test.

PARSING

A vtc file will be read word after word, with very little tokenization, meaning a syntax error won’t be detected until the test actually reach the relevant action in the test.

VTLA - Varnish Three Letter Acronyms

Mon, 16 Mar 2026 00:00:00 +0000

Very early in the project, we made a fortunate bargain on eBay, buying up a batch of 676 three letter acronyms, all starting with ‘V’.

This page tells you what we use them for, if & when we remember to add them…

VAV: Varnish Arg Vector – Argv parsing.
VBE: Varnish Back End – Code for contacting backends (bin/varnishd/cache_backend.c)
VBP: Varnish Backend Polling – Health checks of backends (bin/varnishd/cache_backend_poll.c)
VCA: Varnish Connection Acceptor – The code that receives/accepts the TCP connections (bin/varnishd/cache_acceptor.c)
VCC: VCL to C Compiler – The code that compiles VCL to C code. (lib/libvcl)
VCF: Varnish CatFlap
VCL: Varnish Configuration Language – The domain-specific programming language used for configuring a varnishd.
VCT: Varnish CType(3) – Character classification for RFC2616 and XML parsing.
VDD: Varnish (Core) Developer Day – Quarterly invite-only meeting strictly for Varnish core (C) developers, packagers and VMOD hackers.
VENC: Varnish ENCoding – base64 functions
VEND: Varnish ENDianess – functions to marshall data in specified endianness
VEV: Varnish EVent – library functions to implement a simple event-dispatcher.
VEXT: Varnish Extension – Shared library loaded into the child process.
VGB: Varnish Governing Board – May or may not exist. If you need to ask, you are not on it.
VGC: Varnish Generated Code – Code generated by VCC from VCL.
VIN: Varnish Instance Naming – Resolution of -n arguments.
VLU: Varnish Line Up – library functions to collect stream of bytes into lines for processing. (lib/libvarnish/vlu.c)
VPI: VCC Private Interface – functions in varnishd which only VCC is allowed to call.
VRE: Varnish Regular Expression – library functions for regular expression based matching and substring replacement. (lib/libvarnish/vre.c)
VRT: Varnish Run Time – functions called from compiled code. (bin/varnishd/cache_vrt.c)
VRY: VaRY – Related to processing of Vary: HTTP headers. (bin/varnishd/cache_vary.c)
VSL: Varnish Shared memory Log – The log written into the shared memory segment for varnish{log,ncsa,top,hist} to see.
VSB: Varnish string Buffer – a copy of the FreeBSD “sbuf” library, for safe string handling.
VSC: Varnish Statistics Counter – counters for various stats, exposed via varnishapi.
VSS: Varnish Session Stuff – library functions to wrap DNS/TCP. (lib/libvarnish/vss.c)
VTC: Varnish Test Code – a test-specification for the varnishtest program.
VTE: Varnish Turbo Encabulator
VTLA: Varnish Three Letter Acronym – No rule without an exception.
VUG: Varnish User Group meeting – Half-yearly event where the users and developers of Varnish Cache gather to share experiences and plan future development.
VUT: Varnish UTilities – An API for client utilities to tap into VSM or VSC.
VWx: Varnish Waiter ‘x’ – A code module to monitor idle sessions.
VWE: Varnish Waiter Epoll – epoll(2) (linux) based waiter module.
VWK: Varnish Waiter Kqueue – kqueue(2) (freebsd) based waiter module.
VWP: Varnish Waiter Poll – poll(2) based waiter module.
VWS: Varnish Waiter Solaris – Solaris ports(2) based waiter module.

COPYRIGHT

This document is licensed under the same licence as Varnish itself. See LICENCE for details.

Writing a Director

Mon, 16 Mar 2026 00:00:00 +0000

Varnish already provides a set of general-purpose directors, and since Varnish 4, it is bundled in the built-in VMOD directors - Varnish Directors Module. Writing a director boils down to writing a VMOD, using the proper data structures and APIs. Not only can you write your own director if none of the built-ins fit your needs, but since Varnish 4.1 you can even write your own backends.