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 empty; 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 Integers
97 Certain fields are integers, used as expected. In string context they
98 return a string.
99 Real numbers
101 VCL understands real numbers. As with integers, when used in a string
102 context they will return a string.
103 Regular Expressions
105 Varnish uses Perl-compatible regular expressions (PCRE). For a complete
106 description please see the pcre(3) man page.
107 To send flags to the PCRE engine, such as to do case insensitive match‐
109 ing, add the flag within parens following a question mark, like this:
110 # If host is NOT example dot com..
112 if (req.http.host !~ "(?i)example\.com$") {
113 ...
114 }
115 Include statement
117 To include a VCL file in another file use the include keyword:
118 include "foo.vcl";
120 Import statement
122 The import statement is used to load Varnish Modules (VMODs.)
123 Example:
125 import std;
127 sub vcl_recv {
128 std.log("foo");
129 }
130 Comments
132 Single lines of VCL can be commented out using // or #. Multi-line
133 blocks can be commented out with /*block*/.
134 Example:
136 sub vcl_recv {
138 // Single line of out-commented VCL.
139 # Another way of commenting out a single line.
140 /*
141 Multi-line block of commented-out VCL.
142 */
143 }
144 Backend definition
146 A backend declaration creates and initialises a named backend object. A
147 declaration start with the keyword backend followed by the name of the
148 backend. The actual declaration is in curly brackets, in a key/value
149 fashion.:
150 backend name {
152 .attribute = "value";
153 }
154 One of the attributes .host or .path is mandatory (but not both). The
156 attributes will inherit their defaults from the global parameters. The
157 following attributes are available:
158 .host The host to be used. IP address or a hostname that resolves
160 to a single IP address. This attribute is mandatory, unless
161 .path is declared.
162 .path (VCL >= 4.1)
164 The absolute path of a Unix domain socket at which a backend
165 is listening. The file at that path must exist and must be
166 accessible to Varnish at VCL load time, and it must be a
167 socket. One of .path or .host must be declared (but not
168 both). .path may only be used in VCL since version 4.1.
169 .port The port on the backend that Varnish should connect to.
171 Ignored if a Unix domain socket is declared in .path.
172 .host_header
174 A host header to add to probes and regular backend requests
175 if they have no such header.
176 .connect_timeout
178 Timeout for connections.
179 Default: connect_timeout parameter, see varnishd(1)
181 .first_byte_timeout
183 Timeout for first byte.
184 Default: first_byte_timeout parameter, see varnishd(1)
186 .between_bytes_timeout
188 Timeout between bytes.
189 Default: between_bytes_timeout parameter, see varnishd(1)
191 .probe Attach a probe to the backend. See Probes
193 .proxy_header
195 The PROXY protocol version Varnish should use when connecting
196 to this backend. Allowed values are 1 and 2.
197 Notice this setting will lead to backend connections being
199 used for a single request only (subject to future improve‐
200 ments). Thus, extra care should be taken to avoid running
201 into failing backend connections with EADDRNOTAVAIL due to no
202 local ports being available. Possible options are:
203 · Use additional backend connections to extra IP addresses or
205 TCP ports
206 · Increase the number of available ports (Linux sysctl
208 net.ipv4.ip_local_port_range)
209 · Reuse backend connection ports early (Linux sysctl
211 net.ipv4.tcp_tw_reuse)
212 .max_connections
214 Maximum number of open connections towards this backend. If
215 Varnish reaches the maximum Varnish it will start failing
216 connections.
217 Backends can be used with directors. Please see the vmod_directors(3)
219 man page for more information.
220 Probes
222 Probes will query the backend for status on a regular basis and mark
223 the backend as down it they fail. A probe is defined as this:
224 probe name {
226 .attribute = "value";
227 }
228 The probe named default is special and will be used for all backends
230 which do not explicitly reference a probe.
231 There are no mandatory options. These are the options you can set:
233 .url The URL to query. Defaults to /. Mutually exclusive with
235 .request
236 .request
238 Specify a full HTTP request using multiple strings. .request
239 will have \r\n automatically inserted after every string.
240 Mutually exclusive with .url.
241 Note that probes require the backend to complete sending the
243 response and close the connection within the specified time‐
244 out, so .request will, for HTTP/1.1, most likely need to con‐
245 tain a "Connection: close" string.
246 .expected_response
248 The expected HTTP response code. Defaults to 200.
249 .timeout
251 The timeout for the probe. Default is 2s.
252 .interval
254 How often the probe is run. Default is 5s.
255 .initial
257 How many of the polls in .window are considered good when
258 Varnish starts. Defaults to the value of .threshold - 1. In
259 this case, the backend starts as sick and requires one single
260 poll to be considered healthy.
261 .window
263 How many of the latest polls we examine to determine backend
264 health. Defaults to 8.
265 .threshold
267 How many of the polls in .window must have succeeded to con‐
268 sider the backend to be healthy. Defaults to 3.
269 Access Control List (ACL)
271 An Access Control List (ACL) declaration creates and initialises a
272 named access control list which can later be used to match client
273 addresses:
274 acl localnetwork {
276 "localhost"; # myself
277 "192.0.2.0"/24; # and everyone on the local network
278 ! "192.0.2.23"; # except for the dial-in router
279 }
280 If an ACL entry specifies a host name which Varnish is unable to
282 resolve, it will match any address it is compared to. Consequently, if
283 it is preceded by a negation mark, it will reject any address it is
284 compared to, which may not be what you intended. If the entry is
285 enclosed in parentheses, however, it will simply be ignored.
286 To match an IP address against an ACL, simply use the match operator:
288 if (client.ip ~ localnetwork) {
290 return (pipe);
291 }
292 VCL objects
294 A VCL object can be instantiated with the new keyword:
295 sub vcl_init {
297 new b = directors.round_robin()
298 b.add_backend(node1);
299 }
300 This is only available in vcl_init.
302 Subroutines
304 A subroutine is used to group code for legibility or reusability:
305 sub pipe_if_local {
307 if (client.ip ~ localnetwork) {
308 return (pipe);
309 }
310 }
311 Subroutines in VCL do not take arguments, nor do they return values.
313 The built in subroutines all have names beginning with vcl_, which is
314 reserved.
315 To call a subroutine, use the call keyword followed by the subroutine's
317 name:
318 sub vcl_recv {
320 call pipe_if_local;
321 }
322 Return statements
324 The ongoing vcl_* subroutine execution ends when a return(<action>)
325 statement is made.
326 The <action> specifies how execution should proceed. The context
328 defines which actions are available.
329 Multiple subroutines
331 If multiple subroutines with the name of one of the built-in ones are
332 defined, they are concatenated in the order in which they appear in the
333 source.
334 The built-in VCL distributed with Varnish will be implicitly concate‐
336 nated when the VCL is compiled.
337 VCL Variables
339 Variables provide read, write and delete access to almost all aspects
340 of the work at hand.
341 Reading a variable is done simply by using its name in VCL:
343 if (client.ip ~ bad_guys) {
345 return (synth(400));
346 }
347 Writing a variable, where this is possible, is done with a set state‐
349 ment:
350 set resp.http.never = "Let You Down";
352 Similarly, deleting a variable, for the few variables where this is
354 possible, is done with a unset statement:
355 unset req.http.cookie;
357 Which operations are possible on each variable is described below,
359 often with the shorthand "backend" which covers the vcl_backend_* meth‐
360 ods and "client" which covers the rest, except vcl_init and vcl_fini.
361 When setting a variable, the right hand side of the equal sign must
363 have the variables type, you cannot assign a STRING to a variable of
364 type NUMBER, even if the string is "42". (Explicit conversion func‐
365 tions can be found in vmod_std(3)).
366 local, server, remote and client
368 These variables describe the network connection between the client and
369 varnishd.
370 Without PROXY protocol:
372 client server
374 remote local
375 v v
376 CLIENT ------------ VARNISHD
377 With PROXY protocol:
379 client server remote local
381 v v v v
382 CLIENT ------------ PROXY ------------ VARNISHD
383 local.ip
385 Type: IP
386 Readable from: client, backend
388 The IP address (and port number) of the local end of the TCP connec‐
390 tion, for instance 192.168.1.1:81
391 If the connection is a UNIX domain socket, the value will be
393 0.0.0.0:0
394 local.endpoint VCL >= 4.1
396 Type: STRING
397 Readable from: client, backend
399 The address of the '-a' socket the session was accepted on.
401 If the argument was -a foo=:81 this would be ":81"
403 local.socket VCL >= 4.1
405 Type: STRING
406 Readable from: client, backend
408 The name of the '-a' socket the session was accepted on.
410 If the argument was -a foo=:81 this would be "foo".
412 Note that all '-a' gets a default name on the form a%d if no name is
414 provided.
415 remote.ip
417 Type: IP
418 Readable from: client, backend
420 The IP address of the other end of the TCP connection. This can
422 either be the clients IP, or the outgoing IP of a proxy server.
423 If the connection is a UNIX domain socket, the value will be
425 0.0.0.0:0
426 client.ip
428 Type: IP
429 Readable from: client, backend
431 The client's IP address, either the same as local.ip or what the
433 PROXY protocol told us.
434 client.identity
436 Type: STRING
437 Readable from: client
439 Writable from: client
441 Identification of the client, used to load balance in the client
443 director. Defaults to client.ip
444 This variable can be overwritten with more precise information, for
446 instance extracted from a Cookie: header.
447 server.ip
449 Type: IP
450 Readable from: client, backend
452 The IP address of the socket on which the client connection was
454 received, either the same as server.ip or what the PROXY protocol
455 told us.
456 server.hostname
458 Type: STRING
459 Readable from: all
461 The host name of the server, as returned by the gethostname(3) sys‐
463 tem function.
464 server.identity
466 Type: STRING
467 Readable from: all
469 The identity of the server, as set by the -i parameter.
471 If an -i parameter is not passed to varnishd, the return value from
473 gethostname(3) system function will be used.
474 req and req_top
476 These variables describe the present request, and when ESI:include
477 requests are being processed, req_top points to the request received
478 from the client.
479 req
481 Type: HTTP
482 Readable from: client
484 The entire request HTTP data structure. Mostly useful for passing
486 to VMODs.
487 req.method
489 Type: STRING
490 Readable from: client
492 Writable from: client
494 The request method (e.g. "GET", "HEAD", ...)
496 req.hash
498 Type: BLOB
499 Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver
501 The hash key of this request. Mostly useful for passing to VMODs,
503 but can also be useful for debugging hit/miss status.
504 req.url
506 Type: STRING
507 Readable from: client
509 Writable from: client
511 The requested URL, for instance "/robots.txt".
513 req.proto VCL <= 4.0
515 Type: STRING
516 Readable from: client
518 Writable from: client
520 The HTTP protocol version used by the client, usually "HTTP/1.1" or
522 "HTTP/2.0".
523 req.proto VCL >= 4.1
525 Type: STRING
526 Readable from: client
528 The HTTP protocol version used by the client, usually "HTTP/1.1" or
530 "HTTP/2.0".
531 req.http.*
533 Type: HEADER
534 Readable from: client
536 Writable from: client
538 Unsetable from: client
540 The headers of request, things like req.http.date.
542 The RFCs allow multiple headers with the same name, and both set and
544 unset will remove all headers with the name given.
545 req.restarts
547 Type: INT
548 Readable from: client
550 A count of how many times this request has been restarted.
552 req.storage
554 Type: STEVEDORE
555 Readable from: client
557 Writable from: client
559 The storage backend to use to save this request body.
561 req.esi_level
563 Type: INT
564 Readable from: client
566 A count of how many levels of ESI requests we're currently at.
568 req.ttl
570 Type: DURATION
571 Readable from: client
573 Writable from: client
575 Upper limit on the object age for cache lookups to return hit.
577 req.grace
579 Type: DURATION
580 Readable from: client
582 Writable from: client
584 Upper limit on the object grace.
586 During lookup the minimum of req.grace and the object's stored grace
588 value will be used as the object's grace.
589 req.xid
591 Type: STRING
592 Readable from: client
594 Unique ID of this request.
596 req.esi VCL <= 4.0
598 Type: BOOL
599 Readable from: client
601 Writable from: client
603 Set to false to disable ESI processing regardless of any value in
605 beresp.do_esi. Defaults to true. This variable is replaced by
606 resp.do_esi in VCL 4.1.
607 req.can_gzip
609 Type: BOOL
610 Readable from: client
612 True if the client provided gzip or x-gzip in the Accept-Encoding
614 header.
615 req.backend_hint
617 Type: BACKEND
618 Readable from: client
620 Writable from: client
622 Set bereq.backend to this if we attempt to fetch. When set to a
624 director, reading this variable returns an actual backend if the
625 director has resolved immediately, or the director otherwise. When
626 used in string context, returns the name of the director or backend,
627 respectively.
628 req.hash_ignore_busy
630 Type: BOOL
631 Readable from: client
633 Writable from: client
635 Default: false
637 Ignore any busy object during cache lookup.
639 You only want to do this when you have two server looking up content
641 sideways from each other to avoid deadlocks.
642 req.hash_always_miss
644 Type: BOOL
645 Readable from: client
647 Writable from: client
649 Default: false
651 Force a cache miss for this request, even if perfectly good matching
653 objects are in the cache.
654 This is useful to force-update the cache without invalidating exist‐
656 ing entries in case the fetch fails.
657 req_top.method
659 Type: STRING
660 Readable from: client
662 The request method of the top-level request in a tree of ESI
664 requests. (e.g. "GET", "HEAD"). Identical to req.method in non-ESI
665 requests.
666 req_top.url
668 Type: STRING
669 Readable from: client
671 The requested URL of the top-level request in a tree of ESI
673 requests. Identical to req.url in non-ESI requests.
674 req_top.http.*
676 Type: HEADER
677 Readable from: client
679 HTTP headers of the top-level request in a tree of ESI requests.
681 Identical to req.http. in non-ESI requests.
682 req_top.proto
684 Type: STRING
685 Readable from: client
687 HTTP protocol version of the top-level request in a tree of ESI
689 requests. Identical to req.proto in non-ESI requests.
690 bereq
692 This is the request we send to the backend, it is built from the
693 clients req.* fields by filtering out "per-hop" fields which should not
694 be passed along (Connection:, Range: and similar).
695 Slightly more fields are allowed through for pass fetches than for miss
697 fetches, for instance Range.
698 bereq
700 Type: HTTP
701 Readable from: backend
703 The entire backend request HTTP data structure. Mostly useful as
705 argument to VMODs.
706 bereq.xid
708 Type: STRING
709 Readable from: backend
711 Unique ID of this request.
713 bereq.retries
715 Type: INT
716 Readable from: backend
718 A count of how many times this request has been retried.
720 bereq.backend
722 Type: BACKEND
723 Readable from: vcl_pipe, backend
725 Writable from: vcl_pipe, backend
727 This is the backend or director we attempt to fetch from. When set
729 to a director, reading this variable returns an actual backend if
730 the director has resolved immediately, or the director otherwise.
731 When used in string context, returns the name of the director or
732 backend, respectively.
733 bereq.body
735 Type: BODY
736 Unsetable from: vcl_backend_fetch
738 The request body, only present on pass requests.
740 Unset will also remove bereq.http.Content-Length.
742 bereq.hash
744 Type: BLOB
745 Readable from: vcl_pipe, backend
747 The hash key of this request, a copy of req.hash.
749 bereq.method
751 Type: STRING
752 Readable from: vcl_pipe, backend
754 Writable from: vcl_pipe, backend
756 The request type (e.g. "GET", "HEAD").
758 Regular (non-pipe, non-pass) fetches are always "GET"
760 bereq.url
762 Type: STRING
763 Readable from: vcl_pipe, backend
765 Writable from: vcl_pipe, backend
767 The requested URL, copied from req.url
769 bereq.proto VCL <= 4.0
771 Type: STRING
772 Readable from: vcl_pipe, backend
774 Writable from: vcl_pipe, backend
776 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
778 has "HTTP/1.0" in req.proto
779 bereq.proto VCL >= 4.1
781 Type: STRING
782 Readable from: vcl_pipe, backend
784 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
786 has "HTTP/1.0" in req.proto
787 bereq.http.*
789 Type: HEADER
790 Readable from: vcl_pipe, backend
792 Writable from: vcl_pipe, backend
794 Unsetable from: vcl_pipe, backend
796 The headers to be sent to the backend.
798 bereq.uncacheable
800 Type: BOOL
801 Readable from: backend
803 Indicates whether this request is uncacheable due to a pass in the
805 client side or a hit on an hit-for-pass object.
806 bereq.connect_timeout
808 Type: DURATION
809 Readable from: vcl_pipe, backend
811 Writable from: vcl_pipe, backend
813 Default: .connect_timeout attribute from the backend_definition,
815 which defaults to the connect_timeout parameter, see varnishd(1)
816 The time in seconds to wait for a backend connection to be estab‐
818 lished.
819 bereq.first_byte_timeout
821 Type: DURATION
822 Readable from: backend
824 Writable from: backend
826 Default: .first_byte_timeout attribute from the backend_definition,
828 which defaults to the first_byte_timeout parameter, see varnishd(1)
829 The time in seconds to wait getting the first byte back from the
831 backend. Not available in pipe mode.
832 bereq.between_bytes_timeout
834 Type: DURATION
835 Readable from: backend
837 Writable from: backend
839 Default: .between_bytes_timeout attribute from the backend_defini‐
841 tion, which defaults to the between_bytes_timeout parameter, see
842 varnishd(1)
843 The time in seconds to wait between each received byte from the
845 backend. Not available in pipe mode.
846 bereq.is_bgfetch
848 Type: BOOL
849 Readable from: backend
851 True for fetches where the client got a hit on an object in grace,
853 and this fetch was kicked of in the background to get a fresh copy.
854 beresp
856 The response received from the backend, one cache misses, the store
857 object is built from beresp.
858 beresp
860 Type: HTTP
861 Readable from: vcl_backend_response, vcl_backend_error
863 The entire backend response HTTP data structure, useful as argument
865 to VMOD functions.
866 beresp.body
868 Type: BODY
869 Writable from: vcl_backend_error
871 For producing a synthetic body.
873 beresp.proto VCL <= 4.0
875 Type: STRING
876 Readable from: vcl_backend_response, vcl_backend_error
878 Writable from: vcl_backend_response, vcl_backend_error
880 The HTTP protocol version the backend replied with.
882 beresp.proto VCL >= 4.1
884 Type: STRING
885 Readable from: vcl_backend_response, vcl_backend_error
887 The HTTP protocol version the backend replied with.
889 beresp.status
891 Type: INT
892 Readable from: vcl_backend_response, vcl_backend_error
894 Writable from: vcl_backend_response, vcl_backend_error
896 The HTTP status code returned by the server.
898 Status codes on the form XXYZZ can be set where XXYZZ is less than
900 65536 and Y is [1...9]. Only YZZ will be sent back to clients.
901 XX can be therefore be used to pass information around inside VCL,
903 for instance return(synth(22404)) from vcl_recv{} to vcl_synth{}
904 beresp.reason
906 Type: STRING
907 Readable from: vcl_backend_response, vcl_backend_error
909 Writable from: vcl_backend_response, vcl_backend_error
911 The HTTP status message returned by the server.
913 beresp.http.*
915 Type: HEADER
916 Readable from: vcl_backend_response, vcl_backend_error
918 Writable from: vcl_backend_response, vcl_backend_error
920 Unsetable from: vcl_backend_response, vcl_backend_error
922 The HTTP headers returned from the server.
924 beresp.do_esi
926 Type: BOOL
927 Readable from: vcl_backend_response, vcl_backend_error
929 Writable from: vcl_backend_response, vcl_backend_error
931 Default: false
933 Set it to true to parse the object for ESI directives. Will only be
935 honored if req.esi is true.
936 beresp.do_stream
938 Type: BOOL
939 Readable from: vcl_backend_response, vcl_backend_error
941 Writable from: vcl_backend_response, vcl_backend_error
943 Default: true
945 Deliver the object to the client while fetching the whole object
947 into varnish.
948 For uncacheable objects, storage for parts of the body which have
950 been sent to the client may get freed early, depending on the stor‐
951 age engine used.
952 This variable has no effect if do_esi is true or when the response
954 body is empty.
955 beresp.do_gzip
957 Type: BOOL
958 Readable from: vcl_backend_response, vcl_backend_error
960 Writable from: vcl_backend_response, vcl_backend_error
962 Default: false
964 Set to true to gzip the object while storing it.
966 If http_gzip_support is disabled, setting this variable has no
968 effect.
969 beresp.do_gunzip
971 Type: BOOL
972 Readable from: vcl_backend_response, vcl_backend_error
974 Writable from: vcl_backend_response, vcl_backend_error
976 Default: false
978 Set to true to gunzip the object while storing it in the cache.
980 If http_gzip_support is disabled, setting this variable has no
982 effect.
983 beresp.was_304
985 Type: BOOL
986 Readable from: vcl_backend_response, vcl_backend_error
988 When true this indicates that we got a 304 response to our condi‐
990 tional fetch from the backend and turned that into beresp.status =
991 200
992 beresp.uncacheable
994 Type: BOOL
995 Readable from: vcl_backend_response, vcl_backend_error
997 Writable from: vcl_backend_response, vcl_backend_error
999 Inherited from bereq.uncacheable, see there.
1001 Setting this variable makes the object uncacheable.
1003 This may may produce a hit-for-miss object in the cache.
1005 Clearing the variable has no effect and will log the warning "Ignor‐
1007 ing attempt to reset beresp.uncacheable".
1008 beresp.ttl
1010 Type: DURATION
1011 Readable from: vcl_backend_response, vcl_backend_error
1013 Writable from: vcl_backend_response, vcl_backend_error
1015 The object's remaining time to live, in seconds.
1017 beresp.age
1019 Type: DURATION
1020 Readable from: vcl_backend_response, vcl_backend_error
1022 The age of the object.
1024 beresp.grace
1026 Type: DURATION
1027 Readable from: vcl_backend_response, vcl_backend_error
1029 Writable from: vcl_backend_response, vcl_backend_error
1031 Set to a period to enable grace.
1033 beresp.keep
1035 Type: DURATION
1036 Readable from: vcl_backend_response, vcl_backend_error
1038 Writable from: vcl_backend_response, vcl_backend_error
1040 Set to a period to enable conditional backend requests.
1042 The keep time is cache lifetime in addition to the ttl.
1044 Objects with ttl expired but with keep time left may be used to
1046 issue conditional (If-Modified-Since / If-None-Match) requests to
1047 the backend to refresh them.
1048 beresp.backend
1050 Type: BACKEND
1051 Readable from: vcl_backend_response, vcl_backend_error
1053 This is the backend we fetched from. If bereq.backend was set to a
1055 director, this will be the backend selected by the director. When
1056 used in string context, returns its name.
1057 beresp.backend.name
1059 Type: STRING
1060 Readable from: vcl_backend_response, vcl_backend_error
1062 Name of the backend this response was fetched from. Same as
1064 beresp.backend.
1065 beresp.backend.ip VCL <= 4.0
1067 Type: IP
1068 Readable from: vcl_backend_response
1070 IP of the backend this response was fetched from.
1072 beresp.storage
1074 Type: STEVEDORE
1075 Readable from: vcl_backend_response, vcl_backend_error
1077 Writable from: vcl_backend_response, vcl_backend_error
1079 The storage backend to use to save this object.
1081 beresp.storage_hint VCL <= 4.0
1083 Type: STRING
1084 Readable from: vcl_backend_response, vcl_backend_error
1086 Writable from: vcl_backend_response, vcl_backend_error
1088 Deprecated since varnish 5.1 and discontinued since VCL 4.1 (varnish
1090 6.0). Use beresp.storage instead.
1091 Hint to Varnish that you want to save this object to a particular
1093 storage backend.
1094 beresp.filters
1096 Type: STRING
1097 Readable from: vcl_backend_response
1099 Writable from: vcl_backend_response
1101 List of VFP filters the beresp.body will be pulled through.
1103 obj
1105 This is the object we found in cache. It cannot be modified.
1106 obj.proto
1108 Type: STRING
1109 Readable from: vcl_hit
1111 The HTTP protocol version stored in the object.
1113 obj.status
1115 Type: INT
1116 Readable from: vcl_hit
1118 The HTTP status code stored in the object.
1120 obj.reason
1122 Type: STRING
1123 Readable from: vcl_hit
1125 The HTTP reason phrase stored in the object.
1127 obj.hits
1129 Type: INT
1130 Readable from: vcl_hit, vcl_deliver
1132 The count of cache-hits on this object.
1134 In vcl_deliver a value of 0 indicates a cache miss.
1136 obj.http.*
1138 Type: HEADER
1139 Readable from: vcl_hit
1141 The HTTP headers stored in the object.
1143 obj.ttl
1145 Type: DURATION
1146 Readable from: vcl_hit, vcl_deliver
1148 The object's remaining time to live, in seconds.
1150 obj.age
1152 Type: DURATION
1153 Readable from: vcl_hit, vcl_deliver
1155 The age of the object.
1157 obj.grace
1159 Type: DURATION
1160 Readable from: vcl_hit, vcl_deliver
1162 The object's grace period in seconds.
1164 obj.keep
1166 Type: DURATION
1167 Readable from: vcl_hit, vcl_deliver
1169 The object's keep period in seconds.
1171 obj.uncacheable
1173 Type: BOOL
1174 Readable from: vcl_deliver
1176 Whether the object is uncacheable (pass, hit-for-pass or
1178 hit-for-miss).
1179 obj.storage
1181 Type: STEVEDORE
1182 Readable from: vcl_hit, vcl_deliver
1184 The storage backend where this object is stored.
1186 resp
1188 This is the response we send to the client, it is built from either
1189 beresp (pass/miss), obj (hits) or created from whole cloth (synth).
1190 With the exception of resp.body all resp.* variables available in both
1192 vcl_deliver{} and vcl_synth{} as a matter of symmetry.
1193 resp
1195 Type: HTTP
1196 Readable from: vcl_deliver, vcl_synth
1198 The entire response HTTP data structure, useful as argument to
1200 VMODs.
1201 resp.body
1203 Type: BODY
1204 Writable from: vcl_synth
1206 To produce a synthetic response body, for instance for errors.
1208 resp.proto VCL <= 4.0
1210 Type: STRING
1211 Readable from: vcl_deliver, vcl_synth
1213 Writable from: vcl_deliver, vcl_synth
1215 The HTTP protocol version to use for the response.
1217 resp.proto VCL >= 4.1
1219 Type: STRING
1220 Readable from: vcl_deliver, vcl_synth
1222 Writable from: vcl_deliver, vcl_synth
1224 The HTTP protocol version to use for the response.
1226 resp.status
1228 Type: INT
1229 Readable from: vcl_deliver, vcl_synth
1231 Writable from: vcl_deliver, vcl_synth
1233 The HTTP status code that will be returned.
1235 Assigning a HTTP standardized code to resp.status will also set
1237 resp.reason to the corresponding status message.
1238 resp.status 200 will get changed into 304 by core code after a
1240 return(deliver) from vcl_deliver for conditional requests to cached
1241 content if validation succeeds.
1242 resp.reason
1244 Type: STRING
1245 Readable from: vcl_deliver, vcl_synth
1247 Writable from: vcl_deliver, vcl_synth
1249 The HTTP status message that will be returned.
1251 resp.http.*
1253 Type: HEADER
1254 Readable from: vcl_deliver, vcl_synth
1256 Writable from: vcl_deliver, vcl_synth
1258 Unsetable from: vcl_deliver, vcl_synth
1260 The HTTP headers that will be returned.
1262 resp.do_esi VCL >= 4.1
1264 Type: BOOL
1265 Readable from: vcl_deliver, vcl_synth
1267 Writable from: vcl_deliver, vcl_synth
1269 Default: Set if ESI parsing has happened.
1271 This can be used to selectively disable ESI processing, even though
1273 ESI parsing happened during fetch. This is useful when Varnish
1274 caches peer with each other.
1275 resp.is_streaming
1277 Type: BOOL
1278 Readable from: vcl_deliver, vcl_synth
1280 Returns true when the response will be streamed while being fetched
1282 from the backend.
1283 Special variables
1285 now
1286 Type: TIME
1287 Readable from: all
1289 The current time, in seconds since the UNIX epoch.
1291 When converted to STRING in expressions it returns a formatted time‐
1293 stamp like Tue, 20 Feb 2018 09:30:31 GMT
1294 sess
1296 A session corresponds to the "conversation" that Varnish has with a
1297 single client connection, over which one or more request/response
1298 transactions may take place. It may comprise the traffic over an HTTP/1
1299 keep-alive connection, or the multiplexed traffic over an HTTP/2 con‐
1300 nection.
1301 sess.xid VCL >= 4.1
1303 Type: STRING
1304 Readable from: client, backend
1306 Unique ID of this session.
1308 storage
1310 storage.<name>.free_space
1311 Type: BYTES
1312 Readable from: client, backend
1314 Free space available in the named stevedore. Only available for the
1316 malloc stevedore.
1317 storage.<name>.used_space
1319 Type: BYTES
1320 Readable from: client, backend
1322 Used space in the named stevedore. Only available for the malloc
1324 stevedore.
1325 storage.<name>.happy
1327 Type: BOOL
1328 Readable from: client, backend
1330 Health status for the named stevedore. Not available in any of the
1332 current stevedores.
1333 Functions
1335 The following built-in functions are available:
1336 ban(STRING)
1338 Invalidates all objects in cache that match the given expression
1339 with the ban mechanism.
1340 The format of STRING is:
1342 <field> <operator> <arg> [&& <field> <oper> <arg> ...]
1344 · <field>:
1346 · req.url: The request url
1348 · req.http.*: Any request header
1350 · obj.status: The cache object status
1352 · obj.http.*: Any cache object header
1354 · <operator>:
1356 · ==: <field> and <arg> are equal strings (case sensitive)
1358 · !=: <field> and <arg> are unequal strings (case sensitive)
1360 · ~: <field> matches the regular expression <arg>
1362 · !~:<field> does not match the regular expression <arg>
1364 · <arg>: Either a literal string or a regular expression. Note that
1366 <arg> does not use any of the string delimiters like " or {"..."}
1367 used elsewhere in varnish. To match against strings containing
1368 whitespace, regular expressions containing \s can be used.
1369 Expressions can be chained using the and operator &&. For or seman‐
1371 tics, use several bans.
1372 The unset <field> is not equal to any string, such that, for a
1374 non-existing header, the operators == and ~ always evaluate as
1375 false, while the operators != and !~ always evaluate as true,
1376 respectively, for any value of <arg>.
1377 hash_data(input)
1379 Adds an input to the hash input. In the built-in VCL hash_data() is
1380 called on the host and URL of the request. Available in vcl_hash.
1381 synthetic(STRING)
1383 Prepare a synthetic response body containing the STRING. Available
1384 in vcl_synth and vcl_backend_error.
1385 Identical to set resp.body / set beresp.body.
1387 regsub(str, regex, sub)
1389 Returns a copy of str with the first occurrence of the regular
1390 expression regex replaced with sub. Within sub, \0 (which can also
1391 be spelled \&) is replaced with the entire matched string, and \n is
1392 replaced with the contents of subgroup n in the matched string.
1393 regsuball(str, regex, sub)
1395 As regsub(), but this replaces all occurrences.
1396 For converting or casting VCL values between data types use the func‐
1398 tions available in the std VMOD.
1399
1401 Multiple versions of the VCL syntax can coexist within certain con‐
1402 straints.
1403 The VCL syntax version at the start of VCL file specified with -f sets
1405 the hard limit that cannot be exceeded anywhere, and it selects the
1406 appropriate version of the builtin VCL.
1407 That means that you can never include vcl 9.1; from vcl 8.7;, but the
1409 opposite may be possible, to the extent the compiler supports it.
1410 Files pulled in via include do not need to have a vcl X.Y; but it may
1412 be a good idea to do it anyway, to not have surprises in the future.
1413 The syntax version set in an included file only applies to that file
1414 and any files it includes - unless these set their own VCL syntax ver‐
1415 sion.
1416 The version of Varnish this file belongs to supports syntax 4.0 only.
1418
1420 For examples, please see the online documentation.
1421
1423 · varnishd(1)
1424 · vmod_directors(3)
1426 · vmod_std(3)
1428
1430 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
1431 AS, Redpill Linpro and Varnish Software. This manual page is written
1432 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
1433 gstøl, Lasse Karstensen and possibly others.
1434
1436 This document is licensed under the same license as Varnish itself. See
1437 LICENSE for details.
1438 · Copyright (c) 2006 Verdens Gang AS
1440 · Copyright (c) 2006-2015 Varnish Software AS
1442 VCL(7)