Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
VCL(7)									VCL(7)

NAME
       VCL - Varnish Configuration Language

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.

       This document focuses on	the syntax of the VCL language.	For a full de-
       scription of syntax and semantics, with ample examples, please see  the
       online documentation at https://www.varnish-cache.org/docs/ .

       Starting	 with  Varnish	4.0, each VCL file must	start by declaring its
       version with vcl	_major_._minor_; marker	at the top of the  file.   See
       more about this under Versioning	below.

   Operators
       The following operators are available in	VCL:

	  =	 Assignment operator.

	  +=, -=, *=, /=
		 Assign	and increment/decrement/multiply/divide	operator.

		 For strings, += appends.

	  ==, !=, <, >,	<=, >=
		 Comparisons

	  ~, !~	 Match	/  non-match.  Can either be used with regular expres-
		 sions or ACLs.

	  !	 Negation.

	  && / ||
		 Logical and/or.

   Conditionals
       VCL has if and else statements. Nested logic can	 be  implemented  with
       the elseif statement (elsif/elif/else if	are equivalent).

       Note that there are no loops or iterators of any	kind in	VCL.

   Strings, booleans, time, duration, integers and real	numbers
       These are the data types	in Varnish. You	can set	or unset these.

       Example:

	  set req.http.User-Agent = "unknown";
	  unset	req.http.Range;

   Strings
       Basic  strings are enclosed in double quotes "...", and may not contain
       newlines. Long strings are enclosed in {"..."}. They  may  contain  any
       character  including  single double quotes ", newline and other control
       characters except for the NUL (0x00) character.

   Booleans
       Booleans	can be either true or false.  In addition, in a	 boolean  con-
       text  some data types will evaluate to true or false depending on their
       value.

       String types will evaluate to false if they  are	 unset.	  This	allows
       checks  of the type if (req.http.opthdr)	{} to test if a	header exists,
       even if it is empty, whereas if (req.http.opthdr	==  "")	 {}  does  not
       distinguish if the header does not exist	or if it is empty.

       Backend	types  will evaluate to	false if they don't have a backend as-
       signed; integer types will evaluate to false if their  value  is	 zero;
       duration	 types	will evaluate to false if their	value is equal or less
       than zero.

   Time
       VCL has time. A duration	can be added to	a time to make	another	 time.
       In  string  context  they  return a formatted string in RFC1123 format,
       e.g. Sun, 06 Nov	1994 08:49:37 GMT.

       The keyword now returns a notion	of the current	time,  which  is  kept
       consistent  during  VCL subroutine invocations, so during the execution
       of a VCL	state subroutine (vcl_*	{}), including all  user-defined  sub-
       routines	being called, now always returns the same value.

   Durations
       Durations  are  defined	by a number followed by	a unit.	The number can
       include a fractional part, e.g. 1.5s. The supported units are:

	  ms	 milliseconds

	  s	 seconds

	  m	 minutes

	  h	 hours

	  d	 days

	  w	 weeks

	  y	 years

       In string context they return a string with their value	rounded	 to  3
       decimal places and excluding the	unit, e.g.  1.500.

   Integers
       Certain	fields	are integers, used as expected.	In string context they
       return a	string,	e.g. 1234.

   Real	numbers
       VCL understands real numbers. In	string context they  return  a	string
       with their value	rounded	to 3 decimal places, e.g. 3.142.

   Regular Expressions
       Varnish uses Perl-compatible regular expressions	(PCRE).	For a complete
       description please see the pcre(3) man page.

       To send flags to	the PCRE engine, such as to do case insensitive	match-
       ing, add	the flag within	parens following a question mark, like this:

	  # If host is NOT example dot com..
	  if (req.http.host !~ "(?i)example\.com$") {
	      ...
	  }

   Include statement
       To include a VCL	file in	another	file use the include keyword:

	  include "foo.vcl";

   Import statement
       The import statement is used to load Varnish Modules (VMODs.)

       Example:

	  import std;
	  sub vcl_recv {
	      std.log("foo");
	  }

   Comments
       Single  lines  of  VCL  can  be commented out using // or #. Multi-line
       blocks can be commented out with	/*block*/.

       Example:

	  sub vcl_recv {
	      // Single	line of	out-commented VCL.
	      #	Another	way of commenting out a	single line.
	      /*
		  Multi-line block of commented-out VCL.
	      */
	  }

   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 {
	      .attribute = "value";
	  }

       One  of	the attributes .host or	.path is mandatory (but	not both). The
       attributes will inherit their defaults from the global parameters.  The
       following attributes are	available:

	  .host	 The  host  to be used.	IP address or a	hostname that resolves
		 to a single IP	address. This attribute	is  mandatory,	unless
		 .path is declared.

	  .path	    (VCL >= 4.1)
	      The  absolute path of a Unix domain socket at which a backend is
	      listening. If the	file at	that path does not exist or is not ac-
	      cessible	to Varnish at VCL load time, then the VCL compiler is-
	      sues a warning, but does not fail. This  makes  it  possible  to
	      start  the  UDS-listening	peer, or set the socket	file's permis-
	      sions, after starting Varnish or loading VCL with	a UDS backend.
	      But  the	socket	file must exist	and have necessary permissions
	      before the first connection is attempted,	otherwise fetches will
	      fail.  If	the file does exist and	is accessible, then it must be
	      a	socket;	otherwise the VCL load fails. One of  .path  or	 .host
	      must  be	declared (but not both). .path may only	be used	in VCL
	      since version 4.1.

	  .port	 The port on the backend that Varnish should connect  to.  Ig-
		 nored if a Unix domain	socket is declared in .path.

	  .host_header
		 A  host  header to add	to probes and regular backend requests
		 if they have no such header.

	  .connect_timeout
		 Timeout for connections.

		 Default: connect_timeout parameter, see varnishd(1)

	  .first_byte_timeout
		 Timeout for first byte.

		 Default: first_byte_timeout parameter,	see varnishd(1)

	  .between_bytes_timeout
		 Timeout between bytes.

		 Default: between_bytes_timeout	parameter, see varnishd(1)

	  .probe Attach	a probe	to the backend.	See Probes

	  .proxy_header
		 The PROXY protocol version Varnish should use when connecting
		 to this backend. Allowed values are 1 and 2.

		 Notice	 this  setting	will lead to backend connections being
		 used for a single request only	(subject  to  future  improve-
		 ments).  Thus,	 extra	care  should be	taken to avoid running
		 into failing backend connections with EADDRNOTAVAIL due to no
		 local ports being available. Possible options are:

		 o Use additional backend connections to extra IP addresses or
		   TCP ports

		 o Increase  the  number  of  available	 ports	(Linux	sysctl
		   net.ipv4.ip_local_port_range)

		 o Reuse   backend   connection	  ports	 early	(Linux	sysctl
		   net.ipv4.tcp_tw_reuse)

	  .max_connections
		 Maximum number	of open	connections towards this  backend.  If
		 Varnish  reaches  the	maximum	 Varnish it will start failing
		 connections.

       Empty backends can also be defined using	the following syntax.:

	  backend name none;

       An empty	backend	will always return status code 503 as if it is sick.

       Backends	can be used with directors. Please see	the  vmod_directors(3)
       man page	for more information.

   Probes
       Probes  will  query  the	backend	for status on a	regular	basis and mark
       the backend as down it they fail. A probe is defined as this:

	  probe	name {
	      .attribute = "value";
	  }

       The probe named default is special and will be used  for	 all  backends
       which do	not explicitly reference a probe.

       There are no mandatory options. These are the options you can set:

	  .url	 The  URL  to  query.  Defaults	to /.  Mutually	exclusive with
		 .request

	  .request
		 Specify a full	HTTP request using multiple strings.  .request
		 will  have  \r\n  automatically  inserted after every string.
		 Mutually exclusive with .url.

		 Note that probes require the backend to complete sending  the
		 response  and close the connection within the specified time-
		 out, so .request will,	for HTTP/1.1, most likely need to con-
		 tain a	"Connection: close" string.

	  .expected_response
		 The expected HTTP response code. Defaults to 200.

	  .timeout
		 The timeout for the probe. Default is 2s.

	  .interval
		 How often the probe is	run. Default is	5s.

	  .initial
		 How  many  of	the  polls in .window are considered good when
		 Varnish starts. Defaults to the value of .threshold -	1.  In
		 this case, the	backend	starts as sick and requires one	single
		 poll to be considered healthy.

	  .window
		 How many of the latest	polls we examine to determine  backend
		 health.  Defaults to 8.

	  .threshold
		 How  many of the polls	in .window must	have succeeded to con-
		 sider the backend to be healthy.  Defaults to 3.

   Access Control List (ACL)
       An Access Control List (ACL)  declaration  creates  and	initialises  a
       named  access  control list which can later be used to match client ad-
       dresses:

	  acl localnetwork {
	      "localhost";    #	myself
	      "192.0.2.0"/24; #	and everyone on	the local network
	      !	"192.0.2.23"; #	except for the dial-in router
	  }

       If an ACL entry specifies a host	name which Varnish is  unable  to  re-
       solve, it will match any	address	it is compared to. Consequently, if it
       is preceded by a	negation mark, it will reject any address it  is  com-
       pared  to, which	may not	be what	you intended. If the entry is enclosed
       in parentheses, however,	it will	simply be ignored.

       To match	an IP address against an ACL, simply use the match operator:

	  if (client.ip	~ localnetwork)	{
	      return (pipe);
	  }

   VCL objects
       A VCL object can	be instantiated	with the new keyword:

	  sub vcl_init {
	      new b = directors.round_robin()
	      b.add_backend(node1);
	  }

       This is only available in vcl_init.

   Subroutines
       A subroutine is used to group code for legibility or reusability:

	  sub pipe_if_local {
	      if (client.ip ~ localnetwork) {
		  return (pipe);
	      }
	  }

       Subroutines in VCL do not take arguments, nor do	 they  return  values.
       The  built  in subroutines all have names beginning with	vcl_, which is
       reserved.

       To call a subroutine, use the call keyword followed by the subroutine's
       name:

	  sub vcl_recv {
	      call pipe_if_local;
	  }

   Return statements
       The  ongoing  vcl_*  subroutine	execution ends when a return(_action_)
       statement is made.

       The _action_ specifies how execution should proceed.  The  context  de-
       fines which actions are available.

   Multiple subroutines
       If  multiple  subroutines with the name of one of the built-in ones are
       defined,	they are concatenated in the order in which they appear	in the
       source.

       The  built-in  VCL distributed with Varnish will	be implicitly concate-
       nated when the VCL is compiled.

   VCL Variables
       Variables provide read, write and delete	access to almost  all  aspects
       of the work at hand.

       Reading a variable is done simply by using its name in VCL:

	  if (client.ip	~ bad_guys) {
	      return (synth(400));
	  }

       Writing	a  variable, where this	is possible, is	done with a set	state-
       ment:

	  set resp.http.never =	"Let You Down";

       Similarly, deleting a variable, for the few  variables  where  this  is
       possible, is done with a	unset statement:

	  unset	req.http.cookie;

       Which  operations are possible on each variable is described below, of-
       ten with	the shorthand "backend"	which covers the vcl_backend_* subrou-
       tines and "client" which	covers the rest, except	vcl_init and vcl_fini.

       When  setting  a	 variable,  the	right hand side	of the equal sign must
       have the	variables type,	you cannot assign a STRING to  a  variable  of
       type  NUMBER,  even  if the string is "42".  (Explicit conversion func-
       tions can be found in vmod_std(3)).

   local, server, remote and client
       These variables describe	the network connection between the client  and
       varnishd.

       Without PROXY protocol:

	       client	 server
	       remote	 local
		 v	    v
	  CLIENT ------------ VARNISHD

       With PROXY protocol:

	       client	 server	  remote     local
		 v	    v	    v	       v
	  CLIENT ------------ PROXY ------------ VARNISHD

       local.ip
	  Type:	IP

	  Readable from: client, backend

	  The IP address (and port number) of the local	end of the TCP connec-
	  tion,	for instance 192.168.1.1:81

	  If the connection is	a  UNIX	 domain	 socket,  the  value  will  be
	  0.0.0.0:0

       local.endpoint  VCL >= 4.1
	  Type:	STRING

	  Readable from: client, backend

	  The address of the '-a' socket the session was accepted on.

	  If the argument was -a foo=:81 this would be ":81"

       local.socket    VCL >= 4.1
	  Type:	STRING

	  Readable from: client, backend

	  The name of the '-a' socket the session was accepted on.

	  If the argument was -a foo=:81 this would be "foo".

	  Note that all	'-a' gets a default name on the	form a%d if no name is
	  provided.

       remote.ip
	  Type:	IP

	  Readable from: client, backend

	  The IP address of the	other end of the TCP connection.  This can ei-
	  ther be the clients IP, or the outgoing IP of	a proxy	server.

	  If  the  connection  is  a  UNIX  domain  socket,  the value will be
	  0.0.0.0:0

       client.ip
	  Type:	IP

	  Readable from: client, backend

	  The client's IP address, either the same as  local.ip	 or  what  the
	  PROXY	protocol told us.

       client.identity
	  Type:	STRING

	  Readable from: client

	  Writable from: client

	  Identification of the	client,	used to	load balance in	the client di-
	  rector.  Defaults to client.ip

	  This variable	can be overwritten with	more precise information,  for
	  instance extracted from a Cookie: header.

       server.ip
	  Type:	IP

	  Readable from: client, backend

	  The  IP address of the socket	on which the client connection was re-
	  ceived, either the same as server.ip or what the PROXY protocol told
	  us.

       server.hostname
	  Type:	STRING

	  Readable from: all

	  The  host name of the	server,	as returned by the gethostname(3) sys-
	  tem function.

       server.identity
	  Type:	STRING

	  Readable from: all

	  The identity of the server, as set by	the -i parameter.

	  If an	-i parameter is	not passed to varnishd,	the return value  from
	  gethostname(3) system	function will be used.

   req and req_top
       These  variables	describe the present request, and when ESI:include re-
       quests are being	processed, req_top points to the request received from
       the client.

       req
	  Type:	HTTP

	  Readable from: client

	  The  entire  request HTTP data structure.  Mostly useful for passing
	  to VMODs.

       req.method
	  Type:	STRING

	  Readable from: client

	  Writable from: client

	  The request method (e.g. "GET", "HEAD", ...)

       req.hash
	  Type:	BLOB

	  Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver

	  The hash key of this request.	 Mostly	useful for passing  to	VMODs,
	  but can also be useful for debugging hit/miss	status.

       req.url
	  Type:	STRING

	  Readable from: client

	  Writable from: client

	  The requested	URL, for instance "/robots.txt".

       req.proto       VCL <= 4.0
	  Type:	STRING

	  Readable from: client

	  Writable from: client

	  The  HTTP protocol version used by the client, usually "HTTP/1.1" or
	  "HTTP/2.0".

       req.proto       VCL >= 4.1
	  Type:	STRING

	  Readable from: client

	  The HTTP protocol version used by the	client,	usually	"HTTP/1.1"  or
	  "HTTP/2.0".

       req.http.*
	  Type:	HEADER

	  Readable from: client

	  Writable from: client

	  Unsetable from: client

	  The headers of request, things like req.http.date.

	  The RFCs allow multiple headers with the same	name, and both set and
	  unset	will remove all	headers	with the name given.

       req.restarts
	  Type:	INT

	  Readable from: client

	  A count of how many times this request has been restarted.

       req.storage
	  Type:	STEVEDORE

	  Readable from: client

	  Writable from: client

	  The storage backend to use to	save this request body.

       req.esi_level
	  Type:	INT

	  Readable from: client

	  A count of how many levels of	ESI requests we're currently at.

       req.ttl
	  Type:	DURATION

	  Readable from: client

	  Writable from: client

	  Upper	limit on the object age	for cache lookups to return hit.

       req.grace
	  Type:	DURATION

	  Readable from: client

	  Writable from: client

	  Upper	limit on the object grace.

	  During lookup	the minimum of req.grace and the object's stored grace
	  value	will be	used as	the object's grace.

       req.xid
	  Type:	STRING

	  Readable from: client

	  Unique ID of this request.

       req.esi VCL <= 4.0
	  Type:	BOOL

	  Readable from: client

	  Writable from: client

	  Set  to  false  to disable ESI processing regardless of any value in
	  beresp.do_esi. Defaults  to  true.  This  variable  is  replaced  by
	  resp.do_esi in VCL 4.1.

       req.can_gzip
	  Type:	BOOL

	  Readable from: client

	  True	if  the	 client	provided gzip or x-gzip	in the Accept-Encoding
	  header.

       req.backend_hint
	  Type:	BACKEND

	  Readable from: client

	  Writable from: client

	  Set bereq.backend to this if we attempt to fetch.  When set to a di-
	  rector,  reading  this variable returns an actual backend if the di-
	  rector has resolved immediately, or the  director  otherwise.	  When
	  used in string context, returns the name of the director or backend,
	  respectively.

       req.hash_ignore_busy
	  Type:	BOOL

	  Readable from: client

	  Writable from: client

	  Default: false.

	  Ignore any busy object during	cache lookup.

	  You only want	to do this when	you have two server looking up content
	  sideways from	each other to avoid deadlocks.

       req.hash_always_miss
	  Type:	BOOL

	  Readable from: client

	  Writable from: client

	  Default: false.

	  Force	a cache	miss for this request, even if perfectly good matching
	  objects are in the cache.

	  This is useful to force-update the cache without invalidating	exist-
	  ing entries in case the fetch	fails.

       req.is_hitmiss
	  Type:	BOOL

	  Readable from: client

	  If this request resulted in a	hitmiss

       req.is_hitpass
	  Type:	BOOL

	  Readable from: client

	  If this request resulted in a	hitpass

       req_top.method
	  Type:	STRING

	  Readable from: client

	  The  request	method	of  the	top-level request in a tree of ESI re-
	  quests. (e.g.	"GET", "HEAD").	 Identical to  req.method  in  non-ESI
	  requests.

       req_top.url
	  Type:	STRING

	  Readable from: client

	  The  requested  URL  of  the	top-level request in a tree of ESI re-
	  quests.  Identical to	req.url	in non-ESI requests.

       req_top.http.*
	  Type:	HEADER

	  Readable from: client

	  HTTP headers of the top-level	request	in a  tree  of	ESI  requests.
	  Identical to req.http. in non-ESI requests.

       req_top.proto
	  Type:	STRING

	  Readable from: client

	  HTTP	protocol version of the	top-level request in a tree of ESI re-
	  quests.  Identical to	req.proto in non-ESI requests.

   bereq
       This is the request we send to  the  backend,  it  is  built  from  the
       clients req.* fields by filtering out "per-hop" fields which should not
       be passed along (Connection:, Range: and	similar).

       Slightly	more fields are	allowed	through	for pass fetches than for miss
       fetches,	for instance Range.

       bereq
	  Type:	HTTP

	  Readable from: backend

	  The  entire  backend	request	HTTP data structure.  Mostly useful as
	  argument to VMODs.

       bereq.xid
	  Type:	STRING

	  Readable from: backend

	  Unique ID of this request.

       bereq.retries
	  Type:	INT

	  Readable from: backend

	  A count of how many times this request has been retried.

       bereq.backend
	  Type:	BACKEND

	  Readable from: vcl_pipe, backend

	  Writable from: vcl_pipe, backend

	  This is the backend or director we attempt to	fetch from.  When  set
	  to  a	 director,  reading this variable returns an actual backend if
	  the director has resolved immediately, or  the  director  otherwise.
	  When	used  in  string  context, returns the name of the director or
	  backend, respectively.

       bereq.body
	  Type:	BODY

	  Unsetable from: vcl_backend_fetch

	  The request body.

	  Unset	will also remove bereq.http.Content-Length.

       bereq.hash
	  Type:	BLOB

	  Readable from: vcl_pipe, backend

	  The hash key of this request,	a copy of req.hash.

       bereq.method
	  Type:	STRING

	  Readable from: vcl_pipe, backend

	  Writable from: vcl_pipe, backend

	  The request type (e.g. "GET",	"HEAD").

	  Regular (non-pipe, non-pass) fetches are always "GET"

       bereq.url
	  Type:	STRING

	  Readable from: vcl_pipe, backend

	  Writable from: vcl_pipe, backend

	  The requested	URL, copied from req.url

       bereq.proto     VCL <= 4.0
	  Type:	STRING

	  Readable from: vcl_pipe, backend

	  Writable from: vcl_pipe, backend

	  The HTTP protocol version, "HTTP/1.1"	unless a pass or pipe  request
	  has "HTTP/1.0" in req.proto

       bereq.proto     VCL >= 4.1
	  Type:	STRING

	  Readable from: vcl_pipe, backend

	  The  HTTP protocol version, "HTTP/1.1" unless	a pass or pipe request
	  has "HTTP/1.0" in req.proto

       bereq.http.*
	  Type:	HEADER

	  Readable from: vcl_pipe, backend

	  Writable from: vcl_pipe, backend

	  Unsetable from: vcl_pipe, backend

	  The headers to be sent to the	backend.

       bereq.uncacheable
	  Type:	BOOL

	  Readable from: backend

	  Indicates whether this request is uncacheable	due to a pass  in  the
	  client side or a hit on an hit-for-pass object.

       bereq.connect_timeout
	  Type:	DURATION

	  Readable from: vcl_pipe, backend

	  Writable from: vcl_pipe, backend

	  Default:  .connect_timeout  attribute	 from  the backend_definition,
	  which	defaults to the	connect_timeout	parameter, see varnishd(1).

	  The time in seconds to wait for a backend connection	to  be	estab-
	  lished.

       bereq.first_byte_timeout
	  Type:	DURATION

	  Readable from: backend

	  Writable from: backend

	  Default:  .first_byte_timeout	attribute from the backend_definition,
	  which	defaults to the	first_byte_timeout parameter, see varnishd(1).

	  The time in seconds to wait getting the first	 byte  back  from  the
	  backend.  Not	available in pipe mode.

       bereq.between_bytes_timeout
	  Type:	DURATION

	  Readable from: backend

	  Writable from: backend

	  Default:  .between_bytes_timeout  attribute from the backend_defini-
	  tion,	which defaults to  the	between_bytes_timeout  parameter,  see
	  varnishd(1).

	  The  time  in	 seconds  to  wait between each	received byte from the
	  backend.  Not	available in pipe mode.

       bereq.is_bgfetch
	  Type:	BOOL

	  Readable from: backend

	  True for fetches where the client got	a hit on an object  in	grace,
	  and this fetch was kicked of in the background to get	a fresh	copy.

   beresp
       The response received from the backend, one cache misses, the store ob-
       ject is built from beresp.

       beresp
	  Type:	HTTP

	  Readable from: vcl_backend_response, vcl_backend_error

	  The entire backend response HTTP data	structure, useful as  argument
	  to VMOD functions.

       beresp.body
	  Type:	BODY

	  Writable from: vcl_backend_error

	  For producing	a synthetic body.

       beresp.proto    VCL <= 4.0
	  Type:	STRING

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  The HTTP protocol version the	backend	replied	with.

       beresp.proto    VCL >= 4.1
	  Type:	STRING

	  Readable from: vcl_backend_response, vcl_backend_error

	  The HTTP protocol version the	backend	replied	with.

       beresp.status
	  Type:	INT

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  The HTTP status code returned	by the server.

	  Status  codes	 on the	form XXYZZ can be set where XXYZZ is less than
	  65536	and Y is [1...9].  Only	YZZ will be sent back to clients.

	  XX can be therefore be used to pass information around  inside  VCL,
	  for instance return(synth(22404)) from vcl_recv{} to vcl_synth{}

       beresp.reason
	  Type:	STRING

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  The HTTP status message returned by the server.

       beresp.http.*
	  Type:	HEADER

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  Unsetable from: vcl_backend_response,	vcl_backend_error

	  The HTTP headers returned from the server.

       beresp.do_esi
	  Type:	BOOL

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  Default: false.

	  Set it to true to parse the object for ESI directives.  Will only be
	  honored if req.esi is	true.

       beresp.do_stream
	  Type:	BOOL

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  Default: true.

	  Deliver the object to	the client while  fetching  the	 whole	object
	  into varnish.

	  For  uncacheable  objects,  storage for parts	of the body which have
	  been sent to the client may get freed	early, depending on the	 stor-
	  age engine used.

	  This	variable  has no effect	if do_esi is true or when the response
	  body is empty.

       beresp.do_gzip
	  Type:	BOOL

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  Default: false.

	  Set to true to gzip the object while storing it.

	  If http_gzip_support is disabled, setting this variable has  no  ef-
	  fect.

       beresp.do_gunzip
	  Type:	BOOL

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  Default: false.

	  Set to true to gunzip	the object while storing it in the cache.

	  If  http_gzip_support	 is disabled, setting this variable has	no ef-
	  fect.

       beresp.was_304
	  Type:	BOOL

	  Readable from: vcl_backend_response, vcl_backend_error

	  When true this indicates that	we got a 304 response  to  our	condi-
	  tional  fetch	 from the backend and turned that into beresp.status =
	  200

       beresp.uncacheable
	  Type:	BOOL

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  Inherited from bereq.uncacheable, see	there.

	  Setting this variable	makes the object uncacheable.

	  This may may produce a hit-for-miss object in	the cache.

	  Clearing the variable	has no effect and will log the warning "Ignor-
	  ing attempt to reset beresp.uncacheable".

       beresp.ttl
	  Type:	DURATION

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  Default:  Cache-Control  s-maxage  or	max-age	directives, or a value
	  computed from	the Expires header's deadline, or the default_ttl  pa-
	  rameter.

	  The object's remaining time to live, in seconds.

       beresp.age
	  Type:	DURATION

	  Readable from: vcl_backend_response, vcl_backend_error

	  Default: Age header, or zero.

	  The age of the object.

       beresp.grace
	  Type:	DURATION

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  Default:  Cache-Control  stale-while-revalidate  directive,  or  de-
	  fault_grace parameter.

	  Set to a period to enable grace.

       beresp.keep
	  Type:	DURATION

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  Default: default_keep	parameter.

	  Set to a period to enable conditional	backend	requests.

	  The keep time	is cache lifetime in addition to the ttl.

	  Objects with ttl expired but with keep time left may be used to  is-
	  sue  conditional (If-Modified-Since /	If-None-Match) requests	to the
	  backend to refresh them.

       beresp.backend
	  Type:	BACKEND

	  Readable from: vcl_backend_response, vcl_backend_error

	  This is the backend we fetched from.	If bereq.backend was set to  a
	  director,  this  will	be the backend selected	by the director.  When
	  used in string context, returns its name.

       beresp.backend.name
	  Type:	STRING

	  Readable from: vcl_backend_response, vcl_backend_error

	  Name of the  backend	this  response	was  fetched  from.   Same  as
	  beresp.backend.

       beresp.backend.ip       VCL <= 4.0
	  Type:	IP

	  Readable from: vcl_backend_response

	  IP of	the backend this response was fetched from.

       beresp.storage
	  Type:	STEVEDORE

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  The storage backend to use to	save this object.

       beresp.storage_hint     VCL <= 4.0
	  Type:	STRING

	  Readable from: vcl_backend_response, vcl_backend_error

	  Writable from: vcl_backend_response, vcl_backend_error

	  Deprecated since varnish 5.1 and discontinued	since VCL 4.1 (varnish
	  6.0).	Use beresp.storage instead.

	  Hint to Varnish that you want	to save	this object  to	 a  particular
	  storage backend.

       beresp.filters
	  Type:	STRING

	  Readable from: vcl_backend_response

	  Writable from: vcl_backend_response

	  List	of  Varnish Fetch Processor (VFP) filters the beresp.body will
	  be pulled through. The order left to right signifies processing from
	  backend  to  cache, iow the leftmost filter is run first on the body
	  as received from the backend after decoding of any  transfer	encod-
	  ings.

	  VFP Filters change the body before going into	the cache and/or being
	  handed to the	client side, where  it	may  get  processed  again  by
	  resp.filters.

	  The following	VFP filters exist in varnish-cache:

	  o gzip: compress a body using	gzip

	  o testgunzip:	Test if	a body is valid	gzip and refuse	it otherwise

	  o gunzip: Uncompress gzip content

	  o esi: ESI-process plain text	content

	  o esi_gzip: Save gzipped snippets for	efficient ESI-processing

	    This  filter  enables  stitching  together	ESI  from individually
	    gzipped fragments, saving processing power for  re-compression  on
	    the	client side at the expense of some compression efficiency.

	  Additional VFP filters are available from VMODs.

	  By default, beresp.filters is	constructed as follows:

	  o gunzip  gets  added	 for  gzipped  content	if beresp.do_gunzip or
	    beresp.do_esi are true.

	  o esi_gzip  gets  added  if  beresp.do_esi  is  true	together  with
	    beresp.do_gzip or content is already compressed.

	  o esi	gets added if beresp.do_esi is true

	  o gzip gets added for	uncompressed content if	beresp.do_gzip is true

	  o testgunzip	gets  added for	compressed content if beresp.do_gunzip
	    is false.

   obj
       This is the object we found in cache.  It cannot	be modified.

       obj.proto
	  Type:	STRING

	  Readable from: vcl_hit

	  The HTTP protocol version stored in the object.

       obj.status
	  Type:	INT

	  Readable from: vcl_hit

	  The HTTP status code stored in the object.

       obj.reason
	  Type:	STRING

	  Readable from: vcl_hit

	  The HTTP reason phrase stored	in the object.

       obj.hits
	  Type:	INT

	  Readable from: vcl_hit, vcl_deliver

	  The count of cache-hits on this object.

	  In vcl_deliver a value of 0 indicates	a cache	miss.

       obj.http.*
	  Type:	HEADER

	  Readable from: vcl_hit

	  The HTTP headers stored in the object.

       obj.ttl
	  Type:	DURATION

	  Readable from: vcl_hit, vcl_deliver

	  The object's remaining time to live, in seconds.

       obj.age
	  Type:	DURATION

	  Readable from: vcl_hit, vcl_deliver

	  The age of the object.

       obj.grace
	  Type:	DURATION

	  Readable from: vcl_hit, vcl_deliver

	  The object's grace period in seconds.

       obj.keep
	  Type:	DURATION

	  Readable from: vcl_hit, vcl_deliver

	  The object's keep period in seconds.

       obj.uncacheable
	  Type:	BOOL

	  Readable from: vcl_deliver

	  Whether  the	object	 is   uncacheable   (pass,   hit-for-pass   or
	  hit-for-miss).

       obj.storage
	  Type:	STEVEDORE

	  Readable from: vcl_hit, vcl_deliver

	  The storage backend where this object	is stored.

   resp
       This  is	 the  response	we send	to the client, it is built from	either
       beresp (pass/miss), obj (hits) or created from whole cloth (synth).

       With the	exception of resp.body all resp.* variables available in  both
       vcl_deliver{} and vcl_synth{} as	a matter of symmetry.

       resp
	  Type:	HTTP

	  Readable from: vcl_deliver, vcl_synth

	  The  entire  response	 HTTP  data  structure,	 useful	as argument to
	  VMODs.

       resp.body
	  Type:	BODY

	  Writable from: vcl_synth

	  To produce a synthetic response body,	for instance for errors.

       resp.proto      VCL <= 4.0
	  Type:	STRING

	  Readable from: vcl_deliver, vcl_synth

	  Writable from: vcl_deliver, vcl_synth

	  The HTTP protocol version to use for the response.

       resp.proto      VCL >= 4.1
	  Type:	STRING

	  Readable from: vcl_deliver, vcl_synth

	  Writable from: vcl_deliver, vcl_synth

	  The HTTP protocol version to use for the response.

       resp.status
	  Type:	INT

	  Readable from: vcl_deliver, vcl_synth

	  Writable from: vcl_deliver, vcl_synth

	  The HTTP status code that will be returned.

	  Assigning a HTTP standardized	code  to  resp.status  will  also  set
	  resp.reason to the corresponding status message.

	  resp.status  200  will get changed into 304 by core code after a re-
	  turn(deliver)	from vcl_deliver for conditional  requests  to	cached
	  content if validation	succeeds.

	  For the validation, first req.http.If-None-Match is compared against
	  resp.http.Etag. If they compare equal	according  to  the  rules  for
	  weak validation (see RFC7232), a 304 is sent.

	  Secondly,    req.http.If-Modified-Since    is	   compared    against
	  resp.http.Last-Modified or, if it is unset,  against	the  point  in
	  time	when  the  object  was last modified based on the Date and Age
	  headers received with	the backend response which created the object.
	  If  the object has not been modified based on	that comparison, a 304
	  is sent.

       resp.reason
	  Type:	STRING

	  Readable from: vcl_deliver, vcl_synth

	  Writable from: vcl_deliver, vcl_synth

	  The HTTP status message that will be returned.

       resp.http.*
	  Type:	HEADER

	  Readable from: vcl_deliver, vcl_synth

	  Writable from: vcl_deliver, vcl_synth

	  Unsetable from: vcl_deliver, vcl_synth

	  The HTTP headers that	will be	returned.

       resp.do_esi     VCL >= 4.1
	  Type:	BOOL

	  Readable from: vcl_deliver, vcl_synth

	  Writable from: vcl_deliver, vcl_synth

	  Default: Set if ESI parsing has happened.

	  This can be used to selectively disable ESI processing, even	though
	  ESI  parsing	happened  during  fetch.   This	is useful when Varnish
	  caches peer with each	other.

       resp.is_streaming
	  Type:	BOOL

	  Readable from: vcl_deliver, vcl_synth

	  Returns true when the	response will be streamed while	being  fetched
	  from the backend.

       resp.filters
	  Type:	STRING

	  Readable from: vcl_deliver, vcl_synth

	  Writable from: vcl_deliver, vcl_synth

	  List of VDP filters the resp.body will be pushed through.

   Special variables
       now
	  Type:	TIME

	  Readable from: all

	  The current time, in seconds since the UNIX epoch.

	  When converted to STRING in expressions it returns a formatted time-
	  stamp	like Tue, 20 Feb 2018 09:30:31 GMT

   sess
       A session corresponds to	the "conversation" that	 Varnish  has  with  a
       single  client  connection,  over  which	 one  or more request/response
       transactions may	take place. It may comprise the	traffic	over an	HTTP/1
       keep-alive  connection,	or the multiplexed traffic over	an HTTP/2 con-
       nection.

       sess.xid	       VCL >= 4.1
	  Type:	STRING

	  Readable from: client, backend

	  Unique ID of this session.

       sess.timeout_idle
	  Type:	DURATION

	  Readable from: client

	  Writable from: client

	  Idle timeout for this	session, defaults to the timeout_idle  parame-
	  ter, see varnishd(1)

       sess.timeout_linger
	  Type:	DURATION

	  Readable from: client

	  Writable from: client

	  Linger  timeout for this session, defaults to	the timeout_linger pa-
	  rameter, see varnishd(1)

       sess.send_timeout
	  Type:	DURATION

	  Readable from: client

	  Writable from: client

	  Total	 timeout  for  ordinary	 HTTP1	responses,  defaults  to   the
	  send_timeout parameter, see varnishd(1)

       sess.idle_send_timeout
	  Type:	DURATION

	  Readable from: client

	  Writable from: client

	  Send	timeout	 for  individual pieces	of data	on client connections,
	  defaults to the idle_send_timeout parameter, see varnishd(1)

   storage
       storage.<name>.free_space
	  Type:	BYTES

	  Readable from: client, backend

	  Free space available in the named stevedore. Only available for  the
	  malloc stevedore.

       storage.<name>.used_space
	  Type:	BYTES

	  Readable from: client, backend

	  Used	space  in  the	named stevedore. Only available	for the	malloc
	  stevedore.

       storage.<name>.happy
	  Type:	BOOL

	  Readable from: client, backend

	  Health status	for the	named stevedore. Not available in any  of  the
	  current stevedores.

   Functions
       The following built-in functions	are available:

   ban(STRING)
	  Invalidates  all  objects  in	 cache that match the given expression
	  with the ban mechanism.

	  The format of	STRING is:

	      <field> <operator> <arg> [&& <field> <oper> <arg>	...]

	  o _field_:

	    o string fields:

	      o	req.url: The request url

	      o	req.http.*: Any	request	header

	      o	obj.status: The	cache object status

	      o	obj.http.*: Any	cache object header

	      obj.status is treated as a string	despite	the fact  that	it  is
	      actually an integer.

	    o duration fields:

	      o	obj.ttl: Remaining ttl at the time the ban is issued

	      o	obj.age: Object	age at the time	the ban	is issued

	      o	obj.grace: The grace time of the object

	      o	obj.keep: The keep time	of the object

	  o _operator_:

	    o for all fields:

	      o	==: _field_ and	_arg_ are equal

	      o	!=: _field_ and	_arg_ are unequal

	      strings are compared case	sensitively

	    o for string fields:

	      o	~: _field_ matches the regular expression _arg_

	      o	!~:_field_ does	not match the regular expression _arg_

	    o for duration fields:

	      o	>: _field_ is greater than _arg_

	      o	>=: _field_ is greater than or equal to	_arg_

	      o	<: _field_ is less than	_arg_

	      o	<=: _field_ is less than or equal to _arg_

	  o _arg_:

	    o for string fields:

	      Either a literal string or a regular expression. Note that _arg_
	      does not use any of the string delimiters	like " or {"..."} used
	      elsewhere	in varnish. To match against strings containing	white-
	      space, regular expressions containing \s can be used.

	    o for duration fields:

	      A	VCL duration like 10s, 5m or 1h, see Durations

	  Expressions can be chained using the and operator &&.	For or	seman-
	  tics,	use several bans.

	  The  unset  _field_  is  not	equal  to any string, such that, for a
	  non-existing header, the operators  ==  and  ~  always  evaluate  as
	  false,  while	 the  operators	!= and !~ always evaluate as true, re-
	  spectively, for any value of _arg_.

   hash_data(input)
	  Adds an input	to the hash input. In the built-in VCL hash_data()  is
	  called on the	host and URL of	the request. Available in vcl_hash.

   synthetic(STRING)
	  Prepare  a  synthetic	response body containing the STRING. Available
	  in vcl_synth and vcl_backend_error.

	  Identical to set resp.body /	set beresp.body.

   regsub(str, regex, sub)
	  Returns a copy of str	with the first occurrence of the  regular  ex-
	  pression  regex replaced with	sub. Within sub, \0 (which can also be
	  spelled \&) is replaced with the entire matched string,  and	\n  is
	  replaced with	the contents of	subgroup n in the matched string.

   regsuball(str, regex, sub)
	  As regsub(), but this	replaces all occurrences.

       For  converting	or casting VCL values between data types use the func-
       tions available in the std VMOD.

