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 client.identity
40 Type: STRING
41 Readable from: client, backend
43 Writable from: client
45 Identification of the client, used to load balance in the client di‐
47 rector. Defaults to client.ip
48 This variable can be overwritten with more precise information, for
50 instance extracted from a Cookie: header.
51 client.ip
53 Type: IP
54 Readable from: client, backend
56 The client's IP address, either the same as remote.ip or what the
58 PROXY protocol told us.
59 server.hostname
61 Type: STRING
62 Readable from: all
64 The host name of the server, as returned by the gethostname(3) sys‐
66 tem function.
67 server.identity
69 Type: STRING
70 Readable from: all
72 The identity of the server, as set by the -i parameter.
74 If an -i parameter is not passed to varnishd, the return value from
76 gethostname(3) system function will be used.
77 server.ip
79 Type: IP
80 Readable from: client, backend
82 The IP address of the socket on which the client connection was re‐
84 ceived, either the same as server.ip or what the PROXY protocol told
85 us.
86 remote.ip
88 Type: IP
89 Readable from: client, backend
91 The IP address of the other end of the TCP connection. This can ei‐
93 ther be the clients IP, or the outgoing IP of a proxy server.
94 If the connection is a UNIX domain socket, the value will be
96 0.0.0.0:0
97 local.endpoint VCL >= 4.1
99 Type: STRING
100 Readable from: client, backend
102 The address of the '-a' socket the session was accepted on.
104 If the argument was -a foo=:81 this would be ":81"
106 local.ip
108 Type: IP
109 Readable from: client, backend
111 The IP address (and port number) of the local end of the TCP connec‐
113 tion, for instance 192.168.1.1:81
114 If the connection is a UNIX domain socket, the value will be
116 0.0.0.0:0
117 local.socket VCL >= 4.1
119 Type: STRING
120 Readable from: client, backend
122 The name of the '-a' socket the session was accepted on.
124 If the argument was -a foo=:81 this would be "foo".
126 Note that all '-a' gets a default name on the form a%d if no name is
128 provided.
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.backend_hint
144 Type: BACKEND
145 Readable from: client
147 Writable from: client
149 Set bereq.backend to this if we attempt to fetch. When set to a di‐
151 rector, reading this variable returns an actual backend if the di‐
152 rector has resolved immediately, or the director otherwise. When
153 used in string context, returns the name of the director or backend,
154 respectively.
155 req.can_gzip
157 Type: BOOL
158 Readable from: client
160 True if the client provided gzip or x-gzip in the Accept-Encoding
162 header.
163 req.esi VCL <= 4.0
165 Type: BOOL
166 Readable from: client
168 Writable from: client
170 Set to false to disable ESI processing regardless of any value in
172 beresp.do_esi. Defaults to true. This variable is replaced by
173 resp.do_esi in VCL 4.1.
174 req.esi_level
176 Type: INT
177 Readable from: client
179 A count of how many levels of ESI requests we're currently at.
181 req.grace
183 Type: DURATION
184 Readable from: client
186 Writable from: client
188 Upper limit on the object grace.
190 During lookup the minimum of req.grace and the object's stored grace
192 value will be used as the object's grace.
193 req.hash
195 Type: BLOB
196 Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver
198 The hash key of this request. Mostly useful for passing to VMODs,
200 but can also be useful for debugging hit/miss status.
201 req.hash_always_miss
203 Type: BOOL
204 Readable from: client
206 Writable from: client
208 Default: false.
210 Force a cache miss for this request, even if perfectly good matching
212 objects are in the cache.
213 This is useful to force-update the cache without invalidating exist‐
215 ing entries in case the fetch fails.
216 req.hash_ignore_busy
218 Type: BOOL
219 Readable from: client
221 Writable from: client
223 Default: false.
225 Ignore any busy object during cache lookup.
227 You only want to do this when you have two server looking up content
229 sideways from each other to avoid deadlocks.
230 req.hash_ignore_vary
232 Type: BOOL
233 Readable from: client
235 Writable from: client
237 Default: false.
239 Ignore objects vary headers during cache lookup.
241 This returns the very first match regardless of the object compati‐
243 bility with the client request. This is useful when variants are ir‐
244 relevant to certain clients, and differences in the way the resouce
245 is presented don't change how the client will interpret it.
246 Use with caution.
248 req.http.*
250 Type: HEADER
251 Readable from: client
253 Writable from: client
255 Unsetable from: client
257 The headers of request, things like req.http.date.
259 The RFCs allow multiple headers with the same name, and both set and
261 unset will remove all headers with the name given.
262 The header name * is a VCL symbol and as such cannot, for example,
264 start with a numeral. To work with valid header that can't be repre‐
265 sented as VCL symbols it is possible to quote the name, like
266 req.http."grammatically.valid". None of the HTTP headers present in
267 IANA registries need to be quoted, so the quoted syntax is discour‐
268 aged but available for interoperability.
269 req.is_hitmiss
271 Type: BOOL
272 Readable from: client
274 If this request resulted in a hitmiss
276 req.is_hitpass
278 Type: BOOL
279 Readable from: client
281 If this request resulted in a hitpass
283 req.method
285 Type: STRING
286 Readable from: client
288 Writable from: client
290 The request method (e.g. "GET", "HEAD", ...)
292 req.proto VCL <= 4.0
294 Type: STRING
295 Readable from: client
297 Writable from: client
299 The HTTP protocol version used by the client, usually "HTTP/1.1" or
301 "HTTP/2.0".
302 req.proto VCL >= 4.1
304 Type: STRING
305 Readable from: client
307 The HTTP protocol version used by the client, usually "HTTP/1.1" or
309 "HTTP/2.0".
310 req.restarts
312 Type: INT
313 Readable from: client
315 A count of how many times this request has been restarted.
317 req.storage
319 Type: STEVEDORE
320 Readable from: client
322 Writable from: client
324 The storage backend to use to save this request body.
326 req.time
328 Type: TIME
329 Readable from: client
331 The time when the request was fully received, remains constant
333 across restarts.
334 req.transport
336 Type: STRING
337 Readable from: client
339 The transport protocol which brought this request.
341 req.ttl
343 Type: DURATION
344 Readable from: client
346 Writable from: client
348 Upper limit on the object age for cache lookups to return hit.
350 req.url
352 Type: STRING
353 Readable from: client
355 Writable from: client
357 The requested URL, for instance "/robots.txt".
359 req.xid
361 Type: INT
362 Readable from: client
364 Unique ID of this request.
366 req_top.http.*
368 Type: HEADER
369 Readable from: client
371 HTTP headers of the top-level request in a tree of ESI requests.
373 Identical to req.http. in non-ESI requests.
374 See req.http.* for general notes.
376 req_top.method
378 Type: STRING
379 Readable from: client
381 The request method of the top-level request in a tree of ESI re‐
383 quests. (e.g. "GET", "HEAD"). Identical to req.method in non-ESI
384 requests.
385 req_top.proto
387 Type: STRING
388 Readable from: client
390 HTTP protocol version of the top-level request in a tree of ESI re‐
392 quests. Identical to req.proto in non-ESI requests.
393 req_top.time
395 Type: TIME
396 Readable from: client
398 The time when the top-level request was fully received, remains con‐
400 stant across restarts.
401 req_top.url
403 Type: STRING
404 Readable from: client
406 The requested URL of the top-level request in a tree of ESI re‐
408 quests. Identical to req.url in non-ESI requests.
409 bereq
411 This is the request we send to the backend, it is built from the
412 clients req.* fields by filtering out "per-hop" fields which should not
413 be passed along (Connection:, Range: and similar).
414 Slightly more fields are allowed through for pass` fetches than for
416 `miss` fetches, for instance ``Range.
417 bereq
419 Type: HTTP
420 Readable from: backend
422 The entire backend request HTTP data structure. Mostly useful as
424 argument to VMODs.
425 bereq.backend
427 Type: BACKEND
428 Readable from: vcl_pipe, backend
430 Writable from: vcl_pipe, backend
432 This is the backend or director we attempt to fetch from. When set
434 to a director, reading this variable returns an actual backend if
435 the director has resolved immediately, or the director otherwise.
436 When used in string context, returns the name of the director or
437 backend, respectively.
438 bereq.between_bytes_timeout
440 Type: DURATION
441 Readable from: backend
443 Writable from: backend
445 Default: .between_bytes_timeout attribute from the backend_defini‐
447 tion, which defaults to the between_bytes_timeout parameter, see
448 varnishd(1).
449 The time in seconds to wait between each received byte from the
451 backend. Not available in pipe mode.
452 bereq.body
454 Type: BODY
455 Unsetable from: vcl_backend_fetch
457 The request body.
459 Unset will also remove bereq.http.Content-Length.
461 bereq.connect_timeout
463 Type: DURATION
464 Readable from: vcl_pipe, backend
466 Writable from: vcl_pipe, backend
468 Default: .connect_timeout attribute from the backend_definition,
470 which defaults to the connect_timeout parameter, see varnishd(1).
471 The time in seconds to wait for a backend connection to be estab‐
473 lished.
474 bereq.first_byte_timeout
476 Type: DURATION
477 Readable from: backend
479 Writable from: backend
481 Default: .first_byte_timeout attribute from the backend_definition,
483 which defaults to the first_byte_timeout parameter, see varnishd(1).
484 The time in seconds to wait getting the first byte back from the
486 backend. Not available in pipe mode.
487 bereq.hash
489 Type: BLOB
490 Readable from: vcl_pipe, backend
492 The hash key of this request, a copy of req.hash.
494 bereq.http.*
496 Type: HEADER
497 Readable from: vcl_pipe, backend
499 Writable from: vcl_pipe, backend
501 Unsetable from: vcl_pipe, backend
503 The headers to be sent to the backend.
505 See req.http.* for general notes.
507 bereq.is_bgfetch
509 Type: BOOL
510 Readable from: backend
512 True for fetches where the client got a hit on an object in grace,
514 and this fetch was kicked of in the background to get a fresh copy.
515 bereq.is_hitmiss
517 Type: BOOL
518 Readable from: backend
520 If this backend request was caused by a hitmiss.
522 bereq.is_hitpass
524 Type: BOOL
525 Readable from: backend
527 If this backend request was caused by a hitpass.
529 bereq.method
531 Type: STRING
532 Readable from: vcl_pipe, backend
534 Writable from: vcl_pipe, backend
536 The request type (e.g. "GET", "HEAD").
538 Regular (non-pipe, non-pass) fetches are always "GET"
540 bereq.proto VCL <= 4.0
542 Type: STRING
543 Readable from: vcl_pipe, backend
545 Writable from: vcl_pipe, backend
547 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
549 has "HTTP/1.0" in req.proto
550 bereq.proto VCL >= 4.1
552 Type: STRING
553 Readable from: vcl_pipe, backend
555 The HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
557 has "HTTP/1.0" in req.proto
558 bereq.retries
560 Type: INT
561 Readable from: backend
563 A count of how many times this request has been retried.
565 bereq.time
567 Type: TIME
568 Readable from: vcl_pipe, backend
570 The time when we started preparing the first backend request, re‐
572 mains constant across retries.
573 bereq.uncacheable
575 Type: BOOL
576 Readable from: backend
578 Indicates whether this request is uncacheable due to a pass in the
580 client side or a hit on an hit-for-pass object.
581 bereq.url
583 Type: STRING
584 Readable from: vcl_pipe, backend
586 Writable from: vcl_pipe, backend
588 The requested URL, copied from req.url
590 bereq.xid
592 Type: INT
593 Readable from: vcl_pipe, backend
595 Unique ID of this request.
597 beresp
599 The response received from the backend, one cache misses, the store ob‐
600 ject is built from beresp.
601 beresp
603 Type: HTTP
604 Readable from: vcl_backend_response, vcl_backend_error
606 The entire backend response HTTP data structure, useful as argument
608 to VMOD functions.
609 beresp.age
611 Type: DURATION
612 Readable from: vcl_backend_response, vcl_backend_error
614 Default: Age header, or zero.
616 The age of the object.
618 beresp.backend
620 Type: BACKEND
621 Readable from: vcl_backend_response, vcl_backend_error
623 This is the backend we fetched from. If bereq.backend was set to a
625 director, this will be the backend selected by the director. When
626 used in string context, returns its name.
627 beresp.backend.ip VCL <= 4.0
629 Type: IP
630 Readable from: vcl_backend_response
632 IP of the backend this response was fetched from.
634 beresp.backend.name
636 Type: STRING
637 Readable from: vcl_backend_response, vcl_backend_error
639 Name of the backend this response was fetched from. Same as
641 beresp.backend.
642 beresp.body
644 Type: BODY
645 Writable from: vcl_backend_error
647 For producing a synthetic body.
649 beresp.do_esi
651 Type: BOOL
652 Readable from: vcl_backend_response, vcl_backend_error
654 Writable from: vcl_backend_response, vcl_backend_error
656 Default: false.
658 Set it to true to parse the object for ESI directives. This is nec‐
660 essary for later ESI processing on the client side. If beresp.do_esi
661 is false when an object enters the cache, client side ESI processing
662 will not be possible (obj.can_esi will be false).
663 It is a VCL error to use beresp.do_esi after setting beresp.filters.
665 beresp.do_gunzip
667 Type: BOOL
668 Readable from: vcl_backend_response, vcl_backend_error
670 Writable from: vcl_backend_response, vcl_backend_error
672 Default: false.
674 Set to true to gunzip the object while storing it in the cache.
676 If http_gzip_support is disabled, setting this variable has no ef‐
678 fect.
679 It is a VCL error to use beresp.do_gunzip after setting beresp.fil‐
681 ters.
682 beresp.do_gzip
684 Type: BOOL
685 Readable from: vcl_backend_response, vcl_backend_error
687 Writable from: vcl_backend_response, vcl_backend_error
689 Default: false.
691 Set to true to gzip the object while storing it.
693 If http_gzip_support is disabled, setting this variable has no ef‐
695 fect.
696 It is a VCL error to use beresp.do_gzip after setting beresp.fil‐
698 ters.
699 beresp.do_stream
701 Type: BOOL
702 Readable from: vcl_backend_response, vcl_backend_error
704 Writable from: vcl_backend_response, vcl_backend_error
706 Default: true.
708 Deliver the object to the client while fetching the whole object
710 into varnish.
711 For uncacheable objects, storage for parts of the body which have
713 been sent to the client may get freed early, depending on the stor‐
714 age engine used.
715 This variable has no effect if beresp.do_esi is true or when the re‐
717 sponse body is empty.
718 beresp.filters
720 Type: STRING
721 Readable from: vcl_backend_response
723 Writable from: vcl_backend_response
725 List of Varnish Fetch Processor (VFP) filters the beresp.body will
727 be pulled through. The order left to right signifies processing from
728 backend to cache, iow the leftmost filter is run first on the body
729 as received from the backend after decoding of any transfer encod‐
730 ings.
731 VFP Filters change the body before going into the cache and/or being
733 handed to the client side, where it may get processed again by
734 resp.filters.
735 The following VFP filters exist in varnish-cache:
737 • gzip: compress a body using gzip
739 • testgunzip: Test if a body is valid gzip and refuse it otherwise
741 • gunzip: Uncompress gzip content
743 • esi: ESI-process plain text content
745 • esi_gzip: Save gzipped snippets for efficient ESI-processing
747 This filter enables stitching together ESI from individually
749 gzipped fragments, saving processing power for re-compression on
750 the client side at the expense of some compression efficiency.
751 Additional VFP filters are available from VMODs.
753 By default, beresp.filters is constructed as follows:
755 • gunzip gets added for gzipped content if beresp.do_gunzip or
757 beresp.do_esi are true.
758 • esi_gzip gets added if beresp.do_esi is true together with
760 beresp.do_gzip or content is already compressed.
761 • esi gets added if beresp.do_esi is true
763 • gzip gets added for uncompressed content if beresp.do_gzip is true
765 • testgunzip gets added for compressed content if beresp.do_gunzip
767 is false.
768 After beresp.filters is set, using any of the beforementioned
770 beresp.do_* switches is a VCL error.
771 beresp.grace
773 Type: DURATION
774 Readable from: vcl_backend_response, vcl_backend_error
776 Writable from: vcl_backend_response, vcl_backend_error
778 Default: Cache-Control stale-while-revalidate directive, or de‐
780 fault_grace parameter.
781 Set to a period to enable grace.
783 beresp.http.*
785 Type: HEADER
786 Readable from: vcl_backend_response, vcl_backend_error
788 Writable from: vcl_backend_response, vcl_backend_error
790 Unsetable from: vcl_backend_response, vcl_backend_error
792 The HTTP headers returned from the server.
794 See req.http.* for general notes.
796 beresp.keep
798 Type: DURATION
799 Readable from: vcl_backend_response, vcl_backend_error
801 Writable from: vcl_backend_response, vcl_backend_error
803 Default: default_keep parameter.
805 Set to a period to enable conditional backend requests.
807 The keep time is cache lifetime in addition to the ttl.
809 Objects with ttl expired but with keep time left may be used to is‐
811 sue conditional (If-Modified-Since / If-None-Match) requests to the
812 backend to refresh them.
813 beresp.proto VCL <= 4.0
815 Type: STRING
816 Readable from: vcl_backend_response, vcl_backend_error
818 Writable from: vcl_backend_response, vcl_backend_error
820 The HTTP protocol version the backend replied with.
822 beresp.proto VCL >= 4.1
824 Type: STRING
825 Readable from: vcl_backend_response, vcl_backend_error
827 The HTTP protocol version the backend replied with.
829 beresp.reason
831 Type: STRING
832 Readable from: vcl_backend_response, vcl_backend_error
834 Writable from: vcl_backend_response, vcl_backend_error
836 The HTTP status message returned by the server.
838 beresp.status
840 Type: INT
841 Readable from: vcl_backend_response, vcl_backend_error
843 Writable from: vcl_backend_response, vcl_backend_error
845 The HTTP status code returned by the server.
847 More information in the HTTP response status section.
849 beresp.storage
851 Type: STEVEDORE
852 Readable from: vcl_backend_response, vcl_backend_error
854 Writable from: vcl_backend_response, vcl_backend_error
856 The storage backend to use to save this object.
858 beresp.storage_hint VCL <= 4.0
860 Type: STRING
861 Readable from: vcl_backend_response, vcl_backend_error
863 Writable from: vcl_backend_response, vcl_backend_error
865 Deprecated since varnish 5.1 and discontinued since VCL 4.1 (varnish
867 6.0). Use beresp.storage instead.
868 Hint to Varnish that you want to save this object to a particular
870 storage backend.
871 beresp.time
873 Type: TIME
874 Readable from: vcl_backend_response, vcl_backend_error
876 When the backend headers were fully received just before vcl_back‐
878 end_response {} was entered, or when vcl_backend_error {} was en‐
879 tered.
880 beresp.transit_buffer
882 Type: BYTES
883 Readable from: vcl_backend_response
885 Writable from: vcl_backend_response
887 Default: transit_buffer parameter, see varnishd(1).
889 The maximum number of bytes the client can be ahead of the backend
891 during a streaming pass if beresp is uncacheable. See also tran‐
892 sit_buffer parameter documentation in varnishd(1).
893 beresp.ttl
895 Type: DURATION
896 Readable from: vcl_backend_response, vcl_backend_error
898 Writable from: vcl_backend_response, vcl_backend_error
900 Default: Cache-Control s-maxage or max-age directives, or a value
902 computed from the Expires header's deadline, or the default_ttl pa‐
903 rameter.
904 The object's remaining time to live, in seconds.
906 beresp.uncacheable
908 Type: BOOL
909 Readable from: vcl_backend_response, vcl_backend_error
911 Writable from: vcl_backend_response, vcl_backend_error
913 Inherited from bereq.uncacheable, see there.
915 Setting this variable makes the object uncacheable.
917 This may may produce a hit-for-miss object in the cache.
919 Clearing the variable has no effect and will log the warning "Ignor‐
921 ing attempt to reset beresp.uncacheable".
922 beresp.was_304
924 Type: BOOL
925 Readable from: vcl_backend_response, vcl_backend_error
927 When true this indicates that we got a 304 response to our condi‐
929 tional fetch from the backend and turned that into beresp.status =
930 200
931 obj
933 This is the object we found in cache. It cannot be modified.
934 obj.age
936 Type: DURATION
937 Readable from: vcl_hit, vcl_deliver
939 The age of the object.
941 obj.can_esi
943 Type: BOOL
944 Readable from: vcl_hit, vcl_deliver
946 If the object can be ESI processed, that is if setting resp.do_esi
948 or adding esi to resp.filters in vcl_deliver {} would cause the re‐
949 sponse body to be ESI processed.
950 obj.grace
952 Type: DURATION
953 Readable from: vcl_hit, vcl_deliver
955 The object's grace period in seconds.
957 obj.hits
959 Type: INT
960 Readable from: vcl_hit, vcl_deliver
962 The count of cache-hits on this object.
964 In vcl_deliver a value of 0 indicates a cache miss.
966 obj.http.*
968 Type: HEADER
969 Readable from: vcl_hit
971 The HTTP headers stored in the object.
973 See req.http.* for general notes.
975 obj.keep
977 Type: DURATION
978 Readable from: vcl_hit, vcl_deliver
980 The object's keep period in seconds.
982 obj.proto
984 Type: STRING
985 Readable from: vcl_hit
987 The HTTP protocol version stored in the object.
989 obj.reason
991 Type: STRING
992 Readable from: vcl_hit
994 The HTTP reason phrase stored in the object.
996 obj.status
998 Type: INT
999 Readable from: vcl_hit
1001 The HTTP status code stored in the object.
1003 More information in the HTTP response status section.
1005 obj.storage
1007 Type: STEVEDORE
1008 Readable from: vcl_hit, vcl_deliver
1010 The storage backend where this object is stored.
1012 obj.time
1014 Type: TIME
1015 Readable from: vcl_hit, vcl_deliver
1017 The time the object was created from the perspective of the server
1019 which generated it. This will roughly be equivalent to now -
1020 obj.age.
1021 obj.ttl
1023 Type: DURATION
1024 Readable from: vcl_hit, vcl_deliver
1026 The object's remaining time to live, in seconds.
1028 obj.uncacheable
1030 Type: BOOL
1031 Readable from: vcl_deliver
1033 Whether the object is uncacheable (pass, hit-for-pass or
1035 hit-for-miss).
1036 resp
1038 This is the response we send to the client, it is built from either
1039 beresp (pass/miss), obj (hits) or created from whole cloth (synth).
1040 With the exception of resp.body all resp.* variables available in both
1042 vcl_deliver{} and vcl_synth{} as a matter of symmetry.
1043 resp
1045 Type: HTTP
1046 Readable from: vcl_deliver, vcl_synth
1048 The entire response HTTP data structure, useful as argument to
1050 VMODs.
1051 resp.body
1053 Type: BODY
1054 Writable from: vcl_synth
1056 To produce a synthetic response body, for instance for errors.
1058 resp.do_esi VCL >= 4.1
1060 Type: BOOL
1061 Readable from: vcl_deliver, vcl_synth
1063 Writable from: vcl_deliver, vcl_synth
1065 Default: obj.can_esi
1067 This can be used to selectively disable ESI processing, even though
1069 ESI parsing happened during fetch (see beresp.do_esi). This is use‐
1070 ful when Varnish caches peer with each other.
1071 It is a VCL error to use resp.do_esi after setting resp.filters.
1073 resp.filters
1075 Type: STRING
1076 Readable from: vcl_deliver, vcl_synth
1078 Writable from: vcl_deliver, vcl_synth
1080 List of VDP filters the resp.body will be pushed through.
1082 Before resp.filters is set, the value read will be the default fil‐
1084 ter list as determined by varnish based on resp.do_esi and request
1085 headers.
1086 After resp.filters is set, changing any of the conditions which oth‐
1088 erwise determine the filter selection will have no effiect. Using
1089 resp.do_esi is an error once resp.filters is set.
1090 resp.http.*
1092 Type: HEADER
1093 Readable from: vcl_deliver, vcl_synth
1095 Writable from: vcl_deliver, vcl_synth
1097 Unsetable from: vcl_deliver, vcl_synth
1099 The HTTP headers that will be returned.
1101 See req.http.* for general notes.
1103 resp.is_streaming
1105 Type: BOOL
1106 Readable from: vcl_deliver, vcl_synth
1108 Returns true when the response will be streamed while being fetched
1110 from the backend.
1111 resp.proto VCL <= 4.0
1113 Type: STRING
1114 Readable from: vcl_deliver, vcl_synth
1116 Writable from: vcl_deliver, vcl_synth
1118 The HTTP protocol version to use for the response.
1120 resp.proto VCL >= 4.1
1122 Type: STRING
1123 Readable from: vcl_deliver, vcl_synth
1125 The HTTP protocol version to use for the response.
1127 resp.reason
1129 Type: STRING
1130 Readable from: vcl_deliver, vcl_synth
1132 Writable from: vcl_deliver, vcl_synth
1134 The HTTP status message that will be returned.
1136 resp.status
1138 Type: INT
1139 Readable from: vcl_deliver, vcl_synth
1141 Writable from: vcl_deliver, vcl_synth
1143 The HTTP status code that will be returned.
1145 More information in the HTTP response status section.
1147 resp.status 200 will get changed into 304 by core code after a re‐
1149 turn(deliver) from vcl_deliver for conditional requests to cached
1150 content if validation succeeds.
1151 For the validation, first req.http.If-None-Match is compared against
1153 resp.http.Etag. If they compare equal according to the rules for
1154 weak validation (see RFC7232), a 304 is sent.
1155 Secondly, req.http.If-Modified-Since is compared against
1157 resp.http.Last-Modified or, if it is unset or weak, against the
1158 point in time when the object was last modified based on the Date
1159 and Age headers received with the backend response which created the
1160 object. If the object has not been modified based on that compari‐
1161 son, a 304 is sent.
1162 resp.time
1164 Type: TIME
1165 Readable from: vcl_deliver, vcl_synth
1167 The time when we started preparing the response, just before enter‐
1169 ing vcl_synth {} or vcl_deliver {}.
1170 Special variables
1172 now
1173 Type: TIME
1174 Readable from: all
1176 The current time, in seconds since the UNIX epoch.
1178 When converted to STRING in expressions it returns a formatted time‐
1180 stamp like Tue, 20 Feb 2018 09:30:31 GMT
1181 now remains stable for the duration of any built-in VCL subroutine
1183 to make time-based calculations predictable and avoid edge cases.
1184 In other words, even if considerable amounts of time are spent in
1186 VCL, now will always represent the point in time when the respective
1187 built-in VCL subroutine was entered. now is thus not suitable for
1188 any kind of time measurements. See std.timestamp(), std.now() and
1189 std.timed_call() in vmod_std(3).
1190 sess
1192 A session corresponds to the "conversation" that Varnish has with a
1193 single client connection, over which one or more request/response
1194 transactions may take place. It may comprise the traffic over an HTTP/1
1195 keep-alive connection, or the multiplexed traffic over an HTTP/2 con‐
1196 nection.
1197 sess.idle_send_timeout
1199 Type: DURATION
1200 Readable from: client
1202 Writable from: client
1204 Send timeout for individual pieces of data on client connections,
1206 defaults to the idle_send_timeout parameter, see varnishd(1)
1207 sess.send_timeout
1209 Type: DURATION
1210 Readable from: client
1212 Writable from: client
1214 Total timeout for ordinary HTTP1 responses, defaults to the
1216 send_timeout parameter, see varnishd(1)
1217 sess.timeout_idle
1219 Type: DURATION
1220 Readable from: client
1222 Writable from: client
1224 Idle timeout for this session, defaults to the timeout_idle parame‐
1226 ter, see varnishd(1)
1227 sess.timeout_linger
1229 Type: DURATION
1230 Readable from: client
1232 Writable from: client
1234 Linger timeout for this session, defaults to the timeout_linger pa‐
1236 rameter, see varnishd(1)
1237 sess.xid VCL >= 4.1
1239 Type: INT
1240 Readable from: client, backend
1242 Unique ID of this session.
1244 storage
1246 storage.<name>.free_space
1247 Type: BYTES
1248 Readable from: client, backend
1250 Free space available in the named stevedore. Only available for the
1252 malloc stevedore.
1253 storage.<name>.happy
1255 Type: BOOL
1256 Readable from: client, backend
1258 Health status for the named stevedore. Not available in any of the
1260 current stevedores.
1261 storage.<name>.used_space
1263 Type: BYTES
1264 Readable from: client, backend
1266 Used space in the named stevedore. Only available for the malloc
1268 stevedore.
1269 HTTP response status
1271 A HTTP status code has 3 digits XYZ where X must be between 1 and 5 in‐
1272 cluded. Since it is not uncommon to see HTTP clients or servers rely‐
1273 ing on non-standard or even invalid status codes, Varnish can work with
1274 any status between 100 and 999.
1275 Within VCL code it is even possible to use status codes in the form
1277 VWXYZ as long as the overall value is lower than 65536, but only the
1278 XYZ part will be sent to the client, by which time the X must also have
1279 become non-zero.
1280 The VWXYZ form of status codes can be communicate extra information in
1282 resp.status and beresp.status to return(synth(...)) and return(er‐
1283 ror(...)), to indicate which synthetic content to produce:
1284 sub vcl_recv {
1286 if ([...]) {
1287 return synth(12404);
1288 }
1289 }
1290 sub vcl_synth {
1292 if (resp.status == 12404) {
1293 [...] // this specific 404
1294 } else if (resp.status % 1000 == 404) {
1295 [...] // all other 404's
1296 }
1297 }
1298 The obj.status variable will inherit the VWXYZ form, but in a ban ex‐
1300 pression only the XYZ part will be available. The VWXYZ form is
1301 strictly limited to VCL execution.
1302 Assigning an HTTP standardized code to resp.status or beresp.status
1304 will also set resp.reason or beresp.reason to the corresponding status
1305 message.
1306
1308 • varnishd(1)
1309 • vcl(7)
1311
1313 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
1314 AS, Redpill Linpro and Varnish Software. This manual page is written
1315 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
1316 gstøl, Lasse Karstensen and others.
1317
1319 This document is licensed under the same license as Varnish itself. See
1320 LICENSE for details.
1321 • Copyright (c) 2006 Verdens Gang AS
1323 • Copyright (c) 2006-2021 Varnish Software AS
1325 VCL-VARIABLES(7)