1VCL-VARIABLES(7)                                              VCL-VARIABLES(7)
2
3
4

NAME

6       VCL-Variables - The complete album
7

DESCRIPTION

9       This is a list of all variables in the VCL language.
10
11       Variable names take the form scope.variable[.index], for instance:
12
13          req.url
14          beresp.http.date
15          client.ip
16
17       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
22   local, server, remote and client
23       These variables describe the network connection between the client  and
24       varnishd.
25
26       Without PROXY protocol:
27
28               client    server
29               remote    local
30                 v          v
31          CLIENT ------------ VARNISHD
32
33       With PROXY protocol:
34
35               client    server   remote     local
36                 v          v       v          v
37          CLIENT ------------ PROXY ------------ VARNISHD
38
39       client.identity
40          Type: STRING
41
42          Readable from: client, backend
43
44          Writable from: client
45
46          Identification of the client, used to load balance in the client di‐
47          rector.  Defaults to client.ip
48
49          This variable can be overwritten with more precise information,  for
50          instance extracted from a Cookie: header.
51
52       client.ip
53          Type: IP
54
55          Readable from: client, backend
56
57          The  client's  IP  address, either the same as remote.ip or what the
58          PROXY protocol told us.
59
60       server.hostname
61          Type: STRING
62
63          Readable from: all
64
65          The host name of the server, as returned by the gethostname(3)  sys‐
66          tem function.
67
68       server.identity
69          Type: STRING
70
71          Readable from: all
72
73          The identity of the server, as set by the -i parameter.
74
75          If  an -i parameter is not passed to varnishd, the return value from
76          gethostname(3) system function will be used.
77
78       server.ip
79          Type: IP
80
81          Readable from: client, backend
82
83          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
87       remote.ip
88          Type: IP
89
90          Readable from: client, backend
91
92          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
95          If  the  connection  is  a  UNIX  domain  socket,  the value will be
96          0.0.0.0:0
97
98       local.endpoint  VCL >= 4.1
99          Type: STRING
100
101          Readable from: client, backend
102
103          The address of the '-a' socket the session was accepted on.
104
105          If the argument was -a foo=:81 this would be ":81"
106
107       local.ip
108          Type: IP
109
110          Readable from: client, backend
111
112          The IP address (and port number) of the local end of the TCP connec‐
113          tion, for instance 192.168.1.1:81
114
115          If  the  connection  is  a  UNIX  domain  socket,  the value will be
116          0.0.0.0:0
117
118       local.socket    VCL >= 4.1
119          Type: STRING
120
121          Readable from: client, backend
122
123          The name of the '-a' socket the session was accepted on.
124
125          If the argument was -a foo=:81 this would be "foo".
126
127          Note that all '-a' gets a default name on the form a%d if no name is
128          provided.
129
130   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
135       req
136          Type: HTTP
137
138          Readable from: client
139
140          The  entire  request HTTP data structure.  Mostly useful for passing
141          to VMODs.
142
143       req.backend_hint
144          Type: BACKEND
145
146          Readable from: client
147
148          Writable from: client
149
150          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
156       req.can_gzip
157          Type: BOOL
158
159          Readable from: client
160
161          True if the client provided gzip or x-gzip  in  the  Accept-Encoding
162          header.
163
164       req.esi VCL <= 4.0
165          Type: BOOL
166
167          Readable from: client
168
169          Writable from: client
170
171          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
175       req.esi_level
176          Type: INT
177
178          Readable from: client
179
180          A count of how many levels of ESI requests we're currently at.
181
182       req.grace
183          Type: DURATION
184
185          Readable from: client
186
187          Writable from: client
188
189          Upper limit on the object grace.
190
191          During lookup the minimum of req.grace and the object's stored grace
192          value will be used as the object's grace.
193
194       req.hash
195          Type: BLOB
196
197          Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver
198
199          The hash key of this request.  Mostly useful for passing  to  VMODs,
200          but can also be useful for debugging hit/miss status.
201
202       req.hash_always_miss
203          Type: BOOL
204
205          Readable from: client
206
207          Writable from: client
208
209          Default: false.
210
211          Force a cache miss for this request, even if perfectly good matching
212          objects are in the cache.
213
214          This is useful to force-update the cache without invalidating exist‐
215          ing entries in case the fetch fails.
216
217       req.hash_ignore_busy
218          Type: BOOL
219
220          Readable from: client
221
222          Writable from: client
223
224          Default: false.
225
226          Ignore any busy object during cache lookup.
227
228          You only want to do this when you have two server looking up content
229          sideways from each other to avoid deadlocks.
230
231       req.hash_ignore_vary
232          Type: BOOL
233
234          Readable from: client
235
236          Writable from: client
237
238          Default: false.
239
240          Ignore objects vary headers during cache lookup.
241
242          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
247          Use with caution.
248
249       req.http.*
250          Type: HEADER
251
252          Readable from: client
253
254          Writable from: client
255
256          Unsetable from: client
257
258          The headers of request, things like req.http.date.
259
260          The RFCs allow multiple headers with the same name, and both set and
261          unset will remove all headers with the name given.
262
263          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
270       req.is_hitmiss
271          Type: BOOL
272
273          Readable from: client
274
275          If this request resulted in a hitmiss
276
277       req.is_hitpass
278          Type: BOOL
279
280          Readable from: client
281
282          If this request resulted in a hitpass
283
284       req.method
285          Type: STRING
286
287          Readable from: client
288
289          Writable from: client
290
291          The request method (e.g. "GET", "HEAD", ...)
292
293       req.proto       VCL <= 4.0
294          Type: STRING
295
296          Readable from: client
297
298          Writable from: client
299
300          The  HTTP protocol version used by the client, usually "HTTP/1.1" or
301          "HTTP/2.0".
302
303       req.proto       VCL >= 4.1
304          Type: STRING
305
306          Readable from: client
307
308          The HTTP protocol version used by the client, usually "HTTP/1.1"  or
309          "HTTP/2.0".
310
311       req.restarts
312          Type: INT
313
314          Readable from: client
315
316          A count of how many times this request has been restarted.
317
318       req.storage
319          Type: STEVEDORE
320
321          Readable from: client
322
323          Writable from: client
324
325          The storage backend to use to save this request body.
326
327       req.time
328          Type: TIME
329
330          Readable from: client
331
332          The  time  when  the  request  was  fully received, remains constant
333          across restarts.
334
335       req.transport
336          Type: STRING
337
338          Readable from: client
339
340          The transport protocol which brought this request.
341
342       req.ttl
343          Type: DURATION
344
345          Readable from: client
346
347          Writable from: client
348
349          Upper limit on the object age for cache lookups to return hit.
350
351       req.url
352          Type: STRING
353
354          Readable from: client
355
356          Writable from: client
357
358          The requested URL, for instance "/robots.txt".
359
360       req.xid
361          Type: INT
362
363          Readable from: client
364
365          Unique ID of this request.
366
367       req_top.http.*
368          Type: HEADER
369
370          Readable from: client
371
372          HTTP headers of the top-level request in a  tree  of  ESI  requests.
373          Identical to req.http. in non-ESI requests.
374
375          See req.http.* for general notes.
376
377       req_top.method
378          Type: STRING
379
380          Readable from: client
381
382          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
386       req_top.proto
387          Type: STRING
388
389          Readable from: client
390
391          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
394       req_top.time
395          Type: TIME
396
397          Readable from: client
398
399          The time when the top-level request was fully received, remains con‐
400          stant across restarts.
401
402       req_top.url
403          Type: STRING
404
405          Readable from: client
406
407          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
410   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
415       Slightly more fields are allowed through for  pass`  fetches  than  for
416       `miss` fetches, for instance ``Range.
417
418       bereq
419          Type: HTTP
420
421          Readable from: backend
422
423          The  entire  backend  request HTTP data structure.  Mostly useful as
424          argument to VMODs.
425
426       bereq.backend
427          Type: BACKEND
428
429          Readable from: vcl_pipe, backend
430
431          Writable from: vcl_pipe, backend
432
433          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
439       bereq.between_bytes_timeout
440          Type: DURATION
441
442          Readable from: backend
443
444          Writable from: backend
445
446          Default: .between_bytes_timeout attribute from  the  backend_defini‐
447          tion,  which  defaults  to  the between_bytes_timeout parameter, see
448          varnishd(1).
449
450          The time in seconds to wait between  each  received  byte  from  the
451          backend.  Not available in pipe mode.
452
453       bereq.body
454          Type: BODY
455
456          Unsetable from: vcl_backend_fetch
457
458          The request body.
459
460          Unset will also remove bereq.http.Content-Length.
461
462       bereq.connect_timeout
463          Type: DURATION
464
465          Readable from: vcl_pipe, backend
466
467          Writable from: vcl_pipe, backend
468
469          Default:  .connect_timeout  attribute  from  the backend_definition,
470          which defaults to the connect_timeout parameter, see varnishd(1).
471
472          The time in seconds to wait for a backend connection  to  be  estab‐
473          lished.
474
475       bereq.first_byte_timeout
476          Type: DURATION
477
478          Readable from: backend
479
480          Writable from: backend
481
482          Default:  .first_byte_timeout attribute from the backend_definition,
483          which defaults to the first_byte_timeout parameter, see varnishd(1).
484
485          The time in seconds to wait getting the first  byte  back  from  the
486          backend.  Not available in pipe mode.
487
488       bereq.hash
489          Type: BLOB
490
491          Readable from: vcl_pipe, backend
492
493          The hash key of this request, a copy of req.hash.
494
495       bereq.http.*
496          Type: HEADER
497
498          Readable from: vcl_pipe, backend
499
500          Writable from: vcl_pipe, backend
501
502          Unsetable from: vcl_pipe, backend
503
504          The headers to be sent to the backend.
505
506          See req.http.* for general notes.
507
508       bereq.is_bgfetch
509          Type: BOOL
510
511          Readable from: backend
512
513          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
516       bereq.is_hitmiss
517          Type: BOOL
518
519          Readable from: backend
520
521          If this backend request was caused by a hitmiss.
522
523       bereq.is_hitpass
524          Type: BOOL
525
526          Readable from: backend
527
528          If this backend request was caused by a hitpass.
529
530       bereq.method
531          Type: STRING
532
533          Readable from: vcl_pipe, backend
534
535          Writable from: vcl_pipe, backend
536
537          The request type (e.g. "GET", "HEAD").
538
539          Regular (non-pipe, non-pass) fetches are always "GET"
540
541       bereq.proto     VCL <= 4.0
542          Type: STRING
543
544          Readable from: vcl_pipe, backend
545
546          Writable from: vcl_pipe, backend
547
548          The HTTP protocol version, "HTTP/1.1" unless a pass or pipe  request
549          has "HTTP/1.0" in req.proto
550
551       bereq.proto     VCL >= 4.1
552          Type: STRING
553
554          Readable from: vcl_pipe, backend
555
556          The  HTTP protocol version, "HTTP/1.1" unless a pass or pipe request
557          has "HTTP/1.0" in req.proto
558
559       bereq.retries
560          Type: INT
561
562          Readable from: backend
563
564          A count of how many times this request has been retried.
565
566       bereq.time
567          Type: TIME
568
569          Readable from: vcl_pipe, backend
570
571          The time when we started preparing the first  backend  request,  re‐
572          mains constant across retries.
573
574       bereq.uncacheable
575          Type: BOOL
576
577          Readable from: backend
578
579          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
582       bereq.url
583          Type: STRING
584
585          Readable from: vcl_pipe, backend
586
587          Writable from: vcl_pipe, backend
588
589          The requested URL, copied from req.url
590
591       bereq.xid
592          Type: INT
593
594          Readable from: vcl_pipe, backend
595
596          Unique ID of this request.
597
598   beresp
599       The response received from the backend, one cache misses, the store ob‐
600       ject is built from beresp.
601
602       beresp
603          Type: HTTP
604
605          Readable from: vcl_backend_response, vcl_backend_error
606
607          The  entire backend response HTTP data structure, useful as argument
608          to VMOD functions.
609
610       beresp.age
611          Type: DURATION
612
613          Readable from: vcl_backend_response, vcl_backend_error
614
615          Default: Age header, or zero.
616
617          The age of the object.
618
619       beresp.backend
620          Type: BACKEND
621
622          Readable from: vcl_backend_response, vcl_backend_error
623
624          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
628       beresp.backend.ip       VCL <= 4.0
629          Type: IP
630
631          Readable from: vcl_backend_response
632
633          IP of the backend this response was fetched from.
634
635       beresp.backend.name
636          Type: STRING
637
638          Readable from: vcl_backend_response, vcl_backend_error
639
640          Name of the  backend  this  response  was  fetched  from.   Same  as
641          beresp.backend.
642
643       beresp.body
644          Type: BODY
645
646          Writable from: vcl_backend_error
647
648          For producing a synthetic body.
649
650       beresp.do_esi
651          Type: BOOL
652
653          Readable from: vcl_backend_response, vcl_backend_error
654
655          Writable from: vcl_backend_response, vcl_backend_error
656
657          Default: false.
658
659          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
664          It is a VCL error to use beresp.do_esi after setting beresp.filters.
665
666       beresp.do_gunzip
667          Type: BOOL
668
669          Readable from: vcl_backend_response, vcl_backend_error
670
671          Writable from: vcl_backend_response, vcl_backend_error
672
673          Default: false.
674
675          Set to true to gunzip the object while storing it in the cache.
676
677          If http_gzip_support is disabled, setting this variable has  no  ef‐
678          fect.
679
680          It  is a VCL error to use beresp.do_gunzip after setting beresp.fil‐
681          ters.
682
683       beresp.do_gzip
684          Type: BOOL
685
686          Readable from: vcl_backend_response, vcl_backend_error
687
688          Writable from: vcl_backend_response, vcl_backend_error
689
690          Default: false.
691
692          Set to true to gzip the object while storing it.
693
694          If http_gzip_support is disabled, setting this variable has  no  ef‐
695          fect.
696
697          It  is  a  VCL error to use beresp.do_gzip after setting beresp.fil‐
698          ters.
699
700       beresp.do_stream
701          Type: BOOL
702
703          Readable from: vcl_backend_response, vcl_backend_error
704
705          Writable from: vcl_backend_response, vcl_backend_error
706
707          Default: true.
708
709          Deliver the object to the client while  fetching  the  whole  object
710          into varnish.
711
712          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
716          This variable has no effect if beresp.do_esi is true or when the re‐
717          sponse body is empty.
718
719       beresp.filters
720          Type: STRING
721
722          Readable from: vcl_backend_response
723
724          Writable from: vcl_backend_response
725
726          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
732          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
736          The following VFP filters exist in varnish-cache:
737
738gzip: compress a body using gzip
739
740testgunzip: Test if a body is valid gzip and refuse it otherwise
741
742gunzip: Uncompress gzip content
743
744esi: ESI-process plain text content
745
746esi_gzip: Save gzipped snippets for efficient ESI-processing
747
748            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
752          Additional VFP filters are available from VMODs.
753
754          By default, beresp.filters is constructed as follows:
755
756gunzip gets added  for  gzipped  content  if  beresp.do_gunzip  or
757            beresp.do_esi are true.
758
759esi_gzip  gets  added  if  beresp.do_esi  is  true  together  with
760            beresp.do_gzip or content is already compressed.
761
762esi gets added if beresp.do_esi is true
763
764gzip gets added for uncompressed content if beresp.do_gzip is true
765
766testgunzip gets added for compressed content  if  beresp.do_gunzip
767            is false.
768
769          After  beresp.filters  is  set,  using  any  of  the beforementioned
770          beresp.do_* switches is a VCL error.
771
772       beresp.grace
773          Type: DURATION
774
775          Readable from: vcl_backend_response, vcl_backend_error
776
777          Writable from: vcl_backend_response, vcl_backend_error
778
779          Default:  Cache-Control  stale-while-revalidate  directive,  or  de‐
780          fault_grace parameter.
781
782          Set to a period to enable grace.
783
784       beresp.http.*
785          Type: HEADER
786
787          Readable from: vcl_backend_response, vcl_backend_error
788
789          Writable from: vcl_backend_response, vcl_backend_error
790
791          Unsetable from: vcl_backend_response, vcl_backend_error
792
793          The HTTP headers returned from the server.
794
795          See req.http.* for general notes.
796
797       beresp.keep
798          Type: DURATION
799
800          Readable from: vcl_backend_response, vcl_backend_error
801
802          Writable from: vcl_backend_response, vcl_backend_error
803
804          Default: default_keep parameter.
805
806          Set to a period to enable conditional backend requests.
807
808          The keep time is cache lifetime in addition to the ttl.
809
810          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
814       beresp.proto    VCL <= 4.0
815          Type: STRING
816
817          Readable from: vcl_backend_response, vcl_backend_error
818
819          Writable from: vcl_backend_response, vcl_backend_error
820
821          The HTTP protocol version the backend replied with.
822
823       beresp.proto    VCL >= 4.1
824          Type: STRING
825
826          Readable from: vcl_backend_response, vcl_backend_error
827
828          The HTTP protocol version the backend replied with.
829
830       beresp.reason
831          Type: STRING
832
833          Readable from: vcl_backend_response, vcl_backend_error
834
835          Writable from: vcl_backend_response, vcl_backend_error
836
837          The HTTP status message returned by the server.
838
839       beresp.status
840          Type: INT
841
842          Readable from: vcl_backend_response, vcl_backend_error
843
844          Writable from: vcl_backend_response, vcl_backend_error
845
846          The HTTP status code returned by the server.
847
848          More information in the HTTP response status section.
849
850       beresp.storage
851          Type: STEVEDORE
852
853          Readable from: vcl_backend_response, vcl_backend_error
854
855          Writable from: vcl_backend_response, vcl_backend_error
856
857          The storage backend to use to save this object.
858
859       beresp.storage_hint     VCL <= 4.0
860          Type: STRING
861
862          Readable from: vcl_backend_response, vcl_backend_error
863
864          Writable from: vcl_backend_response, vcl_backend_error
865
866          Deprecated since varnish 5.1 and discontinued since VCL 4.1 (varnish
867          6.0). Use beresp.storage instead.
868
869          Hint to Varnish that you want to save this object  to  a  particular
870          storage backend.
871
872       beresp.time
873          Type: TIME
874
875          Readable from: vcl_backend_response, vcl_backend_error
876
877          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
881       beresp.transit_buffer
882          Type: BYTES
883
884          Readable from: vcl_backend_response
885
886          Writable from: vcl_backend_response
887
888          Default: transit_buffer parameter, see varnishd(1).
889
890          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
894       beresp.ttl
895          Type: DURATION
896
897          Readable from: vcl_backend_response, vcl_backend_error
898
899          Writable from: vcl_backend_response, vcl_backend_error
900
901          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
905          The object's remaining time to live, in seconds.
906
907       beresp.uncacheable
908          Type: BOOL
909
910          Readable from: vcl_backend_response, vcl_backend_error
911
912          Writable from: vcl_backend_response, vcl_backend_error
913
914          Inherited from bereq.uncacheable, see there.
915
916          Setting this variable makes the object uncacheable.
917
918          This may may produce a hit-for-miss object in the cache.
919
920          Clearing the variable has no effect and will log the warning "Ignor‐
921          ing attempt to reset beresp.uncacheable".
922
923       beresp.was_304
924          Type: BOOL
925
926          Readable from: vcl_backend_response, vcl_backend_error
927
928          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
932   obj
933       This is the object we found in cache.  It cannot be modified.
934
935       obj.age
936          Type: DURATION
937
938          Readable from: vcl_hit, vcl_deliver
939
940          The age of the object.
941
942       obj.can_esi
943          Type: BOOL
944
945          Readable from: vcl_hit, vcl_deliver
946
947          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
951       obj.grace
952          Type: DURATION
953
954          Readable from: vcl_hit, vcl_deliver
955
956          The object's grace period in seconds.
957
958       obj.hits
959          Type: INT
960
961          Readable from: vcl_hit, vcl_deliver
962
963          The count of cache-hits on this object.
964
965          In vcl_deliver a value of 0 indicates a cache miss.
966
967       obj.http.*
968          Type: HEADER
969
970          Readable from: vcl_hit
971
972          The HTTP headers stored in the object.
973
974          See req.http.* for general notes.
975
976       obj.keep
977          Type: DURATION
978
979          Readable from: vcl_hit, vcl_deliver
980
981          The object's keep period in seconds.
982
983       obj.proto
984          Type: STRING
985
986          Readable from: vcl_hit
987
988          The HTTP protocol version stored in the object.
989
990       obj.reason
991          Type: STRING
992
993          Readable from: vcl_hit
994
995          The HTTP reason phrase stored in the object.
996
997       obj.status
998          Type: INT
999
1000          Readable from: vcl_hit
1001
1002          The HTTP status code stored in the object.
1003
1004          More information in the HTTP response status section.
1005
1006       obj.storage
1007          Type: STEVEDORE
1008
1009          Readable from: vcl_hit, vcl_deliver
1010
1011          The storage backend where this object is stored.
1012
1013       obj.time
1014          Type: TIME
1015
1016          Readable from: vcl_hit, vcl_deliver
1017
1018          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
1022       obj.ttl
1023          Type: DURATION
1024
1025          Readable from: vcl_hit, vcl_deliver
1026
1027          The object's remaining time to live, in seconds.
1028
1029       obj.uncacheable
1030          Type: BOOL
1031
1032          Readable from: vcl_deliver
1033
1034          Whether  the  object   is   uncacheable   (pass,   hit-for-pass   or
1035          hit-for-miss).
1036
1037   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
1041       With the exception of resp.body all resp.* variables available in  both
1042       vcl_deliver{} and vcl_synth{} as a matter of symmetry.
1043
1044       resp
1045          Type: HTTP
1046
1047          Readable from: vcl_deliver, vcl_synth
1048
1049          The  entire  response  HTTP  data  structure,  useful as argument to
1050          VMODs.
1051
1052       resp.body
1053          Type: BODY
1054
1055          Writable from: vcl_synth
1056
1057          To produce a synthetic response body, for instance for errors.
1058
1059       resp.do_esi     VCL >= 4.1
1060          Type: BOOL
1061
1062          Readable from: vcl_deliver, vcl_synth
1063
1064          Writable from: vcl_deliver, vcl_synth
1065
1066          Default: obj.can_esi
1067
1068          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
1072          It is a VCL error to use resp.do_esi after setting resp.filters.
1073
1074       resp.filters
1075          Type: STRING
1076
1077          Readable from: vcl_deliver, vcl_synth
1078
1079          Writable from: vcl_deliver, vcl_synth
1080
1081          List of VDP filters the resp.body will be pushed through.
1082
1083          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
1087          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
1091       resp.http.*
1092          Type: HEADER
1093
1094          Readable from: vcl_deliver, vcl_synth
1095
1096          Writable from: vcl_deliver, vcl_synth
1097
1098          Unsetable from: vcl_deliver, vcl_synth
1099
1100          The HTTP headers that will be returned.
1101
1102          See req.http.* for general notes.
1103
1104       resp.is_streaming
1105          Type: BOOL
1106
1107          Readable from: vcl_deliver, vcl_synth
1108
1109          Returns true when the response will be streamed while being  fetched
1110          from the backend.
1111
1112       resp.proto      VCL <= 4.0
1113          Type: STRING
1114
1115          Readable from: vcl_deliver, vcl_synth
1116
1117          Writable from: vcl_deliver, vcl_synth
1118
1119          The HTTP protocol version to use for the response.
1120
1121       resp.proto      VCL >= 4.1
1122          Type: STRING
1123
1124          Readable from: vcl_deliver, vcl_synth
1125
1126          The HTTP protocol version to use for the response.
1127
1128       resp.reason
1129          Type: STRING
1130
1131          Readable from: vcl_deliver, vcl_synth
1132
1133          Writable from: vcl_deliver, vcl_synth
1134
1135          The HTTP status message that will be returned.
1136
1137       resp.status
1138          Type: INT
1139
1140          Readable from: vcl_deliver, vcl_synth
1141
1142          Writable from: vcl_deliver, vcl_synth
1143
1144          The HTTP status code that will be returned.
1145
1146          More information in the HTTP response status section.
1147
1148          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
1152          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
1156          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
1163       resp.time
1164          Type: TIME
1165
1166          Readable from: vcl_deliver, vcl_synth
1167
1168          The time when we started preparing the response, just before  enter‐
1169          ing vcl_synth {} or vcl_deliver {}.
1170
1171   Special variables
1172       now
1173          Type: TIME
1174
1175          Readable from: all
1176
1177          The current time, in seconds since the UNIX epoch.
1178
1179          When converted to STRING in expressions it returns a formatted time‐
1180          stamp like Tue, 20 Feb 2018 09:30:31 GMT
1181
1182          now remains stable for the duration of any built-in  VCL  subroutine
1183          to make time-based calculations predictable and avoid edge cases.
1184
1185          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
1191   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
1198       sess.idle_send_timeout
1199          Type: DURATION
1200
1201          Readable from: client
1202
1203          Writable from: client
1204
1205          Send  timeout  for  individual pieces of data on client connections,
1206          defaults to the idle_send_timeout parameter, see varnishd(1)
1207
1208       sess.send_timeout
1209          Type: DURATION
1210
1211          Readable from: client
1212
1213          Writable from: client
1214
1215          Total  timeout  for  ordinary  HTTP1  responses,  defaults  to   the
1216          send_timeout parameter, see varnishd(1)
1217
1218       sess.timeout_idle
1219          Type: DURATION
1220
1221          Readable from: client
1222
1223          Writable from: client
1224
1225          Idle  timeout for this session, defaults to the timeout_idle parame‐
1226          ter, see varnishd(1)
1227
1228       sess.timeout_linger
1229          Type: DURATION
1230
1231          Readable from: client
1232
1233          Writable from: client
1234
1235          Linger timeout for this session, defaults to the timeout_linger  pa‐
1236          rameter, see varnishd(1)
1237
1238       sess.xid        VCL >= 4.1
1239          Type: INT
1240
1241          Readable from: client, backend
1242
1243          Unique ID of this session.
1244
1245   storage
1246       storage.<name>.free_space
1247          Type: BYTES
1248
1249          Readable from: client, backend
1250
1251          Free  space available in the named stevedore. Only available for the
1252          malloc stevedore.
1253
1254       storage.<name>.happy
1255          Type: BOOL
1256
1257          Readable from: client, backend
1258
1259          Health status for the named stevedore. Not available in any  of  the
1260          current stevedores.
1261
1262       storage.<name>.used_space
1263          Type: BYTES
1264
1265          Readable from: client, backend
1266
1267          Used  space  in  the  named stevedore. Only available for the malloc
1268          stevedore.
1269
1270   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
1276       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
1281       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
1285          sub vcl_recv {
1286              if ([...]) {
1287                  return synth(12404);
1288              }
1289          }
1290
1291          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
1299       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
1303       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

SEE ALSO

1308varnishd(1)
1309
1310vcl(7)
1311

HISTORY

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
1322       • Copyright (c) 2006 Verdens Gang AS
1323
1324       • Copyright (c) 2006-2021 Varnish Software AS
1325
1326
1327
1328
1329                                                              VCL-VARIABLES(7)
Impressum