VERSIONING
       Multiple	versions of the	VCL syntax can	coexist	 within	 certain  con-
       straints.

       The  VCL	syntax version at the start of VCL file	specified with -f sets
       the hard	limit that cannot be exceeded anywhere,	and it selects the ap-
       propriate version of the	builtin	VCL.

       That  means  that you can never include vcl 9.1;	from vcl 8.7;, but the
       opposite	may be possible, to the	extent the compiler supports it.

       Files pulled in via include do not need to have a vcl X.Y; but  it  may
       be  a  good  idea to do it anyway, to not have surprises	in the future.
       The syntax version set in an included file only applies	to  that  file
       and  any	files it includes - unless these set their own VCL syntax ver-
       sion.

       The version of Varnish this file	belongs	to  supports  syntax  4.0  and
       4.1.

EXAMPLES
       For examples, please see	the online documentation.

SEE ALSO
       o varnishd(1)

       o vmod_directors(3)

       o vmod_std(3)

HISTORY
       VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
       AS, Redpill Linpro and Varnish Software.	 This manual page  is  written
       by  Per	Buer,  Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn-
       gstA,l, Lasse Karstensen	and possibly others.

COPYRIGHT
       This document is	licensed under the same	license	as Varnish itself. See
       LICENSE for details.

       o Copyright (c) 2006 Verdens Gang AS

       o Copyright (c) 2006-2015 Varnish Software AS

									VCL(7)

NAME | DESCRIPTION | VERSIONING | EXAMPLES | SEE ALSO | HISTORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=vcl&sektion=7&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help