Ubuntu Manpage: VCL-steps - Built-in subroutines

NAME

       VCL-steps - Built-in subroutines

DESCRIPTION

       Various  built-in  subroutines are called during processing of client and backend requests
       as well as upon vcl.load and vcl.discard.

       See reference-states for a detailed graphical overview of the states and how  they  relate
       to core code functions and VCL subroutines.

       Built-in  subroutines always terminate with a return (<action>), where <action> determines
       how processing continues in the request processing state machine.

       The behaviour of  actions  is  identical  or  at  least  similar  across  subroutines,  so
       differences are only documented where relevant.

       Common actions are documented in vcl_actions in the next section. Actions specific to only
       one or some subroutines are documented in vcl_steps.

       A default behavior is provided for all reference-states in the vcl-built-in-code code.

VCL ACTIONS

Actions are used with the return(<action>) keyword, which returns control from subroutines
back to varnish. The action determines how processing in varnish continues as shown in
reference-states.

Common actions are documented here, while additional actions specific to only one or some
subroutines are documented in the next section vcl_steps as well as which action can be
used from which built in subroutine.

Common actions for the client and backend side
fail
Transition to vcl_synth on the client side as for return(synth(503, "VCL Failed")), but
with any request state changes undone as if std.rollback() was called and forcing a
connection close.

Intended for fatal errors, for which only minimal error handling is possible.

Common actions for the client side
synth(status code, reason)
Transition to vcl_synth with resp.status and resp.reason being preset to the arguments
of synth().

pass
Switch to pass mode, making the current request not use the cache and not putting its
response into it. Control will eventually pass to vcl_pass.

pipe
Switch to pipe mode. Control will eventually pass to vcl_pipe.

restart
Restart the transaction. Increases the req.restarts counter.

If the number of restarts is higher than the max_restarts parameter, control is passed
to vcl_synth as for return(synth(503, "Too many restarts"))

For a restart, all modifications to req attributes are preserved except for
req.restarts and req.xid, which need to change by design.

Common actions for the backend side
abandon
Abandon the backend request. Unless the backend request was a background fetch, control
is passed to vcl_synth on the client side with resp.status preset to 503.

VCL STEPS

Client side
vcl_recv
Called at the beginning of a request, after the complete request has been received and
parsed, after a restart or as the result of an ESI include.

Its purpose is to decide whether or not to serve the request, possibly modify it and
decide on how to process it further. A backend hint may be set as a default for the
backend processing side.

The vcl_recv subroutine may terminate with calling return() on one of the following
keywords:

fail
see fail section above

synth(status code, reason)
see synth section above

restart
see restart section above

pass
see pass section above

pipe
see pipe section above

hash
Continue processing the object as a potential candidate for
caching. Passes the control over to vcl_hash.

purge
Purge the object and it's variants. Control passes through
vcl_hash to vcl_purge.

vcl(label)
Switch to vcl labelled label.

This will roll back the request as if std.rollback(req) was
called and continue vcl processing in vcl_recv of the vcl
labelled label as if it was the active vcl.

The vcl(label) return is only valid while the req.restarts
count is zero and if used from the active vcl.

See the ref_cli_vcl_label command in varnish-cli(7).

vcl_pipe
Called upon entering pipe mode. In this mode, the request is passed on to the backend, and
any further data from both the client and backend is passed on unaltered until either end
closes the connection. Basically, Varnish will degrade into a simple TCP proxy, shuffling
bytes back and forth. For a connection in pipe mode, no other VCL subroutine will ever get
called after vcl_pipe.

The vcl_pipe subroutine may terminate with calling return() with one of the following
keywords:

fail
see fail section above

synth(status code, reason)
see synth section above

pipe
Proceed with pipe mode.

vcl_pass
Called upon entering pass mode. In this mode, the request is passed on to the backend, and
the backend's response is passed on to the client, but is not entered into the cache.
Subsequent requests submitted over the same client connection are handled normally.

The vcl_pass subroutine may terminate with calling return() with one of the following
keywords:

fail
see fail section above

synth(status code, reason)
see synth section above

restart
see restart section above

fetch
Proceed with pass mode - initiate a backend request.

vcl_hash
Called after vcl_recv to create a hash value for the request. This is used as a key to
look up the object in Varnish.

The vcl_hash subroutine may terminate with calling return() with one of the following
keywords:

fail
see fail section above

lookup
Look up the object in cache.

Control passes to vcl_purge when coming from a purge
return in vcl_recv.

Otherwise control passes to the next subroutine depending on the
result of the cache lookup:

* a hit: pass to vcl_hit

* a miss or a hit on a hit-for-miss object (an object with
obj.uncacheable == true): pass to vcl_miss

* a hit on a hit-for-pass object (for which pass(DURATION) had been
previously returned from vcl_backend_response): pass to
vcl_pass

vcl_purge
Called after the purge has been executed and all its variants have been evicted.

The vcl_purge subroutine may terminate with calling return() with one of the following
keywords:

fail
see fail section above

synth(status code, reason)
see synth section above

restart
see restart section above

vcl_miss
Called after a cache lookup if the requested document was not found in the cache or if
vcl_hit returned fetch.

Its purpose is to decide whether or not to attempt to retrieve the document from the
backend. A backend hint may be set as a default for the backend processing side.

The vcl_miss subroutine may terminate with calling return() with one of the following
keywords:

fail
see fail section above

