1VCL(7) VCL(7)
2
6 VCL - Varnish Configuration Language
7
9 The VCL language is a small domain-specific language designed to be
10 used to describe request handling and document caching policies for
11 Varnish Cache.
12 When a new configuration is loaded, the varnishd management process
14 translates the VCL code to C and compiles it to a shared object which
15 is then loaded into the server process.
16 This document focuses on the syntax of the VCL language. For a full
18 description of syntax and semantics, with ample examples, please see
19 the online documentation at https://www.varnish-cache.org/docs/ .
20 Starting with Varnish 4.0, each VCL file must start by declaring its
22 version with vcl <major>.<minor>; marker at the top of the file. See
23 more about this under Versioning below.
24 Operators
26 The following operators are available in VCL:
27 = Assignment operator.
29 == Comparison.
31 ~ Match. Can either be used with regular expressions or ACLs.
33 ! Negation.
35 && Logical and.
37 || Logical or.
39 Conditionals
41 VCL has if and else statements. Nested logic can be implemented with
42 the elseif statement (elsif/elif/else if are equivalent).
43 Note that there are no loops or iterators of any kind in VCL.
45 Strings, booleans, time, duration, integers and real numbers
47 These are the data types in Varnish. You can set or unset these.
48 Example:
50 set req.http.User-Agent = "unknown";
52 unset req.http.Range;
53 Strings
55 Basic strings are enclosed in double quotes "...", and may not contain
56 newlines. Long strings are enclosed in {"..."}. They may contain any
57 character including single double quotes ", newline and other control
58 characters except for the NUL (0x00) character.
59 Booleans
61 Booleans can be either true or false. In addition, in a boolean con‐
62 text some data types will evaluate to true or false depending on their
63 value.
64 String types will evaluate to false if they are unset. This allows
66 checks of the type if (req.http.opthdr) {} to test if a header exists,
67 even if it is empty, whereas if (req.http.opthdr == "") {} does not
68 distinguish if the header does not exist or if it is empty.
69 Backend types will evaluate to false if they don't have a backend
71 assigned; integer types will evaluate to false if their value is zero;
72 duration types will evaluate to false if their value is equal or less
73 than zero.
74 Time
76 VCL has time. A duration can be added to a time to make another time.
77 In string context they return a formatted string in RFC1123 format,
78 e.g. Sun, 06 Nov 1994 08:49:37 GMT.
79 The keyword now returns a notion of the current time, which is kept
81 consistent during vcl subroutine invocations, so during the execution
82 of a vcl subroutine callback (vcl_* {}), including all user-defined
83 subroutines being called, now always returns the same value.
84 Durations
86 Durations are defined by a number followed by a unit. The number can
87 include a fractional part, e.g. 1.5s. The supported units are:
88 ms milliseconds
90 s seconds
92 m minutes
94 h hours
96 d days
98 w weeks
100 y years
102 In string context they return a string with their value rounded to 3
104 decimal places and excluding the unit, e.g. 1.500.
105 Integers
107 Certain fields are integers, used as expected. In string context they
108 return a string, e.g. 1234.
109 Real numbers
111 VCL understands real numbers. In string context they return a string
112 with their value rounded to 3 decimal places, e.g. 3.142.
113 Regular Expressions
115 Varnish uses Perl-compatible regular expressions (PCRE). For a complete
116 description please see the pcre(3) man page.
117 To send flags to the PCRE engine, such as to do case insensitive match‐
119 ing, add the flag within parens following a question mark, like this:
120 # If host is NOT example dot com..
122 if (req.http.host !~ "(?i)example\.com$") {
123 ...
124 }
125 Include statement
127 To include a VCL file in another file use the include keyword:
128 include "foo.vcl";
130 Import statement
132 The import statement is used to load Varnish Modules (VMODs.)
133 Example:
135 import std;
137 sub vcl_recv {
138 std.log("foo");
139 }
140 Comments
142 Single lines of VCL can be commented out using // or #. Multi-line
143 blocks can be commented out with /*block*/.
144 Example:
146 sub vcl_recv {
148 // Single line of out-commented VCL.
149 # Another way of commenting out a single line.
150 /*
151 Multi-line block of commented-out VCL.
152 */
153 }
154 Backend definition
156 A backend declaration creates and initialises a named backend object. A
157 declaration start with the keyword backend followed by the name of the
158 backend. The actual declaration is in curly brackets, in a key/value
159 fashion.:
160 backend name {
162 .attribute = "value";
163 }
164 One of the attributes .host or .path is mandatory (but not both). The
166 attributes will inherit their defaults from the global parameters. The
167 following attributes are available:
168 .host The host to be used. IP address or a hostname that resolves
170 to a single IP address. This attribute is mandatory, unless
171 .path is declared.
172 .path (VCL >= 4.1)
174 The absolute path of a Unix domain socket at which a backend is
175 listening. If the file at that path does not exist or is not
176 accessible to Varnish at VCL load time, then the VCL compiler
177 issues a warning, but does not fail. This makes it possible to
178 start the UDS-listening peer, or set the socket file's permis‐
179 sions, after starting Varnish or loading VCL with a UDS backend.
180 But the socket file must exist and have necessary permissions
181 before the first connection is attempted, otherwise fetches will
182 fail. If the file does exist and is accessible, then it must be
183 a socket; otherwise the VCL load fails. One of .path or .host
184 must be declared (but not both). .path may only be used in VCL
185 since version 4.1.
186 .port The port on the backend that Varnish should connect to.
188 Ignored if a Unix domain socket is declared in .path.
189 .host_header
191 A host header to add to probes and regular backend requests
192 if they have no such header.
193 .connect_timeout
195 Timeout for connections.
196 Default: connect_timeout parameter, see varnishd(1)
198 .first_byte_timeout
200 Timeout for first byte.
201 Default: first_byte_timeout parameter, see varnishd(1)
203 .between_bytes_timeout
205 Timeout between bytes.
206 Default: between_bytes_timeout parameter, see varnishd(1)
208 .probe Attach a probe to the backend. See Probes
210 .proxy_header
212 The PROXY protocol version Varnish should use when connecting
213 to this backend. Allowed values are 1 and 2.
214 Notice this setting will lead to backend connections being
216 used for a single request only (subject to future improve‐
217 ments). Thus, extra care should be taken to avoid running
218 into failing backend connections with EADDRNOTAVAIL due to no
219 local ports being available. Possible options are:
220 · Use additional backend connections to extra IP addresses or
222 TCP ports
223 · Increase the number of available ports (Linux sysctl
225 net.ipv4.ip_local_port_range)
226 · Reuse backend connection ports early (Linux sysctl
228 net.ipv4.tcp_tw_reuse)
229 .max_connections
231 Maximum number of open connections towards this backend. If
232 Varnish reaches the maximum Varnish it will start failing
233 connections.
234 Backends can be used with directors. Please see the vmod_directors(3)
236 man page for more information.
237 Probes
239 Probes will query the backend for status on a regular basis and mark
240 the backend as down it they fail. A probe is defined as this:
241 probe name {
243 .attribute = "value";
244 }
245 The probe named default is special and will be used for all backends
247 which do not explicitly reference a probe.
248 There are no mandatory options. These are the options you can set:
250 .url The URL to query. Defaults to /. Mutually exclusive with
252 .request
253 .request
255 Specify a full HTTP request using multiple strings. .request
256 will have \r\n automatically inserted after every string.
257 Mutually exclusive with .url.
258 Note that probes require the backend to complete sending the
260 response and close the connection within the specified time‐
261 out, so .request will, for HTTP/1.1, most likely need to con‐
262 tain a "Connection: close" string.
263 .expected_response
265 The expected HTTP response code. Defaults to 200.
266 .timeout
268 The timeout for the probe. Default is 2s.
269 .interval
271 How often the probe is run. Default is 5s.
272 .initial
274 How many of the polls in .window are considered good when
275 Varnish starts. Defaults to the value of .threshold - 1. In
276 this case, the backend starts as sick and requires one single
277 poll to be considered healthy.
278 .window
280 How many of the latest polls we examine to determine backend
281 health. Defaults to 8.
282 .threshold
284 How many of the polls in .window must have succeeded to con‐
285 sider the backend to be healthy. Defaults to 3.
286 Access Control List (ACL)
288 An Access Control List (ACL) declaration creates and initialises a
289 named access control list which can later be used to match client
290 addresses:
291 acl localnetwork {
293 "localhost"; # myself
294 "192.0.2.0"/24; # and everyone on the local network
295 ! "192.0.2.23"; # except for the dial-in router
296 }
297 If an ACL entry specifies a host name which Varnish is unable to
299 resolve, it will match any address it is compared to. Consequently, if
300 it is preceded by a negation mark, it will reject any address it is
301 compared to, which may not be what you intended. If the entry is
302 enclosed in parentheses, however, it will simply be ignored.
303 To match an IP address against an ACL, simply use the match operator:
305 if (client.ip ~ localnetwork) {
307 return (pipe);
308 }
309 VCL objects
311 A VCL object can be instantiated with the new keyword:
312 sub vcl_init {
314 new b = directors.round_robin()
315 b.add_backend(node1);
316 }
317 This is only available in vcl_init.
319 Subroutines
321 A subroutine is used to group code for legibility or reusability:
322 sub pipe_if_local {
324 if (client.ip ~ localnetwork) {
325 return (pipe);
326 }
327 }
328 Subroutines in VCL do not take arguments, nor do they return values.
330 The built in subroutines all have names beginning with vcl_, which is
331 reserved.
332 To call a subroutine, use the call keyword followed by the subroutine's
334 name:
335 sub vcl_recv {
337 call pipe_if_local;
338 }
339 Return statements
341 The ongoing vcl_* subroutine execution ends when a return(<action>)
342 statement is made.
343 The <action> specifies how execution should proceed. The context
345 defines which actions are available.
346 Multiple subroutines
348 If multiple subroutines with the name of one of the built-in ones are
349 defined, they are concatenated in the order in which they appear in the
350 source.
351 The built-in VCL distributed with Varnish will be implicitly concate‐
353 nated when the VCL is compiled.
354 VCL Variables
356 Variables provide read, write and delete access to almost all aspects
357 of the work at hand.
358 Reading a variable is done simply by using its name in VCL:
360 if (client.ip ~ bad_guys) {
362 return (synth(400));
363 }
364 Writing a variable, where this is possible, is done with a set state‐
366 ment:
367 set resp.http.never = "Let You Down";
369 Similarly, deleting a variable, for the few variables where this is
371 possible, is done with a unset statement:
372 unset req.http.cookie;
374 Which operations are possible on each variable is described below,
376 often with the shorthand "backend" which covers the vcl_backend_* meth‐
377 ods and "client" which covers the rest, except vcl_init and vcl_fini.
378 When setting a variable, the right hand side of the equal sign must
380 have the variables type, you cannot assign a STRING to a variable of
381 type NUMBER, even if the string is "42". (Explicit conversion func‐
382 tions can be found in vmod_std(3)).
383 local, server, remote and client
385 These variables describe the network connection between the client and
386 varnishd.
387 Without PROXY protocol:
389 client server
391 remote local
392 v v
393 CLIENT ------------ VARNISHD
394 With PROXY protocol:
396 client server remote local
398 v v v v
399 CLIENT ------------ PROXY ------------ VARNISHD
400 local.ip
402 Type: IP
403 Readable from: client, backend
405 The IP address (and port number) of the local end of the TCP connec‐
407 tion, for instance 192.168.1.1:81
408 If the connection is a UNIX domain socket, the value will be
410 0.0.0.0:0
411 local.endpoint VCL >= 4.1
413 Type: STRING
414 Readable from: client, backend
416 The address of the '-a' socket the session was accepted on.
418 If the argument was -a foo=:81 this would be ":81"
420 local.socket VCL >= 4.1
422 Type: STRING
423 Readable from: client, backend
425 The name of the '-a' socket the session was accepted on.
427 If the argument was -a foo=:81 this would be "foo".
429 Note that all '-a' gets a default name on the form a%d if no name is
431 provided.
432 remote.ip
434 Type: IP
435 Readable from: client, backend
437 The IP address of the other end of the TCP connection. This can
439 either be the clients IP, or the outgoing IP of a proxy server.
440 If the connection is a UNIX domain socket, the value will be
442 0.0.0.0:0
443 client.ip
445 Type: IP
446 Readable from: client, backend
448 The client's IP address, either the same as local.ip or what the
450 PROXY protocol told us.
451 client.identity
453 Type: STRING
454 Readable from: client
456 Writable from: client
458 Identification of the client, used to load balance in the client
460 director. Defaults to client.ip
461 This variable can be overwritten with more precise information, for
463 instance extracted from a Cookie: header.
464 server.ip
466 Type: IP
467 Readable from: client, backend
469 The IP address of the socket on which the client connection was
471 received, either the same as server.ip or what the PROXY protocol
472 told us.
473 server.hostname
475 Type: STRING
476 Readable from: all
478 The host name of the server, as returned by the gethostname(3) sys‐
480 tem function.
481 server.identity
483 Type: STRING
484 Readable from: all
486 The identity of the server, as set by the -i parameter.
488 If an -i parameter is not passed to varnishd, the return value from
490 gethostname(3) system function will be used.
491 req and req_top
493 These variables describe the present request, and when ESI:include
494 requests are being processed, req_top points to the request received
495 from the client.
496 req
498 Type: HTTP
499 Readable from: client
501 The entire request HTTP data structure. Mostly useful for passing
503 to VMODs.
504 req.method
506 Type: STRING
507 Readable from: client
509 Writable from: client
511 The request method (e.g. "GET", "HEAD", ...)
513 req.hash
515 Type: BLOB
516 Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver
518 The hash key of this request. Mostly useful for passing to VMODs,
520 but can also be useful for debugging hit/miss status.
521 req.url
523 Type: STRING
524 Readable from: client
526 Writable from: client
528 The requested URL, for instance "/robots.txt".
530 req.proto VCL <= 4.0
532 Type: STRING
533 Readable from: client
535 Writable from: client
537 The HTTP protocol version used by the client, usually "HTTP/1.1" or
539 "HTTP/2.0".
540 req.proto VCL >= 4.1
542 Type: STRING
543 Readable from: client
545 The HTTP protocol version used by the client, usually "HTTP/1.1" or
547 "HTTP/2.0".
548 req.http.*
550 Type: HEADER
551 Readable from: client
553 Writable from: client
555 Unsetable from: client
557 The headers of request, things like req.http.date.
559 The RFCs allow multiple headers with the same name, and both set and
561 unset will remove all headers with the name given.
562 req.restarts
564 Type: INT
565 Readable from: client
567 A count of how many times this request has been restarted.
569 req.storage
571 Type: STEVEDORE
572 Readable from: client
574 Writable from: client
576 The storage backend to use to save this request body.
578 req.esi_level
580 Type: INT
581 Readable from: client
583 A count of how many levels of ESI requests we're currently at.
585 req.ttl
587 Type: DURATION
588 Readable from: client
590 Writable from: client
592 Upper limit on the object age for cache lookups to return hit.
594 req.grace
596 Type: DURATION
597 Readable from: client
599 Writable from: client
601 Upper limit on the object grace.
603 During lookup the minimum of req.grace and the object's stored grace
605 value will be used as the object's grace.
606 req.xid
608 Type: STRING
609 Readable from: client
611 Unique ID of this request.
613 req.esi VCL <= 4.0
615 Type: BOOL
616 Readable from: client
618 Writable from: client
620 Set to false to disable ESI processing regardless of any value in
622 beresp.do_esi. Defaults to true. This variable is replaced by
623 resp.do_esi in VCL 4.1.
624 req.can_gzip
626 Type: BOOL
627 Readable from: client
629 True if the client provided gzip or x-gzip in the Accept-Encoding
631 header.
632 req.backend_hint
634 Type: BACKEND
635 Readable from: client
637 Writable from: client
639 Set bereq.backend to this if we attempt to fetch. When set to a
641 director, reading this variable returns an actual backend if the
642 director has resolved immediately, or the director otherwise. When
643 used in string context, returns the name of the director or backend,
644 respectively.
645 req.hash_ignore_busy
647 Type: BOOL
648 Readable from: client
650 Writable from: client
652 Default: false
654 Ignore any busy object during cache lookup.
656 You only want to do this when you have two server looking up content
658 sideways from each other to avoid deadlocks.
659 req.hash_always_miss
661 Type: BOOL
662 Readable from: client
664 Writable from: client
666 Default: false
668 Force a cache miss for this request, even if perfectly good matching
670 objects are in the cache.
671 This is useful to force-update the cache without invalidating exist‐
673 ing entries in case the fetch fails.
674 req.is_hitmiss
676 Type: BOOL
677 Readable from: client
679 If this request resulted in a hitmiss
681 req.is_hitpass
683 Type: BOOL
684 Readable from: client
686 If this request resulted in a hitpass
688 req_top.method
690 Type: STRING
691 Readable from: client
693 The request method of the top-level request in a tree of ESI
695 requests. (e.g. "GET", "HEAD"). Identical to req.method in non-ESI
696 requests.
697 req_top.url
699 Type: STRING
700 Readable from: client
702 The requested URL of the top-level request in a tree of ESI
704 requests. Identical to req.url in non-ESI requests.
705 req_top.http.*
707 Type: HEADER
708 Readable from: client
710 HTTP headers of the top-level request in a tree of ESI requests.
712 Identical to req.http. in non-ESI requests.
713 req_top.proto
715 Type: STRING
716 Readable from: client
718 HTTP protocol version of the top-level request in a tree of ESI
720 requests. Identical to req.proto in non-ESI requests.
721 bereq
723 This is the request we send to the backend, it is built from the
724 clients req.* fields by filtering out "per-hop" fields which should not
725 be passed along (Connection:, Range: and similar).
726 Slightly more fields are allowed through for pass fetches than for miss
728 fetches, for instance Range.
729 bereq
731 Type: HTTP
732 Readable from: backend
734 The entire backend request HTTP data structure. Mostly useful as
736 argument to VMODs.
737 bereq.xid
739 Type: STRING
740 Readable from: backend
742 Unique ID of this request.
744 bereq.retries
746 Type: INT
747 Readable from: backend
749 A count of how many times this request has been retried.
751 bereq.backend
753 Type: BACKEND
754 Readable from: vcl_pipe, backend
756 Writable from: vcl_pipe, backend
758 This is the backend or director we attempt to fetch from. When set
760 to a director, reading this variable returns an actual backend if
761 the director has resolved immediately, or the director otherwise.
762 When used in string context, returns the name of the director or
763 backend, respectively.
764 bereq.body
766 Type: BODY
767 Unsetable from: vcl_backend_fetch
769 The request body.
771 Unset will also remove bereq.http.Content-Length.
773 bereq.hash
775 Type: BLOB
776 Readable from: vcl_pipe, backend
778 The hash key of this request, a copy of req.hash.
780 bereq.method
782 Type: STRING
783 Readable from: vcl_pipe, backend
785 Writable from: vcl_pipe, backend
787 The request type (e.g. "GET", "HEAD").
789 Regular (non-pipe, non-pass) fetches are always "GET"
791 bereq.url
793 Type: STRING
794 Readable from: vcl_pipe, backend
796 Writable from: vcl_pipe, backend
798 The requested URL, copied from req.url
800 bereq.proto VCL <= 4.0
802 Type: STRING
803 Readable from: vcl_pipe, backend
805 Writable from: vcl_pipe, backend
807 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
809 has "HTTP/1.0" in req.proto
810 bereq.proto VCL >= 4.1
812 Type: STRING
813 Readable from: vcl_pipe, backend
815 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
817 has "HTTP/1.0" in req.proto
818 bereq.http.*
820 Type: HEADER
821 Readable from: vcl_pipe, backend
823 Writable from: vcl_pipe, backend
825 Unsetable from: vcl_pipe, backend
827 The headers to be sent to the backend.
829 bereq.uncacheable
831 Type: BOOL
832 Readable from: backend
834 Indicates whether this request is uncacheable due to a pass in the
836 client side or a hit on an hit-for-pass object.
837 bereq.connect_timeout
839 Type: DURATION
840 Readable from: vcl_pipe, backend
842 Writable from: vcl_pipe, backend
844 Default: .connect_timeout attribute from the backend_definition,
846 which defaults to the connect_timeout parameter, see varnishd(1)
847 The time in seconds to wait for a backend connection to be estab‐
849 lished.
850 bereq.first_byte_timeout
852 Type: DURATION
853 Readable from: backend
855 Writable from: backend
857 Default: .first_byte_timeout attribute from the backend_definition,
859 which defaults to the first_byte_timeout parameter, see varnishd(1)
860 The time in seconds to wait getting the first byte back from the
862 backend. Not available in pipe mode.
863 bereq.between_bytes_timeout
865 Type: DURATION
866 Readable from: backend
868 Writable from: backend
870 Default: .between_bytes_timeout attribute from the backend_defini‐
872 tion, which defaults to the between_bytes_timeout parameter, see
873 varnishd(1)
874 The time in seconds to wait between each received byte from the
876 backend. Not available in pipe mode.
877 bereq.is_bgfetch
879 Type: BOOL
880 Readable from: backend
882 True for fetches where the client got a hit on an object in grace,
884 and this fetch was kicked of in the background to get a fresh copy.
885 beresp
887 The response received from the backend, one cache misses, the store
888 object is built from beresp.
889 beresp
891 Type: HTTP
892 Readable from: vcl_backend_response, vcl_backend_error
894 The entire backend response HTTP data structure, useful as argument
896 to VMOD functions.
897 beresp.body
899 Type: BODY
900 Writable from: vcl_backend_error
902 For producing a synthetic body.
904 beresp.proto VCL <= 4.0
906 Type: STRING
907 Readable from: vcl_backend_response, vcl_backend_error
909 Writable from: vcl_backend_response, vcl_backend_error
911 The HTTP protocol version the backend replied with.
913 beresp.proto VCL >= 4.1
915 Type: STRING
916 Readable from: vcl_backend_response, vcl_backend_error
918 The HTTP protocol version the backend replied with.
920 beresp.status
922 Type: INT
923 Readable from: vcl_backend_response, vcl_backend_error
925 Writable from: vcl_backend_response, vcl_backend_error
927 The HTTP status code returned by the server.
929 Status codes on the form XXYZZ can be set where XXYZZ is less than
931 65536 and Y is [1...9]. Only YZZ will be sent back to clients.
932 XX can be therefore be used to pass information around inside VCL,
934 for instance return(synth(22404)) from vcl_recv{} to vcl_synth{}
935 beresp.reason
937 Type: STRING
938 Readable from: vcl_backend_response, vcl_backend_error
940 Writable from: vcl_backend_response, vcl_backend_error
942 The HTTP status message returned by the server.
944 beresp.http.*
946 Type: HEADER
947 Readable from: vcl_backend_response, vcl_backend_error
949 Writable from: vcl_backend_response, vcl_backend_error
951 Unsetable from: vcl_backend_response, vcl_backend_error
953 The HTTP headers returned from the server.
955 beresp.do_esi
957 Type: BOOL
958 Readable from: vcl_backend_response, vcl_backend_error
960 Writable from: vcl_backend_response, vcl_backend_error
962 Default: false
964 Set it to true to parse the object for ESI directives. Will only be
966 honored if req.esi is true.
967 beresp.do_stream
969 Type: BOOL
970 Readable from: vcl_backend_response, vcl_backend_error
972 Writable from: vcl_backend_response, vcl_backend_error
974 Default: true
976 Deliver the object to the client while fetching the whole object
978 into varnish.
979 For uncacheable objects, storage for parts of the body which have
981 been sent to the client may get freed early, depending on the stor‐
982 age engine used.
983 This variable has no effect if do_esi is true or when the response
985 body is empty.
986 beresp.do_gzip
988 Type: BOOL
989 Readable from: vcl_backend_response, vcl_backend_error
991 Writable from: vcl_backend_response, vcl_backend_error
993 Default: false
995 Set to true to gzip the object while storing it.
997 If http_gzip_support is disabled, setting this variable has no
999 effect.
1000 beresp.do_gunzip
1002 Type: BOOL
1003 Readable from: vcl_backend_response, vcl_backend_error
1005 Writable from: vcl_backend_response, vcl_backend_error
1007 Default: false
1009 Set to true to gunzip the object while storing it in the cache.
1011 If http_gzip_support is disabled, setting this variable has no
1013 effect.
1014 beresp.was_304
1016 Type: BOOL
1017 Readable from: vcl_backend_response, vcl_backend_error
1019 When true this indicates that we got a 304 response to our condi‐
1021 tional fetch from the backend and turned that into beresp.status =
1022 200
1023 beresp.uncacheable
1025 Type: BOOL
1026 Readable from: vcl_backend_response, vcl_backend_error
1028 Writable from: vcl_backend_response, vcl_backend_error
1030 Inherited from bereq.uncacheable, see there.
1032 Setting this variable makes the object uncacheable.
1034 This may may produce a hit-for-miss object in the cache.
1036 Clearing the variable has no effect and will log the warning "Ignor‐
1038 ing attempt to reset beresp.uncacheable".
1039 beresp.ttl
1041 Type: DURATION
1042 Readable from: vcl_backend_response, vcl_backend_error
1044 Writable from: vcl_backend_response, vcl_backend_error
1046 The object's remaining time to live, in seconds.
1048 beresp.age
1050 Type: DURATION
1051 Readable from: vcl_backend_response, vcl_backend_error
1053 The age of the object.
1055 beresp.grace
1057 Type: DURATION
1058 Readable from: vcl_backend_response, vcl_backend_error
1060 Writable from: vcl_backend_response, vcl_backend_error
1062 Set to a period to enable grace.
1064 beresp.keep
1066 Type: DURATION
1067 Readable from: vcl_backend_response, vcl_backend_error
1069 Writable from: vcl_backend_response, vcl_backend_error
1071 Set to a period to enable conditional backend requests.
1073 The keep time is cache lifetime in addition to the ttl.
1075 Objects with ttl expired but with keep time left may be used to
1077 issue conditional (If-Modified-Since / If-None-Match) requests to
1078 the backend to refresh them.
1079 beresp.backend
1081 Type: BACKEND
1082 Readable from: vcl_backend_response, vcl_backend_error
1084 This is the backend we fetched from. If bereq.backend was set to a
1086 director, this will be the backend selected by the director. When
1087 used in string context, returns its name.
1088 beresp.backend.name
1090 Type: STRING
1091 Readable from: vcl_backend_response, vcl_backend_error
1093 Name of the backend this response was fetched from. Same as
1095 beresp.backend.
1096 beresp.backend.ip VCL <= 4.0
1098 Type: IP
1099 Readable from: vcl_backend_response
1101 IP of the backend this response was fetched from.
1103 beresp.storage
1105 Type: STEVEDORE
1106 Readable from: vcl_backend_response, vcl_backend_error
1108 Writable from: vcl_backend_response, vcl_backend_error
1110 The storage backend to use to save this object.
1112 beresp.storage_hint VCL <= 4.0
1114 Type: STRING
1115 Readable from: vcl_backend_response, vcl_backend_error
1117 Writable from: vcl_backend_response, vcl_backend_error
1119 Deprecated since varnish 5.1 and discontinued since VCL 4.1 (varnish
1121 6.0). Use beresp.storage instead.
1122 Hint to Varnish that you want to save this object to a particular
1124 storage backend.
1125 beresp.filters
1127 Type: STRING
1128 Readable from: vcl_backend_response
1130 Writable from: vcl_backend_response
1132 List of Varnish Fetch Processor (VFP) filters the beresp.body will
1134 be pulled through. The order left to right signifies processing from
1135 backend to cache, iow the leftmost filter is run first on the body
1136 as received from the backend after decoding of any transfer encod‐
1137 ings.
1138 VFP Filters change the body before going into the cache and/or being
1140 handed to the client side, where it may get processed again by
1141 resp.filters.
1142 The following VFP filters exist in varnish-cache:
1144 · gzip: compress a body using gzip
1146 · testgunzip: Test if a body is valid gzip and refuse it otherwise
1148 · gunzip: Uncompress gzip content
1150 · esi: ESI-process plain text content
1152 · esi_gzip: Save gzipped snippets for efficient ESI-processing
1154 This filter enables stitching together ESI from individually
1156 gzipped fragments, saving processing power for re-compression on
1157 the client side at the expense of some compression efficiency.
1158 Additional VFP filters are available from VMODs.
1160 By default, beresp.filters is constructed as follows:
1162 · gunzip gets added for gzipped content if beresp.do_gunzip or
1164 beresp.do_esi are true.
1165 · esi_gzip gets added if beresp.do_esi is true together with
1167 beresp.do_gzip or content is already compressed.
1168 · esi gets added if beresp.do_esi is true
1170 · gzip gets added for uncompressed content if beresp.do_gzip is true
1172 · testgunzip gets added for compressed content if beresp.do_gunzip
1174 is false.
1175 obj
1177 This is the object we found in cache. It cannot be modified.
1178 obj.proto
1180 Type: STRING
1181 Readable from: vcl_hit
1183 The HTTP protocol version stored in the object.
1185 obj.status
1187 Type: INT
1188 Readable from: vcl_hit
1190 The HTTP status code stored in the object.
1192 obj.reason
1194 Type: STRING
1195 Readable from: vcl_hit
1197 The HTTP reason phrase stored in the object.
1199 obj.hits
1201 Type: INT
1202 Readable from: vcl_hit, vcl_deliver
1204 The count of cache-hits on this object.
1206 In vcl_deliver a value of 0 indicates a cache miss.
1208 obj.http.*
1210 Type: HEADER
1211 Readable from: vcl_hit
1213 The HTTP headers stored in the object.
1215 obj.ttl
1217 Type: DURATION
1218 Readable from: vcl_hit, vcl_deliver
1220 The object's remaining time to live, in seconds.
1222 obj.age
1224 Type: DURATION
1225 Readable from: vcl_hit, vcl_deliver
1227 The age of the object.
1229 obj.grace
1231 Type: DURATION
1232 Readable from: vcl_hit, vcl_deliver
1234 The object's grace period in seconds.
1236 obj.keep
1238 Type: DURATION
1239 Readable from: vcl_hit, vcl_deliver
1241 The object's keep period in seconds.
1243 obj.uncacheable
1245 Type: BOOL
1246 Readable from: vcl_deliver
1248 Whether the object is uncacheable (pass, hit-for-pass or
1250 hit-for-miss).
1251 obj.storage
1253 Type: STEVEDORE
1254 Readable from: vcl_hit, vcl_deliver
1256 The storage backend where this object is stored.
1258 resp
1260 This is the response we send to the client, it is built from either
1261 beresp (pass/miss), obj (hits) or created from whole cloth (synth).
1262 With the exception of resp.body all resp.* variables available in both
1264 vcl_deliver{} and vcl_synth{} as a matter of symmetry.
1265 resp
1267 Type: HTTP
1268 Readable from: vcl_deliver, vcl_synth
1270 The entire response HTTP data structure, useful as argument to
1272 VMODs.
1273 resp.body
1275 Type: BODY
1276 Writable from: vcl_synth
1278 To produce a synthetic response body, for instance for errors.
1280 resp.proto VCL <= 4.0
1282 Type: STRING
1283 Readable from: vcl_deliver, vcl_synth
1285 Writable from: vcl_deliver, vcl_synth
1287 The HTTP protocol version to use for the response.
1289 resp.proto VCL >= 4.1
1291 Type: STRING
1292 Readable from: vcl_deliver, vcl_synth
1294 Writable from: vcl_deliver, vcl_synth
1296 The HTTP protocol version to use for the response.
1298 resp.status
1300 Type: INT
1301 Readable from: vcl_deliver, vcl_synth
1303 Writable from: vcl_deliver, vcl_synth
1305 The HTTP status code that will be returned.
1307 Assigning a HTTP standardized code to resp.status will also set
1309 resp.reason to the corresponding status message.
1310 resp.status 200 will get changed into 304 by core code after a
1312 return(deliver) from vcl_deliver for conditional requests to cached
1313 content if validation succeeds.
1314 resp.reason
1316 Type: STRING
1317 Readable from: vcl_deliver, vcl_synth
1319 Writable from: vcl_deliver, vcl_synth
1321 The HTTP status message that will be returned.
1323 resp.http.*
1325 Type: HEADER
1326 Readable from: vcl_deliver, vcl_synth
1328 Writable from: vcl_deliver, vcl_synth
1330 Unsetable from: vcl_deliver, vcl_synth
1332 The HTTP headers that will be returned.
1334 resp.do_esi VCL >= 4.1
1336 Type: BOOL
1337 Readable from: vcl_deliver, vcl_synth
1339 Writable from: vcl_deliver, vcl_synth
1341 Default: Set if ESI parsing has happened.
1343 This can be used to selectively disable ESI processing, even though
1345 ESI parsing happened during fetch. This is useful when Varnish
1346 caches peer with each other.
1347 resp.is_streaming
1349 Type: BOOL
1350 Readable from: vcl_deliver, vcl_synth
1352 Returns true when the response will be streamed while being fetched
1354 from the backend.
1355 resp.filters
1357 Type: STRING
1358 Readable from: vcl_deliver, vcl_synth
1360 Writable from: vcl_deliver, vcl_synth
1362 List of VDP filters the resp.body will be pushed through.
1364 Special variables
1366 now
1367 Type: TIME
1368 Readable from: all
1370 The current time, in seconds since the UNIX epoch.
1372 When converted to STRING in expressions it returns a formatted time‐
1374 stamp like Tue, 20 Feb 2018 09:30:31 GMT
1375 sess
1377 A session corresponds to the "conversation" that Varnish has with a
1378 single client connection, over which one or more request/response
1379 transactions may take place. It may comprise the traffic over an HTTP/1
1380 keep-alive connection, or the multiplexed traffic over an HTTP/2 con‐
1381 nection.
1382 sess.xid VCL >= 4.1
1384 Type: STRING
1385 Readable from: client, backend
1387 Unique ID of this session.
1389 sess.timeout_idle
1391 Type: DURATION
1392 Readable from: client
1394 Writable from: client
1396 Idle timeout for this session, defaults to the timeout_idle parame‐
1398 ter, see varnishd(1)
1399 storage
1401 storage.<name>.free_space
1402 Type: BYTES
1403 Readable from: client, backend
1405 Free space available in the named stevedore. Only available for the
1407 malloc stevedore.
1408 storage.<name>.used_space
1410 Type: BYTES
1411 Readable from: client, backend
1413 Used space in the named stevedore. Only available for the malloc
1415 stevedore.
1416 storage.<name>.happy
1418 Type: BOOL
1419 Readable from: client, backend
1421 Health status for the named stevedore. Not available in any of the
1423 current stevedores.
1424 Functions
1426 The following built-in functions are available:
1427 ban(STRING)
1429 Invalidates all objects in cache that match the given expression
1430 with the ban mechanism.
1431 The format of STRING is:
1433 <field> <operator> <arg> [&& <field> <oper> <arg> ...]
1435 · <field>:
1437 · string fields:
1439 · req.url: The request url
1441 · req.http.*: Any request header
1443 · obj.status: The cache object status
1445 · obj.http.*: Any cache object header
1447 obj.status is treated as a string despite the fact that it is
1449 actually an integer.
1450 · duration fields:
1452 · obj.ttl: Remaining ttl at the time the ban is issued
1454 · obj.age: Object age at the time the ban is issued
1456 · obj.grace: The grace time of the object
1458 · obj.keep: The keep time of the object
1460 · <operator>:
1462 · for all fields:
1464 · ==: <field> and <arg> are equal
1466 · !=: <field> and <arg> are unequal
1468 strings are compared case sensitively
1470 · for string fields:
1472 · ~: <field> matches the regular expression <arg>
1474 · !~:<field> does not match the regular expression <arg>
1476 · for duration fields:
1478 · >: <field> is greater than <arg>
1480 · >=: <field> is greater than or equal to <arg>
1482 · <: <field> is less than <arg>
1484 · <=: <field> is less than or equal to <arg>
1486 · <arg>:
1488 · for string fields:
1490 Either a literal string or a regular expression. Note that <arg>
1492 does not use any of the string delimiters like " or {"..."} used
1493 elsewhere in varnish. To match against strings containing white‐
1494 space, regular expressions containing \s can be used.
1495 · for duration fields:
1497 A VCL duration like 10s, 5m or 1h, see Durations
1499 Expressions can be chained using the and operator &&. For or seman‐
1501 tics, use several bans.
1502 The unset <field> is not equal to any string, such that, for a
1504 non-existing header, the operators == and ~ always evaluate as
1505 false, while the operators != and !~ always evaluate as true,
1506 respectively, for any value of <arg>.
1507 hash_data(input)
1509 Adds an input to the hash input. In the built-in VCL hash_data() is
1510 called on the host and URL of the request. Available in vcl_hash.
1511 synthetic(STRING)
1513 Prepare a synthetic response body containing the STRING. Available
1514 in vcl_synth and vcl_backend_error.
1515 Identical to set resp.body / set beresp.body.
1517 regsub(str, regex, sub)
1519 Returns a copy of str with the first occurrence of the regular
1520 expression regex replaced with sub. Within sub, \0 (which can also
1521 be spelled \&) is replaced with the entire matched string, and \n is
1522 replaced with the contents of subgroup n in the matched string.
1523 regsuball(str, regex, sub)
1525 As regsub(), but this replaces all occurrences.
1526 For converting or casting VCL values between data types use the func‐
1528 tions available in the std VMOD.
1529
1531 Multiple versions of the VCL syntax can coexist within certain con‐
1532 straints.
1533 The VCL syntax version at the start of VCL file specified with -f sets
1535 the hard limit that cannot be exceeded anywhere, and it selects the
1536 appropriate version of the builtin VCL.
1537 That means that you can never include vcl 9.1; from vcl 8.7;, but the
1539 opposite may be possible, to the extent the compiler supports it.
1540 Files pulled in via include do not need to have a vcl X.Y; but it may
1542 be a good idea to do it anyway, to not have surprises in the future.
1543 The syntax version set in an included file only applies to that file
1544 and any files it includes - unless these set their own VCL syntax ver‐
1545 sion.
1546 The version of Varnish this file belongs to supports syntax 4.0 only.
1548
1550 For examples, please see the online documentation.
1551
1553 · varnishd(1)
1554 · vmod_directors(3)
1556 · vmod_std(3)
1558
1560 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
1561 AS, Redpill Linpro and Varnish Software. This manual page is written
1562 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
1563 gstøl, Lasse Karstensen and possibly others.
1564
1566 This document is licensed under the same license as Varnish itself. See
1567 LICENSE for details.
1568 · Copyright (c) 2006 Verdens Gang AS
1570 · Copyright (c) 2006-2015 Varnish Software AS
1572 VCL(7)