Variables

Although subroutines take no arguments, the necessary information is made available to the handler subroutines through global variables.

The following variables are always available:

.host

Host name or IP address of a backend.

.port

Service name or port number of a backend.

client.ip

The client’s IP address.

server.hostname

The host name of the server.

server.identity

The identity of the server, as set by the -i parameter. If the -i parameter is not passed to varnishd, server.identity will be set to the name of the instance, as specified by the -n parameter.

server.ip

The IP address of the socket on which the client connection was received.

server.port

The port number of the socket on which the client connection was received.

req.request

The request type (e.g. “GET”, “HEAD”).

req.url

The requested URL.

req.proto

The HTTP protocol version used by the client.

req.backend

The backend to use to service the request.

req.backend.healthy

Whether the backend is healthy or not. Requires an active probe to be set on the backend.

req.http.header

The corresponding HTTP header.

req.hash_always_miss

Force a cache miss for this request. If set to true Varnish will disregard any existing objects and always (re)fetch from the backend.

req.hash_ignore_busy

Ignore any busy object during cache lookup. You would want to do this if you have two server looking up content from each other to avoid potential deadlocks.

req.can_gzip

Does the client accept the gzip transfer encoding.

The following variables are available while preparing a backend request (either for a cache miss or for pass or pipe mode):

bereq.request

The request type (e.g. “GET”, “HEAD”).

bereq.url

The requested URL.

bereq.proto

The HTTP protocol version used to talk to the server.

bereq.http.header

The corresponding HTTP header.

bereq.connect_timeout

The time in seconds to wait for a backend connection.

bereq.first_byte_timeout

The time in seconds to wait for the first byte from the backend. Not available in pipe mode.

bereq.between_bytes_timeout

The time in seconds to wait between each received byte from the backend. Not available in pipe mode.

The following variables are available after the requested object has been retrieved from the backend, before it is entered into the cache. In other words, they are available in vcl_fetch:

beresp.do_esi

Boolean. ESI-process the object after fetching it. Defaults to false. Set it to true to parse the object for ESI directives.

beresp.do_gzip

Boolean. Gzip the object before storing it. Defaults to false.

beresp.do_gunzip

Boolean. Unzip the object before storing it in the cache. Defaults to false.

beresp.proto

The HTTP protocol version used the backend replied with.

beresp.status

The HTTP status code returned by the server.

beresp.response

The HTTP status message returned by the server.

beresp.cacheable

True if the request resulted in a cacheable response. A response is considered cacheable if HTTP status code is 200, 203, 300, 301, 302, 404 or 410 and pass wasn’t called in vcl_recv. If however, both the TTL and the grace time for the response are 0 beresp.cacheable will be 0.

beresp.cacheable is writable.

beresp.ttl

The object’s remaining time to live, in seconds. beresp.ttl is writable.

After the object is entered into the cache, the following (mostly read-only) variables are available when the object has been located in cache, typically in vcl_hit and vcl_deliver.

obj.proto

The HTTP protocol version used when the object was retrieved.

obj.status

The HTTP status code returned by the server.

obj.response

The HTTP status message returned by the server.

obj.cacheable

True if the object had beresp.cacheable. Unless you’ve forced delivery in your VCL obj.cacheable will always be true.

obj.ttl

The object’s remaining time to live, in seconds. obj.ttl is writable.

obj.lastuse

The approximate time elapsed since the object was last requests, in seconds.

obj.hits

The approximate number of times the object has been delivered. A value of 0 indicates a cache miss.

The following variables are available while determining the hash key of an object:

req.hash

The hash key used to refer to an object in the cache. Used when both reading from and writing to the cache.

The following variables are available while preparing a response to the client:

resp.proto

The HTTP protocol version to use for the response.

resp.status

The HTTP status code that will be returned.

resp.response

The HTTP status message that will be returned.

resp.http.header

The corresponding HTTP header.

Values may be assigned to variables using the set keyword::

sub vcl_recv {# Normalize the Host: headerif (req.http.host ~ "(?i)^(www.)?example.com$") {set req.http.host = "www.example.com";}
}

HTTP headers can be removed entirely using the remove keyword::

sub vcl_fetch {# Don't cache cookiesremove beresp.http.Set-Cookie;
}