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 not set; backend types
66 will evaluate to false if they don't have a backend assigned; integer
67 types will evaluate to false if their value is zero; duration types
68 will evaluate to false if their value is equal or less than zero.
69 Time
71 VCL has time. A duration can be added to a time to make another time.
72 In string context they return a formatted string in RFC1123 format,
73 e.g. Sun, 06 Nov 1994 08:49:37 GMT.
74 The keyword now returns a time representing the current time in seconds
76 since the Epoch.
77 Durations
79 Durations are defined by a number followed by a unit. The number can
80 include a fractional part, e.g. 1.5s. The supported units are:
81 ms milliseconds
83 s seconds
85 m minutes
87 h hours
89 d days
91 w weeks
93 y years
95 In string context they return a string with their value rounded to 3
97 decimal places and excluding the unit, e.g. 1.500.
98 Integers
100 Certain fields are integers, used as expected. In string context they
101 return a string, e.g. 1234.
102 Real numbers
104 VCL understands real numbers. In string context they return a string
105 with their value rounded to 3 decimal places, e.g. 3.142.
106 Regular Expressions
108 Varnish uses Perl-compatible regular expressions (PCRE). For a complete
109 description please see the pcre(3) man page.
110 To send flags to the PCRE engine, such as to do case insensitive match‐
112 ing, add the flag within parens following a question mark, like this:
113 # If host is NOT example dot com..
115 if (req.http.host !~ "(?i)example\.com$") {
116 ...
117 }
118 Include statement
120 To include a VCL file in another file use the include keyword:
121 include "foo.vcl";
123 Import statement
125 The import statement is used to load Varnish Modules (VMODs.)
126 Example:
128 import std;
130 sub vcl_recv {
131 std.log("foo");
132 }
133 Comments
135 Single lines of VCL can be commented out using // or #. Multi-line
136 blocks can be commented out with /*block*/.
137 Example:
139 sub vcl_recv {
141 // Single line of out-commented VCL.
142 # Another way of commenting out a single line.
143 /*
144 Multi-line block of commented-out VCL.
145 */
146 }
147 Backend definition
149 A backend declaration creates and initialises a named backend object. A
150 declaration start with the keyword backend followed by the name of the
151 backend. The actual declaration is in curly brackets, in a key/value
152 fashion.:
153 backend name {
155 .attribute = "value";
156 }
157 One of the attributes .host or .path is mandatory (but not both). The
159 attributes will inherit their defaults from the global parameters. The
160 following attributes are available:
161 .host The host to be used. IP address or a hostname that resolves
163 to a single IP address. This attribute is mandatory, unless
164 .path is declared.
165 .path (VCL >= 4.1)
167 The absolute path of a Unix domain socket at which a backend
168 is listening. The file at that path must exist and must be
169 accessible to Varnish at VCL load time, and it must be a
170 socket. One of .path or .host must be declared (but not
171 both). .path may only be used in VCL since version 4.1.
172 .port The port on the backend that Varnish should connect to.
174 Ignored if a Unix domain socket is declared in .path.
175 .host_header
177 A host header to add to probes and regular backend requests
178 if they have no such header.
179 .connect_timeout
181 Timeout for connections.
182 Default: connect_timeout parameter, see varnishd(1)
184 .first_byte_timeout
186 Timeout for first byte.
187 Default: first_byte_timeout parameter, see varnishd(1)
189 .between_bytes_timeout
191 Timeout between bytes.
192 Default: between_bytes_timeout parameter, see varnishd(1)
194 .probe Attach a probe to the backend. See Probes
196 .proxy_header
198 The PROXY protocol version Varnish should use when connecting
199 to this backend. Allowed values are 1 and 2.
200 Notice this setting will lead to backend connections being
202 used for a single request only (subject to future improve‐
203 ments). Thus, extra care should be taken to avoid running
204 into failing backend connections with EADDRNOTAVAIL due to no
205 local ports being available. Possible options are:
206 · Use additional backend connections to extra IP addresses or
208 TCP ports
209 · Increase the number of available ports (Linux sysctl
211 net.ipv4.ip_local_port_range)
212 · Reuse backend connection ports early (Linux sysctl
214 net.ipv4.tcp_tw_reuse)
215 .max_connections
217 Maximum number of open connections towards this backend. If
218 Varnish reaches the maximum Varnish it will start failing
219 connections.
220 Backends can be used with directors. Please see the vmod_directors(3)
222 man page for more information.
223 Probes
225 Probes will query the backend for status on a regular basis and mark
226 the backend as down it they fail. A probe is defined as this:
227 probe name {
229 .attribute = "value";
230 }
231 The probe named default is special and will be used for all backends
233 which do not explicitly reference a probe.
234 There are no mandatory options. These are the options you can set:
236 .url The URL to query. Defaults to /. Mutually exclusive with
238 .request
239 .request
241 Specify a full HTTP request using multiple strings. .request
242 will have \r\n automatically inserted after every string.
243 Mutually exclusive with .url.
244 Note that probes require the backend to complete sending the
246 response and close the connection within the specified time‐
247 out, so .request will, for HTTP/1.1, most likely need to con‐
248 tain a "Connection: close" string.
249 .expected_response
251 The expected HTTP response code. Defaults to 200.
252 .timeout
254 The timeout for the probe. Default is 2s.
255 .interval
257 How often the probe is run. Default is 5s.
258 .initial
260 How many of the polls in .window are considered good when
261 Varnish starts. Defaults to the value of .threshold - 1. In
262 this case, the backend starts as sick and requires one single
263 poll to be considered healthy.
264 .window
266 How many of the latest polls we examine to determine backend
267 health. Defaults to 8.
268 .threshold
270 How many of the polls in .window must have succeeded to con‐
271 sider the backend to be healthy. Defaults to 3.
272 Access Control List (ACL)
274 An Access Control List (ACL) declaration creates and initialises a
275 named access control list which can later be used to match client
276 addresses:
277 acl localnetwork {
279 "localhost"; # myself
280 "192.0.2.0"/24; # and everyone on the local network
281 ! "192.0.2.23"; # except for the dial-in router
282 }
283 If an ACL entry specifies a host name which Varnish is unable to
285 resolve, it will match any address it is compared to. Consequently, if
286 it is preceded by a negation mark, it will reject any address it is
287 compared to, which may not be what you intended. If the entry is
288 enclosed in parentheses, however, it will simply be ignored.
289 To match an IP address against an ACL, simply use the match operator:
291 if (client.ip ~ localnetwork) {
293 return (pipe);
294 }
295 VCL objects
297 A VCL object can be instantiated with the new keyword:
298 sub vcl_init {
300 new b = directors.round_robin()
301 b.add_backend(node1);
302 }
303 This is only available in vcl_init.
305 Subroutines
307 A subroutine is used to group code for legibility or reusability:
308 sub pipe_if_local {
310 if (client.ip ~ localnetwork) {
311 return (pipe);
312 }
313 }
314 Subroutines in VCL do not take arguments, nor do they return values.
316 The built in subroutines all have names beginning with vcl_, which is
317 reserved.
318 To call a subroutine, use the call keyword followed by the subroutine's
320 name:
321 sub vcl_recv {
323 call pipe_if_local;
324 }
325 Return statements
327 The ongoing vcl_* subroutine execution ends when a return(<action>)
328 statement is made.
329 The <action> specifies how execution should proceed. The context
331 defines which actions are available.
332 Multiple subroutines
334 If multiple subroutines with the name of one of the built-in ones are
335 defined, they are concatenated in the order in which they appear in the
336 source.
337 The built-in VCL distributed with Varnish will be implicitly concate‐
339 nated when the VCL is compiled.
340 VCL Variables
342 Variables provide read, write and delete access to almost all aspects
343 of the work at hand.
344 Reading a variable is done simply by using its name in VCL:
346 if (client.ip ~ bad_guys) {
348 return (synth(400));
349 }
350 Writing a variable, where this is possible, is done with a set state‐
352 ment:
353 set resp.http.never = "Let You Down";
355 Similarly, deleting a variable, for the few variables where this is
357 possible, is done with a unset statement:
358 unset req.http.cookie;
360 Which operations are possible on each variable is described below,
362 often with the shorthand "backend" which covers the vcl_backend_* meth‐
363 ods and "client" which covers the rest, except vcl_init and vcl_fini.
364 When setting a variable, the right hand side of the equal sign must
366 have the variables type, you cannot assign a STRING to a variable of
367 type NUMBER, even if the string is "42". (Explicit conversion func‐
368 tions can be found in vmod_std(3)).
369 local, server, remote and client
371 These variables describe the network connection between the client and
372 varnishd.
373 Without PROXY protocol:
375 client server
377 remote local
378 v v
379 CLIENT ------------ VARNISHD
380 With PROXY protocol:
382 client server remote local
384 v v v v
385 CLIENT ------------ PROXY ------------ VARNISHD
386 local.ip
388 Type: IP
389 Readable from: client, backend
391 The IP address (and port number) of the local end of the TCP connec‐
393 tion, for instance 192.168.1.1:81
394 If the connection is a UNIX domain socket, the value will be
396 0.0.0.0:0
397 local.endpoint VCL >= 4.1
399 Type: STRING
400 Readable from: client, backend
402 The address of the '-a' socket the session was accepted on.
404 If the argument was -a foo=:81 this would be ":81"
406 local.socket VCL >= 4.1
408 Type: STRING
409 Readable from: client, backend
411 The name of the '-a' socket the session was accepted on.
413 If the argument was -a foo=:81 this would be "foo".
415 Note that all '-a' gets a default name on the form a%d if no name is
417 provided.
418 remote.ip
420 Type: IP
421 Readable from: client, backend
423 The IP address of the other end of the TCP connection. This can
425 either be the clients IP, or the outgoing IP of a proxy server.
426 If the connection is a UNIX domain socket, the value will be
428 0.0.0.0:0
429 client.ip
431 Type: IP
432 Readable from: client, backend
434 The client's IP address, either the same as local.ip or what the
436 PROXY protocol told us.
437 client.identity
439 Type: STRING
440 Readable from: client
442 Writable from: client
444 Identification of the client, used to load balance in the client
446 director. Defaults to client.ip
447 This variable can be overwritten with more precise information, for
449 instance extracted from a Cookie: header.
450 server.ip
452 Type: IP
453 Readable from: client, backend
455 The IP address of the socket on which the client connection was
457 received, either the same as server.ip or what the PROXY protocol
458 told us.
459 server.hostname
461 Type: STRING
462 Readable from: all
464 The host name of the server, as returned by the gethostname(3) sys‐
466 tem function.
467 server.identity
469 Type: STRING
470 Readable from: all
472 The identity of the server, as set by the -i parameter.
474 If an -i parameter is not passed to varnishd, the return value from
476 gethostname(3) system function will be used.
477 req and req_top
479 These variables describe the present request, and when ESI:include
480 requests are being processed, req_top points to the request received
481 from the client.
482 req
484 Type: HTTP
485 Readable from: client
487 The entire request HTTP data structure. Mostly useful for passing
489 to VMODs.
490 req.method
492 Type: STRING
493 Readable from: client
495 Writable from: client
497 The request method (e.g. "GET", "HEAD", ...)
499 req.hash
501 Type: BLOB
502 Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver
504 The hash key of this request. Mostly useful for passing to VMODs,
506 but can also be useful for debugging hit/miss status.
507 req.url
509 Type: STRING
510 Readable from: client
512 Writable from: client
514 The requested URL, for instance "/robots.txt".
516 req.proto VCL <= 4.0
518 Type: STRING
519 Readable from: client
521 Writable from: client
523 The HTTP protocol version used by the client, usually "HTTP/1.1" or
525 "HTTP/2.0".
526 req.proto VCL >= 4.1
528 Type: STRING
529 Readable from: client
531 The HTTP protocol version used by the client, usually "HTTP/1.1" or
533 "HTTP/2.0".
534 req.http.*
536 Type: HEADER
537 Readable from: client
539 Writable from: client
541 Unsetable from: client
543 The headers of request, things like req.http.date.
545 The RFCs allow multiple headers with the same name, and both set and
547 unset will remove all headers with the name given.
548 req.restarts
550 Type: INT
551 Readable from: client
553 A count of how many times this request has been restarted.
555 req.storage
557 Type: STEVEDORE
558 Readable from: client
560 Writable from: client
562 The storage backend to use to save this request body.
564 req.esi_level
566 Type: INT
567 Readable from: client
569 A count of how many levels of ESI requests we're currently at.
571 req.ttl
573 Type: DURATION
574 Readable from: client
576 Writable from: client
578 Upper limit on the object age for cache lookups to return hit.
580 req.grace
582 Type: DURATION
583 Readable from: client
585 Writable from: client
587 Upper limit on the object grace.
589 During lookup the minimum of req.grace and the object's stored grace
591 value will be used as the object's grace.
592 req.xid
594 Type: STRING
595 Readable from: client
597 Unique ID of this request.
599 req.esi VCL <= 4.0
601 Type: BOOL
602 Readable from: client
604 Writable from: client
606 Set to false to disable ESI processing regardless of any value in
608 beresp.do_esi. Defaults to true. This variable is replaced by
609 resp.do_esi in VCL 4.1.
610 req.can_gzip
612 Type: BOOL
613 Readable from: client
615 True if the client provided gzip or x-gzip in the Accept-Encoding
617 header.
618 req.backend_hint
620 Type: BACKEND
621 Readable from: client
623 Writable from: client
625 Set bereq.backend to this if we attempt to fetch. When set to a
627 director, reading this variable returns an actual backend if the
628 director has resolved immediately, or the director otherwise. When
629 used in string context, returns the name of the director or backend,
630 respectively.
631 req.hash_ignore_busy
633 Type: BOOL
634 Readable from: client
636 Writable from: client
638 Default: false
640 Ignore any busy object during cache lookup.
642 You only want to do this when you have two server looking up content
644 sideways from each other to avoid deadlocks.
645 req.hash_always_miss
647 Type: BOOL
648 Readable from: client
650 Writable from: client
652 Default: false
654 Force a cache miss for this request, even if perfectly good matching
656 objects are in the cache.
657 This is useful to force-update the cache without invalidating exist‐
659 ing entries in case the fetch fails.
660 req.is_hitmiss
662 Type: BOOL
663 Readable from: client
665 If this request resulted in a hitmiss
667 req.is_hitpass
669 Type: BOOL
670 Readable from: client
672 If this request resulted in a hitpass
674 req_top.method
676 Type: STRING
677 Readable from: client
679 The request method of the top-level request in a tree of ESI
681 requests. (e.g. "GET", "HEAD"). Identical to req.method in non-ESI
682 requests.
683 req_top.url
685 Type: STRING
686 Readable from: client
688 The requested URL of the top-level request in a tree of ESI
690 requests. Identical to req.url in non-ESI requests.
691 req_top.http.*
693 Type: HEADER
694 Readable from: client
696 HTTP headers of the top-level request in a tree of ESI requests.
698 Identical to req.http. in non-ESI requests.
699 req_top.proto
701 Type: STRING
702 Readable from: client
704 HTTP protocol version of the top-level request in a tree of ESI
706 requests. Identical to req.proto in non-ESI requests.
707 bereq
709 This is the request we send to the backend, it is built from the
710 clients req.* fields by filtering out "per-hop" fields which should not
711 be passed along (Connection:, Range: and similar).
712 Slightly more fields are allowed through for pass fetches than for miss
714 fetches, for instance Range.
715 bereq
717 Type: HTTP
718 Readable from: backend
720 The entire backend request HTTP data structure. Mostly useful as
722 argument to VMODs.
723 bereq.xid
725 Type: STRING
726 Readable from: backend
728 Unique ID of this request.
730 bereq.retries
732 Type: INT
733 Readable from: backend
735 A count of how many times this request has been retried.
737 bereq.backend
739 Type: BACKEND
740 Readable from: vcl_pipe, backend
742 Writable from: vcl_pipe, backend
744 This is the backend or director we attempt to fetch from. When set
746 to a director, reading this variable returns an actual backend if
747 the director has resolved immediately, or the director otherwise.
748 When used in string context, returns the name of the director or
749 backend, respectively.
750 bereq.body
752 Type: BODY
753 Unsetable from: vcl_backend_fetch
755 The request body, only present on pass requests.
757 Unset will also remove bereq.http.Content-Length.
759 bereq.hash
761 Type: BLOB
762 Readable from: vcl_pipe, backend
764 The hash key of this request, a copy of req.hash.
766 bereq.method
768 Type: STRING
769 Readable from: vcl_pipe, backend
771 Writable from: vcl_pipe, backend
773 The request type (e.g. "GET", "HEAD").
775 Regular (non-pipe, non-pass) fetches are always "GET"
777 bereq.url
779 Type: STRING
780 Readable from: vcl_pipe, backend
782 Writable from: vcl_pipe, backend
784 The requested URL, copied from req.url
786 bereq.proto VCL <= 4.0
788 Type: STRING
789 Readable from: vcl_pipe, backend
791 Writable from: vcl_pipe, backend
793 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
795 has "HTTP/1.0" in req.proto
796 bereq.proto VCL >= 4.1
798 Type: STRING
799 Readable from: vcl_pipe, backend
801 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
803 has "HTTP/1.0" in req.proto
804 bereq.http.*
806 Type: HEADER
807 Readable from: vcl_pipe, backend
809 Writable from: vcl_pipe, backend
811 Unsetable from: vcl_pipe, backend
813 The headers to be sent to the backend.
815 bereq.uncacheable
817 Type: BOOL
818 Readable from: backend
820 Indicates whether this request is uncacheable due to a pass in the
822 client side or a hit on an hit-for-pass object.
823 bereq.connect_timeout
825 Type: DURATION
826 Readable from: vcl_pipe, backend
828 Writable from: vcl_pipe, backend
830 Default: .connect_timeout attribute from the backend_definition,
832 which defaults to the connect_timeout parameter, see varnishd(1)
833 The time in seconds to wait for a backend connection to be estab‐
835 lished.
836 bereq.first_byte_timeout
838 Type: DURATION
839 Readable from: backend
841 Writable from: backend
843 Default: .first_byte_timeout attribute from the backend_definition,
845 which defaults to the first_byte_timeout parameter, see varnishd(1)
846 The time in seconds to wait getting the first byte back from the
848 backend. Not available in pipe mode.
849 bereq.between_bytes_timeout
851 Type: DURATION
852 Readable from: backend
854 Writable from: backend
856 Default: .between_bytes_timeout attribute from the backend_defini‐
858 tion, which defaults to the between_bytes_timeout parameter, see
859 varnishd(1)
860 The time in seconds to wait between each received byte from the
862 backend. Not available in pipe mode.
863 bereq.is_bgfetch
865 Type: BOOL
866 Readable from: backend
868 True for fetches where the client got a hit on an object in grace,
870 and this fetch was kicked of in the background to get a fresh copy.
871 beresp
873 The response received from the backend, one cache misses, the store
874 object is built from beresp.
875 beresp
877 Type: HTTP
878 Readable from: vcl_backend_response, vcl_backend_error
880 The entire backend response HTTP data structure, useful as argument
882 to VMOD functions.
883 beresp.body
885 Type: BODY
886 Writable from: vcl_backend_error
888 For producing a synthetic body.
890 beresp.proto VCL <= 4.0
892 Type: STRING
893 Readable from: vcl_backend_response, vcl_backend_error
895 Writable from: vcl_backend_response, vcl_backend_error
897 The HTTP protocol version the backend replied with.
899 beresp.proto VCL >= 4.1
901 Type: STRING
902 Readable from: vcl_backend_response, vcl_backend_error
904 The HTTP protocol version the backend replied with.
906 beresp.status
908 Type: INT
909 Readable from: vcl_backend_response, vcl_backend_error
911 Writable from: vcl_backend_response, vcl_backend_error
913 The HTTP status code returned by the server.
915 Status codes on the form XXYZZ can be set where XXYZZ is less than
917 65536 and Y is [1...9]. Only YZZ will be sent back to clients.
918 XX can be therefore be used to pass information around inside VCL,
920 for instance return(synth(22404)) from vcl_recv{} to vcl_synth{}
921 beresp.reason
923 Type: STRING
924 Readable from: vcl_backend_response, vcl_backend_error
926 Writable from: vcl_backend_response, vcl_backend_error
928 The HTTP status message returned by the server.
930 beresp.http.*
932 Type: HEADER
933 Readable from: vcl_backend_response, vcl_backend_error
935 Writable from: vcl_backend_response, vcl_backend_error
937 Unsetable from: vcl_backend_response, vcl_backend_error
939 The HTTP headers returned from the server.
941 beresp.do_esi
943 Type: BOOL
944 Readable from: vcl_backend_response, vcl_backend_error
946 Writable from: vcl_backend_response, vcl_backend_error
948 Default: false
950 Set it to true to parse the object for ESI directives. Will only be
952 honored if req.esi is true.
953 beresp.do_stream
955 Type: BOOL
956 Readable from: vcl_backend_response, vcl_backend_error
958 Writable from: vcl_backend_response, vcl_backend_error
960 Default: true
962 Deliver the object to the client while fetching the whole object
964 into varnish.
965 For uncacheable objects, storage for parts of the body which have
967 been sent to the client may get freed early, depending on the stor‐
968 age engine used.
969 This variable has no effect if do_esi is true or when the response
971 body is empty.
972 beresp.do_gzip
974 Type: BOOL
975 Readable from: vcl_backend_response, vcl_backend_error
977 Writable from: vcl_backend_response, vcl_backend_error
979 Default: false
981 Set to true to gzip the object while storing it.
983 If http_gzip_support is disabled, setting this variable has no
985 effect.
986 beresp.do_gunzip
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 gunzip the object while storing it in the cache.
997 If http_gzip_support is disabled, setting this variable has no
999 effect.
1000 beresp.was_304
1002 Type: BOOL
1003 Readable from: vcl_backend_response, vcl_backend_error
1005 When true this indicates that we got a 304 response to our condi‐
1007 tional fetch from the backend and turned that into beresp.status =
1008 200
1009 beresp.uncacheable
1011 Type: BOOL
1012 Readable from: vcl_backend_response, vcl_backend_error
1014 Writable from: vcl_backend_response, vcl_backend_error
1016 Inherited from bereq.uncacheable, see there.
1018 Setting this variable makes the object uncacheable.
1020 This may may produce a hit-for-miss object in the cache.
1022 Clearing the variable has no effect and will log the warning "Ignor‐
1024 ing attempt to reset beresp.uncacheable".
1025 beresp.ttl
1027 Type: DURATION
1028 Readable from: vcl_backend_response, vcl_backend_error
1030 Writable from: vcl_backend_response, vcl_backend_error
1032 The object's remaining time to live, in seconds.
1034 beresp.age
1036 Type: DURATION
1037 Readable from: vcl_backend_response, vcl_backend_error
1039 The age of the object.
1041 beresp.grace
1043 Type: DURATION
1044 Readable from: vcl_backend_response, vcl_backend_error
1046 Writable from: vcl_backend_response, vcl_backend_error
1048 Set to a period to enable grace.
1050 beresp.keep
1052 Type: DURATION
1053 Readable from: vcl_backend_response, vcl_backend_error
1055 Writable from: vcl_backend_response, vcl_backend_error
1057 Set to a period to enable conditional backend requests.
1059 The keep time is cache lifetime in addition to the ttl.
1061 Objects with ttl expired but with keep time left may be used to
1063 issue conditional (If-Modified-Since / If-None-Match) requests to
1064 the backend to refresh them.
1065 beresp.backend
1067 Type: BACKEND
1068 Readable from: vcl_backend_response, vcl_backend_error
1070 This is the backend we fetched from. If bereq.backend was set to a
1072 director, this will be the backend selected by the director. When
1073 used in string context, returns its name.
1074 beresp.backend.name
1076 Type: STRING
1077 Readable from: vcl_backend_response, vcl_backend_error
1079 Name of the backend this response was fetched from. Same as
1081 beresp.backend.
1082 beresp.backend.ip VCL <= 4.0
1084 Type: IP
1085 Readable from: vcl_backend_response
1087 IP of the backend this response was fetched from.
1089 beresp.storage
1091 Type: STEVEDORE
1092 Readable from: vcl_backend_response, vcl_backend_error
1094 Writable from: vcl_backend_response, vcl_backend_error
1096 The storage backend to use to save this object.
1098 beresp.storage_hint VCL <= 4.0
1100 Type: STRING
1101 Readable from: vcl_backend_response, vcl_backend_error
1103 Writable from: vcl_backend_response, vcl_backend_error
1105 Deprecated since varnish 5.1 and discontinued since VCL 4.1 (varnish
1107 6.0). Use beresp.storage instead.
1108 Hint to Varnish that you want to save this object to a particular
1110 storage backend.
1111 obj
1113 This is the object we found in cache. It cannot be modified.
1114 obj.proto
1116 Type: STRING
1117 Readable from: vcl_hit
1119 The HTTP protocol version stored in the object.
1121 obj.status
1123 Type: INT
1124 Readable from: vcl_hit
1126 The HTTP status code stored in the object.
1128 obj.reason
1130 Type: STRING
1131 Readable from: vcl_hit
1133 The HTTP reason phrase stored in the object.
1135 obj.hits
1137 Type: INT
1138 Readable from: vcl_hit, vcl_deliver
1140 The count of cache-hits on this object.
1142 In vcl_deliver a value of 0 indicates a cache miss.
1144 obj.http.*
1146 Type: HEADER
1147 Readable from: vcl_hit
1149 The HTTP headers stored in the object.
1151 obj.ttl
1153 Type: DURATION
1154 Readable from: vcl_hit, vcl_deliver
1156 The object's remaining time to live, in seconds.
1158 obj.age
1160 Type: DURATION
1161 Readable from: vcl_hit, vcl_deliver
1163 The age of the object.
1165 obj.grace
1167 Type: DURATION
1168 Readable from: vcl_hit, vcl_deliver
1170 The object's grace period in seconds.
1172 obj.keep
1174 Type: DURATION
1175 Readable from: vcl_hit, vcl_deliver
1177 The object's keep period in seconds.
1179 obj.uncacheable
1181 Type: BOOL
1182 Readable from: vcl_deliver
1184 Whether the object is uncacheable (pass, hit-for-pass or
1186 hit-for-miss).
1187 obj.storage
1189 Type: STEVEDORE
1190 Readable from: vcl_hit, vcl_deliver
1192 The storage backend where this object is stored.
1194 resp
1196 This is the response we send to the client, it is built from either
1197 beresp (pass/miss), obj (hits) or created from whole cloth (synth).
1198 With the exception of resp.body all resp.* variables available in both
1200 vcl_deliver{} and vcl_synth{} as a matter of symmetry.
1201 resp
1203 Type: HTTP
1204 Readable from: vcl_deliver, vcl_synth
1206 The entire response HTTP data structure, useful as argument to
1208 VMODs.
1209 resp.body
1211 Type: BODY
1212 Writable from: vcl_synth
1214 To produce a synthetic response body, for instance for errors.
1216 resp.proto VCL <= 4.0
1218 Type: STRING
1219 Readable from: vcl_deliver, vcl_synth
1221 Writable from: vcl_deliver, vcl_synth
1223 The HTTP protocol version to use for the response.
1225 resp.proto VCL >= 4.1
1227 Type: STRING
1228 Readable from: vcl_deliver, vcl_synth
1230 Writable from: vcl_deliver, vcl_synth
1232 The HTTP protocol version to use for the response.
1234 resp.status
1236 Type: INT
1237 Readable from: vcl_deliver, vcl_synth
1239 Writable from: vcl_deliver, vcl_synth
1241 The HTTP status code that will be returned.
1243 Assigning a HTTP standardized code to resp.status will also set
1245 resp.reason to the corresponding status message.
1246 resp.status 200 will get changed into 304 by core code after a
1248 return(deliver) from vcl_deliver for conditional requests to cached
1249 content if validation succeeds.
1250 resp.reason
1252 Type: STRING
1253 Readable from: vcl_deliver, vcl_synth
1255 Writable from: vcl_deliver, vcl_synth
1257 The HTTP status message that will be returned.
1259 resp.http.*
1261 Type: HEADER
1262 Readable from: vcl_deliver, vcl_synth
1264 Writable from: vcl_deliver, vcl_synth
1266 Unsetable from: vcl_deliver, vcl_synth
1268 The HTTP headers that will be returned.
1270 resp.do_esi VCL >= 4.1
1272 Type: BOOL
1273 Readable from: vcl_deliver, vcl_synth
1275 Writable from: vcl_deliver, vcl_synth
1277 Default: Set if ESI parsing has happened.
1279 This can be used to selectively disable ESI processing, even though
1281 ESI parsing happened during fetch. This is useful when Varnish
1282 caches peer with each other.
1283 resp.is_streaming
1285 Type: BOOL
1286 Readable from: vcl_deliver, vcl_synth
1288 Returns true when the response will be streamed while being fetched
1290 from the backend.
1291 Special variables
1293 now
1294 Type: TIME
1295 Readable from: all
1297 The current time, in seconds since the UNIX epoch.
1299 When converted to STRING in expressions it returns a formatted time‐
1301 stamp like Tue, 20 Feb 2018 09:30:31 GMT
1302 sess
1304 A session corresponds to the "conversation" that Varnish has with a
1305 single client connection, over which one or more request/response
1306 transactions may take place. It may comprise the traffic over an HTTP/1
1307 keep-alive connection, or the multiplexed traffic over an HTTP/2 con‐
1308 nection.
1309 sess.xid VCL >= 4.1
1311 Type: STRING
1312 Readable from: client, backend
1314 Unique ID of this session.
1316 storage
1318 storage.<name>.free_space
1319 Type: BYTES
1320 Readable from: client, backend
1322 Free space available in the named stevedore. Only available for the
1324 malloc stevedore.
1325 storage.<name>.used_space
1327 Type: BYTES
1328 Readable from: client, backend
1330 Used space in the named stevedore. Only available for the malloc
1332 stevedore.
1333 storage.<name>.happy
1335 Type: BOOL
1336 Readable from: client, backend
1338 Health status for the named stevedore. Not available in any of the
1340 current stevedores.
1341 Functions
1343 The following built-in functions are available:
1344 ban(STRING)
1346 Invalidates all objects in cache that match the given expression
1347 with the ban mechanism.
1348 The format of STRING is:
1350 <field> <operator> <arg> [&& <field> <oper> <arg> ...]
1352 · <field>:
1354 · req.url: The request url
1356 · req.http.*: Any request header
1358 · obj.status: The cache object status
1360 · obj.http.*: Any cache object header
1362 · <operator>:
1364 · ==: <field> and <arg> are equal strings (case sensitive)
1366 · !=: <field> and <arg> are unequal strings (case sensitive)
1368 · ~: <field> matches the regular expression <arg>
1370 · !~:<field> does not match the regular expression <arg>
1372 · <arg>: Either a literal string or a regular expression. Note that
1374 <arg> does not use any of the string delimiters like " or {"..."}
1375 used elsewhere in varnish. To match against strings containing
1376 whitespace, regular expressions containing \s can be used.
1377 Expressions can be chained using the and operator &&. For or seman‐
1379 tics, use several bans.
1380 The unset <field> is not equal to any string, such that, for a
1382 non-existing header, the operators == and ~ always evaluate as
1383 false, while the operators != and !~ always evaluate as true,
1384 respectively, for any value of <arg>.
1385 hash_data(input)
1387 Adds an input to the hash input. In the built-in VCL hash_data() is
1388 called on the host and URL of the request. Available in vcl_hash.
1389 synthetic(STRING)
1391 Prepare a synthetic response body containing the STRING. Available
1392 in vcl_synth and vcl_backend_error.
1393 Identical to set resp.body / set beresp.body.
1395 regsub(str, regex, sub)
1397 Returns a copy of str with the first occurrence of the regular
1398 expression regex replaced with sub. Within sub, \0 (which can also
1399 be spelled \&) is replaced with the entire matched string, and \n is
1400 replaced with the contents of subgroup n in the matched string.
1401 regsuball(str, regex, sub)
1403 As regsub(), but this replaces all occurrences.
1404 For converting or casting VCL values between data types use the func‐
1406 tions available in the std VMOD.
1407
1409 Multiple versions of the VCL syntax can coexist within certain con‐
1410 straints.
1411 The VCL syntax version at the start of VCL file specified with -f sets
1413 the hard limit that cannot be exceeded anywhere, and it selects the
1414 appropriate version of the builtin VCL.
1415 That means that you can never include vcl 9.1; from vcl 8.7;, but the
1417 opposite may be possible, to the extent the compiler supports it.
1418 Files pulled in via include do not need to have a vcl X.Y; but it may
1420 be a good idea to do it anyway, to not have surprises in the future.
1421 The syntax version set in an included file only applies to that file
1422 and any files it includes - unless these set their own VCL syntax ver‐
1423 sion.
1424 The version of Varnish this file belongs to supports syntax 4.0 only.
1426
1428 For examples, please see the online documentation.
1429
1431 · varnishd(1)
1432 · vmod_directors(3)
1434 · vmod_std(3)
1436
1438 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
1439 AS, Redpill Linpro and Varnish Software. This manual page is written
1440 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
1441 gstøl, Lasse Karstensen and possibly others.
1442
1444 This document is licensed under the same license as Varnish itself. See
1445 LICENSE for details.
1446 · Copyright (c) 2006 Verdens Gang AS
1448 · Copyright (c) 2006-2015 Varnish Software AS
1450 VCL(7)