[master] 948cf26de doc: Sort VCL variables alphabetically
Dridi Boukelmoune
dridi.boukelmoune at gmail.com
Wed Dec 15 16:45:09 UTC 2021
commit 948cf26deb09848aade89d7f0c1f7e7a669f592a
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date: Wed Dec 15 17:17:07 2021 +0100
doc: Sort VCL variables alphabetically
They are grouped by categories and that hasn't changed, and the order
of groups haven't changed. All occurrences of foo.* variables are sorted
alphabetically instead of approximately by relationship between each
other.
Inside the first group, variables are now ordered based on the PROXY
protocol diagram:
- client
- server
- remote
- local
A note was added and is hopefully visible enough to maintain this order.
You can verify that nothing changed:
$ COMMIT=<this-commit-hash>
$ git show $COMMIT~:doc/sphinx/reference/vcl_var.rst |
sed '/^$/d' |
sort |
sha1sum
3400130e88c0456b3bc779b9dfeeff09e130efa3
$ git show ${COMMIT}:doc/sphinx/reference/vcl_var.rst |
sed '/^$/d ; /.. NOTE:/d' |
sort |
sha1sum
3400130e88c0456b3bc779b9dfeeff09e130efa3
Use whatever alternative to sha1sum your system may provide.
diff --git a/doc/sphinx/reference/vcl_var.rst b/doc/sphinx/reference/vcl_var.rst
index 02f71001f..049c1f3cf 100644
--- a/doc/sphinx/reference/vcl_var.rst
+++ b/doc/sphinx/reference/vcl_var.rst
@@ -3,6 +3,8 @@
SPDX-License-Identifier: BSD-2-Clause
See LICENSE file for full text of license
+.. NOTE: please maintain lexicographic order of foo.* variable names
+
.. _vcl_variables:
@@ -27,65 +29,6 @@ With PROXY protocol::
CLIENT ------------ PROXY ------------ VARNISHD
-local.ip
-
- Type: IP
-
- Readable from: client, backend
-
- The IP address (and port number) of the local end of the
- TCP connection, for instance ``192.168.1.1:81``
-
- If the connection is a UNIX domain socket, the value
- will be ``0.0.0.0:0``
-
-local.endpoint ``VCL >= 4.1``
-
- Type: STRING
-
- Readable from: client, backend
-
- The address of the '-a' socket the session was accepted on.
-
- If the argument was ``-a foo=:81`` this would be ":81"
-
-
-local.socket ``VCL >= 4.1``
-
- Type: STRING
-
- Readable from: client, backend
-
- The name of the '-a' socket the session was accepted on.
-
- If the argument was ``-a foo=:81`` this would be "foo".
-
- Note that all '-a' gets a default name on the form ``a%d``
- if no name is provided.
-
-remote.ip
-
- Type: IP
-
- Readable from: client, backend
-
- The IP address of the other end of the TCP connection.
- This can either be the clients IP, or the outgoing IP
- of a proxy server.
-
- If the connection is a UNIX domain socket, the value
- will be ``0.0.0.0:0``
-
-client.ip
-
- Type: IP
-
- Readable from: client, backend
-
-
- The client's IP address, either the same as ``remote.ip``
- or what the PROXY protocol told us.
-
client.identity
Type: STRING
@@ -103,15 +46,14 @@ client.identity
header.
-server.ip
+client.ip
Type: IP
Readable from: client, backend
- The IP address of the socket on which the client
- connection was received, either the same as ``server.ip``
+ The client's IP address, either the same as ``remote.ip``
or what the PROXY protocol told us.
@@ -136,126 +78,127 @@ server.identity
If an ``-i`` parameter is not passed to varnishd, the return
value from `gethostname(3)` system function will be used.
-req and req_top
-~~~~~~~~~~~~~~~
-These variables describe the present request, and when ESI:include
-requests are being processed, req_top points to the request received
-from the client.
+server.ip
-req
+ Type: IP
- Type: HTTP
+ Readable from: client, backend
- Readable from: client
+ The IP address of the socket on which the client
+ connection was received, either the same as ``server.ip``
+ or what the PROXY protocol told us.
- The entire request HTTP data structure.
- Mostly useful for passing to VMODs.
+remote.ip
-req.method
+ Type: IP
- Type: STRING
+ Readable from: client, backend
- Readable from: client
+ The IP address of the other end of the TCP connection.
+ This can either be the clients IP, or the outgoing IP
+ of a proxy server.
- Writable from: client
+ If the connection is a UNIX domain socket, the value
+ will be ``0.0.0.0:0``
- The request method (e.g. "GET", "HEAD", ...)
+local.endpoint ``VCL >= 4.1``
+ Type: STRING
-req.hash
+ Readable from: client, backend
- Type: BLOB
+ The address of the '-a' socket the session was accepted on.
- Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver
+ If the argument was ``-a foo=:81`` this would be ":81"
- The hash key of this request.
- Mostly useful for passing to VMODs, but can also be useful
- for debugging hit/miss status.
+local.ip
+ Type: IP
-req.url
+ Readable from: client, backend
- Type: STRING
+ The IP address (and port number) of the local end of the
+ TCP connection, for instance ``192.168.1.1:81``
- Readable from: client
+ If the connection is a UNIX domain socket, the value
+ will be ``0.0.0.0:0``
- Writable from: client
+local.socket ``VCL >= 4.1``
- The requested URL, for instance "/robots.txt".
+ Type: STRING
+ Readable from: client, backend
-req.proto ``VCL <= 4.0``
+ The name of the '-a' socket the session was accepted on.
- Type: STRING
+ If the argument was ``-a foo=:81`` this would be "foo".
- Readable from: client
+ Note that all '-a' gets a default name on the form ``a%d``
+ if no name is provided.
- Writable from: client
- The HTTP protocol version used by the client, usually "HTTP/1.1"
- or "HTTP/2.0".
+req and req_top
+~~~~~~~~~~~~~~~
-req.proto ``VCL >= 4.1``
+These variables describe the present request, and when ESI:include
+requests are being processed, req_top points to the request received
+from the client.
- Type: STRING
+req
+
+ Type: HTTP
Readable from: client
- The HTTP protocol version used by the client, usually "HTTP/1.1"
- or "HTTP/2.0".
+
+ The entire request HTTP data structure.
+ Mostly useful for passing to VMODs.
-req.http.*
+req.backend_hint
- Type: HEADER
+ Type: BACKEND
Readable from: client
Writable from: client
- Unsetable from: client
-
-
- The headers of request, things like ``req.http.date``.
-
- The RFCs allow multiple headers with the same name, and both
- ``set`` and ``unset`` will remove *all* headers with the name
- given.
-
- The header name ``*`` is a VCL symbol and as such cannot, for
- example, start with a numeral. To work with valid header that
- can't be represented as VCL symbols it is possible to quote the
- name, like ``req.http."grammatically.valid"``. None of the HTTP
- headers present in IANA registries need to be quoted, so the
- quoted syntax is discouraged but available for interoperability.
+ Set bereq.backend to this if we attempt to fetch.
+ When set to a director, reading this variable returns
+ an actual backend if the director has resolved immediately,
+ or the director otherwise.
+ When used in string context, returns the name of the director
+ or backend, respectively.
-req.restarts
+req.can_gzip
- Type: INT
+ Type: BOOL
Readable from: client
-
- A count of how many times this request has been restarted.
+ True if the client provided ``gzip`` or ``x-gzip`` in the
+ ``Accept-Encoding`` header.
-req.storage
+req.esi ``VCL <= 4.0``
- Type: STEVEDORE
+ Type: BOOL
Readable from: client
Writable from: client
-
- The storage backend to use to save this request body.
+ Set to ``false`` to disable ESI processing
+ regardless of any value in beresp.do_esi. Defaults
+ to ``true``. This variable is replaced by ``resp.do_esi``
+ in VCL 4.1.
req.esi_level
@@ -266,17 +209,6 @@ req.esi_level
A count of how many levels of ESI requests we're currently at.
-req.ttl
-
- Type: DURATION
-
- Readable from: client
-
- Writable from: client
-
-
- Upper limit on the object age for cache lookups to return hit.
-
req.grace
@@ -293,51 +225,33 @@ req.grace
grace value will be used as the object's grace.
-req.xid
-
- Type: STRING
-
- Readable from: client
-
- Unique ID of this request.
+req.hash
-req.esi ``VCL <= 4.0``
+ Type: BLOB
- Type: BOOL
+ Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver
- Readable from: client
- Writable from: client
+ The hash key of this request.
+ Mostly useful for passing to VMODs, but can also be useful
+ for debugging hit/miss status.
- Set to ``false`` to disable ESI processing
- regardless of any value in beresp.do_esi. Defaults
- to ``true``. This variable is replaced by ``resp.do_esi``
- in VCL 4.1.
-req.can_gzip
+req.hash_always_miss
Type: BOOL
Readable from: client
- True if the client provided ``gzip`` or ``x-gzip`` in the
- ``Accept-Encoding`` header.
-
-
-req.backend_hint
-
- Type: BACKEND
+ Writable from: client
- Readable from: client
+ Default: ``false``.
- Writable from: client
+ Force a cache miss for this request, even if perfectly
+ good matching objects are in the cache.
- Set bereq.backend to this if we attempt to fetch.
- When set to a director, reading this variable returns
- an actual backend if the director has resolved immediately,
- or the director otherwise.
- When used in string context, returns the name of the director
- or backend, respectively.
+ This is useful to force-update the cache without invalidating
+ existing entries in case the fetch fails.
req.hash_ignore_busy
@@ -377,23 +291,32 @@ req.hash_ignore_vary
Use with caution.
-req.hash_always_miss
+req.http.*
- Type: BOOL
+ Type: HEADER
Readable from: client
Writable from: client
- Default: ``false``.
-
- Force a cache miss for this request, even if perfectly
- good matching objects are in the cache.
+ Unsetable from: client
- This is useful to force-update the cache without invalidating
- existing entries in case the fetch fails.
-req.is_hitmiss
+ The headers of request, things like ``req.http.date``.
+
+ The RFCs allow multiple headers with the same name, and both
+ ``set`` and ``unset`` will remove *all* headers with the name
+ given.
+
+ The header name ``*`` is a VCL symbol and as such cannot, for
+ example, start with a numeral. To work with valid header that
+ can't be represented as VCL symbols it is possible to quote the
+ name, like ``req.http."grammatically.valid"``. None of the HTTP
+ headers present in IANA registries need to be quoted, so the
+ quoted syntax is discouraged but available for interoperability.
+
+
+req.is_hitmiss
Type: BOOL
@@ -401,6 +324,7 @@ req.is_hitmiss
If this request resulted in a hitmiss
+
req.is_hitpass
Type: BOOL
@@ -409,210 +333,221 @@ req.is_hitpass
If this request resulted in a hitpass
-req.time
- Type: TIME
+req.method
+
+ Type: STRING
Readable from: client
- The time when the request was fully received, remains constant
- across restarts.
+ Writable from: client
-req_top.method
+
+ The request method (e.g. "GET", "HEAD", ...)
+
+
+req.proto ``VCL <= 4.0``
Type: STRING
Readable from: client
- The request method of the top-level request in a tree
- of ESI requests. (e.g. "GET", "HEAD").
- Identical to req.method in non-ESI requests.
+ Writable from: client
+ The HTTP protocol version used by the client, usually "HTTP/1.1"
+ or "HTTP/2.0".
-req_top.url
+req.proto ``VCL >= 4.1``
Type: STRING
Readable from: client
- The requested URL of the top-level request in a tree
- of ESI requests.
- Identical to req.url in non-ESI requests.
+ The HTTP protocol version used by the client, usually "HTTP/1.1"
+ or "HTTP/2.0".
-req_top.http.*
+req.restarts
- Type: HEADER
+ Type: INT
Readable from: client
- HTTP headers of the top-level request in a tree of ESI requests.
- Identical to req.http. in non-ESI requests.
- See ``req.http.*`` for general notes.
+ A count of how many times this request has been restarted.
-req_top.proto
+req.storage
- Type: STRING
+ Type: STEVEDORE
Readable from: client
- HTTP protocol version of the top-level request in a tree of
- ESI requests.
- Identical to req.proto in non-ESI requests.
+ Writable from: client
-req_top.time
+
+ The storage backend to use to save this request body.
+
+
+req.time
Type: TIME
Readable from: client
- The time when the top-level request was fully received,
- remains constant across restarts.
+ The time when the request was fully received, remains constant
+ across restarts.
-bereq
-~~~~~
-This is the request we send to the backend, it is built from the
-clients ``req.*`` fields by filtering out "per-hop" fields which
-should not be passed along (``Connection:``, ``Range:`` and similar).
+req.ttl
-Slightly more fields are allowed through for ``pass` fetches
-than for `miss` fetches, for instance ``Range``.
+ Type: DURATION
-bereq
+ Readable from: client
- Type: HTTP
+ Writable from: client
- Readable from: backend
- The entire backend request HTTP data structure.
- Mostly useful as argument to VMODs.
+ Upper limit on the object age for cache lookups to return hit.
-bereq.xid
+req.url
Type: STRING
- Readable from: vcl_pipe, backend
+ Readable from: client
- Unique ID of this request.
+ Writable from: client
-bereq.retries
+ The requested URL, for instance "/robots.txt".
- Type: INT
- Readable from: backend
+req.xid
- A count of how many times this request has been retried.
+ Type: STRING
+ Readable from: client
-bereq.backend
+ Unique ID of this request.
- Type: BACKEND
- Readable from: vcl_pipe, backend
+req_top.http.*
- Writable from: vcl_pipe, backend
+ Type: HEADER
- This is the backend or director we attempt to fetch from.
- When set to a director, reading this variable returns
- an actual backend if the director has resolved immediately,
- or the director otherwise.
- When used in string context, returns the name of the director
- or backend, respectively.
+ Readable from: client
+ HTTP headers of the top-level request in a tree of ESI requests.
+ Identical to req.http. in non-ESI requests.
-bereq.body
+ See ``req.http.*`` for general notes.
- Type: BODY
- Unsetable from: vcl_backend_fetch
+req_top.method
- The request body.
+ Type: STRING
- Unset will also remove ``bereq.http.Content-Length``.
+ Readable from: client
-bereq.hash
+ The request method of the top-level request in a tree
+ of ESI requests. (e.g. "GET", "HEAD").
+ Identical to req.method in non-ESI requests.
- Type: BLOB
- Readable from: vcl_pipe, backend
+req_top.proto
- The hash key of this request, a copy of ``req.hash``.
+ Type: STRING
+ Readable from: client
-bereq.method
+ HTTP protocol version of the top-level request in a tree of
+ ESI requests.
+ Identical to req.proto in non-ESI requests.
- Type: STRING
- Readable from: vcl_pipe, backend
+req_top.time
- Writable from: vcl_pipe, backend
+ Type: TIME
- The request type (e.g. "GET", "HEAD").
+ Readable from: client
- Regular (non-pipe, non-pass) fetches are always "GET"
+ The time when the top-level request was fully received,
+ remains constant across restarts.
-bereq.url
+req_top.url
Type: STRING
- Readable from: vcl_pipe, backend
+ Readable from: client
- Writable from: vcl_pipe, backend
+ The requested URL of the top-level request in a tree
+ of ESI requests.
+ Identical to req.url in non-ESI requests.
- The requested URL, copied from ``req.url``
+bereq
+~~~~~
-bereq.proto ``VCL <= 4.0``
+This is the request we send to the backend, it is built from the
+clients ``req.*`` fields by filtering out "per-hop" fields which
+should not be passed along (``Connection:``, ``Range:`` and similar).
- Type: STRING
+Slightly more fields are allowed through for ``pass` fetches
+than for `miss` fetches, for instance ``Range``.
- Readable from: vcl_pipe, backend
+bereq
- Writable from: vcl_pipe, backend
+ Type: HTTP
- The HTTP protocol version, "HTTP/1.1" unless a pass or pipe
- request has "HTTP/1.0" in ``req.proto``
+ Readable from: backend
-bereq.proto ``VCL >= 4.1``
+ The entire backend request HTTP data structure.
+ Mostly useful as argument to VMODs.
- Type: STRING
+
+bereq.backend
+
+ Type: BACKEND
Readable from: vcl_pipe, backend
- The HTTP protocol version, "HTTP/1.1" unless a pass or pipe
- request has "HTTP/1.0" in ``req.proto``
+ Writable from: vcl_pipe, backend
+ This is the backend or director we attempt to fetch from.
+ When set to a director, reading this variable returns
+ an actual backend if the director has resolved immediately,
+ or the director otherwise.
+ When used in string context, returns the name of the director
+ or backend, respectively.
-bereq.http.*
- Type: HEADER
+bereq.between_bytes_timeout
- Readable from: vcl_pipe, backend
+ Type: DURATION
- Writable from: vcl_pipe, backend
+ Readable from: backend
- Unsetable from: vcl_pipe, backend
+ Writable from: backend
- The headers to be sent to the backend.
+ Default: ``.between_bytes_timeout`` attribute from the
+ :ref:`backend_definition`, which defaults to the
+ ``between_bytes_timeout`` parameter, see :ref:`varnishd(1)`.
- See ``req.http.*`` for general notes.
+ The time in seconds to wait between each received byte from the
+ backend. Not available in pipe mode.
-bereq.uncacheable
- Type: BOOL
+bereq.body
- Readable from: backend
+ Type: BODY
+ Unsetable from: vcl_backend_fetch
- Indicates whether this request is uncacheable due to a
- `pass` in the client side or a hit on an hit-for-pass object.
+ The request body.
+ Unset will also remove ``bereq.http.Content-Length``.
bereq.connect_timeout
@@ -646,20 +581,28 @@ bereq.first_byte_timeout
from the backend. Not available in pipe mode.
-bereq.between_bytes_timeout
+bereq.hash
- Type: DURATION
+ Type: BLOB
- Readable from: backend
+ Readable from: vcl_pipe, backend
- Writable from: backend
+ The hash key of this request, a copy of ``req.hash``.
- Default: ``.between_bytes_timeout`` attribute from the
- :ref:`backend_definition`, which defaults to the
- ``between_bytes_timeout`` parameter, see :ref:`varnishd(1)`.
- The time in seconds to wait between each received byte from the
- backend. Not available in pipe mode.
+bereq.http.*
+
+ Type: HEADER
+
+ Readable from: vcl_pipe, backend
+
+ Writable from: vcl_pipe, backend
+
+ Unsetable from: vcl_pipe, backend
+
+ The headers to be sent to the backend.
+
+ See ``req.http.*`` for general notes.
bereq.is_bgfetch
@@ -672,6 +615,7 @@ bereq.is_bgfetch
grace, and this fetch was kicked of in the background to get
a fresh copy.
+
bereq.is_hitmiss
Type: BOOL
@@ -680,6 +624,7 @@ bereq.is_hitmiss
If this backend request was caused by a hitmiss.
+
bereq.is_hitpass
Type: BOOL
@@ -688,92 +633,156 @@ bereq.is_hitpass
If this backend request was caused by a hitpass.
-bereq.time
- Type: TIME
+bereq.method
- Readable from: backend
+ Type: STRING
- The time when we started preparing the first backend request,
- remains constant across retries.
+ Readable from: vcl_pipe, backend
-beresp
-~~~~~~
+ Writable from: vcl_pipe, backend
-The response received from the backend, one cache misses, the
-store object is built from ``beresp``.
+ The request type (e.g. "GET", "HEAD").
-beresp
+ Regular (non-pipe, non-pass) fetches are always "GET"
- Type: HTTP
- Readable from: vcl_backend_response, vcl_backend_error
+bereq.proto ``VCL <= 4.0``
- The entire backend response HTTP data structure, useful as
- argument to VMOD functions.
+ Type: STRING
-beresp.body
+ Readable from: vcl_pipe, backend
- Type: BODY
+ Writable from: vcl_pipe, backend
- Writable from: vcl_backend_error
+ The HTTP protocol version, "HTTP/1.1" unless a pass or pipe
+ request has "HTTP/1.0" in ``req.proto``
- For producing a synthetic body.
+bereq.proto ``VCL >= 4.1``
-beresp.proto ``VCL <= 4.0``
+ Type: STRING
+
+ Readable from: vcl_pipe, backend
+
+ The HTTP protocol version, "HTTP/1.1" unless a pass or pipe
+ request has "HTTP/1.0" in ``req.proto``
+
+
+bereq.retries
+
+ Type: INT
+
+ Readable from: backend
+
+ A count of how many times this request has been retried.
+
+
+bereq.time
+
+ Type: TIME
+
+ Readable from: backend
+
+ The time when we started preparing the first backend request,
+ remains constant across retries.
+
+
+bereq.uncacheable
+
+ Type: BOOL
+
+ Readable from: backend
+
+
+ Indicates whether this request is uncacheable due to a
+ `pass` in the client side or a hit on an hit-for-pass object.
+
+
+bereq.url
Type: STRING
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_pipe, backend
- Writable from: vcl_backend_response, vcl_backend_error
+ Writable from: vcl_pipe, backend
- The HTTP protocol version the backend replied with.
+ The requested URL, copied from ``req.url``
-beresp.proto ``VCL >= 4.1``
+
+bereq.xid
Type: STRING
- Readable from: vcl_backend_response, vcl_backend_error
+ Readable from: vcl_pipe, backend
- The HTTP protocol version the backend replied with.
+ Unique ID of this request.
-beresp.status
+beresp
+~~~~~~
- Type: INT
+The response received from the backend, one cache misses, the
+store object is built from ``beresp``.
+
+beresp
+
+ Type: HTTP
Readable from: vcl_backend_response, vcl_backend_error
- Writable from: vcl_backend_response, vcl_backend_error
+ The entire backend response HTTP data structure, useful as
+ argument to VMOD functions.
- The HTTP status code returned by the server.
+beresp.age
- More information in the `HTTP response status`_ section.
+ Type: DURATION
-beresp.reason
+ Readable from: vcl_backend_response, vcl_backend_error
- Type: STRING
+ Default: Age header, or zero.
+
+ The age of the object.
+
+
+beresp.backend
+
+ Type: BACKEND
Readable from: vcl_backend_response, vcl_backend_error
- Writable from: vcl_backend_response, vcl_backend_error
+ This is the backend we fetched from. If bereq.backend
+ was set to a director, this will be the backend selected
+ by the director.
+ When used in string context, returns its name.
- The HTTP status message returned by the server.
-beresp.http.*
+beresp.backend.ip ``VCL <= 4.0``
- Type: HEADER
+ Type: IP
+
+ Readable from: vcl_backend_response
+
+ IP of the backend this response was fetched from.
+
+
+beresp.backend.name
+
+ Type: STRING
Readable from: vcl_backend_response, vcl_backend_error
- Writable from: vcl_backend_response, vcl_backend_error
+ Name of the backend this response was fetched from.
+ Same as beresp.backend.
- Unsetable from: vcl_backend_response, vcl_backend_error
- The HTTP headers returned from the server.
+beresp.body
+
+ Type: BODY
+
+ Writable from: vcl_backend_error
+
+ For producing a synthetic body.
- See ``req.http.*`` for general notes.
beresp.do_esi
@@ -793,7 +802,8 @@ beresp.do_esi
It is a VCL error to use beresp.do_esi after setting beresp.filters.
-beresp.do_stream
+
+beresp.do_gunzip
Type: BOOL
@@ -801,17 +811,16 @@ beresp.do_stream
Writable from: vcl_backend_response, vcl_backend_error
- Default: ``true``.
+ Default: ``false``.
- Deliver the object to the client while fetching the whole
- object into varnish.
+ Set to ``true`` to gunzip the object while storing it in the
+ cache.
- For uncacheable objects, storage for parts of the body which
- have been sent to the client may get freed early, depending
- on the storage engine used.
+ If ``http_gzip_support`` is disabled, setting this variable
+ has no effect.
+
+ It is a VCL error to use beresp.do_gunzip after setting beresp.filters.
- This variable has no effect if beresp.do_esi is true or when
- the response body is empty.
beresp.do_gzip
@@ -830,7 +839,8 @@ beresp.do_gzip
It is a VCL error to use beresp.do_gzip after setting beresp.filters.
-beresp.do_gunzip
+
+beresp.do_stream
Type: BOOL
@@ -838,83 +848,106 @@ beresp.do_gunzip
Writable from: vcl_backend_response, vcl_backend_error
- Default: ``false``.
+ Default: ``true``.
- Set to ``true`` to gunzip the object while storing it in the
- cache.
+ Deliver the object to the client while fetching the whole
+ object into varnish.
- If ``http_gzip_support`` is disabled, setting this variable
- has no effect.
+ For uncacheable objects, storage for parts of the body which
+ have been sent to the client may get freed early, depending
+ on the storage engine used.
- It is a VCL error to use beresp.do_gunzip after setting beresp.filters.
+ This variable has no effect if beresp.do_esi is true or when
+ the response body is empty.
-beresp.was_304
- Type: BOOL
+beresp.filters
- Readable from: vcl_backend_response, vcl_backend_error
+ Type: STRING
+ Readable from: vcl_backend_response
- When ``true`` this indicates that we got a 304 response
- to our conditional fetch from the backend and turned
- that into ``beresp.status = 200``
+ Writable from: vcl_backend_response
-beresp.uncacheable
+ List of Varnish Fetch Processor (VFP) filters the beresp.body
+ will be pulled through. The order left to right signifies
+ processing from backend to cache, iow the leftmost filter is
+ run first on the body as received from the backend after
+ decoding of any transfer encodings.
- Type: BOOL
+ VFP Filters change the body before going into the cache and/or
+ being handed to the client side, where it may get processed
+ again by resp.filters.
- Readable from: vcl_backend_response, vcl_backend_error
+ The following VFP filters exist in varnish-cache:
- Writable from: vcl_backend_response, vcl_backend_error
+ * ``gzip``: compress a body using gzip
- Inherited from bereq.uncacheable, see there.
+ * ``testgunzip``: Test if a body is valid gzip and refuse it
+ otherwise
- Setting this variable makes the object uncacheable.
+ * ``gunzip``: Uncompress gzip content
- This may may produce a hit-for-miss object in the cache.
+ * ``esi``: ESI-process plain text content
- Clearing the variable has no effect and will log the warning
- "Ignoring attempt to reset beresp.uncacheable".
+ * ``esi_gzip``: Save gzipped snippets for efficient
+ ESI-processing
+ This filter enables stitching together ESI from individually
+ gzipped fragments, saving processing power for
+ re-compression on the client side at the expense of some
+ compression efficiency.
-beresp.ttl
+ Additional VFP filters are available from VMODs.
- Type: DURATION
+ By default, beresp.filters is constructed as follows:
- Readable from: vcl_backend_response, vcl_backend_error
+ * ``gunzip`` gets added for gzipped content if
+ ``beresp.do_gunzip`` or ``beresp.do_esi`` are true.
- Writable from: vcl_backend_response, vcl_backend_error
+ * ``esi_gzip`` gets added if ``beresp.do_esi`` is true
+ together with ``beresp.do_gzip`` or content is already
+ compressed.
- Default: Cache-Control ``s-maxage`` or ``max-age`` directives,
- or a value computed from the Expires header's deadline, or the
- ``default_ttl`` parameter.
+ * ``esi`` gets added if ``beresp.do_esi`` is true
- The object's remaining time to live, in seconds.
+ * ``gzip`` gets added for uncompressed content if
+ ``beresp.do_gzip`` is true
+ * ``testgunzip`` gets added for compressed content if
+ ``beresp.do_gunzip`` is false.
+
+ After beresp.filters is set, using any of the beforementioned
+ ``beresp.do_*`` switches is a VCL error.
-beresp.age
+
+beresp.grace
Type: DURATION
Readable from: vcl_backend_response, vcl_backend_error
- Default: Age header, or zero.
+ Writable from: vcl_backend_response, vcl_backend_error
- The age of the object.
+ Default: Cache-Control ``stale-while-revalidate`` directive,
+ or ``default_grace`` parameter.
+ Set to a period to enable grace.
-beresp.grace
- Type: DURATION
+beresp.http.*
+
+ Type: HEADER
Readable from: vcl_backend_response, vcl_backend_error
Writable from: vcl_backend_response, vcl_backend_error
- Default: Cache-Control ``stale-while-revalidate`` directive,
- or ``default_grace`` parameter.
+ Unsetable from: vcl_backend_response, vcl_backend_error
- Set to a period to enable grace.
+ The HTTP headers returned from the server.
+
+ See ``req.http.*`` for general notes.
beresp.keep
@@ -936,35 +969,49 @@ beresp.keep
requests to the backend to refresh them.
-beresp.backend
+beresp.proto ``VCL <= 4.0``
- Type: BACKEND
+ Type: STRING
Readable from: vcl_backend_response, vcl_backend_error
- This is the backend we fetched from. If bereq.backend
- was set to a director, this will be the backend selected
- by the director.
- When used in string context, returns its name.
+ Writable from: vcl_backend_response, vcl_backend_error
+ The HTTP protocol version the backend replied with.
-beresp.backend.name
+
+beresp.proto ``VCL >= 4.1``
Type: STRING
Readable from: vcl_backend_response, vcl_backend_error
- Name of the backend this response was fetched from.
- Same as beresp.backend.
+ The HTTP protocol version the backend replied with.
-beresp.backend.ip ``VCL <= 4.0``
+beresp.reason
- Type: IP
+ Type: STRING
- Readable from: vcl_backend_response
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+ The HTTP status message returned by the server.
+
+
+beresp.status
+
+ Type: INT
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+ The HTTP status code returned by the server.
+
+ More information in the `HTTP response status`_ section.
- IP of the backend this response was fetched from.
beresp.storage
@@ -992,74 +1039,61 @@ beresp.storage_hint ``VCL <= 4.0``
Hint to Varnish that you want to save this object to a
particular storage backend.
-beresp.filters
- Type: STRING
+beresp.time
- Readable from: vcl_backend_response
+ Type: TIME
- Writable from: vcl_backend_response
+ Readable from: vcl_backend_response, vcl_backend_error
- List of Varnish Fetch Processor (VFP) filters the beresp.body
- will be pulled through. The order left to right signifies
- processing from backend to cache, iow the leftmost filter is
- run first on the body as received from the backend after
- decoding of any transfer encodings.
+ When the backend headers were fully received just before
+ ``vcl_backend_response {}`` was entered, or when
+ ``vcl_backend_error {}`` was entered.
- VFP Filters change the body before going into the cache and/or
- being handed to the client side, where it may get processed
- again by resp.filters.
- The following VFP filters exist in varnish-cache:
+beresp.ttl
- * ``gzip``: compress a body using gzip
+ Type: DURATION
- * ``testgunzip``: Test if a body is valid gzip and refuse it
- otherwise
+ Readable from: vcl_backend_response, vcl_backend_error
- * ``gunzip``: Uncompress gzip content
+ Writable from: vcl_backend_response, vcl_backend_error
- * ``esi``: ESI-process plain text content
+ Default: Cache-Control ``s-maxage`` or ``max-age`` directives,
+ or a value computed from the Expires header's deadline, or the
+ ``default_ttl`` parameter.
- * ``esi_gzip``: Save gzipped snippets for efficient
- ESI-processing
+ The object's remaining time to live, in seconds.
- This filter enables stitching together ESI from individually
- gzipped fragments, saving processing power for
- re-compression on the client side at the expense of some
- compression efficiency.
- Additional VFP filters are available from VMODs.
+beresp.uncacheable
- By default, beresp.filters is constructed as follows:
+ Type: BOOL
- * ``gunzip`` gets added for gzipped content if
- ``beresp.do_gunzip`` or ``beresp.do_esi`` are true.
+ Readable from: vcl_backend_response, vcl_backend_error
- * ``esi_gzip`` gets added if ``beresp.do_esi`` is true
- together with ``beresp.do_gzip`` or content is already
- compressed.
+ Writable from: vcl_backend_response, vcl_backend_error
- * ``esi`` gets added if ``beresp.do_esi`` is true
+ Inherited from bereq.uncacheable, see there.
- * ``gzip`` gets added for uncompressed content if
- ``beresp.do_gzip`` is true
+ Setting this variable makes the object uncacheable.
- * ``testgunzip`` gets added for compressed content if
- ``beresp.do_gunzip`` is false.
+ This may may produce a hit-for-miss object in the cache.
- After beresp.filters is set, using any of the beforementioned
- ``beresp.do_*`` switches is a VCL error.
+ Clearing the variable has no effect and will log the warning
+ "Ignoring attempt to reset beresp.uncacheable".
-beresp.time
- Type: TIME
+beresp.was_304
+
+ Type: BOOL
Readable from: vcl_backend_response, vcl_backend_error
- When the backend headers were fully received just before
- ``vcl_backend_response {}`` was entered, or when
- ``vcl_backend_error {}`` was entered.
+
+ When ``true`` this indicates that we got a 304 response
+ to our conditional fetch from the backend and turned
+ that into ``beresp.status = 200``
obj
@@ -1067,35 +1101,34 @@ obj
This is the object we found in cache. It cannot be modified.
-obj.proto
-
- Type: STRING
-
- Readable from: vcl_hit
-
- The HTTP protocol version stored in the object.
+obj.age
+ Type: DURATION
-obj.status
+ Readable from: vcl_hit, vcl_deliver
- Type: INT
+ The age of the object.
- Readable from: vcl_hit
+obj.can_esi
- The HTTP status code stored in the object.
+ Type: BOOL
- More information in the `HTTP response status`_ section.
+ Readable from: vcl_hit, vcl_deliver
+ If the object can be ESI processed, that is if setting
+ ``resp.do_esi`` or adding ``esi`` to ``resp.filters`` in
+ ``vcl_deliver {}`` would cause the response body to be ESI
+ processed.
-obj.reason
- Type: STRING
+obj.grace
- Readable from: vcl_hit
+ Type: DURATION
+ Readable from: vcl_hit, vcl_deliver
- The HTTP reason phrase stored in the object.
+ The object's grace period in seconds.
obj.hits
@@ -1120,50 +1153,45 @@ obj.http.*
See ``req.http.*`` for general notes.
-obj.ttl
+
+obj.keep
Type: DURATION
Readable from: vcl_hit, vcl_deliver
- The object's remaining time to live, in seconds.
-
-
-obj.age
+ The object's keep period in seconds.
- Type: DURATION
- Readable from: vcl_hit, vcl_deliver
+obj.proto
- The age of the object.
+ Type: STRING
+ Readable from: vcl_hit
-obj.grace
+ The HTTP protocol version stored in the object.
- Type: DURATION
- Readable from: vcl_hit, vcl_deliver
+obj.reason
- The object's grace period in seconds.
+ Type: STRING
+ Readable from: vcl_hit
-obj.keep
- Type: DURATION
+ The HTTP reason phrase stored in the object.
- Readable from: vcl_hit, vcl_deliver
- The object's keep period in seconds.
+obj.status
+ Type: INT
-obj.uncacheable
+ Readable from: vcl_hit
- Type: BOOL
- Readable from: vcl_deliver
+ The HTTP status code stored in the object.
- Whether the object is uncacheable (pass, hit-for-pass or
- hit-for-miss).
+ More information in the `HTTP response status`_ section.
obj.storage
@@ -1175,17 +1203,6 @@ obj.storage
The storage backend where this object is stored.
-obj.can_esi
-
- Type: BOOL
-
- Readable from: vcl_hit, vcl_deliver
-
- If the object can be ESI processed, that is if setting
- ``resp.do_esi`` or adding ``esi`` to ``resp.filters`` in
- ``vcl_deliver {}`` would cause the response body to be ESI
- processed.
-
obj.time
Type: TIME
@@ -1196,6 +1213,26 @@ obj.time
server which generated it. This will roughly be equivalent to
``now`` - ``obj.age``.
+
+obj.ttl
+
+ Type: DURATION
+
+ Readable from: vcl_hit, vcl_deliver
+
+ The object's remaining time to live, in seconds.
+
+
+obj.uncacheable
+
+ Type: BOOL
+
+ Readable from: vcl_deliver
+
+ Whether the object is uncacheable (pass, hit-for-pass or
+ hit-for-miss).
+
+
resp
~~~~
@@ -1214,6 +1251,7 @@ resp
The entire response HTTP data structure, useful as argument
to VMODs.
+
resp.body
Type: BODY
@@ -1222,53 +1260,25 @@ resp.body
To produce a synthetic response body, for instance for errors.
-resp.proto ``VCL <= 4.0``
-
- Type: STRING
-
- Readable from: vcl_deliver, vcl_synth
-
- Writable from: vcl_deliver, vcl_synth
-
- The HTTP protocol version to use for the response.
-
-resp.proto ``VCL >= 4.1``
-
- Type: STRING
-
- Readable from: vcl_deliver, vcl_synth
-
- The HTTP protocol version to use for the response.
-resp.status
+resp.do_esi ``VCL >= 4.1``
- Type: INT
+ Type: BOOL
Readable from: vcl_deliver, vcl_synth
Writable from: vcl_deliver, vcl_synth
- The HTTP status code that will be returned.
-
- More information in the `HTTP response status`_ section.
+ Default: obj.can_esi
- resp.status 200 will get changed into 304 by core code after
- a return(deliver) from vcl_deliver for conditional requests
- to cached content if validation succeeds.
+ This can be used to selectively disable ESI processing, even
+ though ESI parsing happened during fetch (see beresp.do_esi).
+ This is useful when Varnish caches peer with each other.
- For the validation, first ``req.http.If-None-Match`` is
- compared against ``resp.http.Etag``. If they compare equal
- according to the rules for weak validation (see RFC7232), a
- 304 is sent.
+ It is a VCL error to use resp.do_esi after setting resp.filters.
- Secondly, ``req.http.If-Modified-Since`` is compared against
- ``resp.http.Last-Modified`` or, if it is unset, against the
- point in time when the object was last modified based on the
- ``Date`` and ``Age`` headers received with the backend
- response which created the object. If the object has not been
- modified based on that comparison, a 304 is sent.
-resp.reason
+resp.filters
Type: STRING
@@ -1276,7 +1286,16 @@ resp.reason
Writable from: vcl_deliver, vcl_synth
- The HTTP status message that will be returned.
+ List of VDP filters the resp.body will be pushed through.
+
+ Before resp.filters is set, the value read will be the default
+ filter list as determined by varnish based on resp.do_esi and
+ request headers.
+
+ After resp.filters is set, changing any of the conditions
+ which otherwise determine the filter selection will have no
+ effiect. Using resp.do_esi is an error once resp.filters is
+ set.
resp.http.*
@@ -1293,33 +1312,38 @@ resp.http.*
See ``req.http.*`` for general notes.
-resp.do_esi ``VCL >= 4.1``
+
+resp.is_streaming
Type: BOOL
Readable from: vcl_deliver, vcl_synth
- Writable from: vcl_deliver, vcl_synth
+ Returns true when the response will be streamed
+ while being fetched from the backend.
- Default: obj.can_esi
- This can be used to selectively disable ESI processing, even
- though ESI parsing happened during fetch (see beresp.do_esi).
- This is useful when Varnish caches peer with each other.
+resp.proto ``VCL <= 4.0``
- It is a VCL error to use resp.do_esi after setting resp.filters.
+ Type: STRING
+ Readable from: vcl_deliver, vcl_synth
-resp.is_streaming
+ Writable from: vcl_deliver, vcl_synth
- Type: BOOL
+ The HTTP protocol version to use for the response.
+
+
+resp.proto ``VCL >= 4.1``
+
+ Type: STRING
Readable from: vcl_deliver, vcl_synth
- Returns true when the response will be streamed
- while being fetched from the backend.
+ The HTTP protocol version to use for the response.
-resp.filters
+
+resp.reason
Type: STRING
@@ -1327,16 +1351,37 @@ resp.filters
Writable from: vcl_deliver, vcl_synth
- List of VDP filters the resp.body will be pushed through.
+ The HTTP status message that will be returned.
- Before resp.filters is set, the value read will be the default
- filter list as determined by varnish based on resp.do_esi and
- request headers.
- After resp.filters is set, changing any of the conditions
- which otherwise determine the filter selection will have no
- effiect. Using resp.do_esi is an error once resp.filters is
- set.
+resp.status
+
+ Type: INT
+
+ Readable from: vcl_deliver, vcl_synth
+
+ Writable from: vcl_deliver, vcl_synth
+
+ The HTTP status code that will be returned.
+
+ More information in the `HTTP response status`_ section.
+
+ resp.status 200 will get changed into 304 by core code after
+ a return(deliver) from vcl_deliver for conditional requests
+ to cached content if validation succeeds.
+
+ For the validation, first ``req.http.If-None-Match`` is
+ compared against ``resp.http.Etag``. If they compare equal
+ according to the rules for weak validation (see RFC7232), a
+ 304 is sent.
+
+ Secondly, ``req.http.If-Modified-Since`` is compared against
+ ``resp.http.Last-Modified`` or, if it is unset, against the
+ point in time when the object was last modified based on the
+ ``Date`` and ``Age`` headers received with the backend
+ response which created the object. If the object has not been
+ modified based on that comparison, a 304 is sent.
+
resp.time
@@ -1347,6 +1392,7 @@ resp.time
The time when we started preparing the response, just before
entering ``vcl_synth {}`` or ``vcl_deliver {}``.
+
Special variables
~~~~~~~~~~~~~~~~~
@@ -1362,6 +1408,7 @@ now
When converted to STRING in expressions it returns
a formatted timestamp like ``Tue, 20 Feb 2018 09:30:31 GMT``
+
sess
~~~~
@@ -1371,15 +1418,20 @@ transactions may take place. It may comprise the traffic over an
HTTP/1 keep-alive connection, or the multiplexed traffic over an
HTTP/2 connection.
-sess.xid ``VCL >= 4.1``
+sess.idle_send_timeout
- Type: STRING
+ Type: DURATION
- Readable from: client, backend
+ Readable from: client
- Unique ID of this session.
+ Writable from: client
+
+ Send timeout for individual pieces of data on client
+ connections, defaults to the ``idle_send_timeout`` parameter,
+ see :ref:`varnishd(1)`
-sess.timeout_idle
+
+sess.send_timeout
Type: DURATION
@@ -1387,10 +1439,11 @@ sess.timeout_idle
Writable from: client
- Idle timeout for this session, defaults to the
- ``timeout_idle`` parameter, see :ref:`varnishd(1)`
+ Total timeout for ordinary HTTP1 responses, defaults to the
+ ``send_timeout`` parameter, see :ref:`varnishd(1)`
-sess.timeout_linger
+
+sess.timeout_idle
Type: DURATION
@@ -1398,10 +1451,11 @@ sess.timeout_linger
Writable from: client
- Linger timeout for this session, defaults to the
- ``timeout_linger`` parameter, see :ref:`varnishd(1)`
+ Idle timeout for this session, defaults to the
+ ``timeout_idle`` parameter, see :ref:`varnishd(1)`
-sess.send_timeout
+
+sess.timeout_linger
Type: DURATION
@@ -1409,20 +1463,18 @@ sess.send_timeout
Writable from: client
- Total timeout for ordinary HTTP1 responses, defaults to the
- ``send_timeout`` parameter, see :ref:`varnishd(1)`
+ Linger timeout for this session, defaults to the
+ ``timeout_linger`` parameter, see :ref:`varnishd(1)`
-sess.idle_send_timeout
- Type: DURATION
+sess.xid ``VCL >= 4.1``
- Readable from: client
+ Type: STRING
- Writable from: client
+ Readable from: client, backend
+
+ Unique ID of this session.
- Send timeout for individual pieces of data on client
- connections, defaults to the ``idle_send_timeout`` parameter,
- see :ref:`varnishd(1)`
storage
~~~~~~~
@@ -1438,24 +1490,24 @@ storage.<name>.free_space
the malloc stevedore.
-storage.<name>.used_space
+storage.<name>.happy
- Type: BYTES
+ Type: BOOL
Readable from: client, backend
- Used space in the named stevedore. Only available for the malloc
- stevedore.
+ Health status for the named stevedore. Not available in any of the
+ current stevedores.
-storage.<name>.happy
+storage.<name>.used_space
- Type: BOOL
+ Type: BYTES
Readable from: client, backend
- Health status for the named stevedore. Not available in any of the
- current stevedores.
+ Used space in the named stevedore. Only available for the malloc
+ stevedore.
More information about the varnish-commit
mailing list