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 +=, -=, *=, /=
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
77 assigned; 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
182 accessible to Varnish at VCL load time, then the VCL compiler
183 issues 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.
194 Ignored 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
302 addresses:
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
311 resolve, it will match any address it is compared to. Consequently, if
312 it is preceded by a negation mark, it will reject any address it is
313 compared to, which may not be what you intended. If the entry is
314 enclosed 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
357 defines 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,
388 often 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
452 either 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 local.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
473 director. 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
484 received, either the same as server.ip or what the PROXY protocol
485 told 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
507 requests are being processed, req_top points to the request received
508 from 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
654 director, reading this variable returns an actual backend if the
655 director 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
708 requests. (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
717 requests. 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
733 requests. 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 miss
741 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
901 object 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 Status codes on the form XXYZZ can be set where XXYZZ is less than
944 65536 and Y is [1...9]. Only YZZ will be sent back to clients.
945 XX can be therefore be used to pass information around inside VCL,
947 for instance return(synth(22404)) from vcl_recv{} to vcl_synth{}
948 beresp.reason
950 Type: STRING
951 Readable from: vcl_backend_response, vcl_backend_error
953 Writable from: vcl_backend_response, vcl_backend_error
955 The HTTP status message returned by the server.
957 beresp.http.*
959 Type: HEADER
960 Readable from: vcl_backend_response, vcl_backend_error
962 Writable from: vcl_backend_response, vcl_backend_error
964 Unsetable from: vcl_backend_response, vcl_backend_error
966 The HTTP headers returned from the server.
968 beresp.do_esi
970 Type: BOOL
971 Readable from: vcl_backend_response, vcl_backend_error
973 Writable from: vcl_backend_response, vcl_backend_error
975 Default: false.
977 Set it to true to parse the object for ESI directives. Will only be
979 honored if req.esi is true.
980 beresp.do_stream
982 Type: BOOL
983 Readable from: vcl_backend_response, vcl_backend_error
985 Writable from: vcl_backend_response, vcl_backend_error
987 Default: true.
989 Deliver the object to the client while fetching the whole object
991 into varnish.
992 For uncacheable objects, storage for parts of the body which have
994 been sent to the client may get freed early, depending on the stor‐
995 age engine used.
996 This variable has no effect if do_esi is true or when the response
998 body is empty.
999 beresp.do_gzip
1001 Type: BOOL
1002 Readable from: vcl_backend_response, vcl_backend_error
1004 Writable from: vcl_backend_response, vcl_backend_error
1006 Default: false.
1008 Set to true to gzip the object while storing it.
1010 If http_gzip_support is disabled, setting this variable has no
1012 effect.
1013 beresp.do_gunzip
1015 Type: BOOL
1016 Readable from: vcl_backend_response, vcl_backend_error
1018 Writable from: vcl_backend_response, vcl_backend_error
1020 Default: false.
1022 Set to true to gunzip the object while storing it in the cache.
1024 If http_gzip_support is disabled, setting this variable has no
1026 effect.
1027 beresp.was_304
1029 Type: BOOL
1030 Readable from: vcl_backend_response, vcl_backend_error
1032 When true this indicates that we got a 304 response to our condi‐
1034 tional fetch from the backend and turned that into beresp.status =
1035 200
1036 beresp.uncacheable
1038 Type: BOOL
1039 Readable from: vcl_backend_response, vcl_backend_error
1041 Writable from: vcl_backend_response, vcl_backend_error
1043 Inherited from bereq.uncacheable, see there.
1045 Setting this variable makes the object uncacheable.
1047 This may may produce a hit-for-miss object in the cache.
1049 Clearing the variable has no effect and will log the warning "Ignor‐
1051 ing attempt to reset beresp.uncacheable".
1052 beresp.ttl
1054 Type: DURATION
1055 Readable from: vcl_backend_response, vcl_backend_error
1057 Writable from: vcl_backend_response, vcl_backend_error
1059 Default: Cache-Control s-maxage or max-age directives, or a value
1061 computed from the Expires header's deadline, or the default_ttl
1062 parameter.
1063 The object's remaining time to live, in seconds.
1065 beresp.age
1067 Type: DURATION
1068 Readable from: vcl_backend_response, vcl_backend_error
1070 Default: Age header, or zero.
1072 The age of the object.
1074 beresp.grace
1076 Type: DURATION
1077 Readable from: vcl_backend_response, vcl_backend_error
1079 Writable from: vcl_backend_response, vcl_backend_error
1081 Default: Cache-Control stale-while-revalidate directive, or
1083 default_grace parameter.
1084 Set to a period to enable grace.
1086 beresp.keep
1088 Type: DURATION
1089 Readable from: vcl_backend_response, vcl_backend_error
1091 Writable from: vcl_backend_response, vcl_backend_error
1093 Default: default_keep parameter.
1095 Set to a period to enable conditional backend requests.
1097 The keep time is cache lifetime in addition to the ttl.
1099 Objects with ttl expired but with keep time left may be used to
1101 issue conditional (If-Modified-Since / If-None-Match) requests to
1102 the backend to refresh them.
1103 beresp.backend
1105 Type: BACKEND
1106 Readable from: vcl_backend_response, vcl_backend_error
1108 This is the backend we fetched from. If bereq.backend was set to a
1110 director, this will be the backend selected by the director. When
1111 used in string context, returns its name.
1112 beresp.backend.name
1114 Type: STRING
1115 Readable from: vcl_backend_response, vcl_backend_error
1117 Name of the backend this response was fetched from. Same as
1119 beresp.backend.
1120 beresp.backend.ip VCL <= 4.0
1122 Type: IP
1123 Readable from: vcl_backend_response
1125 IP of the backend this response was fetched from.
1127 beresp.storage
1129 Type: STEVEDORE
1130 Readable from: vcl_backend_response, vcl_backend_error
1132 Writable from: vcl_backend_response, vcl_backend_error
1134 The storage backend to use to save this object.
1136 beresp.storage_hint VCL <= 4.0
1138 Type: STRING
1139 Readable from: vcl_backend_response, vcl_backend_error
1141 Writable from: vcl_backend_response, vcl_backend_error
1143 Deprecated since varnish 5.1 and discontinued since VCL 4.1 (varnish
1145 6.0). Use beresp.storage instead.
1146 Hint to Varnish that you want to save this object to a particular
1148 storage backend.
1149 beresp.filters
1151 Type: STRING
1152 Readable from: vcl_backend_response
1154 Writable from: vcl_backend_response
1156 List of Varnish Fetch Processor (VFP) filters the beresp.body will
1158 be pulled through. The order left to right signifies processing from
1159 backend to cache, iow the leftmost filter is run first on the body
1160 as received from the backend after decoding of any transfer encod‐
1161 ings.
1162 VFP Filters change the body before going into the cache and/or being
1164 handed to the client side, where it may get processed again by
1165 resp.filters.
1166 The following VFP filters exist in varnish-cache:
1168 · gzip: compress a body using gzip
1170 · testgunzip: Test if a body is valid gzip and refuse it otherwise
1172 · gunzip: Uncompress gzip content
1174 · esi: ESI-process plain text content
1176 · esi_gzip: Save gzipped snippets for efficient ESI-processing
1178 This filter enables stitching together ESI from individually
1180 gzipped fragments, saving processing power for re-compression on
1181 the client side at the expense of some compression efficiency.
1182 Additional VFP filters are available from VMODs.
1184 By default, beresp.filters is constructed as follows:
1186 · gunzip gets added for gzipped content if beresp.do_gunzip or
1188 beresp.do_esi are true.
1189 · esi_gzip gets added if beresp.do_esi is true together with
1191 beresp.do_gzip or content is already compressed.
1192 · esi gets added if beresp.do_esi is true
1194 · gzip gets added for uncompressed content if beresp.do_gzip is true
1196 · testgunzip gets added for compressed content if beresp.do_gunzip
1198 is false.
1199 obj
1201 This is the object we found in cache. It cannot be modified.
1202 obj.proto
1204 Type: STRING
1205 Readable from: vcl_hit
1207 The HTTP protocol version stored in the object.
1209 obj.status
1211 Type: INT
1212 Readable from: vcl_hit
1214 The HTTP status code stored in the object.
1216 obj.reason
1218 Type: STRING
1219 Readable from: vcl_hit
1221 The HTTP reason phrase stored in the object.
1223 obj.hits
1225 Type: INT
1226 Readable from: vcl_hit, vcl_deliver
1228 The count of cache-hits on this object.
1230 In vcl_deliver a value of 0 indicates a cache miss.
1232 obj.http.*
1234 Type: HEADER
1235 Readable from: vcl_hit
1237 The HTTP headers stored in the object.
1239 obj.ttl
1241 Type: DURATION
1242 Readable from: vcl_hit, vcl_deliver
1244 The object's remaining time to live, in seconds.
1246 obj.age
1248 Type: DURATION
1249 Readable from: vcl_hit, vcl_deliver
1251 The age of the object.
1253 obj.grace
1255 Type: DURATION
1256 Readable from: vcl_hit, vcl_deliver
1258 The object's grace period in seconds.
1260 obj.keep
1262 Type: DURATION
1263 Readable from: vcl_hit, vcl_deliver
1265 The object's keep period in seconds.
1267 obj.uncacheable
1269 Type: BOOL
1270 Readable from: vcl_deliver
1272 Whether the object is uncacheable (pass, hit-for-pass or
1274 hit-for-miss).
1275 obj.storage
1277 Type: STEVEDORE
1278 Readable from: vcl_hit, vcl_deliver
1280 The storage backend where this object is stored.
1282 resp
1284 This is the response we send to the client, it is built from either
1285 beresp (pass/miss), obj (hits) or created from whole cloth (synth).
1286 With the exception of resp.body all resp.* variables available in both
1288 vcl_deliver{} and vcl_synth{} as a matter of symmetry.
1289 resp
1291 Type: HTTP
1292 Readable from: vcl_deliver, vcl_synth
1294 The entire response HTTP data structure, useful as argument to
1296 VMODs.
1297 resp.body
1299 Type: BODY
1300 Writable from: vcl_synth
1302 To produce a synthetic response body, for instance for errors.
1304 resp.proto VCL <= 4.0
1306 Type: STRING
1307 Readable from: vcl_deliver, vcl_synth
1309 Writable from: vcl_deliver, vcl_synth
1311 The HTTP protocol version to use for the response.
1313 resp.proto VCL >= 4.1
1315 Type: STRING
1316 Readable from: vcl_deliver, vcl_synth
1318 Writable from: vcl_deliver, vcl_synth
1320 The HTTP protocol version to use for the response.
1322 resp.status
1324 Type: INT
1325 Readable from: vcl_deliver, vcl_synth
1327 Writable from: vcl_deliver, vcl_synth
1329 The HTTP status code that will be returned.
1331 Assigning a HTTP standardized code to resp.status will also set
1333 resp.reason to the corresponding status message.
1334 resp.status 200 will get changed into 304 by core code after a
1336 return(deliver) from vcl_deliver for conditional requests to cached
1337 content if validation succeeds.
1338 For the validation, first req.http.If-None-Match is compared against
1340 resp.http.Etag. If they compare equal according to the rules for
1341 weak validation (see RFC7232), a 304 is sent.
1342 Secondly, req.http.If-Modified-Since is compared against
1344 resp.http.Last-Modified or, if it is unset, against the point in
1345 time when the object was last modified based on the Date and Age
1346 headers received with the backend response which created the object.
1347 If the object has not been modified based on that comparison, a 304
1348 is sent.
1349 resp.reason
1351 Type: STRING
1352 Readable from: vcl_deliver, vcl_synth
1354 Writable from: vcl_deliver, vcl_synth
1356 The HTTP status message that will be returned.
1358 resp.http.*
1360 Type: HEADER
1361 Readable from: vcl_deliver, vcl_synth
1363 Writable from: vcl_deliver, vcl_synth
1365 Unsetable from: vcl_deliver, vcl_synth
1367 The HTTP headers that will be returned.
1369 resp.do_esi VCL >= 4.1
1371 Type: BOOL
1372 Readable from: vcl_deliver, vcl_synth
1374 Writable from: vcl_deliver, vcl_synth
1376 Default: Set if ESI parsing has happened.
1378 This can be used to selectively disable ESI processing, even though
1380 ESI parsing happened during fetch. This is useful when Varnish
1381 caches peer with each other.
1382 resp.is_streaming
1384 Type: BOOL
1385 Readable from: vcl_deliver, vcl_synth
1387 Returns true when the response will be streamed while being fetched
1389 from the backend.
1390 resp.filters
1392 Type: STRING
1393 Readable from: vcl_deliver, vcl_synth
1395 Writable from: vcl_deliver, vcl_synth
1397 List of VDP filters the resp.body will be pushed through.
1399 Special variables
1401 now
1402 Type: TIME
1403 Readable from: all
1405 The current time, in seconds since the UNIX epoch.
1407 When converted to STRING in expressions it returns a formatted time‐
1409 stamp like Tue, 20 Feb 2018 09:30:31 GMT
1410 sess
1412 A session corresponds to the "conversation" that Varnish has with a
1413 single client connection, over which one or more request/response
1414 transactions may take place. It may comprise the traffic over an HTTP/1
1415 keep-alive connection, or the multiplexed traffic over an HTTP/2 con‐
1416 nection.
1417 sess.xid VCL >= 4.1
1419 Type: STRING
1420 Readable from: client, backend
1422 Unique ID of this session.
1424 sess.timeout_idle
1426 Type: DURATION
1427 Readable from: client
1429 Writable from: client
1431 Idle timeout for this session, defaults to the timeout_idle parame‐
1433 ter, see varnishd(1)
1434 sess.timeout_linger
1436 Type: DURATION
1437 Readable from: client
1439 Writable from: client
1441 Linger timeout for this session, defaults to the timeout_linger
1443 parameter, see varnishd(1)
1444 sess.send_timeout
1446 Type: DURATION
1447 Readable from: client
1449 Writable from: client
1451 Total timeout for ordinary HTTP1 responses, defaults to the
1453 send_timeout parameter, see varnishd(1)
1454 sess.idle_send_timeout
1456 Type: DURATION
1457 Readable from: client
1459 Writable from: client
1461 Send timeout for individual pieces of data on client connections,
1463 defaults to the idle_send_timeout parameter, see varnishd(1)
1464 storage
1466 storage.<name>.free_space
1467 Type: BYTES
1468 Readable from: client, backend
1470 Free space available in the named stevedore. Only available for the
1472 malloc stevedore.
1473 storage.<name>.used_space
1475 Type: BYTES
1476 Readable from: client, backend
1478 Used space in the named stevedore. Only available for the malloc
1480 stevedore.
1481 storage.<name>.happy
1483 Type: BOOL
1484 Readable from: client, backend
1486 Health status for the named stevedore. Not available in any of the
1488 current stevedores.
1489 Functions
1491 The following built-in functions are available:
1492 ban(STRING)
1494 Invalidates all objects in cache that match the given expression
1495 with the ban mechanism.
1496 The format of STRING is:
1498 <field> <operator> <arg> [&& <field> <oper> <arg> ...]
1500 · <field>:
1502 · string fields:
1504 · req.url: The request url
1506 · req.http.*: Any request header
1508 · obj.status: The cache object status
1510 · obj.http.*: Any cache object header
1512 obj.status is treated as a string despite the fact that it is
1514 actually an integer.
1515 · duration fields:
1517 · obj.ttl: Remaining ttl at the time the ban is issued
1519 · obj.age: Object age at the time the ban is issued
1521 · obj.grace: The grace time of the object
1523 · obj.keep: The keep time of the object
1525 · <operator>:
1527 · for all fields:
1529 · ==: <field> and <arg> are equal
1531 · !=: <field> and <arg> are unequal
1533 strings are compared case sensitively
1535 · for string fields:
1537 · ~: <field> matches the regular expression <arg>
1539 · !~:<field> does not match the regular expression <arg>
1541 · for duration fields:
1543 · >: <field> is greater than <arg>
1545 · >=: <field> is greater than or equal to <arg>
1547 · <: <field> is less than <arg>
1549 · <=: <field> is less than or equal to <arg>
1551 · <arg>:
1553 · for string fields:
1555 Either a literal string or a regular expression. Note that <arg>
1557 does not use any of the string delimiters like " or {"..."} used
1558 elsewhere in varnish. To match against strings containing white‐
1559 space, regular expressions containing \s can be used.
1560 · for duration fields:
1562 A VCL duration like 10s, 5m or 1h, see Durations
1564 Expressions can be chained using the and operator &&. For or seman‐
1566 tics, use several bans.
1567 The unset <field> is not equal to any string, such that, for a
1569 non-existing header, the operators == and ~ always evaluate as
1570 false, while the operators != and !~ always evaluate as true,
1571 respectively, for any value of <arg>.
1572 hash_data(input)
1574 Adds an input to the hash input. In the built-in VCL hash_data() is
1575 called on the host and URL of the request. Available in vcl_hash.
1576 synthetic(STRING)
1578 Prepare a synthetic response body containing the STRING. Available
1579 in vcl_synth and vcl_backend_error.
1580 Identical to set resp.body / set beresp.body.
1582 regsub(str, regex, sub)
1584 Returns a copy of str with the first occurrence of the regular
1585 expression regex replaced with sub. Within sub, \0 (which can also
1586 be spelled \&) is replaced with the entire matched string, and \n is
1587 replaced with the contents of subgroup n in the matched string.
1588 regsuball(str, regex, sub)
1590 As regsub(), but this replaces all occurrences.
1591 For converting or casting VCL values between data types use the func‐
1593 tions available in the std VMOD.
1594
1596 Multiple versions of the VCL syntax can coexist within certain con‐
1597 straints.
1598 The VCL syntax version at the start of VCL file specified with -f sets
1600 the hard limit that cannot be exceeded anywhere, and it selects the
1601 appropriate version of the builtin VCL.
1602 That means that you can never include vcl 9.1; from vcl 8.7;, but the
1604 opposite may be possible, to the extent the compiler supports it.
1605 Files pulled in via include do not need to have a vcl X.Y; but it may
1607 be a good idea to do it anyway, to not have surprises in the future.
1608 The syntax version set in an included file only applies to that file
1609 and any files it includes - unless these set their own VCL syntax ver‐
1610 sion.
1611 The version of Varnish this file belongs to supports syntax 4.0 and
1613 4.1.
1614
1616 For examples, please see the online documentation.
1617
1619 · varnishd(1)
1620 · vmod_directors(3)
1622 · vmod_std(3)
1624
1626 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
1627 AS, Redpill Linpro and Varnish Software. This manual page is written
1628 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
1629 gstøl, Lasse Karstensen and possibly others.
1630
1632 This document is licensed under the same license as Varnish itself. See
1633 LICENSE for details.
1634 · Copyright (c) 2006 Verdens Gang AS
1636 · Copyright (c) 2006-2015 Varnish Software AS
1638 VCL(7)