============= VCL-Variables

The complete album

:Manual section: 7

DESCRIPTION

This is a list of all variables in the VCL language.

Variable names take the form scope.variable[.index], for instance::

req.url
beresp.http.date
client.ip

Which operations are possible on each variable is described below, often with the shorthand "backend" which covers the vcl_backend_* {} subroutines and "client" which covers the rest, except vcl_init {} and vcl_fini {}.

.. include:: vcl_var.rst

.. _protected_headers:

Protected header fields

The content-length and transfer-encoding headers are read-only. They must be preserved to ensure HTTP/1 framing remains consistent and maintain a proper request and response synchronization with both clients and backends.

VMODs can still update these headers, when there is a reason to change the framing, such as a transformation of a request or response body.

HTTP response status

A HTTP status code has 3 digits XYZ where X must be between 1 and 5 included. Since it is not uncommon to see HTTP clients or servers relying on non-standard or even invalid status codes, Varnish can work with any status between 100 and 999.

Within VCL code it is even possible to use status codes in the form VWXYZ as long as the overall value is lower than 65536, but only the XYZ part will be sent to the client, by which time the X must also have become non-zero.

The VWXYZ form of status codes can be communicate extra information in resp.status and beresp.status to return(synth(...)) and return(error(...)), to indicate which synthetic content to produce::

sub vcl_recv {
    if ([...]) {
        return synth(12404);
    }
}

sub vcl_synth {
    if (resp.status == 12404) {
        [...] 	// this specific 404
    } else if (resp.status % 1000 == 404) {
        [...] 	// all other 404's
    }
}

The obj.status variable will inherit the VWXYZ form, but in a ban expression only the XYZ part will be available. The VWXYZ form is strictly limited to VCL execution.

Assigning an HTTP standardized code to resp.status or beresp.status will also set resp.reason or beresp.reason to the corresponding status message.

304 handling


For a 304 response, Varnish core code amends ``beresp`` before calling
`vcl_backend_response`:

* If the gzip status changed, ``Content-Encoding`` is unset and any
  ``Etag`` is weakened

* Any headers not present in the 304 response are copied from the
  existing cache object. ``Content-Length`` is copied if present in
  the existing cache object and discarded otherwise.

* The status gets set to 200.

`beresp.was_304` marks that this conditional response processing has
happened.

Note: Backend conditional requests are independent of client
conditional requests, so clients may receive 304 responses no matter
if a backend request was conditional.

beresp.ttl / beresp.grace / beresp.keep

Before calling vcl_backend_response, core code sets beresp.ttl based on the response status and the response headers Age, Cache-Control or Expires and Date as follows:

If present and valid, the value of the Age header is effectively deduced from all ttl calculations.
For status codes 200, 203, 204, 300, 301, 304, 404, 410 and 414:
- If Cache-Control contains an s-maxage or max-age field (in that order of preference), the ttl is set to the respective non-negative value or 0 if negative.
- Otherwise, if no Expires header exists, the default ttl is used.
- Otherwise, if Expires contains a time stamp before Date, the ttl is set to 0.
- Otherwise, if no Date header is present or the Date header timestamp differs from the local clock by no more than the clock_skew parameter, the ttl is set to
  - 0 if Expires denotes a past timestamp or
  - the difference between the local clock and the Expires header otherwise.
- Otherwise, the ttl is set to the difference between Expires and Date
For status codes 302 and 307, the calculation is identical except that the default ttl is not used and -1 is returned if neither Cache-Control nor Expires exists.
For all other status codes, ttl -1 is returned.

beresp.grace defaults to the default_grace parameter.

For a non-negative ttl, if Cache-Control contains a stale-while-revalidate field value, beresp.grace is set to that value if non-negative or 0 otherwise.

beresp.keep defaults to the default_keep parameter.

HISTORY

VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang AS, Redpill Linpro and Varnish Software. This manual page is written by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyngstøl, Lasse Karstensen and others.

COPYRIGHT

This document is licensed under the same license as Varnish itself. See LICENSE for details.

VCL-Variables