[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