File: //proc/thread-self/root/usr/share/doc/varnish-6.0.3/html/users-guide/vcl-built-in-subs.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Built in subroutines — Varnish version 6.0.3 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Request and response VCL objects" href="vcl-variables.html" />
<link rel="prev" title="VCL Syntax" href="vcl-syntax.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="vcl-variables.html" title="Request and response VCL objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="vcl-syntax.html" title="VCL Syntax"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Varnish version 6.0.3 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Varnish Users Guide</a> »</li>
<li class="nav-item nav-item-2"><a href="vcl.html" accesskey="U">VCL - Varnish Configuration Language</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="built-in-subroutines">
<span id="vcl-built-in-subs"></span><h1>Built in subroutines<a class="headerlink" href="#built-in-subroutines" title="Permalink to this headline">¶</a></h1>
<p>Various built-in subroutines are called during processing of client-
and backend requests as well as upon <code class="docutils literal notranslate"><span class="pre">vcl.load</span></code> and <code class="docutils literal notranslate"><span class="pre">vcl.discard</span></code>.</p>
<p>See <a class="reference internal" href="../reference/states.html#reference-states"><span class="std std-ref">Varnish Processing States</span></a> for a detailed graphical overview of the
states and how they relate to core code functions and VCL subroutines.</p>
<p>Subroutines always terminate with a <code class="docutils literal notranslate"><span class="pre">return()</span></code> on a keyword, which
determines how processing continues in the request processing state
machine.</p>
<p>The behaviour for <code class="docutils literal notranslate"><span class="pre">return()</span></code> keywords is identical or at least
similar across subroutines, so differences are only documented where
relevant.</p>
<div class="section" id="common-return-keywords">
<h2>common return keywords<a class="headerlink" href="#common-return-keywords" title="Permalink to this headline">¶</a></h2>
<blockquote id="fail">
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd><p class="first">Transition to <a class="reference internal" href="#vcl-synth"><span class="std std-ref">vcl_synth</span></a> on the client side as for
<code class="docutils literal notranslate"><span class="pre">return(synth(503,</span> <span class="pre">"VCL</span> <span class="pre">Failed"))</span></code>, but with any request state
changes undone as if <code class="docutils literal notranslate"><span class="pre">std.rollback()</span></code> was called and forcing a
connection close.</p>
<p class="last">Intended for fatal errors, for which only minimal error handling is
possible.</p>
</dd>
</dl>
</div></blockquote>
<blockquote id="synth">
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></dt>
<dd>Transition to <a class="reference internal" href="#vcl-synth"><span class="std std-ref">vcl_synth</span></a> with <code class="docutils literal notranslate"><span class="pre">resp.status</span></code> and
<code class="docutils literal notranslate"><span class="pre">resp.reason</span></code> being preset to the arguments of <code class="docutils literal notranslate"><span class="pre">synth()</span></code>.</dd>
</dl>
</div></blockquote>
<blockquote id="pass">
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">pass</span></code></dt>
<dd>Switch to pass mode. Control will eventually pass to
<a class="reference internal" href="#vcl-pass"><span class="std std-ref">vcl_pass</span></a>.</dd>
</dl>
</div></blockquote>
<blockquote id="pipe">
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">pipe</span></code></dt>
<dd>Switch to pipe mode. Control will eventually pass to
<a class="reference internal" href="#vcl-pipe"><span class="std std-ref">vcl_pipe</span></a>.</dd>
</dl>
</div></blockquote>
<blockquote id="restart">
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">restart</span></code></dt>
<dd><p class="first">Restart the transaction. Increases the <code class="docutils literal notranslate"><span class="pre">req.restarts</span></code> counter.</p>
<p>If the number of restarts is higher than the <em>max_restarts</em>
parameter, control is passed to <a class="reference internal" href="#vcl-synth"><span class="std std-ref">vcl_synth</span></a> as for
<code class="docutils literal notranslate"><span class="pre">return(synth(503,</span> <span class="pre">"Too</span> <span class="pre">many</span> <span class="pre">restarts"))</span></code></p>
<p class="last">For a restart, all modifications to <code class="docutils literal notranslate"><span class="pre">req</span></code> attributes are
preserved except for <code class="docutils literal notranslate"><span class="pre">req.restarts</span></code> and <code class="docutils literal notranslate"><span class="pre">req.xid</span></code>, which need
to change by design.</p>
</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="client-side">
<h2>client side<a class="headerlink" href="#client-side" title="Permalink to this headline">¶</a></h2>
<div class="section" id="vcl-recv">
<span id="id1"></span><h3>vcl_recv<a class="headerlink" href="#vcl-recv" title="Permalink to this headline">¶</a></h3>
<p>Called at the beginning of a request, after the complete request has
been received and parsed, after a <cite>restart</cite> or as the result of an ESI
include.</p>
<p>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.</p>
<p>The <cite>vcl_recv</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code> on one
of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></dt>
<dd>see <a class="reference internal" href="#synth">synth</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">restart</span></code></dt>
<dd>see <a class="reference internal" href="#restart">restart</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">pass</span></code></dt>
<dd>see <a class="reference internal" href="#pass">pass</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">pipe</span></code></dt>
<dd>see <a class="reference internal" href="#pipe">pipe</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">hash</span></code></dt>
<dd>Continue processing the object as a potential candidate for
caching. Passes the control over to <a class="reference internal" href="#vcl-hash"><span class="std std-ref">vcl_hash</span></a>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">purge</span></code></dt>
<dd>Purge the object and it’s variants. Control passes through
<a class="reference internal" href="#vcl-hash"><span class="std std-ref">vcl_hash</span></a> to <a class="reference internal" href="#vcl-purge"><span class="std std-ref">vcl_purge</span></a>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">vcl(label)</span></code></dt>
<dd><p class="first">Switch to vcl labelled <em>label</em>. This will continue vcl processing
in this vcl’s <a class="reference internal" href="#vcl-recv"><span class="std std-ref">vcl_recv</span></a> as if it was the active vcl.</p>
<p class="last">See the <a class="reference internal" href="../reference/varnishadm.html#varnishadm-1"><span class="std std-ref">varnishadm</span></a> <code class="docutils literal notranslate"><span class="pre">vcl.label</span></code> command.</p>
</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="vcl-pipe">
<span id="id2"></span><h3>vcl_pipe<a class="headerlink" href="#vcl-pipe" title="Permalink to this headline">¶</a></h3>
<p>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 <cite>vcl_pipe</cite>.</p>
<p>The <cite>vcl_pipe</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code> with one
of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></dt>
<dd>see <a class="reference internal" href="#synth">synth</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">pipe</span></code></dt>
<dd>Proceed with pipe mode.</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="vcl-pass">
<span id="id3"></span><h3>vcl_pass<a class="headerlink" href="#vcl-pass" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>The <cite>vcl_pass</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code> with one
of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></dt>
<dd>see <a class="reference internal" href="#synth">synth</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">restart</span></code></dt>
<dd>see <a class="reference internal" href="#restart">restart</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">fetch</span></code></dt>
<dd>Proceed with pass mode - initiate a backend request.</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="vcl-hash">
<span id="id4"></span><h3>vcl_hash<a class="headerlink" href="#vcl-hash" title="Permalink to this headline">¶</a></h3>
<p>Called after <cite>vcl_recv</cite> to create a hash value for the request. This is
used as a key to look up the object in Varnish.</p>
<p>The <cite>vcl_hash</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code> with one
of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">lookup</span></code></dt>
<dd><p class="first">Look up the object in cache.</p>
<p>Control passes to <a class="reference internal" href="#vcl-purge"><span class="std std-ref">vcl_purge</span></a> when coming from a <code class="docutils literal notranslate"><span class="pre">purge</span></code>
return in <cite>vcl_recv</cite>.</p>
<p>Otherwise control passes to the next subroutine depending on the
result of the cache lookup:</p>
<ul class="last simple">
<li>a hit: pass to <a class="reference internal" href="#vcl-hit"><span class="std std-ref">vcl_hit</span></a></li>
<li>a miss or a hit on a hit-for-miss object (an object with
<code class="docutils literal notranslate"><span class="pre">obj.uncacheable</span> <span class="pre">==</span> <span class="pre">true</span></code>): pass to <a class="reference internal" href="#vcl-miss"><span class="std std-ref">vcl_miss</span></a></li>
<li>a hit on a hit-for-pass object (for which <code class="docutils literal notranslate"><span class="pre">pass(DURATION)</span></code> had been
previously returned from <code class="docutils literal notranslate"><span class="pre">vcl_backend_response</span></code>): pass to
<a class="reference internal" href="#vcl-pass"><span class="std std-ref">vcl_pass</span></a></li>
</ul>
</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="vcl-purge">
<span id="id5"></span><h3>vcl_purge<a class="headerlink" href="#vcl-purge" title="Permalink to this headline">¶</a></h3>
<p>Called after the purge has been executed and all its variants have been evicted.</p>
<p>The <cite>vcl_purge</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code> with one
of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></dt>
<dd>see <a class="reference internal" href="#synth">synth</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">restart</span></code></dt>
<dd>see <a class="reference internal" href="#restart">restart</a></dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="vcl-miss">
<span id="id6"></span><h3>vcl_miss<a class="headerlink" href="#vcl-miss" title="Permalink to this headline">¶</a></h3>
<p>Called after a cache lookup if the requested document was not found in
the cache or if <a class="reference internal" href="#vcl-hit"><span class="std std-ref">vcl_hit</span></a> returned <code class="docutils literal notranslate"><span class="pre">fetch</span></code>.</p>
<p>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.</p>
<p>The <cite>vcl_miss</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code> with one
of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></dt>
<dd>see <a class="reference internal" href="#synth">synth</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">restart</span></code></dt>
<dd>see <a class="reference internal" href="#restart">restart</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">pass</span></code></dt>
<dd>see <a class="reference internal" href="#pass">pass</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">fetch</span></code></dt>
<dd>Retrieve the requested object from the backend. Control will
eventually pass to <cite>vcl_backend_fetch</cite>.</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="vcl-hit">
<span id="id7"></span><h3>vcl_hit<a class="headerlink" href="#vcl-hit" title="Permalink to this headline">¶</a></h3>
<p>Called when a cache lookup is successful. The object being hit may be
stale: It can have a zero or negative <cite>ttl</cite> with only <cite>grace</cite> or
<cite>keep</cite> time left.</p>
<p>The <cite>vcl_hit</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code>
with one of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></dt>
<dd>see <a class="reference internal" href="#synth">synth</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">restart</span></code></dt>
<dd>see <a class="reference internal" href="#restart">restart</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">pass</span></code></dt>
<dd>see <a class="reference internal" href="#pass">pass</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">miss</span></code></dt>
<dd>Synchronously refresh the object from the backend despite the
cache hit. Control will eventually pass to <a class="reference internal" href="#vcl-miss"><span class="std std-ref">vcl_miss</span></a>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">deliver</span></code></dt>
<dd>Deliver the object. If it is stale, a background fetch to refresh
it is triggered.</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="vcl-deliver">
<span id="id8"></span><h3>vcl_deliver<a class="headerlink" href="#vcl-deliver" title="Permalink to this headline">¶</a></h3>
<p>Called before any object except a <cite>vcl_synth</cite> result is delivered to the client.</p>
<p>The <cite>vcl_deliver</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code> with one
of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></dt>
<dd>see <a class="reference internal" href="#synth">synth</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">restart</span></code></dt>
<dd>see <a class="reference internal" href="#restart">restart</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">deliver</span></code></dt>
<dd>Deliver the object to the client.</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="vcl-synth">
<span id="id9"></span><h3>vcl_synth<a class="headerlink" href="#vcl-synth" title="Permalink to this headline">¶</a></h3>
<p>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 <code class="docutils literal notranslate"><span class="pre">synthetic()</span></code> function.</p>
<p>A <cite>vcl_synth</cite> defined object never enters the cache, contrary to a
<a class="reference internal" href="#vcl-backend-error"><span class="std std-ref">vcl_backend_error</span></a> defined object, which may end up in cache.</p>
<p>The subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code> with one of the
following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">restart</span></code></dt>
<dd>see <a class="reference internal" href="#restart">restart</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">deliver</span></code></dt>
<dd>Directly deliver the object defined by <cite>vcl_synth</cite> to the client
without calling <cite>vcl_deliver</cite>.</dd>
</dl>
</div></blockquote>
</div>
</div>
<div class="section" id="backend-side">
<h2>Backend Side<a class="headerlink" href="#backend-side" title="Permalink to this headline">¶</a></h2>
<div class="section" id="vcl-backend-fetch">
<span id="id10"></span><h3>vcl_backend_fetch<a class="headerlink" href="#vcl-backend-fetch" title="Permalink to this headline">¶</a></h3>
<p>Called before sending the backend request. In this subroutine you
typically alter the request before it gets to the backend.</p>
<p>The <cite>vcl_backend_fetch</cite> subroutine may terminate with calling
<code class="docutils literal notranslate"><span class="pre">return()</span></code> with one of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">fetch</span></code></dt>
<dd>Fetch the object from the backend.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">abandon</span></code></dt>
<dd>Abandon the backend request. Unless the backend request was a
background fetch, control is passed to <a class="reference internal" href="#vcl-synth"><span class="std std-ref">vcl_synth</span></a> on the
client side with <code class="docutils literal notranslate"><span class="pre">resp.status</span></code> preset to 503.</dd>
</dl>
</div></blockquote>
<p>Before calling <cite>vcl_backend_fetch</cite>, varnish core prepares the <cite>bereq</cite>
backend request as follows:</p>
<ul class="simple">
<li>Unless the request is a <cite>pass</cite>,<ul>
<li>set <code class="docutils literal notranslate"><span class="pre">bereq.method</span></code> to <code class="docutils literal notranslate"><span class="pre">GET</span></code> and <code class="docutils literal notranslate"><span class="pre">bereq.proto</span></code> to
<code class="docutils literal notranslate"><span class="pre">HTTP/1.1</span></code> and</li>
<li>set <code class="docutils literal notranslate"><span class="pre">bereq.http.Accept_Encoding</span></code> to <code class="docutils literal notranslate"><span class="pre">gzip</span></code> if
<a class="reference internal" href="../reference/varnishd.html#ref-param-http-gzip-support"><span class="std std-ref">http_gzip_support</span></a> is enabled.</li>
</ul>
</li>
<li>If there is an existing cache object to be revalidated, set
<code class="docutils literal notranslate"><span class="pre">bereq.http.If-Modified-Since</span></code> from its <code class="docutils literal notranslate"><span class="pre">Last-Modified</span></code> header
and/or set <code class="docutils literal notranslate"><span class="pre">bereq.http.If-None-Match</span></code> from its <code class="docutils literal notranslate"><span class="pre">Etag</span></code> header</li>
<li>Set <code class="docutils literal notranslate"><span class="pre">bereq.http.X-Varnish</span></code> to the current transaction id (<cite>vxid</cite>)</li>
</ul>
<p>These changes can be undone or modified in <cite>vcl_backend_fetch</cite> before
the backend request is issued.</p>
<p>In particular, to cache non-GET requests, <code class="docutils literal notranslate"><span class="pre">req.method</span></code> needs to be
saved to a header or variable in <a class="reference internal" href="#vcl-recv"><span class="std std-ref">vcl_recv</span></a> and restored to
<code class="docutils literal notranslate"><span class="pre">bereq.method</span></code>. Notice that caching non-GET requests typically also
requires changing the cache key in <a class="reference internal" href="#vcl-hash"><span class="std std-ref">vcl_hash</span></a> e.g. by also
hashing the request method and/or request body.</p>
<p>HEAD request can be satisfied from cached GET responses.</p>
</div>
<div class="section" id="vcl-backend-response">
<span id="id11"></span><h3>vcl_backend_response<a class="headerlink" href="#vcl-backend-response" title="Permalink to this headline">¶</a></h3>
<p>Called after the response headers have been successfully retrieved from
the backend.</p>
<p>The <cite>vcl_backend_response</cite> subroutine may terminate with calling
<code class="docutils literal notranslate"><span class="pre">return()</span></code> with one of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">deliver</span></code></dt>
<dd>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).</dd>
<dt><code class="docutils literal notranslate"><span class="pre">retry</span></code></dt>
<dd>Retry the backend transaction. Increases the <cite>retries</cite> counter.
If the number of retries is higher than <em>max_retries</em>,
control will be passed to <a class="reference internal" href="#vcl-backend-error"><span class="std std-ref">vcl_backend_error</span></a>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">abandon</span></code></dt>
<dd>Abandon the backend request. Unless the backend request was a
background fetch, control is passed to <a class="reference internal" href="#vcl-synth"><span class="std std-ref">vcl_synth</span></a> on the
client side with <code class="docutils literal notranslate"><span class="pre">resp.status</span></code> preset to 503.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">pass(duration)</span></code></dt>
<dd>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 <code class="docutils literal notranslate"><span class="pre">vcl_recv</span></code> had returned <code class="docutils literal notranslate"><span class="pre">pass</span></code>.</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="handling">
<h3>304 handling<a class="headerlink" href="#handling" title="Permalink to this headline">¶</a></h3>
<p>For a 304 response, varnish core code amends <code class="docutils literal notranslate"><span class="pre">beresp</span></code> before calling
<cite>vcl_backend_response</cite>:</p>
<ul class="simple">
<li>If the gzip status changed, <code class="docutils literal notranslate"><span class="pre">Content-Encoding</span></code> is unset and any
<code class="docutils literal notranslate"><span class="pre">Etag</span></code> is weakened</li>
<li>Any headers not present in the 304 response are copied from the
existing cache object. <code class="docutils literal notranslate"><span class="pre">Content-Length</span></code> is copied if present in
the existing cache object and discarded otherwise.</li>
<li>The status gets set to 200.</li>
</ul>
<p><cite>beresp.was_304</cite> marks that this conditional response processing has
happened.</p>
<p>Note: Backend conditional requests are independent of client
conditional requests, so clients may receive 304 responses no matter
if a backend request was conditional.</p>
</div>
<div class="section" id="beresp-ttl-beresp-grace-beresp-keep">
<h3>beresp.ttl / beresp.grace / beresp.keep<a class="headerlink" href="#beresp-ttl-beresp-grace-beresp-keep" title="Permalink to this headline">¶</a></h3>
<p>Before calling <cite>vcl_backend_response</cite>, core code sets <code class="docutils literal notranslate"><span class="pre">beresp.ttl</span></code>
based on the response status and the response headers <code class="docutils literal notranslate"><span class="pre">Age</span></code>,
<code class="docutils literal notranslate"><span class="pre">Cache-Control</span></code> or <code class="docutils literal notranslate"><span class="pre">Expires</span></code> and <code class="docutils literal notranslate"><span class="pre">Date</span></code> as follows:</p>
<ul class="simple">
<li>If present and valid, the value of the <code class="docutils literal notranslate"><span class="pre">Age</span></code> header is effectively
deduced from all ttl calculations.</li>
<li>For status codes 200, 203, 204, 300, 301, 304, 404, 410 and 414:<ul>
<li>If <code class="docutils literal notranslate"><span class="pre">Cache-Control</span></code> contains an <code class="docutils literal notranslate"><span class="pre">s-maxage</span></code> or <code class="docutils literal notranslate"><span class="pre">max-age</span></code> field
(in that order of preference), the ttl is set to the respective
non-negative value or 0 if negative.</li>
<li>Otherwise, if no <code class="docutils literal notranslate"><span class="pre">Expires</span></code> header exists, the default ttl is
used.</li>
<li>Otherwise, if <code class="docutils literal notranslate"><span class="pre">Expires</span></code> contains a time stamp before <code class="docutils literal notranslate"><span class="pre">Date</span></code>,
the ttl is set to 0.</li>
<li>Otherwise, if no <code class="docutils literal notranslate"><span class="pre">Date</span></code> header is present or the <code class="docutils literal notranslate"><span class="pre">Date</span></code> header
timestamp differs from the local clock by no more than the
<cite>clock_skew</cite> parameter, the ttl is set to<ul>
<li>0 if <code class="docutils literal notranslate"><span class="pre">Expires</span></code> denotes a past timestamp or</li>
<li>the difference between the local clock and the <code class="docutils literal notranslate"><span class="pre">Expires</span></code>
header otherwise.</li>
</ul>
</li>
<li>Otherwise, the ttl is set to the difference between <code class="docutils literal notranslate"><span class="pre">Expires</span></code>
and <code class="docutils literal notranslate"><span class="pre">Date</span></code></li>
</ul>
</li>
<li>For status codes 302 and 307, the calculation is identical except
that the default ttl is not used and -1 is returned if neither
<code class="docutils literal notranslate"><span class="pre">Cache-Control</span></code> nor <code class="docutils literal notranslate"><span class="pre">Expires</span></code> exists.</li>
<li>For all other status codes, ttl -1 is returned.</li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">beresp.grace</span></code> defaults to the <cite>default_grace</cite> parameter.</p>
<p>For a non-negative ttl, if <code class="docutils literal notranslate"><span class="pre">Cache-Control</span></code> contains a
<code class="docutils literal notranslate"><span class="pre">stale-while-revalidate</span></code> field value, <code class="docutils literal notranslate"><span class="pre">beresp.grace</span></code> is
set to that value if non-negative or 0 otherwise.</p>
<p><code class="docutils literal notranslate"><span class="pre">beresp.keep</span></code> defaults to the <cite>default_keep</cite> parameter.</p>
</div>
<div class="section" id="vcl-backend-error">
<span id="id12"></span><h3>vcl_backend_error<a class="headerlink" href="#vcl-backend-error" title="Permalink to this headline">¶</a></h3>
<p>This subroutine is called if we fail the backend fetch or if
<em>max_retries</em> has been exceeded.</p>
<p>A synthetic object is generated in VCL, whose body may be constructed
using the <code class="docutils literal notranslate"><span class="pre">synthetic()</span></code> function.</p>
<p>The <cite>vcl_backend_error</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code>
with one of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>see <a class="reference internal" href="#fail">fail</a></dd>
<dt><code class="docutils literal notranslate"><span class="pre">deliver</span></code></dt>
<dd>Deliver and possibly cache the object defined in
<cite>vcl_backend_error</cite> <strong>as if it was fetched from the backend</strong>, also
referred to as a “backend synth”.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">retry</span></code></dt>
<dd>Retry the backend transaction. Increases the <cite>retries</cite> counter.
If the number of retries is higher than <em>max_retries</em>,
<a class="reference internal" href="#vcl-synth"><span class="std std-ref">vcl_synth</span></a> on the client side is called with <code class="docutils literal notranslate"><span class="pre">resp.status</span></code>
preset to 503.</dd>
</dl>
</div></blockquote>
</div>
</div>
<div class="section" id="vcl-load-vcl-discard">
<h2>vcl.load / vcl.discard<a class="headerlink" href="#vcl-load-vcl-discard" title="Permalink to this headline">¶</a></h2>
<div class="section" id="vcl-init">
<span id="id13"></span><h3>vcl_init<a class="headerlink" href="#vcl-init" title="Permalink to this headline">¶</a></h3>
<p>Called when VCL is loaded, before any requests pass through it.
Typically used to initialize VMODs.</p>
<p>The <cite>vcl_init</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code>
with one of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">ok</span></code></dt>
<dd>Normal return, VCL continues loading.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">fail</span></code></dt>
<dd>Abort loading of this VCL.</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="vcl-fini">
<span id="id14"></span><h3>vcl_fini<a class="headerlink" href="#vcl-fini" title="Permalink to this headline">¶</a></h3>
<p>Called when VCL is discarded only after all requests have exited the VCL.
Typically used to clean up VMODs.</p>
<p>The <cite>vcl_fini</cite> subroutine may terminate with calling <code class="docutils literal notranslate"><span class="pre">return()</span></code>
with one of the following keywords:</p>
<blockquote>
<div><dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">ok</span></code></dt>
<dd>Normal return, VCL will be discarded.</dd>
</dl>
</div></blockquote>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Built in subroutines</a><ul>
<li><a class="reference internal" href="#common-return-keywords">common return keywords</a></li>
<li><a class="reference internal" href="#client-side">client side</a><ul>
<li><a class="reference internal" href="#vcl-recv">vcl_recv</a></li>
<li><a class="reference internal" href="#vcl-pipe">vcl_pipe</a></li>
<li><a class="reference internal" href="#vcl-pass">vcl_pass</a></li>
<li><a class="reference internal" href="#vcl-hash">vcl_hash</a></li>
<li><a class="reference internal" href="#vcl-purge">vcl_purge</a></li>
<li><a class="reference internal" href="#vcl-miss">vcl_miss</a></li>
<li><a class="reference internal" href="#vcl-hit">vcl_hit</a></li>
<li><a class="reference internal" href="#vcl-deliver">vcl_deliver</a></li>
<li><a class="reference internal" href="#vcl-synth">vcl_synth</a></li>
</ul>
</li>
<li><a class="reference internal" href="#backend-side">Backend Side</a><ul>
<li><a class="reference internal" href="#vcl-backend-fetch">vcl_backend_fetch</a></li>
<li><a class="reference internal" href="#vcl-backend-response">vcl_backend_response</a></li>
<li><a class="reference internal" href="#handling">304 handling</a></li>
<li><a class="reference internal" href="#beresp-ttl-beresp-grace-beresp-keep">beresp.ttl / beresp.grace / beresp.keep</a></li>
<li><a class="reference internal" href="#vcl-backend-error">vcl_backend_error</a></li>
</ul>
</li>
<li><a class="reference internal" href="#vcl-load-vcl-discard">vcl.load / vcl.discard</a><ul>
<li><a class="reference internal" href="#vcl-init">vcl_init</a></li>
<li><a class="reference internal" href="#vcl-fini">vcl_fini</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="vcl-syntax.html"
title="previous chapter">VCL Syntax</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="vcl-variables.html"
title="next chapter">Request and response VCL objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/users-guide/vcl-built-in-subs.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="vcl-variables.html" title="Request and response VCL objects"
>next</a> |</li>
<li class="right" >
<a href="vcl-syntax.html" title="VCL Syntax"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Varnish version 6.0.3 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Varnish Users Guide</a> »</li>
<li class="nav-item nav-item-2"><a href="vcl.html" >VCL - Varnish Configuration Language</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2010-2014, Varnish Software AS.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>