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: STRING
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: STRING
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.ttl
882 Type: DURATION
883 Readable from: vcl_backend_response, vcl_backend_error
885 Writable from: vcl_backend_response, vcl_backend_error
887 Default: Cache-Control s-maxage or max-age directives, or a value
889 computed from the Expires header's deadline, or the default_ttl pa‐
890 rameter.
891 The object's remaining time to live, in seconds.
893 beresp.uncacheable
895 Type: BOOL
896 Readable from: vcl_backend_response, vcl_backend_error
898 Writable from: vcl_backend_response, vcl_backend_error
900 Inherited from bereq.uncacheable, see there.
902 Setting this variable makes the object uncacheable.
904 This may may produce a hit-for-miss object in the cache.
906 Clearing the variable has no effect and will log the warning "Ignor‐
908 ing attempt to reset beresp.uncacheable".
909 beresp.was_304
911 Type: BOOL
912 Readable from: vcl_backend_response, vcl_backend_error
914 When true this indicates that we got a 304 response to our condi‐
916 tional fetch from the backend and turned that into beresp.status =
917 200
918 obj
920 This is the object we found in cache. It cannot be modified.
921 obj.age
923 Type: DURATION
924 Readable from: vcl_hit, vcl_deliver
926 The age of the object.
928 obj.can_esi
930 Type: BOOL
931 Readable from: vcl_hit, vcl_deliver
933 If the object can be ESI processed, that is if setting resp.do_esi
935 or adding esi to resp.filters in vcl_deliver {} would cause the re‐
936 sponse body to be ESI processed.
937 obj.grace
939 Type: DURATION
940 Readable from: vcl_hit, vcl_deliver
942 The object's grace period in seconds.
944 obj.hits
946 Type: INT
947 Readable from: vcl_hit, vcl_deliver
949 The count of cache-hits on this object.
951 In vcl_deliver a value of 0 indicates a cache miss.
953 obj.http.*
955 Type: HEADER
956 Readable from: vcl_hit
958 The HTTP headers stored in the object.
960 See req.http.* for general notes.
962 obj.keep
964 Type: DURATION
965 Readable from: vcl_hit, vcl_deliver
967 The object's keep period in seconds.
969 obj.proto
971 Type: STRING
972 Readable from: vcl_hit
974 The HTTP protocol version stored in the object.
976 obj.reason
978 Type: STRING
979 Readable from: vcl_hit
981 The HTTP reason phrase stored in the object.
983 obj.status
985 Type: INT
986 Readable from: vcl_hit
988 The HTTP status code stored in the object.
990 More information in the HTTP response status section.
992 obj.storage
994 Type: STEVEDORE
995 Readable from: vcl_hit, vcl_deliver
997 The storage backend where this object is stored.
999 obj.time
1001 Type: TIME
1002 Readable from: vcl_hit, vcl_deliver
1004 The time the object was created from the perspective of the server
1006 which generated it. This will roughly be equivalent to now -
1007 obj.age.
1008 obj.ttl
1010 Type: DURATION
1011 Readable from: vcl_hit, vcl_deliver
1013 The object's remaining time to live, in seconds.
1015 obj.uncacheable
1017 Type: BOOL
1018 Readable from: vcl_deliver
1020 Whether the object is uncacheable (pass, hit-for-pass or
1022 hit-for-miss).
1023 resp
1025 This is the response we send to the client, it is built from either
1026 beresp (pass/miss), obj (hits) or created from whole cloth (synth).
1027 With the exception of resp.body all resp.* variables available in both
1029 vcl_deliver{} and vcl_synth{} as a matter of symmetry.
1030 resp
1032 Type: HTTP
1033 Readable from: vcl_deliver, vcl_synth
1035 The entire response HTTP data structure, useful as argument to
1037 VMODs.
1038 resp.body
1040 Type: BODY
1041 Writable from: vcl_synth
1043 To produce a synthetic response body, for instance for errors.
1045 resp.do_esi VCL >= 4.1
1047 Type: BOOL
1048 Readable from: vcl_deliver, vcl_synth
1050 Writable from: vcl_deliver, vcl_synth
1052 Default: obj.can_esi
1054 This can be used to selectively disable ESI processing, even though
1056 ESI parsing happened during fetch (see beresp.do_esi). This is use‐
1057 ful when Varnish caches peer with each other.
1058 It is a VCL error to use resp.do_esi after setting resp.filters.
1060 resp.filters
1062 Type: STRING
1063 Readable from: vcl_deliver, vcl_synth
1065 Writable from: vcl_deliver, vcl_synth
1067 List of VDP filters the resp.body will be pushed through.
1069 Before resp.filters is set, the value read will be the default fil‐
1071 ter list as determined by varnish based on resp.do_esi and request
1072 headers.
1073 After resp.filters is set, changing any of the conditions which oth‐
1075 erwise determine the filter selection will have no effiect. Using
1076 resp.do_esi is an error once resp.filters is set.
1077 resp.http.*
1079 Type: HEADER
1080 Readable from: vcl_deliver, vcl_synth
1082 Writable from: vcl_deliver, vcl_synth
1084 Unsetable from: vcl_deliver, vcl_synth
1086 The HTTP headers that will be returned.
1088 See req.http.* for general notes.
1090 resp.is_streaming
1092 Type: BOOL
1093 Readable from: vcl_deliver, vcl_synth
1095 Returns true when the response will be streamed while being fetched
1097 from the backend.
1098 resp.proto VCL <= 4.0
1100 Type: STRING
1101 Readable from: vcl_deliver, vcl_synth
1103 Writable from: vcl_deliver, vcl_synth
1105 The HTTP protocol version to use for the response.
1107 resp.proto VCL >= 4.1
1109 Type: STRING
1110 Readable from: vcl_deliver, vcl_synth
1112 The HTTP protocol version to use for the response.
1114 resp.reason
1116 Type: STRING
1117 Readable from: vcl_deliver, vcl_synth
1119 Writable from: vcl_deliver, vcl_synth
1121 The HTTP status message that will be returned.
1123 resp.status
1125 Type: INT
1126 Readable from: vcl_deliver, vcl_synth
1128 Writable from: vcl_deliver, vcl_synth
1130 The HTTP status code that will be returned.
1132 More information in the HTTP response status section.
1134 resp.status 200 will get changed into 304 by core code after a re‐
1136 turn(deliver) from vcl_deliver for conditional requests to cached
1137 content if validation succeeds.
1138 For the validation, first req.http.If-None-Match is compared against
1140 resp.http.Etag. If they compare equal according to the rules for
1141 weak validation (see RFC7232), a 304 is sent.
1142 Secondly, req.http.If-Modified-Since is compared against
1144 resp.http.Last-Modified or, if it is unset, against the point in
1145 time when the object was last modified based on the Date and Age
1146 headers received with the backend response which created the object.
1147 If the object has not been modified based on that comparison, a 304
1148 is sent.
1149 resp.time
1151 Type: TIME
1152 Readable from: vcl_deliver, vcl_synth
1154 The time when we started preparing the response, just before enter‐
1156 ing vcl_synth {} or vcl_deliver {}.
1157 Special variables
1159 now
1160 Type: TIME
1161 Readable from: all
1163 The current time, in seconds since the UNIX epoch.
1165 When converted to STRING in expressions it returns a formatted time‐
1167 stamp like Tue, 20 Feb 2018 09:30:31 GMT
1168 sess
1170 A session corresponds to the "conversation" that Varnish has with a
1171 single client connection, over which one or more request/response
1172 transactions may take place. It may comprise the traffic over an HTTP/1
1173 keep-alive connection, or the multiplexed traffic over an HTTP/2 con‐
1174 nection.
1175 sess.idle_send_timeout
1177 Type: DURATION
1178 Readable from: client
1180 Writable from: client
1182 Send timeout for individual pieces of data on client connections,
1184 defaults to the idle_send_timeout parameter, see varnishd(1)
1185 sess.send_timeout
1187 Type: DURATION
1188 Readable from: client
1190 Writable from: client
1192 Total timeout for ordinary HTTP1 responses, defaults to the
1194 send_timeout parameter, see varnishd(1)
1195 sess.timeout_idle
1197 Type: DURATION
1198 Readable from: client
1200 Writable from: client
1202 Idle timeout for this session, defaults to the timeout_idle parame‐
1204 ter, see varnishd(1)
1205 sess.timeout_linger
1207 Type: DURATION
1208 Readable from: client
1210 Writable from: client
1212 Linger timeout for this session, defaults to the timeout_linger pa‐
1214 rameter, see varnishd(1)
1215 sess.xid VCL >= 4.1
1217 Type: STRING
1218 Readable from: client, backend
1220 Unique ID of this session.
1222 storage
1224 storage.<name>.free_space
1225 Type: BYTES
1226 Readable from: client, backend
1228 Free space available in the named stevedore. Only available for the
1230 malloc stevedore.
1231 storage.<name>.happy
1233 Type: BOOL
1234 Readable from: client, backend
1236 Health status for the named stevedore. Not available in any of the
1238 current stevedores.
1239 storage.<name>.used_space
1241 Type: BYTES
1242 Readable from: client, backend
1244 Used space in the named stevedore. Only available for the malloc
1246 stevedore.
1247 HTTP response status
1249 A HTTP status code has 3 digits XYZ where X must be between 1 and 5 in‐
1250 cluded. Since it is not uncommon to see HTTP clients or servers rely‐
1251 ing on non-standard or even invalid status codes, Varnish can work with
1252 any status between 100 and 999.
1253 Within VCL code it is even possible to use status codes in the form
1255 VWXYZ as long as the overall value is lower than 65536, but only the
1256 XYZ part will be sent to the client, by which time the X must also have
1257 become non-zero.
1258 The VWXYZ form of status codes can be communicate extra information in
1260 resp.status and beresp.status to return(synth(...)) and return(er‐
1261 ror(...)), to indicate which synthetic content to produce:
1262 sub vcl_recv {
1264 if ([...]) {
1265 return synth(12404);
1266 }
1267 }
1268 sub vcl_synth {
1270 if (resp.status == 12404) {
1271 [...] // this specific 404
1272 } else if (resp.status % 1000 == 404) {
1273 [...] // all other 404's
1274 }
1275 }
1276 The obj.status variable will inherit the VWXYZ form, but in a ban ex‐
1278 pression only the XYZ part will be available. The VWXYZ form is
1279 strictly limited to VCL execution.
1280 Assigning an HTTP standardized code to resp.status or beresp.status
1282 will also set resp.reason or beresp.reason to the corresponding status
1283 message.
1284
1286 • varnishd(1)
1287 • vcl(7)
1289
1291 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
1292 AS, Redpill Linpro and Varnish Software. This manual page is written
1293 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
1294 gstøl, Lasse Karstensen and others.
1295
1297 This document is licensed under the same license as Varnish itself. See
1298 LICENSE for details.
1299 • Copyright (c) 2006 Verdens Gang AS
1301 • Copyright (c) 2006-2021 Varnish Software AS
1303 VCL-VARIABLES(7)