⚝
One Hat Cyber Team
⚝
Your IP:
216.73.216.96
Server IP:
147.93.97.220
Server:
Linux srv843233 6.8.0-71-generic #71-Ubuntu SMP PREEMPT_DYNAMIC Tue Jul 22 16:52:38 UTC 2025 x86_64
Server Software:
nginx/1.28.0
PHP Version:
8.2.29
Buat File
|
Buat Folder
Eksekusi
Dir :
~
/
usr
/
share
/
doc
/
varnish
/
html
/
reference
/
View File Name :
vcl-step.html
<!DOCTYPE html> <html lang="en" data-content_root="../"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <title>VCL-steps — Varnish version 7.5.0 documentation</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" /> <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=e2714048" /> <script src="../_static/documentation_options.js?v=8214db13"></script> <script src="../_static/doctools.js?v=888ff710"></script> <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="next" title="VCL-backends" href="vcl-backend.html" /> <link rel="prev" title="VCL-Variables" href="vcl-var.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-backend.html" title="VCL-backends" accesskey="N">next</a> |</li> <li class="right" > <a href="vcl-var.html" title="VCL-Variables" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> »</li> <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Varnish Reference Manual</a> »</li> <li class="nav-item nav-item-this"><a href="">VCL-steps</a></li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <section id="vcl-steps"> <span id="vcl-step-7"></span><h1>VCL-steps<a class="headerlink" href="#vcl-steps" title="Link to this heading">¶</a></h1> <section id="built-in-subroutines"> <h2>Built-in subroutines<a class="headerlink" href="#built-in-subroutines" title="Link to this heading">¶</a></h2> <dl class="field-list simple"> <dt class="field-odd">Manual section<span class="colon">:</span></dt> <dd class="field-odd"><p>7</p> </dd> </dl> <section id="description"> <h3>DESCRIPTION<a class="headerlink" href="#description" title="Link to this heading">¶</a></h3> <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="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>Built-in subroutines always terminate with a <code class="docutils literal notranslate"><span class="pre">return</span> <span class="pre">(<action>)</span></code>, where <code class="docutils literal notranslate"><span class="pre"><action></span></code> determines how processing continues in the request processing state machine.</p> <p>The behaviour of actions is identical or at least similar across subroutines, so differences are only documented where relevant.</p> <p>Common actions are documented in <a class="reference internal" href="#vcl-actions"><span class="std std-ref">VCL Actions</span></a> in the next section. Actions specific to only one or some subroutines are documented in <a class="reference internal" href="#id7"><span class="std std-ref">VCL Steps</span></a>.</p> <p>A default behavior is provided for all <a class="reference internal" href="states.html#reference-states"><span class="std std-ref">Varnish Processing States</span></a> in the <a class="reference internal" href="../users-guide/vcl-built-in-code.html#vcl-built-in-code"><span class="std std-ref">Built-in VCL</span></a> code.</p> </section> <section id="vcl-actions"> <span id="id1"></span><h3>VCL Actions<a class="headerlink" href="#vcl-actions" title="Link to this heading">¶</a></h3> <p>Actions are used with the <code class="docutils literal notranslate"><span class="pre">return(<action>)</span></code> keyword, which returns control from subroutines back to varnish. The action determines how processing in varnish continues as shown in <a class="reference internal" href="states.html#reference-states"><span class="std std-ref">Varnish Processing States</span></a>.</p> <p>Common actions are documented here, while additional actions specific to only one or some subroutines are documented in the next section <a class="reference internal" href="#id7"><span class="std std-ref">VCL Steps</span></a> as well as which action can be used from which built in subroutine.</p> <section id="common-actions-for-the-client-and-backend-side"> <h4>Common actions for the client and backend side<a class="headerlink" href="#common-actions-for-the-client-and-backend-side" title="Link to this heading">¶</a></h4> <section id="fail"> <span id="id2"></span><h5><code class="docutils literal notranslate"><span class="pre">fail</span></code><a class="headerlink" href="#fail" title="Link to this heading">¶</a></h5> <blockquote> <div><p>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>Intended for fatal errors, for which only minimal error handling is possible.</p> </div></blockquote> </section> </section> <section id="common-actions-for-the-client-side"> <h4>Common actions for the client side<a class="headerlink" href="#common-actions-for-the-client-side" title="Link to this heading">¶</a></h4> <section id="synth-status-code-reason"> <span id="synth"></span><h5><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code><a class="headerlink" href="#synth-status-code-reason" title="Link to this heading">¶</a></h5> <blockquote> <div><p>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>.</p> </div></blockquote> </section> <section id="pass"> <span id="id3"></span><h5><code class="docutils literal notranslate"><span class="pre">pass</span></code><a class="headerlink" href="#pass" title="Link to this heading">¶</a></h5> <blockquote> <div><p>Switch to pass mode, making the current request not use the cache and not putting its response into it. Control will eventually pass to <a class="reference internal" href="#vcl-pass"><span class="std std-ref">vcl_pass</span></a>.</p> </div></blockquote> </section> <section id="pipe"> <span id="id4"></span><h5><code class="docutils literal notranslate"><span class="pre">pipe</span></code><a class="headerlink" href="#pipe" title="Link to this heading">¶</a></h5> <blockquote> <div><p>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>.</p> </div></blockquote> </section> <section id="restart"> <span id="id5"></span><h5><code class="docutils literal notranslate"><span class="pre">restart</span></code><a class="headerlink" href="#restart" title="Link to this heading">¶</a></h5> <blockquote> <div><p>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>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> </div></blockquote> </section> </section> <section id="common-actions-for-the-backend-side"> <h4>Common actions for the backend side<a class="headerlink" href="#common-actions-for-the-backend-side" title="Link to this heading">¶</a></h4> <section id="abandon"> <span id="id6"></span><h5><code class="docutils literal notranslate"><span class="pre">abandon</span></code><a class="headerlink" href="#abandon" title="Link to this heading">¶</a></h5> <blockquote> <div><p>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.</p> </div></blockquote> </section> </section> </section> <section id="id7"> <span id="id8"></span><h3>VCL Steps<a class="headerlink" href="#id7" title="Link to this heading">¶</a></h3> <section id="client-side"> <h4>Client side<a class="headerlink" href="#client-side" title="Link to this heading">¶</a></h4> <section id="vcl-recv"> <span id="id9"></span><h5>vcl_recv<a class="headerlink" href="#vcl-recv" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#synth"><span class="std std-ref">synth(status code, reason)</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">restart</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#restart"><span class="std std-ref">restart</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">pass</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#pass"><span class="std std-ref">pass</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">pipe</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#pipe"><span class="std std-ref">pipe</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">hash</span></code></div> <div class="line-block"> <div class="line">Continue processing the object as a potential candidate for</div> <div class="line">caching. Passes the control over to <a class="reference internal" href="#vcl-hash"><span class="std std-ref">vcl_hash</span></a>.</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">purge</span></code></div> <div class="line-block"> <div class="line">Purge the object and it’s variants. Control passes through</div> <div class="line"><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>.</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">vcl(label)</span></code></div> <div class="line-block"> <div class="line">Switch to vcl labelled <em>label</em>.</div> <div class="line"><br /></div> <div class="line">This will roll back the request as if <code class="docutils literal notranslate"><span class="pre">std.rollback(req)</span></code> was</div> <div class="line">called and continue vcl processing in <a class="reference internal" href="#vcl-recv"><span class="std std-ref">vcl_recv</span></a> of the vcl</div> <div class="line">labelled <em>label</em> as if it was the active vcl.</div> <div class="line"><br /></div> <div class="line">The <code class="docutils literal notranslate"><span class="pre">vcl(label)</span></code> return is only valid while the <code class="docutils literal notranslate"><span class="pre">req.restarts</span></code></div> <div class="line">count is zero and if used from the active vcl.</div> <div class="line"><br /></div> <div class="line">See the <a class="reference internal" href="varnish-cli.html#ref-cli-vcl-label"><span class="std std-ref">vcl.label <label> <configname></span></a> command in <a class="reference internal" href="varnish-cli.html#varnish-cli-7"><span class="std std-ref">varnish-cli</span></a>.</div> </div> </div> </div></blockquote> </section> <section id="vcl-pipe"> <span id="id10"></span><h5>vcl_pipe<a class="headerlink" href="#vcl-pipe" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#synth"><span class="std std-ref">synth(status code, reason)</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">pipe</span></code></div> <div class="line-block"> <div class="line">Proceed with pipe mode.</div> </div> </div> </div></blockquote> </section> <section id="vcl-pass"> <span id="id11"></span><h5>vcl_pass<a class="headerlink" href="#vcl-pass" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#synth"><span class="std std-ref">synth(status code, reason)</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">restart</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#restart"><span class="std std-ref">restart</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fetch</span></code></div> <div class="line-block"> <div class="line">Proceed with pass mode - initiate a backend request.</div> </div> </div> </div></blockquote> </section> <section id="vcl-hash"> <span id="id12"></span><h5>vcl_hash<a class="headerlink" href="#vcl-hash" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">lookup</span></code></div> <div class="line-block"> <div class="line">Look up the object in cache.</div> <div class="line"><br /></div> <div class="line">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></div> <div class="line">return in <cite>vcl_recv</cite>.</div> <div class="line"><br /></div> <div class="line">Otherwise control passes to the next subroutine depending on the</div> <div class="line">result of the cache lookup:</div> <div class="line"><br /></div> <div class="line">* a hit: pass to <a class="reference internal" href="#vcl-hit"><span class="std std-ref">vcl_hit</span></a></div> <div class="line"><br /></div> <div class="line">* a miss or a hit on a hit-for-miss object (an object with</div> <div class="line-block"> <div class="line"><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></div> <div class="line"><br /></div> </div> <div class="line">* a hit on a hit-for-pass object (for which <code class="docutils literal notranslate"><span class="pre">pass(DURATION)</span></code> had been</div> <div class="line-block"> <div class="line">previously returned from <code class="docutils literal notranslate"><span class="pre">vcl_backend_response</span></code>): pass to</div> <div class="line"><a class="reference internal" href="#vcl-pass"><span class="std std-ref">vcl_pass</span></a></div> </div> </div> </div> </div></blockquote> </section> <section id="vcl-purge"> <span id="id13"></span><h5>vcl_purge<a class="headerlink" href="#vcl-purge" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#synth"><span class="std std-ref">synth(status code, reason)</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">restart</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#restart"><span class="std std-ref">restart</span></a> section above</div> </div> </div> </div></blockquote> </section> <section id="vcl-miss"> <span id="id14"></span><h5>vcl_miss<a class="headerlink" href="#vcl-miss" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#synth"><span class="std std-ref">synth(status code, reason)</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">restart</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#restart"><span class="std std-ref">restart</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">pass</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#pass"><span class="std std-ref">pass</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fetch</span></code></div> <div class="line-block"> <div class="line">Retrieve the requested object from the backend. Control will</div> <div class="line">eventually pass to <cite>vcl_backend_fetch</cite>.</div> </div> </div> </div></blockquote> </section> <section id="vcl-hit"> <span id="id15"></span><h5>vcl_hit<a class="headerlink" href="#vcl-hit" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#synth"><span class="std std-ref">synth(status code, reason)</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">restart</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#restart"><span class="std std-ref">restart</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">pass</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#pass"><span class="std std-ref">pass</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">deliver</span></code></div> <div class="line-block"> <div class="line">Deliver the object. If it is stale, a background fetch to refresh</div> <div class="line">it is triggered.</div> </div> </div> </div></blockquote> </section> <section id="vcl-deliver"> <span id="id16"></span><h5>vcl_deliver<a class="headerlink" href="#vcl-deliver" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#synth"><span class="std std-ref">synth(status code, reason)</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">restart</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#restart"><span class="std std-ref">restart</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">deliver</span></code></div> <div class="line-block"> <div class="line">Deliver the object to the client.</div> </div> </div> </div></blockquote> </section> <section id="vcl-synth"> <span id="id17"></span><h5>vcl_synth<a class="headerlink" href="#vcl-synth" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">restart</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#restart"><span class="std std-ref">restart</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">deliver</span></code></div> <div class="line-block"> <div class="line">Directly deliver the object defined by <cite>vcl_synth</cite> to the client</div> <div class="line">without calling <cite>vcl_deliver</cite>.</div> </div> </div> </div></blockquote> </section> </section> <section id="backend-side"> <h4>Backend Side<a class="headerlink" href="#backend-side" title="Link to this heading">¶</a></h4> <section id="vcl-backend-fetch"> <span id="id18"></span><h5>vcl_backend_fetch<a class="headerlink" href="#vcl-backend-fetch" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">abandon</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#abandon"><span class="std std-ref">abandon</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fetch</span></code></div> <div class="line-block"> <div class="line">Fetch the object from the backend.</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">error(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></div> <div class="line-block"> <div class="line">Transition to <a class="reference internal" href="#vcl-backend-error"><span class="std std-ref">vcl_backend_error</span></a> with <code class="docutils literal notranslate"><span class="pre">beresp.status</span></code> and</div> <div class="line"><code class="docutils literal notranslate"><span class="pre">beresp.reason</span></code> being preset to the arguments of <code class="docutils literal notranslate"><span class="pre">error()</span></code> if</div> <div class="line">arguments are provided.</div> </div> </div> </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><p>Unless the request is a <cite>pass</cite>,</p> <ul> <li><p>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</p></li> <li><p>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="varnishd.html#ref-param-http-gzip-support"><span class="std std-ref">http_gzip_support</span></a> is enabled.</p></li> </ul> </li> <li><p>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</p></li> <li><p>Set <code class="docutils literal notranslate"><span class="pre">bereq.http.X-Varnish</span></code> to the current transaction id (<cite>vxid</cite>)</p></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> </section> <section id="vcl-backend-response"> <span id="id19"></span><h5>vcl_backend_response<a class="headerlink" href="#vcl-backend-response" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">abandon</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#abandon"><span class="std std-ref">abandon</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">deliver</span></code></div> <div class="line-block"> <div class="line">For a 304 response, create an updated cache object.</div> <div class="line">Otherwise, fetch the object body from the backend and initiate</div> <div class="line">delivery to any waiting client requests, possibly in parallel</div> <div class="line">(streaming).</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">retry</span></code></div> <div class="line-block"> <div class="line">Retry the backend transaction. Increases the <cite>retries</cite> counter.</div> <div class="line">If the number of retries is higher than <em>max_retries</em>,</div> <div class="line">control will be passed to <a class="reference internal" href="#vcl-backend-error"><span class="std std-ref">vcl_backend_error</span></a>.</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">pass(duration)</span></code></div> <div class="line-block"> <div class="line">Mark the object as a hit-for-pass for the given duration. Subsequent</div> <div class="line">lookups hitting this object will be turned into passed transactions,</div> <div class="line">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>.</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">error(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></div> <div class="line-block"> <div class="line">Transition to <a class="reference internal" href="#vcl-backend-error"><span class="std std-ref">vcl_backend_error</span></a> with <code class="docutils literal notranslate"><span class="pre">beresp.status</span></code> and</div> <div class="line"><code class="docutils literal notranslate"><span class="pre">beresp.reason</span></code> being preset to the arguments of <code class="docutils literal notranslate"><span class="pre">error()</span></code> if</div> <div class="line">arguments are provided.</div> </div> </div> </div></blockquote> </section> <section id="vcl-backend-error"> <span id="id20"></span><h5>vcl_backend_error<a class="headerlink" href="#vcl-backend-error" title="Link to this heading">¶</a></h5> <p>This subroutine is called if we fail the backend fetch or if <em>max_retries</em> has been exceeded.</p> <p>Returning with <a class="reference internal" href="#abandon"><span class="std std-ref">abandon</span></a> does not leave a cache object.</p> <p>If returning with <code class="docutils literal notranslate"><span class="pre">deliver</span></code> and a <code class="docutils literal notranslate"><span class="pre">beresp.ttl</span> <span class="pre">></span> <span class="pre">0s</span></code>, a synthetic cache 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>When there is a waiting list on the object, the default <code class="docutils literal notranslate"><span class="pre">ttl</span></code> will be positive (currently one second), set before entering <code class="docutils literal notranslate"><span class="pre">vcl_backend_error</span></code>. This is to avoid request serialization and hammering on a potentially failing backend.</p> <p>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 <code class="docutils literal notranslate"><span class="pre">beresp.ttl</span></code> to zero in <code class="docutils literal notranslate"><span class="pre">vcl_backend_error</span></code>.</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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#fail"><span class="std std-ref">fail</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">abandon</span></code></div> <div class="line-block"> <div class="line">see <a class="reference internal" href="#abandon"><span class="std std-ref">abandon</span></a> section above</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">deliver</span></code></div> <div class="line-block"> <div class="line">Deliver and possibly cache the object defined in</div> <div class="line"><cite>vcl_backend_error</cite> <strong>as if it was fetched from the backend</strong>, also</div> <div class="line">referred to as a “backend synth”.</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">retry</span></code></div> <div class="line-block"> <div class="line">Retry the backend transaction. Increases the <cite>retries</cite> counter.</div> <div class="line">If the number of retries is higher than <em>max_retries</em>,</div> <div class="line"><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></div> <div class="line">preset to 503.</div> </div> </div> </div></blockquote> </section> </section> <section id="during-vcl-load-vcl-discard"> <h4>During vcl.load / vcl.discard<a class="headerlink" href="#during-vcl-load-vcl-discard" title="Link to this heading">¶</a></h4> <section id="vcl-init"> <span id="id21"></span><h5>vcl_init<a class="headerlink" href="#vcl-init" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">ok</span></code></div> <div class="line-block"> <div class="line">Normal return, VCL continues loading.</div> <div class="line"><br /></div> </div> <div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div> <div class="line-block"> <div class="line">Abort loading of this VCL.</div> </div> </div> </div></blockquote> </section> <section id="vcl-fini"> <span id="id22"></span><h5>vcl_fini<a class="headerlink" href="#vcl-fini" title="Link to this heading">¶</a></h5> <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><div class="line-block"> <div class="line"><br /></div> <div class="line"><code class="docutils literal notranslate"><span class="pre">ok</span></code></div> <div class="line-block"> <div class="line">Normal return, VCL will be discarded.</div> </div> </div> </div></blockquote> </section> </section> </section> <section id="see-also"> <h3>SEE ALSO<a class="headerlink" href="#see-also" title="Link to this heading">¶</a></h3> <ul class="simple"> <li><p><a class="reference internal" href="varnishd.html#varnishd-1"><span class="std std-ref">varnishd</span></a></p></li> <li><p><a class="reference internal" href="vcl.html#vcl-7"><span class="std std-ref">VCL</span></a></p></li> </ul> </section> <section id="copyright"> <h3>COPYRIGHT<a class="headerlink" href="#copyright" title="Link to this heading">¶</a></h3> <p>This document is licensed under the same license as Varnish itself. See LICENSE for details.</p> <ul class="simple"> <li><p>Copyright (c) 2006 Verdens Gang AS</p></li> <li><p>Copyright (c) 2006-2021 Varnish Software AS</p></li> </ul> </section> </section> </section> <div class="clearer"></div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <div> <h3><a href="../index.html">Table of Contents</a></h3> <ul> <li><a class="reference internal" href="#">VCL-steps</a><ul> <li><a class="reference internal" href="#built-in-subroutines">Built-in subroutines</a><ul> <li><a class="reference internal" href="#description">DESCRIPTION</a></li> <li><a class="reference internal" href="#vcl-actions">VCL Actions</a><ul> <li><a class="reference internal" href="#common-actions-for-the-client-and-backend-side">Common actions for the client and backend side</a><ul> <li><a class="reference internal" href="#fail"><code class="docutils literal notranslate"><span class="pre">fail</span></code></a></li> </ul> </li> <li><a class="reference internal" href="#common-actions-for-the-client-side">Common actions for the client side</a><ul> <li><a class="reference internal" href="#synth-status-code-reason"><code class="docutils literal notranslate"><span class="pre">synth(status</span> <span class="pre">code,</span> <span class="pre">reason)</span></code></a></li> <li><a class="reference internal" href="#pass"><code class="docutils literal notranslate"><span class="pre">pass</span></code></a></li> <li><a class="reference internal" href="#pipe"><code class="docutils literal notranslate"><span class="pre">pipe</span></code></a></li> <li><a class="reference internal" href="#restart"><code class="docutils literal notranslate"><span class="pre">restart</span></code></a></li> </ul> </li> <li><a class="reference internal" href="#common-actions-for-the-backend-side">Common actions for the backend side</a><ul> <li><a class="reference internal" href="#abandon"><code class="docutils literal notranslate"><span class="pre">abandon</span></code></a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#id7">VCL Steps</a><ul> <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="#vcl-backend-error">vcl_backend_error</a></li> </ul> </li> <li><a class="reference internal" href="#during-vcl-load-vcl-discard">During 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> <li><a class="reference internal" href="#see-also">SEE ALSO</a></li> <li><a class="reference internal" href="#copyright">COPYRIGHT</a></li> </ul> </li> </ul> </li> </ul> </div> <div> <h4>Previous topic</h4> <p class="topless"><a href="vcl-var.html" title="previous chapter">VCL-Variables</a></p> </div> <div> <h4>Next topic</h4> <p class="topless"><a href="vcl-backend.html" title="next chapter">VCL-backends</a></p> </div> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../_sources/reference/vcl-step.rst.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3 id="searchlabel">Quick search</h3> <div class="searchformwrapper"> <form class="search" action="../search.html" method="get"> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> <input type="submit" value="Go" /> </form> </div> </div> <script>document.getElementById('searchbox').style.display = "block"</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-backend.html" title="VCL-backends" >next</a> |</li> <li class="right" > <a href="vcl-var.html" title="VCL-Variables" >previous</a> |</li> <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> »</li> <li class="nav-item nav-item-1"><a href="index.html" >The Varnish Reference Manual</a> »</li> <li class="nav-item nav-item-this"><a href="">VCL-steps</a></li> </ul> </div> <div class="footer" role="contentinfo"> © Copyright 2010-2014, Varnish Software AS. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6. </div> </body> </html>