Built in subroutines¶

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

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:

hash

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

pass

Switch to pass mode. Control will eventually pass to vcl_pass.

pipe

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

synth(status code, reason)

Transition to vcl_synth with resp.status and resp.reason being preset to the arguments of synth().

purge

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

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:

pipe

Proceed with pipe mode.

synth(status code, reason)

Transition to vcl_synth with resp.status and resp.reason being preset to the arguments of synth().

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:

fetch

Proceed with pass mode - initiate a backend request.

restart

Restart the transaction. Increases the restart counter. If the number of restarts is higher than max_restarts Varnish emits a guru meditation error.

synth(status code, reason)

Transition to vcl_synth with resp.status and resp.reason being preset to the arguments of synth().

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:

deliver

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

fetch

Synchronously refresh the object from the backend despite the cache hit. Control will eventually pass to vcl_miss.

pass

Switch to pass mode. Control will eventually pass to vcl_pass.

restart

Restart the transaction. Increases the restart counter. If the number of restarts is higher than max_restarts Varnish emits a guru meditation error.

synth(status code, reason)

Transition to vcl_synth with resp.status and resp.reason being preset to the arguments of synth().

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:

fetch

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

pass

Switch to pass mode. Control will eventually pass to vcl_pass.

restart

Restart the transaction. Increases the restart counter. If the number of restarts is higher than max_restarts Varnish emits a guru meditation error.

synth(status code, reason)

Transition to vcl_synth with resp.status and resp.reason being preset to the arguments of synth().

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 only terminate with calling return(lookup):

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 vcl_hit, vcl_miss or vcl_pass if the cache lookup result was a hit, a miss or hit on a hit-for-pass object (object with obj.uncacheable == true), respectively.

vcl_purge¶

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

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

restart

Restart the transaction. Increases the restart counter. If the number of restarts is higher than max_restarts Varnish emits a guru meditation error.

synth(status code, reason)

Transition to vcl_synth with resp.status and resp.reason being preset to the arguments of synth().

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:

deliver

Deliver the object to the client.

restart

Restart the transaction. Increases the restart counter. If the number of restarts is higher than max_restarts Varnish emits a guru meditation error.

synth(status code, reason)

Transition to vcl_synth with resp.status and resp.reason being preset to the arguments of synth().

vcl_synth¶

Called to deliver a synthetic object. A synthetic object is generated in VCL, not fetched from the backend. Its body may be contructed 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:

deliver

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

restart

Restart the transaction. Increases the restart counter. If the number of restarts is higher than max_restarts Varnish emits a guru meditation error.

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:

fetch

Fetch the object from the backend.

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_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:

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).

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.

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.

vcl_backend_error¶

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

A synthetic object is generated in VCL, whose body may be contructed using the synthetic() function.

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

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.

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.