File: //usr/share/doc/varnish/html/users-guide/esi.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="Content-Type" content="text/html; charset=utf-8" />
<title>Content composition with Edge Side Includes — Varnish version 6.4.0 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '6.4.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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="top" title="Varnish version 6.4.0 documentation" href="../index.html" />
<link rel="up" title="The Varnish Users Guide" href="index.html" />
<link rel="next" title="Troubleshooting Varnish" href="troubleshooting.html" />
<link rel="prev" title="Compression" href="compression.html" />
</head>
<body>
<div class="related">
<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><a href="../index.html">Varnish version 6.4.0 documentation</a> »</li>
<li><a href="index.html" accesskey="U">The Varnish Users Guide</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<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-python"><pre>esi:include
esi:remove
<!--esi ...--></pre>
</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-python"><pre>#!/bin/sh
echo 'Content-type: text/html'
echo ''
date "+%Y-%m-%d %H:%M"</pre>
</div>
<p>Now, lets have an HTML file that has an ESI include statement:</p>
<div class="highlight-python"><pre><HTML>
<BODY>
The time is: <esi:include src="/cgi-bin/date.cgi"/>
at this very moment.
</BODY>
</HTML></pre>
</div>
<p>For ESI to work you need to activate ESI processing in VCL, like this:</p>
<div class="highlight-python"><pre>sub vcl_backend_response {
if (bereq.url == "/test.html") {
set beresp.do_esi = true; // Do ESI processing
set beresp.ttl = 24 h; // Sets the TTL on the HTML above
} elseif (bereq.url == "/cgi-bin/date.cgi") {
set beresp.ttl = 1m; // Sets a one minute TTL on
// the included object
}
}</pre>
</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-python"><pre><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 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-python"><pre>param.set feature +esi_disable_xml_check</pre>
</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 reponse, the "<" check will fail unless you set:</p>
<div class="highlight-python"><pre>param.set feature +esi_remove_bom</pre>
</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-python"><pre>param.set feature +esi_ignore_other_elements</pre>
</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-python"><pre>param.set feature +esi_ignore_https</pre>
</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 <tt class="docutils literal"><span class="pre">pass</span></tt> 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-python"><pre>sub vcl_backend_response {
if (beresp.status == 206 && beresp.http.secret == "swordfish") {
set beresp.do_esi = True;
set beresp.status = 1206;
}
}</pre>
</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
<tt class="docutils literal"><span class="pre">return(vcl(...))</span></tt> in <tt class="docutils literal"><span class="pre">vcl_recv</span></tt>, 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>
</div>
</div>
<div class="sphinxsidebar">
<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>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/users-guide/esi.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<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><a href="../index.html">Varnish version 6.4.0 documentation</a> »</li>
<li><a href="index.html" >The Varnish Users Guide</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010-2014, Varnish Software AS.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>