synth(status code, reason)
see synth section above

restart
see restart section above

pass
see pass section above

fetch
Retrieve the requested object from the backend. Control will
eventually pass to vcl_backend_fetch.

vcl_hit
Called when a cache lookup is successful. The object being hit may be stale: It can have a
zero or negative ttl with only grace or keep time left.

The vcl_hit subroutine may terminate with calling return() with one of the following
keywords:
fail
see fail section above

synth(status code, reason)
see synth section above

restart
see restart section above

pass
see pass section above

deliver
Deliver the object. If it is stale, a background fetch to refresh
it is triggered.

vcl_deliver
Called before any object except a vcl_synth result is delivered to the client.

The vcl_deliver subroutine may terminate with calling return() with one of the following
keywords:

fail
see fail section above

synth(status code, reason)
see synth section above

restart
see restart section above

deliver
Deliver the object to the client.

vcl_synth
Called to deliver a synthetic object. A synthetic object is generated in VCL, not fetched
from the backend. Its body may be constructed using the synthetic() function.

A vcl_synth defined object never enters the cache, contrary to a vcl_backend_error defined
object, which may end up in cache.

The subroutine may terminate with calling return() with one of the following keywords:

fail
see fail section above

restart
see restart section above

deliver
Directly deliver the object defined by vcl_synth to the client
without calling vcl_deliver.

Backend Side
vcl_backend_fetch
Called before sending the backend request. In this subroutine you typically alter the
request before it gets to the backend.

The vcl_backend_fetch subroutine may terminate with calling return() with one of the
following keywords:

fail
see fail section above

abandon
see abandon section above

fetch
Fetch the object from the backend.

error(status code, reason)
Transition to vcl_backend_error with beresp.status and
beresp.reason being preset to the arguments of error() if
arguments are provided.

Before calling vcl_backend_fetch, Varnish core prepares the bereq backend request as
follows:

• Unless the request is a pass,

• set bereq.method to GET and bereq.proto to HTTP/1.1 and

• set bereq.http.Accept_Encoding to gzip if ref_param_http_gzip_support is enabled.

• If there is an existing cache object to be revalidated, set bereq.http.If-Modified-Since
from its Last-Modified header and/or set bereq.http.If-None-Match from its Etag header

• Set bereq.http.X-Varnish to the current transaction id (vxid)

These changes can be undone or modified in vcl_backend_fetch before the backend request is
issued.

In particular, to cache non-GET requests, req.method needs to be saved to a header or
variable in vcl_recv and restored to bereq.method. Notice that caching non-GET requests
typically also requires changing the cache key in vcl_hash e.g. by also hashing the
request method and/or request body.

HEAD request can be satisfied from cached GET responses.

vcl_backend_response
Called after the response headers have been successfully retrieved from the backend.

The vcl_backend_response subroutine may terminate with calling return() with one of the
following keywords:

fail
see fail section above

abandon
see abandon section above

deliver
For a 304 response, create an updated cache object.
Otherwise, fetch the object body from the backend and initiate
delivery to any waiting client requests, possibly in parallel
(streaming).

retry
Retry the backend transaction. Increases the retries counter.
If the number of retries is higher than max_retries,
control will be passed to vcl_backend_error.

pass(duration)
Mark the object as a hit-for-pass for the given duration. Subsequent
lookups hitting this object will be turned into passed transactions,
as if vcl_recv had returned pass.

error(status code, reason)
Transition to vcl_backend_error with beresp.status and
beresp.reason being preset to the arguments of error() if
arguments are provided.

vcl_backend_error
This subroutine is called if we fail the backend fetch or if max_retries has been
exceeded.

Returning with abandon does not leave a cache object.

If returning with deliver and a beresp.ttl > 0s, a synthetic cache object is generated in
VCL, whose body may be constructed using the synthetic() function.

When there is a waiting list on the object, the default ttl will be positive (currently
one second), set before entering vcl_backend_error. This is to avoid request serialization
and hammering on a potentially failing backend.

Since these synthetic objects are cached in these special circumstances, be cautious with
putting private information there. If you really must, then you need to explicitly set
beresp.ttl to zero in vcl_backend_error.

The vcl_backend_error subroutine may terminate with calling return() with one of the
following keywords:

fail
see fail section above

abandon
see abandon section above

deliver
Deliver and possibly cache the object defined in
vcl_backend_error as if it was fetched from the backend, also
referred to as a "backend synth".

retry
Retry the backend transaction. Increases the retries counter.
If the number of retries is higher than max_retries,
vcl_synth on the client side is called with resp.status
preset to 503.

During vcl.load / vcl.discard
vcl_init
Called when VCL is loaded, before any requests pass through it. Typically used to
initialize VMODs.

The vcl_init subroutine may terminate with calling return() with one of the following
keywords:

ok
Normal return, VCL continues loading.

fail
Abort loading of this VCL.

vcl_fini
Called when VCL is discarded only after all requests have exited the VCL. Typically used
to clean up VMODs.

The vcl_fini subroutine may terminate with calling return() with one of the following
keywords:

ok
Normal return, VCL will be discarded.

COPYRIGHT

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

       • Copyright (c) 2006 Verdens Gang AS

       • Copyright (c) 2006-2021 Varnish Software AS

                                                                                     VCL-STEPS(7)

NAME

DESCRIPTION

VCL ACTIONS

VCL STEPS

SEE ALSO

COPYRIGHT