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 de‐
18 scription of syntax and semantics, with ample examples, please see the
19 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 +=, -=, *=, /=
31 Assign and increment/decrement/multiply/divide operator.
32 For strings, += appends.
34 ==, !=, <, >, <=, >=
36 Comparisons
37 ~, !~ Match / non-match. Can either be used with regular expres‐
39 sions or ACLs.
40 ! Negation.
42 && / ||
44 Logical and/or.
45 Conditionals
47 VCL has if and else statements. Nested logic can be implemented with
48 the elseif statement (elsif/elif/else if are equivalent).
49 Note that there are no loops or iterators of any kind in VCL.
51 Strings, booleans, time, duration, integers and real numbers
53 These are the data types in Varnish. You can set or unset these.
54 Example:
56 set req.http.User-Agent = "unknown";
58 unset req.http.Range;
59 Strings
61 Basic strings are enclosed in double quotes "...", and may not contain
62 newlines. Long strings are enclosed in {"..."}. They may contain any
63 character including single double quotes ", newline and other control
64 characters except for the NUL (0x00) character.
65 Booleans
67 Booleans can be either true or false. In addition, in a boolean con‐
68 text some data types will evaluate to true or false depending on their
69 value.
70 String types will evaluate to false if they are unset. This allows
72 checks of the type if (req.http.opthdr) {} to test if a header exists,
73 even if it is empty, whereas if (req.http.opthdr == "") {} does not
74 distinguish if the header does not exist or if it is empty.
75 Backend types will evaluate to false if they don't have a backend as‐
77 signed; integer types will evaluate to false if their value is zero;
78 duration types will evaluate to false if their value is equal or less
79 than zero.
80 Time
82 VCL has time. A duration can be added to a time to make another time.
83 In string context they return a formatted string in RFC1123 format,
84 e.g. Sun, 06 Nov 1994 08:49:37 GMT.
85 The keyword now returns a notion of the current time, which is kept
87 consistent during VCL subroutine invocations, so during the execution
88 of a VCL state subroutine (vcl_* {}), including all user-defined sub‐
89 routines being called, now always returns the same value.
90 Durations
92 Durations are defined by a number followed by a unit. The number can
93 include a fractional part, e.g. 1.5s. The supported units are:
94 ms milliseconds
96 s seconds
98 m minutes
100 h hours
102 d days
104 w weeks
106 y years
108 In string context they return a string with their value rounded to 3
110 decimal places and excluding the unit, e.g. 1.500.
111 Integers
113 Certain fields are integers, used as expected. In string context they
114 return a string, e.g. 1234.
115 Real numbers
117 VCL understands real numbers. In string context they return a string
118 with their value rounded to 3 decimal places, e.g. 3.142.
119 Regular Expressions
121 Varnish uses Perl-compatible regular expressions (PCRE). For a complete
122 description please see the pcre(3) man page.
123 To send flags to the PCRE engine, such as to do case insensitive match‐
125 ing, add the flag within parens following a question mark, like this:
126 # If host is NOT example dot com..
128 if (req.http.host !~ "(?i)example\.com$") {
129 ...
130 }
131 Include statement
133 To include a VCL file in another file use the include keyword:
134 include "foo.vcl";
136 Import statement
138 The import statement is used to load Varnish Modules (VMODs.)
139 Example:
141 import std;
143 sub vcl_recv {
144 std.log("foo");
145 }
146 Comments
148 Single lines of VCL can be commented out using // or #. Multi-line
149 blocks can be commented out with /*block*/.
150 Example:
152 sub vcl_recv {
154 // Single line of out-commented VCL.
155 # Another way of commenting out a single line.
156 /*
157 Multi-line block of commented-out VCL.
158 */
159 }
160 Backend definition
162 A backend declaration creates and initialises a named backend object. A
163 declaration start with the keyword backend followed by the name of the
164 backend. The actual declaration is in curly brackets, in a key/value
165 fashion.:
166 backend name {
168 .attribute = "value";
169 }
170 One of the attributes .host or .path is mandatory (but not both). The
172 attributes will inherit their defaults from the global parameters. The
173 following attributes are available:
174 .host The host to be used. IP address or a hostname that resolves
176 to a single IP address. This attribute is mandatory, unless
177 .path is declared.
178 .path (VCL >= 4.1)
180 The absolute path of a Unix domain socket at which a backend is
181 listening. If the file at that path does not exist or is not ac‐
182 cessible to Varnish at VCL load time, then the VCL compiler is‐
183 sues a warning, but does not fail. This makes it possible to
184 start the UDS-listening peer, or set the socket file's permis‐
185 sions, after starting Varnish or loading VCL with a UDS backend.
186 But the socket file must exist and have necessary permissions
187 before the first connection is attempted, otherwise fetches will
188 fail. If the file does exist and is accessible, then it must be
189 a socket; otherwise the VCL load fails. One of .path or .host
190 must be declared (but not both). .path may only be used in VCL
191 since version 4.1.
192 .port The port on the backend that Varnish should connect to. Ig‐
194 nored if a Unix domain socket is declared in .path.
195 .host_header
197 A host header to add to probes and regular backend requests
198 if they have no such header.
199 .connect_timeout
201 Timeout for connections.
202 Default: connect_timeout parameter, see varnishd(1)
204 .first_byte_timeout
206 Timeout for first byte.
207 Default: first_byte_timeout parameter, see varnishd(1)
209 .between_bytes_timeout
211 Timeout between bytes.
212 Default: between_bytes_timeout parameter, see varnishd(1)
214 .probe Attach a probe to the backend. See Probes
216 .proxy_header
218 The PROXY protocol version Varnish should use when connecting
219 to this backend. Allowed values are 1 and 2.
220 Notice this setting will lead to backend connections being
222 used for a single request only (subject to future improve‐
223 ments). Thus, extra care should be taken to avoid running
224 into failing backend connections with EADDRNOTAVAIL due to no
225 local ports being available. Possible options are:
226 • Use additional backend connections to extra IP addresses or
228 TCP ports
229 • Increase the number of available ports (Linux sysctl
231 net.ipv4.ip_local_port_range)
232 • Reuse backend connection ports early (Linux sysctl
234 net.ipv4.tcp_tw_reuse)
235 .max_connections
237 Maximum number of open connections towards this backend. If
238 Varnish reaches the maximum Varnish it will start failing
239 connections.
240 Empty backends can also be defined using the following syntax.:
242 backend name none;
244 An empty backend will always return status code 503 as if it is sick.
246 Backends can be used with directors. Please see the vmod_directors(3)
248 man page for more information.
249 Probes
251 Probes will query the backend for status on a regular basis and mark
252 the backend as down it they fail. A probe is defined as this:
253 probe name {
255 .attribute = "value";
256 }
257 The probe named default is special and will be used for all backends
259 which do not explicitly reference a probe.
260 There are no mandatory options. These are the options you can set:
262 .url The URL to query. Defaults to /. Mutually exclusive with
264 .request
265 .request
267 Specify a full HTTP request using multiple strings. .request
268 will have \r\n automatically inserted after every string.
269 Mutually exclusive with .url.
270 Note that probes require the backend to complete sending the
272 response and close the connection within the specified time‐
273 out, so .request will, for HTTP/1.1, most likely need to con‐
274 tain a "Connection: close" string.
275 .expected_response
277 The expected HTTP response code. Defaults to 200.
278 .timeout
280 The timeout for the probe. Default is 2s.
281 .interval
283 How often the probe is run. Default is 5s.
284 .initial
286 How many of the polls in .window are considered good when
287 Varnish starts. Defaults to the value of .threshold - 1. In
288 this case, the backend starts as sick and requires one single
289 poll to be considered healthy.
290 .window
292 How many of the latest polls we examine to determine backend
293 health. Defaults to 8.
294 .threshold
296 How many of the polls in .window must have succeeded to con‐
297 sider the backend to be healthy. Defaults to 3.
298 Access Control List (ACL)
300 An Access Control List (ACL) declaration creates and initialises a
301 named access control list which can later be used to match client ad‐
302 dresses:
303 acl localnetwork {
305 "localhost"; # myself
306 "192.0.2.0"/24; # and everyone on the local network
307 ! "192.0.2.23"; # except for the dial-in router
308 }
309 If an ACL entry specifies a host name which Varnish is unable to re‐
311 solve, it will match any address it is compared to. Consequently, if it
312 is preceded by a negation mark, it will reject any address it is com‐
313 pared to, which may not be what you intended. If the entry is enclosed
314 in parentheses, however, it will simply be ignored.
315 To match an IP address against an ACL, simply use the match operator:
317 if (client.ip ~ localnetwork) {
319 return (pipe);
320 }
321 VCL objects
323 A VCL object can be instantiated with the new keyword:
324 sub vcl_init {
326 new b = directors.round_robin()
327 b.add_backend(node1);
328 }
329 This is only available in vcl_init.
331 Subroutines
333 A subroutine is used to group code for legibility or reusability:
334 sub pipe_if_local {
336 if (client.ip ~ localnetwork) {
337 return (pipe);
338 }
339 }
340 Subroutines in VCL do not take arguments, nor do they return values.
342 The built in subroutines all have names beginning with vcl_, which is
343 reserved.
344 To call a subroutine, use the call keyword followed by the subroutine's
346 name:
347 sub vcl_recv {
349 call pipe_if_local;
350 }
351 Return statements
353 The ongoing vcl_* subroutine execution ends when a return(<action>)
354 statement is made.
355 The <action> specifies how execution should proceed. The context de‐
357 fines which actions are available.
358 Multiple subroutines
360 If multiple subroutines with the name of one of the built-in ones are
361 defined, they are concatenated in the order in which they appear in the
362 source.
363 The built-in VCL distributed with Varnish will be implicitly concate‐
365 nated when the VCL is compiled.
366 VCL Variables
368 Variables provide read, write and delete access to almost all aspects
369 of the work at hand.
370 Reading a variable is done simply by using its name in VCL:
372 if (client.ip ~ bad_guys) {
374 return (synth(400));
375 }
376 Writing a variable, where this is possible, is done with a set state‐
378 ment:
379 set resp.http.never = "Let You Down";
381 Similarly, deleting a variable, for the few variables where this is
383 possible, is done with a unset statement:
384 unset req.http.cookie;
386 Which operations are possible on each variable is described below, of‐
388 ten with the shorthand "backend" which covers the vcl_backend_* {} sub‐
389 routines and "client" which covers the rest, except vcl_init {} and
390 vcl_fini {}.
391 When setting a variable, the right hand side of the equal sign must
393 have the variables type, you cannot assign a STRING to a variable of
394 type NUMBER, even if the string is "42". (Explicit conversion func‐
395 tions can be found in vmod_std(3)).
396 local, server, remote and client
398 These variables describe the network connection between the client and
399 varnishd.
400 Without PROXY protocol:
402 client server
404 remote local
405 v v
406 CLIENT ------------ VARNISHD
407 With PROXY protocol:
409 client server remote local
411 v v v v
412 CLIENT ------------ PROXY ------------ VARNISHD
413 local.ip
415 Type: IP
416 Readable from: client, backend
418 The IP address (and port number) of the local end of the TCP connec‐
420 tion, for instance 192.168.1.1:81
421 If the connection is a UNIX domain socket, the value will be
423 0.0.0.0:0
424 local.endpoint VCL >= 4.1
426 Type: STRING
427 Readable from: client, backend
429 The address of the '-a' socket the session was accepted on.
431 If the argument was -a foo=:81 this would be ":81"
433 local.socket VCL >= 4.1
435 Type: STRING
436 Readable from: client, backend
438 The name of the '-a' socket the session was accepted on.
440 If the argument was -a foo=:81 this would be "foo".
442 Note that all '-a' gets a default name on the form a%d if no name is
444 provided.
445 remote.ip
447 Type: IP
448 Readable from: client, backend
450 The IP address of the other end of the TCP connection. This can ei‐
452 ther be the clients IP, or the outgoing IP of a proxy server.
453 If the connection is a UNIX domain socket, the value will be
455 0.0.0.0:0
456 client.ip
458 Type: IP
459 Readable from: client, backend
461 The client's IP address, either the same as remote.ip or what the
463 PROXY protocol told us.
464 client.identity
466 Type: STRING
467 Readable from: client
469 Writable from: client
471 Identification of the client, used to load balance in the client di‐
473 rector. Defaults to client.ip
474 This variable can be overwritten with more precise information, for
476 instance extracted from a Cookie: header.
477 server.ip
479 Type: IP
480 Readable from: client, backend
482 The IP address of the socket on which the client connection was re‐
484 ceived, either the same as server.ip or what the PROXY protocol told
485 us.
486 server.hostname
488 Type: STRING
489 Readable from: all
491 The host name of the server, as returned by the gethostname(3) sys‐
493 tem function.
494 server.identity
496 Type: STRING
497 Readable from: all
499 The identity of the server, as set by the -i parameter.
501 If an -i parameter is not passed to varnishd, the return value from
503 gethostname(3) system function will be used.
504 req and req_top
506 These variables describe the present request, and when ESI:include re‐
507 quests are being processed, req_top points to the request received from
508 the client.
509 req
511 Type: HTTP
512 Readable from: client
514 The entire request HTTP data structure. Mostly useful for passing
516 to VMODs.
517 req.method
519 Type: STRING
520 Readable from: client
522 Writable from: client
524 The request method (e.g. "GET", "HEAD", ...)
526 req.hash
528 Type: BLOB
529 Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver
531 The hash key of this request. Mostly useful for passing to VMODs,
533 but can also be useful for debugging hit/miss status.
534 req.url
536 Type: STRING
537 Readable from: client
539 Writable from: client
541 The requested URL, for instance "/robots.txt".
543 req.proto VCL <= 4.0
545 Type: STRING
546 Readable from: client
548 Writable from: client
550 The HTTP protocol version used by the client, usually "HTTP/1.1" or
552 "HTTP/2.0".
553 req.proto VCL >= 4.1
555 Type: STRING
556 Readable from: client
558 The HTTP protocol version used by the client, usually "HTTP/1.1" or
560 "HTTP/2.0".
561 req.http.*
563 Type: HEADER
564 Readable from: client
566 Writable from: client
568 Unsetable from: client
570 The headers of request, things like req.http.date.
572 The RFCs allow multiple headers with the same name, and both set and
574 unset will remove all headers with the name given.
575 req.restarts
577 Type: INT
578 Readable from: client
580 A count of how many times this request has been restarted.
582 req.storage
584 Type: STEVEDORE
585 Readable from: client
587 Writable from: client
589 The storage backend to use to save this request body.
591 req.esi_level
593 Type: INT
594 Readable from: client
596 A count of how many levels of ESI requests we're currently at.
598 req.ttl
600 Type: DURATION
601 Readable from: client
603 Writable from: client
605 Upper limit on the object age for cache lookups to return hit.
607 req.grace
609 Type: DURATION
610 Readable from: client
612 Writable from: client
614 Upper limit on the object grace.
616 During lookup the minimum of req.grace and the object's stored grace
618 value will be used as the object's grace.
619 req.xid
621 Type: STRING
622 Readable from: client
624 Unique ID of this request.
626 req.esi VCL <= 4.0
628 Type: BOOL
629 Readable from: client
631 Writable from: client
633 Set to false to disable ESI processing regardless of any value in
635 beresp.do_esi. Defaults to true. This variable is replaced by
636 resp.do_esi in VCL 4.1.
637 req.can_gzip
639 Type: BOOL
640 Readable from: client
642 True if the client provided gzip or x-gzip in the Accept-Encoding
644 header.
645 req.backend_hint
647 Type: BACKEND
648 Readable from: client
650 Writable from: client
652 Set bereq.backend to this if we attempt to fetch. When set to a di‐
654 rector, reading this variable returns an actual backend if the di‐
655 rector has resolved immediately, or the director otherwise. When
656 used in string context, returns the name of the director or backend,
657 respectively.
658 req.hash_ignore_busy
660 Type: BOOL
661 Readable from: client
663 Writable from: client
665 Default: false.
667 Ignore any busy object during cache lookup.
669 You only want to do this when you have two server looking up content
671 sideways from each other to avoid deadlocks.
672 req.hash_always_miss
674 Type: BOOL
675 Readable from: client
677 Writable from: client
679 Default: false.
681 Force a cache miss for this request, even if perfectly good matching
683 objects are in the cache.
684 This is useful to force-update the cache without invalidating exist‐
686 ing entries in case the fetch fails.
687 req.is_hitmiss
689 Type: BOOL
690 Readable from: client
692 If this request resulted in a hitmiss
694 req.is_hitpass
696 Type: BOOL
697 Readable from: client
699 If this request resulted in a hitpass
701 req_top.method
703 Type: STRING
704 Readable from: client
706 The request method of the top-level request in a tree of ESI re‐
708 quests. (e.g. "GET", "HEAD"). Identical to req.method in non-ESI
709 requests.
710 req_top.url
712 Type: STRING
713 Readable from: client
715 The requested URL of the top-level request in a tree of ESI re‐
717 quests. Identical to req.url in non-ESI requests.
718 req_top.http.*
720 Type: HEADER
721 Readable from: client
723 HTTP headers of the top-level request in a tree of ESI requests.
725 Identical to req.http. in non-ESI requests.
726 req_top.proto
728 Type: STRING
729 Readable from: client
731 HTTP protocol version of the top-level request in a tree of ESI re‐
733 quests. Identical to req.proto in non-ESI requests.
734 bereq
736 This is the request we send to the backend, it is built from the
737 clients req.* fields by filtering out "per-hop" fields which should not
738 be passed along (Connection:, Range: and similar).
739 Slightly more fields are allowed through for pass` fetches than for
741 `miss` fetches, for instance ``Range.
742 bereq
744 Type: HTTP
745 Readable from: backend
747 The entire backend request HTTP data structure. Mostly useful as
749 argument to VMODs.
750 bereq.xid
752 Type: STRING
753 Readable from: backend
755 Unique ID of this request.
757 bereq.retries
759 Type: INT
760 Readable from: backend
762 A count of how many times this request has been retried.
764 bereq.backend
766 Type: BACKEND
767 Readable from: vcl_pipe, backend
769 Writable from: vcl_pipe, backend
771 This is the backend or director we attempt to fetch from. When set
773 to a director, reading this variable returns an actual backend if
774 the director has resolved immediately, or the director otherwise.
775 When used in string context, returns the name of the director or
776 backend, respectively.
777 bereq.body
779 Type: BODY
780 Unsetable from: vcl_backend_fetch
782 The request body.
784 Unset will also remove bereq.http.Content-Length.
786 bereq.hash
788 Type: BLOB
789 Readable from: vcl_pipe, backend
791 The hash key of this request, a copy of req.hash.
793 bereq.method
795 Type: STRING
796 Readable from: vcl_pipe, backend
798 Writable from: vcl_pipe, backend
800 The request type (e.g. "GET", "HEAD").
802 Regular (non-pipe, non-pass) fetches are always "GET"
804 bereq.url
806 Type: STRING
807 Readable from: vcl_pipe, backend
809 Writable from: vcl_pipe, backend
811 The requested URL, copied from req.url
813 bereq.proto VCL <= 4.0
815 Type: STRING
816 Readable from: vcl_pipe, backend
818 Writable from: vcl_pipe, backend
820 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
822 has "HTTP/1.0" in req.proto
823 bereq.proto VCL >= 4.1
825 Type: STRING
826 Readable from: vcl_pipe, backend
828 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
830 has "HTTP/1.0" in req.proto
831 bereq.http.*
833 Type: HEADER
834 Readable from: vcl_pipe, backend
836 Writable from: vcl_pipe, backend
838 Unsetable from: vcl_pipe, backend
840 The headers to be sent to the backend.
842 bereq.uncacheable
844 Type: BOOL
845 Readable from: backend
847 Indicates whether this request is uncacheable due to a pass in the
849 client side or a hit on an hit-for-pass object.
850 bereq.connect_timeout
852 Type: DURATION
853 Readable from: vcl_pipe, backend
855 Writable from: vcl_pipe, backend
857 Default: .connect_timeout attribute from the backend_definition,
859 which defaults to the connect_timeout parameter, see varnishd(1).
860 The time in seconds to wait for a backend connection to be estab‐
862 lished.
863 bereq.first_byte_timeout
865 Type: DURATION
866 Readable from: backend
868 Writable from: backend
870 Default: .first_byte_timeout attribute from the backend_definition,
872 which defaults to the first_byte_timeout parameter, see varnishd(1).
873 The time in seconds to wait getting the first byte back from the
875 backend. Not available in pipe mode.
876 bereq.between_bytes_timeout
878 Type: DURATION
879 Readable from: backend
881 Writable from: backend
883 Default: .between_bytes_timeout attribute from the backend_defini‐
885 tion, which defaults to the between_bytes_timeout parameter, see
886 varnishd(1).
887 The time in seconds to wait between each received byte from the
889 backend. Not available in pipe mode.
890 bereq.is_bgfetch
892 Type: BOOL
893 Readable from: backend
895 True for fetches where the client got a hit on an object in grace,
897 and this fetch was kicked of in the background to get a fresh copy.
898 beresp
900 The response received from the backend, one cache misses, the store ob‐
901 ject is built from beresp.
902 beresp
904 Type: HTTP
905 Readable from: vcl_backend_response, vcl_backend_error
907 The entire backend response HTTP data structure, useful as argument
909 to VMOD functions.
910 beresp.body
912 Type: BODY
913 Writable from: vcl_backend_error
915 For producing a synthetic body.
917 beresp.proto VCL <= 4.0
919 Type: STRING
920 Readable from: vcl_backend_response, vcl_backend_error
922 Writable from: vcl_backend_response, vcl_backend_error
924 The HTTP protocol version the backend replied with.
926 beresp.proto VCL >= 4.1
928 Type: STRING
929 Readable from: vcl_backend_response, vcl_backend_error
931 The HTTP protocol version the backend replied with.
933 beresp.status
935 Type: INT
936 Readable from: vcl_backend_response, vcl_backend_error
938 Writable from: vcl_backend_response, vcl_backend_error
940 The HTTP status code returned by the server.
942 More information in the HTTP response status section.
944 beresp.reason
946 Type: STRING
947 Readable from: vcl_backend_response, vcl_backend_error
949 Writable from: vcl_backend_response, vcl_backend_error
951 The HTTP status message returned by the server.
953 beresp.http.*
955 Type: HEADER
956 Readable from: vcl_backend_response, vcl_backend_error
958 Writable from: vcl_backend_response, vcl_backend_error
960 Unsetable from: vcl_backend_response, vcl_backend_error
962 The HTTP headers returned from the server.
964 beresp.do_esi
966 Type: BOOL
967 Readable from: vcl_backend_response, vcl_backend_error
969 Writable from: vcl_backend_response, vcl_backend_error
971 Default: false.
973 Set it to true to parse the object for ESI directives. Will only be
975 honored if req.esi is true.
976 It is a VCL error to use beresp.do_esi after setting beresp.filters.
978 beresp.do_stream
980 Type: BOOL
981 Readable from: vcl_backend_response, vcl_backend_error
983 Writable from: vcl_backend_response, vcl_backend_error
985 Default: true.
987 Deliver the object to the client while fetching the whole object
989 into varnish.
990 For uncacheable objects, storage for parts of the body which have
992 been sent to the client may get freed early, depending on the stor‐
993 age engine used.
994 This variable has no effect if do_esi is true or when the response
996 body is empty.
997 beresp.do_gzip
999 Type: BOOL
1000 Readable from: vcl_backend_response, vcl_backend_error
1002 Writable from: vcl_backend_response, vcl_backend_error
1004 Default: false.
1006 Set to true to gzip the object while storing it.
1008 If http_gzip_support is disabled, setting this variable has no ef‐
1010 fect.
1011 It is a VCL error to use beresp.do_gzip after setting beresp.fil‐
1013 ters.
1014 beresp.do_gunzip
1016 Type: BOOL
1017 Readable from: vcl_backend_response, vcl_backend_error
1019 Writable from: vcl_backend_response, vcl_backend_error
1021 Default: false.
1023 Set to true to gunzip the object while storing it in the cache.
1025 If http_gzip_support is disabled, setting this variable has no ef‐
1027 fect.
1028 It is a VCL error to use beresp.do_gunzip after setting beresp.fil‐
1030 ters.
1031 beresp.was_304
1033 Type: BOOL
1034 Readable from: vcl_backend_response, vcl_backend_error
1036 When true this indicates that we got a 304 response to our condi‐
1038 tional fetch from the backend and turned that into beresp.status =
1039 200
1040 beresp.uncacheable
1042 Type: BOOL
1043 Readable from: vcl_backend_response, vcl_backend_error
1045 Writable from: vcl_backend_response, vcl_backend_error
1047 Inherited from bereq.uncacheable, see there.
1049 Setting this variable makes the object uncacheable.
1051 This may may produce a hit-for-miss object in the cache.
1053 Clearing the variable has no effect and will log the warning "Ignor‐
1055 ing attempt to reset beresp.uncacheable".
1056 beresp.ttl
1058 Type: DURATION
1059 Readable from: vcl_backend_response, vcl_backend_error
1061 Writable from: vcl_backend_response, vcl_backend_error
1063 Default: Cache-Control s-maxage or max-age directives, or a value
1065 computed from the Expires header's deadline, or the default_ttl pa‐
1066 rameter.
1067 The object's remaining time to live, in seconds.
1069 beresp.age
1071 Type: DURATION
1072 Readable from: vcl_backend_response, vcl_backend_error
1074 Default: Age header, or zero.
1076 The age of the object.
1078 beresp.grace
1080 Type: DURATION
1081 Readable from: vcl_backend_response, vcl_backend_error
1083 Writable from: vcl_backend_response, vcl_backend_error
1085 Default: Cache-Control stale-while-revalidate directive, or de‐
1087 fault_grace parameter.
1088 Set to a period to enable grace.
1090 beresp.keep
1092 Type: DURATION
1093 Readable from: vcl_backend_response, vcl_backend_error
1095 Writable from: vcl_backend_response, vcl_backend_error
1097 Default: default_keep parameter.
1099 Set to a period to enable conditional backend requests.
1101 The keep time is cache lifetime in addition to the ttl.
1103 Objects with ttl expired but with keep time left may be used to is‐
1105 sue conditional (If-Modified-Since / If-None-Match) requests to the
1106 backend to refresh them.
1107 beresp.backend
1109 Type: BACKEND
1110 Readable from: vcl_backend_response, vcl_backend_error
1112 This is the backend we fetched from. If bereq.backend was set to a
1114 director, this will be the backend selected by the director. When
1115 used in string context, returns its name.
1116 beresp.backend.name
1118 Type: STRING
1119 Readable from: vcl_backend_response, vcl_backend_error
1121 Name of the backend this response was fetched from. Same as
1123 beresp.backend.
1124 beresp.backend.ip VCL <= 4.0
1126 Type: IP
1127 Readable from: vcl_backend_response
1129 IP of the backend this response was fetched from.
1131 beresp.storage
1133 Type: STEVEDORE
1134 Readable from: vcl_backend_response, vcl_backend_error
1136 Writable from: vcl_backend_response, vcl_backend_error
1138 The storage backend to use to save this object.
1140 beresp.storage_hint VCL <= 4.0
1142 Type: STRING
1143 Readable from: vcl_backend_response, vcl_backend_error
1145 Writable from: vcl_backend_response, vcl_backend_error
1147 Deprecated since varnish 5.1 and discontinued since VCL 4.1 (varnish
1149 6.0). Use beresp.storage instead.
1150 Hint to Varnish that you want to save this object to a particular
1152 storage backend.
1153 beresp.filters
1155 Type: STRING
1156 Readable from: vcl_backend_response
1158 Writable from: vcl_backend_response
1160 List of Varnish Fetch Processor (VFP) filters the beresp.body will
1162 be pulled through. The order left to right signifies processing from
1163 backend to cache, iow the leftmost filter is run first on the body
1164 as received from the backend after decoding of any transfer encod‐
1165 ings.
1166 VFP Filters change the body before going into the cache and/or being
1168 handed to the client side, where it may get processed again by
1169 resp.filters.
1170 The following VFP filters exist in varnish-cache:
1172 • gzip: compress a body using gzip
1174 • testgunzip: Test if a body is valid gzip and refuse it otherwise
1176 • gunzip: Uncompress gzip content
1178 • esi: ESI-process plain text content
1180 • esi_gzip: Save gzipped snippets for efficient ESI-processing
1182 This filter enables stitching together ESI from individually
1184 gzipped fragments, saving processing power for re-compression on
1185 the client side at the expense of some compression efficiency.
1186 Additional VFP filters are available from VMODs.
1188 By default, beresp.filters is constructed as follows:
1190 • gunzip gets added for gzipped content if beresp.do_gunzip or
1192 beresp.do_esi are true.
1193 • esi_gzip gets added if beresp.do_esi is true together with
1195 beresp.do_gzip or content is already compressed.
1196 • esi gets added if beresp.do_esi is true
1198 • gzip gets added for uncompressed content if beresp.do_gzip is true
1200 • testgunzip gets added for compressed content if beresp.do_gunzip
1202 is false.
1203 After beresp.filters is set, using any of the beforementioned
1205 beresp.do_* switches is a VCL error.
1206 obj
1208 This is the object we found in cache. It cannot be modified.
1209 obj.proto
1211 Type: STRING
1212 Readable from: vcl_hit
1214 The HTTP protocol version stored in the object.
1216 obj.status
1218 Type: INT
1219 Readable from: vcl_hit
1221 The HTTP status code stored in the object.
1223 More information in the HTTP response status section.
1225 obj.reason
1227 Type: STRING
1228 Readable from: vcl_hit
1230 The HTTP reason phrase stored in the object.
1232 obj.hits
1234 Type: INT
1235 Readable from: vcl_hit, vcl_deliver
1237 The count of cache-hits on this object.
1239 In vcl_deliver a value of 0 indicates a cache miss.
1241 obj.http.*
1243 Type: HEADER
1244 Readable from: vcl_hit
1246 The HTTP headers stored in the object.
1248 obj.ttl
1250 Type: DURATION
1251 Readable from: vcl_hit, vcl_deliver
1253 The object's remaining time to live, in seconds.
1255 obj.age
1257 Type: DURATION
1258 Readable from: vcl_hit, vcl_deliver
1260 The age of the object.
1262 obj.grace
1264 Type: DURATION
1265 Readable from: vcl_hit, vcl_deliver
1267 The object's grace period in seconds.
1269 obj.keep
1271 Type: DURATION
1272 Readable from: vcl_hit, vcl_deliver
1274 The object's keep period in seconds.
1276 obj.uncacheable
1278 Type: BOOL
1279 Readable from: vcl_deliver
1281 Whether the object is uncacheable (pass, hit-for-pass or
1283 hit-for-miss).
1284 obj.storage
1286 Type: STEVEDORE
1287 Readable from: vcl_hit, vcl_deliver
1289 The storage backend where this object is stored.
1291 obj.can_esi
1293 Type: BOOL
1294 Readable from: vcl_hit, vcl_deliver
1296 If the object can be ESI processed, that is if setting resp.do_esi
1298 or adding esi to resp.filters in vcl_deliver {} would cause the re‐
1299 sponse body to be ESI processed.
1300 resp
1302 This is the response we send to the client, it is built from either
1303 beresp (pass/miss), obj (hits) or created from whole cloth (synth).
1304 With the exception of resp.body all resp.* variables available in both
1306 vcl_deliver{} and vcl_synth{} as a matter of symmetry.
1307 resp
1309 Type: HTTP
1310 Readable from: vcl_deliver, vcl_synth
1312 The entire response HTTP data structure, useful as argument to
1314 VMODs.
1315 resp.body
1317 Type: BODY
1318 Writable from: vcl_synth
1320 To produce a synthetic response body, for instance for errors.
1322 resp.proto VCL <= 4.0
1324 Type: STRING
1325 Readable from: vcl_deliver, vcl_synth
1327 Writable from: vcl_deliver, vcl_synth
1329 The HTTP protocol version to use for the response.
1331 resp.proto VCL >= 4.1
1333 Type: STRING
1334 Readable from: vcl_deliver, vcl_synth
1336 Writable from: vcl_deliver, vcl_synth
1338 The HTTP protocol version to use for the response.
1340 resp.status
1342 Type: INT
1343 Readable from: vcl_deliver, vcl_synth
1345 Writable from: vcl_deliver, vcl_synth
1347 The HTTP status code that will be returned.
1349 More information in the HTTP response status section.
1351 resp.status 200 will get changed into 304 by core code after a re‐
1353 turn(deliver) from vcl_deliver for conditional requests to cached
1354 content if validation succeeds.
1355 For the validation, first req.http.If-None-Match is compared against
1357 resp.http.Etag. If they compare equal according to the rules for
1358 weak validation (see RFC7232), a 304 is sent.
1359 Secondly, req.http.If-Modified-Since is compared against
1361 resp.http.Last-Modified or, if it is unset, against the point in
1362 time when the object was last modified based on the Date and Age
1363 headers received with the backend response which created the object.
1364 If the object has not been modified based on that comparison, a 304
1365 is sent.
1366 resp.reason
1368 Type: STRING
1369 Readable from: vcl_deliver, vcl_synth
1371 Writable from: vcl_deliver, vcl_synth
1373 The HTTP status message that will be returned.
1375 resp.http.*
1377 Type: HEADER
1378 Readable from: vcl_deliver, vcl_synth
1380 Writable from: vcl_deliver, vcl_synth
1382 Unsetable from: vcl_deliver, vcl_synth
1384 The HTTP headers that will be returned.
1386 resp.do_esi VCL >= 4.1
1388 Type: BOOL
1389 Readable from: vcl_deliver, vcl_synth
1391 Writable from: vcl_deliver, vcl_synth
1393 Default: obj.can_esi
1395 This can be used to selectively disable ESI processing, even though
1397 ESI parsing happened during fetch. This is useful when Varnish
1398 caches peer with each other.
1399 It is a VCL error to use resp.do_esi after setting resp.filters.
1401 resp.is_streaming
1403 Type: BOOL
1404 Readable from: vcl_deliver, vcl_synth
1406 Returns true when the response will be streamed while being fetched
1408 from the backend.
1409 resp.filters
1411 Type: STRING
1412 Readable from: vcl_deliver, vcl_synth
1414 Writable from: vcl_deliver, vcl_synth
1416 List of VDP filters the resp.body will be pushed through.
1418 Before resp.filters is set, the value read will be the default fil‐
1420 ter list as determined by varnish based on resp.do_esi and request
1421 headers.
1422 After resp.filters is set, changing any of the conditions which oth‐
1424 erwise determine the filter selection will have no effiect. Using
1425 resp.do_esi is an error once resp.filters is set.
1426 Special variables
1428 now
1429 Type: TIME
1430 Readable from: all
1432 The current time, in seconds since the UNIX epoch.
1434 When converted to STRING in expressions it returns a formatted time‐
1436 stamp like Tue, 20 Feb 2018 09:30:31 GMT
1437 sess
1439 A session corresponds to the "conversation" that Varnish has with a
1440 single client connection, over which one or more request/response
1441 transactions may take place. It may comprise the traffic over an HTTP/1
1442 keep-alive connection, or the multiplexed traffic over an HTTP/2 con‐
1443 nection.
1444 sess.xid VCL >= 4.1
1446 Type: STRING
1447 Readable from: client, backend
1449 Unique ID of this session.
1451 sess.timeout_idle
1453 Type: DURATION
1454 Readable from: client
1456 Writable from: client
1458 Idle timeout for this session, defaults to the timeout_idle parame‐
1460 ter, see varnishd(1)
1461 sess.timeout_linger
1463 Type: DURATION
1464 Readable from: client
1466 Writable from: client
1468 Linger timeout for this session, defaults to the timeout_linger pa‐
1470 rameter, see varnishd(1)
1471 sess.send_timeout
1473 Type: DURATION
1474 Readable from: client
1476 Writable from: client
1478 Total timeout for ordinary HTTP1 responses, defaults to the
1480 send_timeout parameter, see varnishd(1)
1481 sess.idle_send_timeout
1483 Type: DURATION
1484 Readable from: client
1486 Writable from: client
1488 Send timeout for individual pieces of data on client connections,
1490 defaults to the idle_send_timeout parameter, see varnishd(1)
1491 storage
1493 storage.<name>.free_space
1494 Type: BYTES
1495 Readable from: client, backend
1497 Free space available in the named stevedore. Only available for the
1499 malloc stevedore.
1500 storage.<name>.used_space
1502 Type: BYTES
1503 Readable from: client, backend
1505 Used space in the named stevedore. Only available for the malloc
1507 stevedore.
1508 storage.<name>.happy
1510 Type: BOOL
1511 Readable from: client, backend
1513 Health status for the named stevedore. Not available in any of the
1515 current stevedores.
1516 HTTP response status
1518 A status code normally has 3 digits XYZ where X must be between 1 and 5
1519 included. Since it is not uncommon to see HTTP clients or servers rely‐
1520 ing on non-standard or even invalid status codes Varnish tolerates any
1521 status between 100 and 999.
1522 With VCL code it is possible to use status codes in the form XXYZZ
1524 where the overall value is lower than 65536 and the Y digit is between
1525 1 and 9 included. Only the YZZ part is sent to the client.
1526 The XXYZZ form of status codes can be set on resp.status and
1528 beresp.status or passed via return(synth(...)) and return(error(...))
1529 transitions.
1530 XX can be therefore be used to pass information around inside VCL, for
1532 instance return(synth(22404)) from vcl_recv{} to vcl_synth{}.
1533 The obj.status variable will inherit the XXYZZ form, but in a ban ex‐
1535 presion only the YZZ part will be available. The XXYZZ form is strictly
1536 limited to VCL execution.
1537 Assigning an HTTP standardized code to resp.status or beresp.status
1539 will also set resp.reason or beresp.reason to the corresponding status
1540 message.
1541 Functions
1543 The following built-in functions are available:
1544 ban(STRING)
1546 Invalidates all objects in cache that match the given expression
1547 with the ban mechanism.
1548 The format of STRING is:
1550 <field> <operator> <arg> [&& <field> <oper> <arg> ...]
1552 • <field>:
1554 • string fields:
1556 • req.url: The request url
1558 • req.http.*: Any request header
1560 • obj.status: The cache object status
1562 • obj.http.*: Any cache object header
1564 obj.status is treated as a string despite the fact that it is
1566 actually an integer.
1567 • duration fields:
1569 • obj.ttl: Remaining ttl at the time the ban is issued
1571 • obj.age: Object age at the time the ban is issued
1573 • obj.grace: The grace time of the object
1575 • obj.keep: The keep time of the object
1577 • <operator>:
1579 • for all fields:
1581 • ==: <field> and <arg> are equal
1583 • !=: <field> and <arg> are unequal
1585 strings are compared case sensitively
1587 • for string fields:
1589 • ~: <field> matches the regular expression <arg>
1591 • !~:<field> does not match the regular expression <arg>
1593 • for duration fields:
1595 • >: <field> is greater than <arg>
1597 • >=: <field> is greater than or equal to <arg>
1599 • <: <field> is less than <arg>
1601 • <=: <field> is less than or equal to <arg>
1603 • <arg>:
1605 • for string fields:
1607 Either a literal string or a regular expression. Note that <arg>
1609 does not use any of the string delimiters like " or {"..."} used
1610 elsewhere in varnish. To match against strings containing white‐
1611 space, regular expressions containing \s can be used.
1612 • for duration fields:
1614 A VCL duration like 10s, 5m or 1h, see Durations
1616 Expressions can be chained using the and operator &&. For or seman‐
1618 tics, use several bans.
1619 The unset <field> is not equal to any string, such that, for a
1621 non-existing header, the operators == and ~ always evaluate as
1622 false, while the operators != and !~ always evaluate as true, re‐
1623 spectively, for any value of <arg>.
1624 hash_data(input)
1626 Adds an input to the hash input. In the built-in VCL hash_data() is
1627 called on the host and URL of the request. Available in vcl_hash.
1628 synthetic(STRING)
1630 Prepare a synthetic response body containing the STRING. Available
1631 in vcl_synth and vcl_backend_error.
1632 Identical to set resp.body / set beresp.body.
1634 regsub(str, regex, sub)
1636 Returns a copy of str with the first occurrence of the regular ex‐
1637 pression regex replaced with sub. Within sub, \0 (which can also be
1638 spelled \&) is replaced with the entire matched string, and \n is
1639 replaced with the contents of subgroup n in the matched string.
1640 regsuball(str, regex, sub)
1642 As regsub(), but this replaces all occurrences.
1643 For converting or casting VCL values between data types use the func‐
1645 tions available in the std VMOD.
1646
1648 Multiple versions of the VCL syntax can coexist within certain con‐
1649 straints.
1650 The VCL syntax version at the start of VCL file specified with -f sets
1652 the hard limit that cannot be exceeded anywhere, and it selects the ap‐
1653 propriate version of the builtin VCL.
1654 That means that you can never include vcl 9.1; from vcl 8.7;, but the
1656 opposite may be possible, to the extent the compiler supports it.
1657 Files pulled in via include do not need to have a vcl X.Y; but it may
1659 be a good idea to do it anyway, to not have surprises in the future.
1660 The syntax version set in an included file only applies to that file
1661 and any files it includes - unless these set their own VCL syntax ver‐
1662 sion.
1663 The version of Varnish this file belongs to supports syntax 4.0 and
1665 4.1.
1666
1668 For examples, please see the online documentation.
1669
1671 • varnishd(1)
1672 • vmod_directors(3)
1674 • vmod_std(3)
1676
1678 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
1679 AS, Redpill Linpro and Varnish Software. This manual page is written
1680 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
1681 gstøl, Lasse Karstensen and possibly others.
1682
1684 This document is licensed under the same license as Varnish itself. See
1685 LICENSE for details.
1686 • Copyright (c) 2006 Verdens Gang AS
1688 • Copyright (c) 2006-2015 Varnish Software AS
1690 VCL(7)