1VCL-VARIABLES(7) VCL-VARIABLES(7)
2
6 VCL-Variables - The complete album
7
9 This is a list of all variables in the VCL language.
10 Variable names take the form scope.variable[.index], for instance:
12 req.url
14 beresp.http.date
15 client.ip
16 Which operations are possible on each variable is described below, of‐
18 ten with the shorthand "backend" which covers the vcl_backend_* {} sub‐
19 routines and "client" which covers the rest, except vcl_init {} and
20 vcl_fini {}.
21 local, server, remote and client
23 These variables describe the network connection between the client and
24 varnishd.
25 Without PROXY protocol:
27 client server
29 remote local
30 v v
31 CLIENT ------------ VARNISHD
32 With PROXY protocol:
34 client server remote local
36 v v v v
37 CLIENT ------------ PROXY ------------ VARNISHD
38 local.ip
40 Type: IP
41 Readable from: client, backend
43 The IP address (and port number) of the local end of the TCP connec‐
45 tion, for instance 192.168.1.1:81
46 If the connection is a UNIX domain socket, the value will be
48 0.0.0.0:0
49 local.endpoint VCL >= 4.1
51 Type: STRING
52 Readable from: client, backend
54 The address of the '-a' socket the session was accepted on.
56 If the argument was -a foo=:81 this would be ":81"
58 local.socket VCL >= 4.1
60 Type: STRING
61 Readable from: client, backend
63 The name of the '-a' socket the session was accepted on.
65 If the argument was -a foo=:81 this would be "foo".
67 Note that all '-a' gets a default name on the form a%d if no name is
69 provided.
70 remote.ip
72 Type: IP
73 Readable from: client, backend
75 The IP address of the other end of the TCP connection. This can ei‐
77 ther be the clients IP, or the outgoing IP of a proxy server.
78 If the connection is a UNIX domain socket, the value will be
80 0.0.0.0:0
81 client.ip
83 Type: IP
84 Readable from: client, backend
86 The client's IP address, either the same as remote.ip or what the
88 PROXY protocol told us.
89 client.identity
91 Type: STRING
92 Readable from: client, backend
94 Writable from: client
96 Identification of the client, used to load balance in the client di‐
98 rector. Defaults to client.ip
99 This variable can be overwritten with more precise information, for
101 instance extracted from a Cookie: header.
102 server.ip
104 Type: IP
105 Readable from: client, backend
107 The IP address of the socket on which the client connection was re‐
109 ceived, either the same as server.ip or what the PROXY protocol told
110 us.
111 server.hostname
113 Type: STRING
114 Readable from: all
116 The host name of the server, as returned by the gethostname(3) sys‐
118 tem function.
119 server.identity
121 Type: STRING
122 Readable from: all
124 The identity of the server, as set by the -i parameter.
126 If an -i parameter is not passed to varnishd, the return value from
128 gethostname(3) system function will be used.
129 req and req_top
131 These variables describe the present request, and when ESI:include re‐
132 quests are being processed, req_top points to the request received from
133 the client.
134 req
136 Type: HTTP
137 Readable from: client
139 The entire request HTTP data structure. Mostly useful for passing
141 to VMODs.
142 req.method
144 Type: STRING
145 Readable from: client
147 Writable from: client
149 The request method (e.g. "GET", "HEAD", ...)
151 req.hash
153 Type: BLOB
154 Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver
156 The hash key of this request. Mostly useful for passing to VMODs,
158 but can also be useful for debugging hit/miss status.
159 req.url
161 Type: STRING
162 Readable from: client
164 Writable from: client
166 The requested URL, for instance "/robots.txt".
168 req.proto VCL <= 4.0
170 Type: STRING
171 Readable from: client
173 Writable from: client
175 The HTTP protocol version used by the client, usually "HTTP/1.1" or
177 "HTTP/2.0".
178 req.proto VCL >= 4.1
180 Type: STRING
181 Readable from: client
183 The HTTP protocol version used by the client, usually "HTTP/1.1" or
185 "HTTP/2.0".
186 req.http.*
188 Type: HEADER
189 Readable from: client
191 Writable from: client
193 Unsetable from: client
195 The headers of request, things like req.http.date.
197 The RFCs allow multiple headers with the same name, and both set and
199 unset will remove all headers with the name given.
200 The header name * is a VCL symbol and as such cannot, for example,
202 start with a numeral. To work with valid header that can't be repre‐
203 sented as VCL symbols it is possible to quote the name, like
204 req.http."grammatically.valid". None of the HTTP headers present in
205 IANA registries need to be quoted, so the quoted syntax is discour‐
206 aged but available for interoperability.
207 req.restarts
209 Type: INT
210 Readable from: client
212 A count of how many times this request has been restarted.
214 req.storage
216 Type: STEVEDORE
217 Readable from: client
219 Writable from: client
221 The storage backend to use to save this request body.
223 req.esi_level
225 Type: INT
226 Readable from: client
228 A count of how many levels of ESI requests we're currently at.
230 req.ttl
232 Type: DURATION
233 Readable from: client
235 Writable from: client
237 Upper limit on the object age for cache lookups to return hit.
239 req.grace
241 Type: DURATION
242 Readable from: client
244 Writable from: client
246 Upper limit on the object grace.
248 During lookup the minimum of req.grace and the object's stored grace
250 value will be used as the object's grace.
251 req.xid
253 Type: STRING
254 Readable from: client
256 Unique ID of this request.
258 req.esi VCL <= 4.0
260 Type: BOOL
261 Readable from: client
263 Writable from: client
265 Set to false to disable ESI processing regardless of any value in
267 beresp.do_esi. Defaults to true. This variable is replaced by
268 resp.do_esi in VCL 4.1.
269 req.can_gzip
271 Type: BOOL
272 Readable from: client
274 True if the client provided gzip or x-gzip in the Accept-Encoding
276 header.
277 req.backend_hint
279 Type: BACKEND
280 Readable from: client
282 Writable from: client
284 Set bereq.backend to this if we attempt to fetch. When set to a di‐
286 rector, reading this variable returns an actual backend if the di‐
287 rector has resolved immediately, or the director otherwise. When
288 used in string context, returns the name of the director or backend,
289 respectively.
290 req.hash_ignore_busy
292 Type: BOOL
293 Readable from: client
295 Writable from: client
297 Default: false.
299 Ignore any busy object during cache lookup.
301 You only want to do this when you have two server looking up content
303 sideways from each other to avoid deadlocks.
304 req.hash_ignore_vary
306 Type: BOOL
307 Readable from: client
309 Writable from: client
311 Default: false.
313 Ignore objects vary headers during cache lookup.
315 This returns the very first match regardless of the object compati‐
317 bility with the client request. This is useful when variants are ir‐
318 relevant to certain clients, and differences in the way the resouce
319 is presented don't change how the client will interpret it.
320 Use with caution.
322 req.hash_always_miss
324 Type: BOOL
325 Readable from: client
327 Writable from: client
329 Default: false.
331 Force a cache miss for this request, even if perfectly good matching
333 objects are in the cache.
334 This is useful to force-update the cache without invalidating exist‐
336 ing entries in case the fetch fails.
337 req.is_hitmiss
339 Type: BOOL
340 Readable from: client
342 If this request resulted in a hitmiss
344 req.is_hitpass
346 Type: BOOL
347 Readable from: client
349 If this request resulted in a hitpass
351 req_top.method
353 Type: STRING
354 Readable from: client
356 The request method of the top-level request in a tree of ESI re‐
358 quests. (e.g. "GET", "HEAD"). Identical to req.method in non-ESI
359 requests.
360 req_top.url
362 Type: STRING
363 Readable from: client
365 The requested URL of the top-level request in a tree of ESI re‐
367 quests. Identical to req.url in non-ESI requests.
368 req_top.http.*
370 Type: HEADER
371 Readable from: client
373 HTTP headers of the top-level request in a tree of ESI requests.
375 Identical to req.http. in non-ESI requests.
376 See req.http.* for general notes.
378 req_top.proto
380 Type: STRING
381 Readable from: client
383 HTTP protocol version of the top-level request in a tree of ESI re‐
385 quests. Identical to req.proto in non-ESI requests.
386 bereq
388 This is the request we send to the backend, it is built from the
389 clients req.* fields by filtering out "per-hop" fields which should not
390 be passed along (Connection:, Range: and similar).
391 Slightly more fields are allowed through for pass` fetches than for
393 `miss` fetches, for instance ``Range.
394 bereq
396 Type: HTTP
397 Readable from: backend
399 The entire backend request HTTP data structure. Mostly useful as
401 argument to VMODs.
402 bereq.xid
404 Type: STRING
405 Readable from: vcl_pipe, backend
407 Unique ID of this request.
409 bereq.retries
411 Type: INT
412 Readable from: backend
414 A count of how many times this request has been retried.
416 bereq.backend
418 Type: BACKEND
419 Readable from: vcl_pipe, backend
421 Writable from: vcl_pipe, backend
423 This is the backend or director we attempt to fetch from. When set
425 to a director, reading this variable returns an actual backend if
426 the director has resolved immediately, or the director otherwise.
427 When used in string context, returns the name of the director or
428 backend, respectively.
429 bereq.body
431 Type: BODY
432 Unsetable from: vcl_backend_fetch
434 The request body.
436 Unset will also remove bereq.http.Content-Length.
438 bereq.hash
440 Type: BLOB
441 Readable from: vcl_pipe, backend
443 The hash key of this request, a copy of req.hash.
445 bereq.method
447 Type: STRING
448 Readable from: vcl_pipe, backend
450 Writable from: vcl_pipe, backend
452 The request type (e.g. "GET", "HEAD").
454 Regular (non-pipe, non-pass) fetches are always "GET"
456 bereq.url
458 Type: STRING
459 Readable from: vcl_pipe, backend
461 Writable from: vcl_pipe, backend
463 The requested URL, copied from req.url
465 bereq.proto VCL <= 4.0
467 Type: STRING
468 Readable from: vcl_pipe, backend
470 Writable from: vcl_pipe, backend
472 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
474 has "HTTP/1.0" in req.proto
475 bereq.proto VCL >= 4.1
477 Type: STRING
478 Readable from: vcl_pipe, backend
480 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
482 has "HTTP/1.0" in req.proto
483 bereq.http.*
485 Type: HEADER
486 Readable from: vcl_pipe, backend
488 Writable from: vcl_pipe, backend
490 Unsetable from: vcl_pipe, backend
492 The headers to be sent to the backend.
494 See req.http.* for general notes.
496 bereq.uncacheable
498 Type: BOOL
499 Readable from: backend
501 Indicates whether this request is uncacheable due to a pass in the
503 client side or a hit on an hit-for-pass object.
504 bereq.connect_timeout
506 Type: DURATION
507 Readable from: vcl_pipe, backend
509 Writable from: vcl_pipe, backend
511 Default: .connect_timeout attribute from the backend_definition,
513 which defaults to the connect_timeout parameter, see varnishd(1).
514 The time in seconds to wait for a backend connection to be estab‐
516 lished.
517 bereq.first_byte_timeout
519 Type: DURATION
520 Readable from: backend
522 Writable from: backend
524 Default: .first_byte_timeout attribute from the backend_definition,
526 which defaults to the first_byte_timeout parameter, see varnishd(1).
527 The time in seconds to wait getting the first byte back from the
529 backend. Not available in pipe mode.
530 bereq.between_bytes_timeout
532 Type: DURATION
533 Readable from: backend
535 Writable from: backend
537 Default: .between_bytes_timeout attribute from the backend_defini‐
539 tion, which defaults to the between_bytes_timeout parameter, see
540 varnishd(1).
541 The time in seconds to wait between each received byte from the
543 backend. Not available in pipe mode.
544 bereq.is_bgfetch
546 Type: BOOL
547 Readable from: backend
549 True for fetches where the client got a hit on an object in grace,
551 and this fetch was kicked of in the background to get a fresh copy.
552 bereq.is_hitmiss
554 Type: BOOL
555 Readable from: backend
557 If this backend request was caused by a hitmiss.
559 bereq.is_hitpass
561 Type: BOOL
562 Readable from: backend
564 If this backend request was caused by a hitpass.
566 beresp
568 The response received from the backend, one cache misses, the store ob‐
569 ject is built from beresp.
570 beresp
572 Type: HTTP
573 Readable from: vcl_backend_response, vcl_backend_error
575 The entire backend response HTTP data structure, useful as argument
577 to VMOD functions.
578 beresp.body
580 Type: BODY
581 Writable from: vcl_backend_error
583 For producing a synthetic body.
585 beresp.proto VCL <= 4.0
587 Type: STRING
588 Readable from: vcl_backend_response, vcl_backend_error
590 Writable from: vcl_backend_response, vcl_backend_error
592 The HTTP protocol version the backend replied with.
594 beresp.proto VCL >= 4.1
596 Type: STRING
597 Readable from: vcl_backend_response, vcl_backend_error
599 The HTTP protocol version the backend replied with.
601 beresp.status
603 Type: INT
604 Readable from: vcl_backend_response, vcl_backend_error
606 Writable from: vcl_backend_response, vcl_backend_error
608 The HTTP status code returned by the server.
610 More information in the HTTP response status section.
612 beresp.reason
614 Type: STRING
615 Readable from: vcl_backend_response, vcl_backend_error
617 Writable from: vcl_backend_response, vcl_backend_error
619 The HTTP status message returned by the server.
621 beresp.http.*
623 Type: HEADER
624 Readable from: vcl_backend_response, vcl_backend_error
626 Writable from: vcl_backend_response, vcl_backend_error
628 Unsetable from: vcl_backend_response, vcl_backend_error
630 The HTTP headers returned from the server.
632 See req.http.* for general notes.
634 beresp.do_esi
636 Type: BOOL
637 Readable from: vcl_backend_response, vcl_backend_error
639 Writable from: vcl_backend_response, vcl_backend_error
641 Default: false.
643 Set it to true to parse the object for ESI directives. This is nec‐
645 essary for later ESI processing on the client side. If beresp.do_esi
646 is false when an object enters the cache, client side ESI processing
647 will not be possible (obj.can_esi will be false).
648 It is a VCL error to use beresp.do_esi after setting beresp.filters.
650 beresp.do_stream
652 Type: BOOL
653 Readable from: vcl_backend_response, vcl_backend_error
655 Writable from: vcl_backend_response, vcl_backend_error
657 Default: true.
659 Deliver the object to the client while fetching the whole object
661 into varnish.
662 For uncacheable objects, storage for parts of the body which have
664 been sent to the client may get freed early, depending on the stor‐
665 age engine used.
666 This variable has no effect if beresp.do_esi is true or when the re‐
668 sponse body is empty.
669 beresp.do_gzip
671 Type: BOOL
672 Readable from: vcl_backend_response, vcl_backend_error
674 Writable from: vcl_backend_response, vcl_backend_error
676 Default: false.
678 Set to true to gzip the object while storing it.
680 If http_gzip_support is disabled, setting this variable has no ef‐
682 fect.
683 It is a VCL error to use beresp.do_gzip after setting beresp.fil‐
685 ters.
686 beresp.do_gunzip
688 Type: BOOL
689 Readable from: vcl_backend_response, vcl_backend_error
691 Writable from: vcl_backend_response, vcl_backend_error
693 Default: false.
695 Set to true to gunzip the object while storing it in the cache.
697 If http_gzip_support is disabled, setting this variable has no ef‐
699 fect.
700 It is a VCL error to use beresp.do_gunzip after setting beresp.fil‐
702 ters.
703 beresp.was_304
705 Type: BOOL
706 Readable from: vcl_backend_response, vcl_backend_error
708 When true this indicates that we got a 304 response to our condi‐
710 tional fetch from the backend and turned that into beresp.status =
711 200
712 beresp.uncacheable
714 Type: BOOL
715 Readable from: vcl_backend_response, vcl_backend_error
717 Writable from: vcl_backend_response, vcl_backend_error
719 Inherited from bereq.uncacheable, see there.
721 Setting this variable makes the object uncacheable.
723 This may may produce a hit-for-miss object in the cache.
725 Clearing the variable has no effect and will log the warning "Ignor‐
727 ing attempt to reset beresp.uncacheable".
728 beresp.ttl
730 Type: DURATION
731 Readable from: vcl_backend_response, vcl_backend_error
733 Writable from: vcl_backend_response, vcl_backend_error
735 Default: Cache-Control s-maxage or max-age directives, or a value
737 computed from the Expires header's deadline, or the default_ttl pa‐
738 rameter.
739 The object's remaining time to live, in seconds.
741 beresp.age
743 Type: DURATION
744 Readable from: vcl_backend_response, vcl_backend_error
746 Default: Age header, or zero.
748 The age of the object.
750 beresp.grace
752 Type: DURATION
753 Readable from: vcl_backend_response, vcl_backend_error
755 Writable from: vcl_backend_response, vcl_backend_error
757 Default: Cache-Control stale-while-revalidate directive, or de‐
759 fault_grace parameter.
760 Set to a period to enable grace.
762 beresp.keep
764 Type: DURATION
765 Readable from: vcl_backend_response, vcl_backend_error
767 Writable from: vcl_backend_response, vcl_backend_error
769 Default: default_keep parameter.
771 Set to a period to enable conditional backend requests.
773 The keep time is cache lifetime in addition to the ttl.
775 Objects with ttl expired but with keep time left may be used to is‐
777 sue conditional (If-Modified-Since / If-None-Match) requests to the
778 backend to refresh them.
779 beresp.backend
781 Type: BACKEND
782 Readable from: vcl_backend_response, vcl_backend_error
784 This is the backend we fetched from. If bereq.backend was set to a
786 director, this will be the backend selected by the director. When
787 used in string context, returns its name.
788 beresp.backend.name
790 Type: STRING
791 Readable from: vcl_backend_response, vcl_backend_error
793 Name of the backend this response was fetched from. Same as
795 beresp.backend.
796 beresp.backend.ip VCL <= 4.0
798 Type: IP
799 Readable from: vcl_backend_response
801 IP of the backend this response was fetched from.
803 beresp.storage
805 Type: STEVEDORE
806 Readable from: vcl_backend_response, vcl_backend_error
808 Writable from: vcl_backend_response, vcl_backend_error
810 The storage backend to use to save this object.
812 beresp.storage_hint VCL <= 4.0
814 Type: STRING
815 Readable from: vcl_backend_response, vcl_backend_error
817 Writable from: vcl_backend_response, vcl_backend_error
819 Deprecated since varnish 5.1 and discontinued since VCL 4.1 (varnish
821 6.0). Use beresp.storage instead.
822 Hint to Varnish that you want to save this object to a particular
824 storage backend.
825 beresp.filters
827 Type: STRING
828 Readable from: vcl_backend_response
830 Writable from: vcl_backend_response
832 List of Varnish Fetch Processor (VFP) filters the beresp.body will
834 be pulled through. The order left to right signifies processing from
835 backend to cache, iow the leftmost filter is run first on the body
836 as received from the backend after decoding of any transfer encod‐
837 ings.
838 VFP Filters change the body before going into the cache and/or being
840 handed to the client side, where it may get processed again by
841 resp.filters.
842 The following VFP filters exist in varnish-cache:
844 • gzip: compress a body using gzip
846 • testgunzip: Test if a body is valid gzip and refuse it otherwise
848 • gunzip: Uncompress gzip content
850 • esi: ESI-process plain text content
852 • esi_gzip: Save gzipped snippets for efficient ESI-processing
854 This filter enables stitching together ESI from individually
856 gzipped fragments, saving processing power for re-compression on
857 the client side at the expense of some compression efficiency.
858 Additional VFP filters are available from VMODs.
860 By default, beresp.filters is constructed as follows:
862 • gunzip gets added for gzipped content if beresp.do_gunzip or
864 beresp.do_esi are true.
865 • esi_gzip gets added if beresp.do_esi is true together with
867 beresp.do_gzip or content is already compressed.
868 • esi gets added if beresp.do_esi is true
870 • gzip gets added for uncompressed content if beresp.do_gzip is true
872 • testgunzip gets added for compressed content if beresp.do_gunzip
874 is false.
875 After beresp.filters is set, using any of the beforementioned
877 beresp.do_* switches is a VCL error.
878 obj
880 This is the object we found in cache. It cannot be modified.
881 obj.proto
883 Type: STRING
884 Readable from: vcl_hit
886 The HTTP protocol version stored in the object.
888 obj.status
890 Type: INT
891 Readable from: vcl_hit
893 The HTTP status code stored in the object.
895 More information in the HTTP response status section.
897 obj.reason
899 Type: STRING
900 Readable from: vcl_hit
902 The HTTP reason phrase stored in the object.
904 obj.hits
906 Type: INT
907 Readable from: vcl_hit, vcl_deliver
909 The count of cache-hits on this object.
911 In vcl_deliver a value of 0 indicates a cache miss.
913 obj.http.*
915 Type: HEADER
916 Readable from: vcl_hit
918 The HTTP headers stored in the object.
920 See req.http.* for general notes.
922 obj.ttl
924 Type: DURATION
925 Readable from: vcl_hit, vcl_deliver
927 The object's remaining time to live, in seconds.
929 obj.age
931 Type: DURATION
932 Readable from: vcl_hit, vcl_deliver
934 The age of the object.
936 obj.grace
938 Type: DURATION
939 Readable from: vcl_hit, vcl_deliver
941 The object's grace period in seconds.
943 obj.keep
945 Type: DURATION
946 Readable from: vcl_hit, vcl_deliver
948 The object's keep period in seconds.
950 obj.uncacheable
952 Type: BOOL
953 Readable from: vcl_deliver
955 Whether the object is uncacheable (pass, hit-for-pass or
957 hit-for-miss).
958 obj.storage
960 Type: STEVEDORE
961 Readable from: vcl_hit, vcl_deliver
963 The storage backend where this object is stored.
965 obj.can_esi
967 Type: BOOL
968 Readable from: vcl_hit, vcl_deliver
970 If the object can be ESI processed, that is if setting resp.do_esi
972 or adding esi to resp.filters in vcl_deliver {} would cause the re‐
973 sponse body to be ESI processed.
974 resp
976 This is the response we send to the client, it is built from either
977 beresp (pass/miss), obj (hits) or created from whole cloth (synth).
978 With the exception of resp.body all resp.* variables available in both
980 vcl_deliver{} and vcl_synth{} as a matter of symmetry.
981 resp
983 Type: HTTP
984 Readable from: vcl_deliver, vcl_synth
986 The entire response HTTP data structure, useful as argument to
988 VMODs.
989 resp.body
991 Type: BODY
992 Writable from: vcl_synth
994 To produce a synthetic response body, for instance for errors.
996 resp.proto VCL <= 4.0
998 Type: STRING
999 Readable from: vcl_deliver, vcl_synth
1001 Writable from: vcl_deliver, vcl_synth
1003 The HTTP protocol version to use for the response.
1005 resp.proto VCL >= 4.1
1007 Type: STRING
1008 Readable from: vcl_deliver, vcl_synth
1010 The HTTP protocol version to use for the response.
1012 resp.status
1014 Type: INT
1015 Readable from: vcl_deliver, vcl_synth
1017 Writable from: vcl_deliver, vcl_synth
1019 The HTTP status code that will be returned.
1021 More information in the HTTP response status section.
1023 resp.status 200 will get changed into 304 by core code after a re‐
1025 turn(deliver) from vcl_deliver for conditional requests to cached
1026 content if validation succeeds.
1027 For the validation, first req.http.If-None-Match is compared against
1029 resp.http.Etag. If they compare equal according to the rules for
1030 weak validation (see RFC7232), a 304 is sent.
1031 Secondly, req.http.If-Modified-Since is compared against
1033 resp.http.Last-Modified or, if it is unset, against the point in
1034 time when the object was last modified based on the Date and Age
1035 headers received with the backend response which created the object.
1036 If the object has not been modified based on that comparison, a 304
1037 is sent.
1038 resp.reason
1040 Type: STRING
1041 Readable from: vcl_deliver, vcl_synth
1043 Writable from: vcl_deliver, vcl_synth
1045 The HTTP status message that will be returned.
1047 resp.http.*
1049 Type: HEADER
1050 Readable from: vcl_deliver, vcl_synth
1052 Writable from: vcl_deliver, vcl_synth
1054 Unsetable from: vcl_deliver, vcl_synth
1056 The HTTP headers that will be returned.
1058 See req.http.* for general notes.
1060 resp.do_esi VCL >= 4.1
1062 Type: BOOL
1063 Readable from: vcl_deliver, vcl_synth
1065 Writable from: vcl_deliver, vcl_synth
1067 Default: obj.can_esi
1069 This can be used to selectively disable ESI processing, even though
1071 ESI parsing happened during fetch (see beresp.do_esi). This is use‐
1072 ful when Varnish caches peer with each other.
1073 It is a VCL error to use resp.do_esi after setting resp.filters.
1075 resp.is_streaming
1077 Type: BOOL
1078 Readable from: vcl_deliver, vcl_synth
1080 Returns true when the response will be streamed while being fetched
1082 from the backend.
1083 resp.filters
1085 Type: STRING
1086 Readable from: vcl_deliver, vcl_synth
1088 Writable from: vcl_deliver, vcl_synth
1090 List of VDP filters the resp.body will be pushed through.
1092 Before resp.filters is set, the value read will be the default fil‐
1094 ter list as determined by varnish based on resp.do_esi and request
1095 headers.
1096 After resp.filters is set, changing any of the conditions which oth‐
1098 erwise determine the filter selection will have no effiect. Using
1099 resp.do_esi is an error once resp.filters is set.
1100 Special variables
1102 now
1103 Type: TIME
1104 Readable from: all
1106 The current time, in seconds since the UNIX epoch.
1108 When converted to STRING in expressions it returns a formatted time‐
1110 stamp like Tue, 20 Feb 2018 09:30:31 GMT
1111 sess
1113 A session corresponds to the "conversation" that Varnish has with a
1114 single client connection, over which one or more request/response
1115 transactions may take place. It may comprise the traffic over an HTTP/1
1116 keep-alive connection, or the multiplexed traffic over an HTTP/2 con‐
1117 nection.
1118 sess.xid VCL >= 4.1
1120 Type: STRING
1121 Readable from: client, backend
1123 Unique ID of this session.
1125 sess.timeout_idle
1127 Type: DURATION
1128 Readable from: client
1130 Writable from: client
1132 Idle timeout for this session, defaults to the timeout_idle parame‐
1134 ter, see varnishd(1)
1135 sess.timeout_linger
1137 Type: DURATION
1138 Readable from: client
1140 Writable from: client
1142 Linger timeout for this session, defaults to the timeout_linger pa‐
1144 rameter, see varnishd(1)
1145 sess.send_timeout
1147 Type: DURATION
1148 Readable from: client
1150 Writable from: client
1152 Total timeout for ordinary HTTP1 responses, defaults to the
1154 send_timeout parameter, see varnishd(1)
1155 sess.idle_send_timeout
1157 Type: DURATION
1158 Readable from: client
1160 Writable from: client
1162 Send timeout for individual pieces of data on client connections,
1164 defaults to the idle_send_timeout parameter, see varnishd(1)
1165 storage
1167 storage.<name>.free_space
1168 Type: BYTES
1169 Readable from: client, backend
1171 Free space available in the named stevedore. Only available for the
1173 malloc stevedore.
1174 storage.<name>.used_space
1176 Type: BYTES
1177 Readable from: client, backend
1179 Used space in the named stevedore. Only available for the malloc
1181 stevedore.
1182 storage.<name>.happy
1184 Type: BOOL
1185 Readable from: client, backend
1187 Health status for the named stevedore. Not available in any of the
1189 current stevedores.
1190 HTTP response status
1192 A HTTP status code has 3 digits XYZ where X must be between 1 and 5 in‐
1193 cluded. Since it is not uncommon to see HTTP clients or servers rely‐
1194 ing on non-standard or even invalid status codes, Varnish can work with
1195 any status between 100 and 999.
1196 Within VCL code it is even possible to use status codes in the form
1198 VWXYZ as long as the overall value is lower than 65536, but only the
1199 XYZ part will be sent to the client, by which time the X must also have
1200 become non-zero.
1201 The VWXYZ form of status codes can be communicate extra information in
1203 resp.status and beresp.status to return(synth(...)) and return(er‐
1204 ror(...)), to indicate which synthetic content to produce:
1205 sub vcl_recv {
1207 if ([...]) {
1208 return synth(12404);
1209 }
1210 }
1211 sub vcl_synth {
1213 if (resp.status == 12404) {
1214 [...] // this specific 404
1215 } else if (resp.status % 1000 == 404) {
1216 [...] // all other 404's
1217 }
1218 }
1219 The obj.status variable will inherit the VWXYZ form, but in a ban ex‐
1221 presion only the XYZ part will be available. The VWXYZ form is strictly
1222 limited to VCL execution.
1223 Assigning an HTTP standardized code to resp.status or beresp.status
1225 will also set resp.reason or beresp.reason to the corresponding status
1226 message.
1227
1229 • varnishd(1)
1230 • vcl(7)
1232
1234 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
1235 AS, Redpill Linpro and Varnish Software. This manual page is written
1236 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
1237 gstøl, Lasse Karstensen and others.
1238
1240 This document is licensed under the same license as Varnish itself. See
1241 LICENSE for details.
1242 • Copyright (c) 2006 Verdens Gang AS
1244 • Copyright (c) 2006-2021 Varnish Software AS
1246 VCL-VARIABLES(7)