File manager - Edit - /usr/share/doc/varnish/html/users-guide/esi.html
Back
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content composition with Edge Side Includes — Varnish version 7.1.1 documentation</title> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="../_static/classic.css" type="text/css" /> <script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> <script src="../_static/jquery.js"></script> <script src="../_static/underscore.js"></script> <script 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="Troubleshooting Varnish" href="troubleshooting.html" /> <link rel="prev" title="Compression" href="compression.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="troubleshooting.html" title="Troubleshooting Varnish" accesskey="N">next</a> |</li> <li class="right" > <a href="compression.html" title="Compression" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.1.1 documentation</a> »</li> <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Varnish Users Guide</a> »</li> <li class="nav-item nav-item-this"><a href="">Content composition with Edge Side Includes</a></li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <div class="section" id="content-composition-with-edge-side-includes"> <span id="users-guide-esi"></span><h1>Content composition with Edge Side Includes<a class="headerlink" href="#content-composition-with-edge-side-includes" title="Permalink to this headline">¶</a></h1> <p>Varnish can create web pages by assembling different pages, called <cite>fragments</cite>, together into one page. These <cite>fragments</cite> can have individual cache policies. If you have a web site with a list showing the five most popular articles on your site, this list can probably be cached as a <cite>fragment</cite> and included in all the other pages.</p> <p>Used properly this strategy can dramatically increase your hit rate and reduce the load on your servers.</p> <p>In Varnish we’ve only implemented a small subset of ESI, because most of the rest of the ESI specifications facilities are easier and better done with VCL:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>esi:include esi:remove <!--esi ...--> </pre></div> </div> <p>Content substitution based on variables and cookies is not implemented but is on the roadmap. At least if you look at the roadmap from a certain angle. During a full moon.</p> <p>Varnish will not process ESI instructions in HTML comments.</p> <div class="section" id="example-esi-include"> <h2>Example: esi:include<a class="headerlink" href="#example-esi-include" title="Permalink to this headline">¶</a></h2> <p>Lets see an example how this could be used. This simple cgi script outputs the date:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/sh</span> <span class="n">echo</span> <span class="s1">'Content-type: text/html'</span> <span class="n">echo</span> <span class="s1">''</span> <span class="n">date</span> <span class="s2">"+%Y-%m-</span><span class="si">%d</span><span class="s2"> %H:%M"</span> </pre></div> </div> <p>Now, lets have an HTML file that has an ESI include statement:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">HTML</span><span class="o">></span> <span class="o"><</span><span class="n">BODY</span><span class="o">></span> <span class="n">The</span> <span class="n">time</span> <span class="ow">is</span><span class="p">:</span> <span class="o"><</span><span class="n">esi</span><span class="p">:</span><span class="n">include</span> <span class="n">src</span><span class="o">=</span><span class="s2">"/cgi-bin/date.cgi"</span><span class="o">/></span> <span class="n">at</span> <span class="n">this</span> <span class="n">very</span> <span class="n">moment</span><span class="o">.</span> <span class="o"></</span><span class="n">BODY</span><span class="o">></span> <span class="o"></</span><span class="n">HTML</span><span class="o">></span> </pre></div> </div> <p>For ESI to work you need to activate ESI processing in VCL, like this:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sub</span> <span class="n">vcl_backend_response</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="n">bereq</span><span class="o">.</span><span class="n">url</span> <span class="o">==</span> <span class="s2">"/test.html"</span><span class="p">)</span> <span class="p">{</span> <span class="nb">set</span> <span class="n">beresp</span><span class="o">.</span><span class="n">do_esi</span> <span class="o">=</span> <span class="n">true</span><span class="p">;</span> <span class="o">//</span> <span class="n">Do</span> <span class="n">ESI</span> <span class="n">processing</span> <span class="nb">set</span> <span class="n">beresp</span><span class="o">.</span><span class="n">ttl</span> <span class="o">=</span> <span class="mi">24</span> <span class="n">h</span><span class="p">;</span> <span class="o">//</span> <span class="n">Sets</span> <span class="n">the</span> <span class="n">TTL</span> <span class="n">on</span> <span class="n">the</span> <span class="n">HTML</span> <span class="n">above</span> <span class="p">}</span> <span class="n">elseif</span> <span class="p">(</span><span class="n">bereq</span><span class="o">.</span><span class="n">url</span> <span class="o">==</span> <span class="s2">"/cgi-bin/date.cgi"</span><span class="p">)</span> <span class="p">{</span> <span class="nb">set</span> <span class="n">beresp</span><span class="o">.</span><span class="n">ttl</span> <span class="o">=</span> <span class="mi">1</span><span class="n">m</span><span class="p">;</span> <span class="o">//</span> <span class="n">Sets</span> <span class="n">a</span> <span class="n">one</span> <span class="n">minute</span> <span class="n">TTL</span> <span class="n">on</span> <span class="o">//</span> <span class="n">the</span> <span class="n">included</span> <span class="nb">object</span> <span class="p">}</span> <span class="p">}</span> </pre></div> </div> </div> <div class="section" id="example-esi-remove-and-esi"> <h2>Example: esi:remove and <!–esi … –><a class="headerlink" href="#example-esi-remove-and-esi" title="Permalink to this headline">¶</a></h2> <p>The <cite><esi:remove></cite> and <cite><!–esi … –></cite> constructs can be used to present appropriate content whether or not ESI is available, for example you can include content when ESI is available or link to it when it is not. ESI processors will remove the start (“<!–esi”) and the end (“–>”) when the page is processed, while still processing the contents. If the page is not processed, it will remain intact, becoming a HTML/XML comment tag. ESI processors will remove <cite><esi:remove></cite> tags and all content contained in them, allowing you to only render the content when the page is not being ESI-processed. For example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><esi:remove> <a href="http://www.example.com/LICENSE">The license</a> </esi:remove> <!--esi <p>The full text of the license:</p> <esi:include src="http://example.com/LICENSE" /> --> </pre></div> </div> </div> </div> <div class="section" id="footnotes-about-esi"> <h1>Footnotes about ESI<a class="headerlink" href="#footnotes-about-esi" title="Permalink to this headline">¶</a></h1> <div class="section" id="doing-esi-on-json-and-other-non-xml-ish-content"> <h2>Doing ESI on JSON and other non-XML’ish content<a class="headerlink" href="#doing-esi-on-json-and-other-non-xml-ish-content" title="Permalink to this headline">¶</a></h2> <p>Varnish will peek at the first byte of an object and if it is not a “<” Varnish assumes you didn’t really mean to ESI process it. You can disable this check by:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">param</span><span class="o">.</span><span class="n">set</span> <span class="n">feature</span> <span class="o">+</span><span class="n">esi_disable_xml_check</span> </pre></div> </div> </div> <div class="section" id="ignoring-bom-in-esi-objects"> <h2>Ignoring BOM in ESI objects<a class="headerlink" href="#ignoring-bom-in-esi-objects" title="Permalink to this headline">¶</a></h2> <p>If you backend spits out a Unicode Byte-Order-Mark as the first bytes of the response, the “<” check will fail unless you set:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">param</span><span class="o">.</span><span class="n">set</span> <span class="n">feature</span> <span class="o">+</span><span class="n">esi_remove_bom</span> </pre></div> </div> </div> <div class="section" id="esi-on-invalid-xml"> <h2>ESI on invalid XML<a class="headerlink" href="#esi-on-invalid-xml" title="Permalink to this headline">¶</a></h2> <p>The ESI parser expects the XML to be reasonably well formed, but this may fail if you are ESI including non-XML files. You can make the ESI parser disregard anything but ESI tags by setting:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">param</span><span class="o">.</span><span class="n">set</span> <span class="n">feature</span> <span class="o">+</span><span class="n">esi_ignore_other_elements</span> </pre></div> </div> </div> <div class="section" id="esi-includes-with-https-protocol"> <h2>ESI includes with HTTPS protocol<a class="headerlink" href="#esi-includes-with-https-protocol" title="Permalink to this headline">¶</a></h2> <p>If ESI:include tags specify HTTPS protocol, it will be ignored by default, because Varnish has no way to fetch it encryption enabled. If you want to treat HTTPS in ESI:include tags as if it were HTTP, set:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">param</span><span class="o">.</span><span class="n">set</span> <span class="n">feature</span> <span class="o">+</span><span class="n">esi_ignore_https</span> </pre></div> </div> </div> <div class="section" id="esi-on-partial-responses-206"> <h2>ESI on partial responses (206)<a class="headerlink" href="#esi-on-partial-responses-206" title="Permalink to this headline">¶</a></h2> <p>Varnish can <code class="docutils literal notranslate"><span class="pre">pass</span></code> range requests but it is ESI processing a partial response makes no sense, so the fetch fails if you do ask for that. If you really know what you are doing, you can use this workaround:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sub</span> <span class="n">vcl_backend_response</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="n">beresp</span><span class="o">.</span><span class="n">status</span> <span class="o">==</span> <span class="mi">206</span> <span class="o">&&</span> <span class="n">beresp</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">secret</span> <span class="o">==</span> <span class="s2">"swordfish"</span><span class="p">)</span> <span class="p">{</span> <span class="nb">set</span> <span class="n">beresp</span><span class="o">.</span><span class="n">do_esi</span> <span class="o">=</span> <span class="kc">True</span><span class="p">;</span> <span class="nb">set</span> <span class="n">beresp</span><span class="o">.</span><span class="n">status</span> <span class="o">=</span> <span class="mi">1206</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </pre></div> </div> </div> <div class="section" id="esi-and-return-vcl"> <h2>ESI and return(vcl(…))<a class="headerlink" href="#esi-and-return-vcl" title="Permalink to this headline">¶</a></h2> <p>If the original client request switched to a different VCL using <code class="docutils literal notranslate"><span class="pre">return(vcl(...))</span></code> in <code class="docutils literal notranslate"><span class="pre">vcl_recv</span></code>, any esi:include-requests will still start out in the same VCL as the original did, <em>not</em> in the one it switched to.</p> </div> </div> <div class="clearer"></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="#">Content composition with Edge Side Includes</a><ul> <li><a class="reference internal" href="#example-esi-include">Example: esi:include</a></li> <li><a class="reference internal" href="#example-esi-remove-and-esi">Example: esi:remove and <!–esi … –></a></li> </ul> </li> <li><a class="reference internal" href="#footnotes-about-esi">Footnotes about ESI</a><ul> <li><a class="reference internal" href="#doing-esi-on-json-and-other-non-xml-ish-content">Doing ESI on JSON and other non-XML’ish content</a></li> <li><a class="reference internal" href="#ignoring-bom-in-esi-objects">Ignoring BOM in ESI objects</a></li> <li><a class="reference internal" href="#esi-on-invalid-xml">ESI on invalid XML</a></li> <li><a class="reference internal" href="#esi-includes-with-https-protocol">ESI includes with HTTPS protocol</a></li> <li><a class="reference internal" href="#esi-on-partial-responses-206">ESI on partial responses (206)</a></li> <li><a class="reference internal" href="#esi-and-return-vcl">ESI and return(vcl(…))</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="compression.html" title="previous chapter">Compression</a></p> <h4>Next topic</h4> <p class="topless"><a href="troubleshooting.html" title="next chapter">Troubleshooting Varnish</a></p> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../_sources/users-guide/esi.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" /> <input type="submit" value="Go" /> </form> </div> </div> <script>$('#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="troubleshooting.html" title="Troubleshooting Varnish" >next</a> |</li> <li class="right" > <a href="compression.html" title="Compression" >previous</a> |</li> <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.1.1 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-this"><a href="">Content composition with Edge Side Includes</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> 3.4.3. </div> </body> </html>
| ver. 1.4 |
Github
|
.
| PHP 8.2.9 | Generation time: 0.1 |
proxy
|
phpinfo
|
Settings