.. _vcl-built-in-subs: .. XXX:This document needs substantional review. Built in subroutines -------------------- vcl_recv ~~~~~~~~ Called at the beginning of a request, after the complete request has been received and parsed. Its purpose is to decide whether or not to serve the request, how to do it, and, if applicable, which backend to use. It is also used to modify the request, something you'll probably find yourself doing frequently. The `vcl_recv` subroutine may terminate with calling ``return()`` on one of the following keywords: synth(status code, reason) Return a synthetic object with the specified status code to the client and abandon the request. pass Switch to pass mode. Control will eventually pass to vcl_pass. pipe Switch to pipe mode. Control will eventually pass to vcl_pipe. 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_pipe ~~~~~~~~ Called upon entering pipe mode. In this mode, the request is passed on to the backend, and any further data from either client or 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. The `vcl_pipe` subroutine may terminate with calling ``return()`` with one of the following keywords: synth(status code, reason) Return the specified status code to the client and abandon the request. 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: synth(status code, reason) Return the specified status code to the client and abandon the request. pass Proceed with pass mode. restart Restart the transaction. Increases the restart counter. If the number of restarts is higher than *max_restarts* Varnish emits a guru meditation error. vcl_hit ~~~~~~~ Called when a cache lookup is successful. The `vcl_hit` 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. deliver Deliver the object. Control passes to `vcl_deliver`. synth(status code, reason) Return the specified status code to the client and abandon the request. vcl_miss ~~~~~~~~ Called after a cache lookup if the requested document was not found in the cache. Its purpose is to decide whether or not to attempt to retrieve the document from the backend, and which backend to use. The `vcl_miss` subroutine may terminate with calling ``return()`` with one of the following keywords: synth(status code, reason) Return the specified status code to the client and abandon the request. pass Switch to pass mode. Control will eventually pass to `vcl_pass`. fetch Retrieve the requested object from the backend. Control will eventually pass to `vcl_backend_fetch`. restart Restart the transaction. Increases the restart counter. If the number of restarts is higher than *max_restarts* Varnish emits a guru meditation error. 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: lookup Look up the object in cache. Control passes to vcl_miss, vcl_hit or vcl_purge. 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: synth Produce a response. restart Restart the transaction. Increases the restart counter. If the number of restarts is higher than *max_restarts* Varnish emits a guru meditation error. vcl_deliver ~~~~~~~~~~~ Called before a cached object 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. 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 and generates an error. vcl_backend_response ~~~~~~~~~~~~~~~~~~~~ Called after the response headers has been successfully retrieved from the backend. The `vcl_backend_response` subroutine may terminate with calling ``return()`` with one of the following keywords: deliver Possibly insert the object into the cache, then deliver it to the Control will eventually pass to `vcl_deliver`. abandon Abandon the backend request and generates an error. retry Retry the backend transaction. Increases the `retries` counter. If the number of retries is higher than *max_retries* Varnish emits a guru meditation error. vcl_backend_error ~~~~~~~~~~~~~~~~~ This subroutine is called if we fail the backend fetch. The `vcl_backend_error` subroutine may terminate with calling ``return()`` with one of the following keywords: deliver Deliver the error. retry Retry the backend transaction. Increases the `retries` counter. If the number of retries is higher than *max_retries* Varnish emits a guru meditation error. 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. 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.