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_* {} sub-
       routines	 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 remote.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.

	  More information in the HTTP response	status section.

       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.

	  It is	a VCL error to use beresp.do_esi after setting beresp.filters.

       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.

	  It is	a VCL error to use beresp.do_gzip  after  setting  beresp.fil-
	  ters.

       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.

	  It is	a VCL error to use beresp.do_gunzip after setting  beresp.fil-
	  ters.

       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.

	  After	 beresp.filters	 is  set,  using  any  of  the beforementioned
	  beresp.do_* switches is a VCL	error.

   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.

	  More information in the HTTP response	status section.

       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.

       obj.can_esi
	  Type:	BOOL

	  Readable from: vcl_hit, vcl_deliver

	  If  the  object can be ESI processed,	that is	if setting resp.do_esi
	  or adding esi	to resp.filters	in vcl_deliver {} would	cause the  re-
	  sponse body to be ESI	processed.

   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.

	  More information in the HTTP response	status section.

	  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: obj.can_esi

	  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.

	  It is	a VCL error to use resp.do_esi after setting resp.filters.

       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.

	  Before resp.filters is set, the value	read will be the default  fil-
	  ter  list  as	determined by varnish based on resp.do_esi and request
	  headers.

	  After	resp.filters is	set, changing any of the conditions which oth-
	  erwise  determine  the  filter selection will	have no	effiect. Using
	  resp.do_esi is an error once resp.filters is set.

   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.

   HTTP	response status
       A status	code normally has 3 digits XYZ where X must be between 1 and 5
       included. Since it is not uncommon to see HTTP clients or servers rely-
       ing on non-standard or even invalid status codes	Varnish	tolerates  any
       status between 100 and 999.

       With  VCL  code	it  is	possible to use	status codes in	the form XXYZZ
       where the overall value is lower	than 65536 and the Y digit is  between
       1 and 9 included.  Only the YZZ part is sent to the client.

       The  XXYZZ  form	 of  status  codes  can	 be  set  on  resp.status  and
       beresp.status or	passed via return(synth(...))  and  return(error(...))
       transitions.

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

       The obj.status variable will inherit the	XXYZZ form, but	in a  ban  ex-
       presion only the	YZZ part will be available. The	XXYZZ form is strictly
       limited to VCL execution.

       Assigning an HTTP standardized code  to	resp.status  or	 beresp.status
       will also set resp.reason or beresp.reason  to the corresponding	status
       message.

   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+13.0-RELEASE+and+Ports>

home | help