trAvis - MANAGER

Edit File: increasing-your-hitrate.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>Achieving a high hitrate &#8212; Varnish version 5.2.1 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">
 var DOCUMENTATION_OPTIONS = {
 URL_ROOT: '../',
 VERSION: '5.2.1',
 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="index" title="Index" href="../genindex.html" />
 <link rel="search" title="Search" href="../search.html" />
 <link rel="top" title="Varnish version 5.2.1 documentation" href="../index.html" />
 <link rel="up" title="Varnish and Website Performance" href="performance.html" />
 <link rel="next" title="Purging and banning" href="purging.html" />
 <link rel="prev" title="Varnish and Website Performance" href="performance.html" /> 
 </head>
 <body role="document">
 <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="purging.html" title="Purging and banning"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="performance.html" title="Varnish and Website Performance"
 accesskey="P">previous</a> |</li>
 <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 5.2.1 documentation</a> &#187;</li>
 <li class="nav-item nav-item-1"><a href="index.html" >The Varnish Users Guide</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="performance.html" accesskey="U">Varnish and Website Performance</a> &#187;</li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <div class="section" id="achieving-a-high-hitrate">
<h1>Achieving a high hitrate<a class="headerlink" href="#achieving-a-high-hitrate" title="Permalink to this headline">¶</a></h1>
Now that Varnish is up and running you can access your web application
through Varnish. Unless your application is specifically written to
work behind a web accelerator you'll probably need to do some
changes to either the configuration or the application in order to
get a high hitrate in Varnish.
Varnish will not cache your data unless it's absolutely sure it is
safe to do so. So, for you to understand how Varnish decides if and
how to cache a page, we'll guide you through a couple of tools that
you should find useful to understand what is happening in your
Varnish setup.
Note that you need a tool to see the HTTP headers that fly between
Varnish and the backend. On the Varnish server, the easiest way to do
this is to use <a class="reference internal" href="../reference/varnishlog.html#varnishlog-1">varnishlog</a> and <a class="reference internal" href="../reference/varnishtop.html#varnishtop-1">varnishtop</a> but
sometimes a client-side tool makes sense. Here are the ones we
commonly use.
<div class="section" id="tool-varnishtop">
<h2>Tool: varnishtop<a class="headerlink" href="#tool-varnishtop" title="Permalink to this headline">¶</a></h2>
You can use varnishtop to identify what URLs are hitting the backend
the most. <code class="docutils literal">varnishtop -i BereqURL</code> is an essential command, showing
you the top requests Varnish is sending to the backend. You can see some
other examples of <a class="reference internal" href="../reference/varnishtop.html#varnishtop-1">varnishtop</a> usage in <a class="reference internal" href="operation-statistics.html#users-guide-statistics">Statistics</a>.
</div>
<div class="section" id="tool-varnishlog">
<h2>Tool: varnishlog<a class="headerlink" href="#tool-varnishlog" title="Permalink to this headline">¶</a></h2>
When you have identified an URL which is frequently sent to the
backend you can use <a class="reference internal" href="../reference/varnishlog.html#varnishlog-1">varnishlog</a> to have a look at the
request. <code class="docutils literal">varnishlog -q 'ReqURL ~ &quot;^/foo/bar&quot;'</code> will show you the
requests coming from the client matching <cite>/foo/bar</cite>.
For more information on how <a class="reference internal" href="../reference/varnishlog.html#varnishlog-1">varnishlog</a> works please see
<a class="reference internal" href="operation-logging.html#users-guide-logging">Logging in Varnish</a> or then man page.
For extended diagnostics headers, see
<a class="reference external" href="https://www.varnish-cache.org/trac/wiki/VCLExampleHitMissHeader">https://www.varnish-cache.org/trac/wiki/VCLExampleHitMissHeader</a>
</div>
<div class="section" id="tool-lwp-request">
<h2>Tool: lwp-request<a class="headerlink" href="#tool-lwp-request" title="Permalink to this headline">¶</a></h2>
<cite>lwp-request</cite> is tool that is a part of The World-Wide Web library
for Perl. It's a couple of really basic programs that can execute
an HTTP request and show you the result. We mostly use the two
programs, <code class="docutils literal">GET</code> and <code class="docutils literal">HEAD</code>.
vg.no was the first site to use Varnish and the people running Varnish
there are quite clueful. So it's interesting to look at their HTTP
Headers. Let's send a GET request for their home page:
<div class="highlight-default"><div class="highlight"><pre>$ GET -H &#39;Host: www.vg.no&#39; -Used http://vg.no/
GET http://vg.no/
Host: www.vg.no
User-Agent: lwp-request/5.834 libwww-perl/5.834

200 OK
Cache-Control: must-revalidate
Refresh: 600
Title: VG Nett - Forsiden - VG Nett
X-Age: 463
X-Cache: HIT
X-Rick-Would-Never: Let you down
X-VG-Jobb: http://www.finn.no/finn/job/fulltime/result?keyword=vg+multimedia Merk:HeaderNinja
X-VG-Korken: http://www.youtube.com/watch?v=Fcj8CnD5188
X-VG-WebCache: joanie
X-VG-WebServer: leon
</pre></div>
</div>
OK. Lets look at what <code class="docutils literal">GET</code> does. <code class="docutils literal">GET</code> usually sends off HTTP 0.9
requests, which lack the 'Host' header. So we add a 'Host' header with the
'-H' option. '-U' print request headers, '-s' prints response status, '-e'
prints response headers and '-d' discards the actual content. We don't
really care about the content, only the headers.
As you can see, VG adds quite a bit of information in their
headers. Some of the headers, like the 'X-Rick-Would-Never' are specific
to vg.no and their somewhat odd sense of humour. Others, like the
'X-VG-Webcache' are for debugging purposes.
So, to check whether a site sets cookies for a specific URL, just do:
<div class="highlight-default"><div class="highlight"><pre>GET -Used http://example.com/ |grep ^Set-Cookie
</pre></div>
</div>
</div>
<div class="section" id="tool-live-http-headers">
<h2>Tool: Live HTTP Headers<a class="headerlink" href="#tool-live-http-headers" title="Permalink to this headline">¶</a></h2>
There is also a plugin for Firefox called <cite>Live HTTP Headers</cite>. This
plugin can show you what headers are being sent and received.
<cite>Live HTTP Headers</cite> can be found at
<a class="reference external" href="https://addons.mozilla.org/en-US/firefox/addon/3829/">https://addons.mozilla.org/en-US/firefox/addon/3829/</a> or by googling
&quot;Live HTTP Headers&quot;.
</div>
</div>
<div class="section" id="the-role-of-http-headers">
<h1>The role of HTTP Headers<a class="headerlink" href="#the-role-of-http-headers" title="Permalink to this headline">¶</a></h1>
Along with each HTTP request and response comes a bunch of headers
carrying metadata. Varnish will look at these headers to determine if
it is appropriate to cache the contents and how long Varnish can keep
the content cached.
Please note that when Varnish considers these headers Varnish actually
considers itself part of the actual webserver. The rationale being
that both are under your control.
The term surrogate origin cache is not really well defined by the
IETF or RFC 2616 so the various ways Varnish works might differ from
your expectations.
Let's take a look at the important headers you should be aware of:
<div class="section" id="cookies">
<h2>Cookies<a class="headerlink" href="#cookies" title="Permalink to this headline">¶</a></h2>
Varnish will, in the default configuration, not cache an object coming
from the backend with a 'Set-Cookie' header present. Also, if the client
sends a Cookie header, Varnish will bypass the cache and go directly to
the backend.
This can be overly conservative. A lot of sites use Google Analytics
(GA) to analyze their traffic. GA sets a cookie to track you. This
cookie is used by the client side javascript and is therefore of no
interest to the server.
<div class="section" id="cookies-from-the-client">
<h3>Cookies from the client<a class="headerlink" href="#cookies-from-the-client" title="Permalink to this headline">¶</a></h3>
For a lot of web applications it makes sense to completely disregard the
cookies unless you are accessing a special part of the web site. This
VCL snippet in <cite>vcl_recv</cite> will disregard cookies unless you are
accessing <cite>/admin/</cite>:
<div class="highlight-default"><div class="highlight"><pre>if (!(req.url ~ &quot;^/admin/&quot;)) {
 unset req.http.Cookie;
}
</pre></div>
</div>
Quite simple. If, however, you need to do something more complicated,
like removing one out of several cookies, things get
difficult. Unfortunately Varnish doesn't have good tools for
manipulating the Cookies. We have to use regular expressions to do the
work. If you are familiar with regular expressions you'll understand
whats going on. If you aren't we recommend that you either pick up a book on
the subject, read through the pcrepattern man page, or read through
one of many online guides.
Lets use the Varnish Software (VS) web as an example here. Very
simplified the setup VS uses can be described as a Drupal-based
backend with a Varnish cache in front. VS uses some cookies for
Google Analytics tracking and similar tools. The cookies are all
set and used by Javascript. Varnish and Drupal doesn't need to see
those cookies and since Varnish will cease caching of pages when
the client sends cookies Varnish will discard these unnecessary
cookies in VCL.
In the following VCL we discard all cookies that start with an
underscore:
<div class="highlight-default"><div class="highlight"><pre># Remove has_js and Google Analytics __* cookies.
set req.http.Cookie = regsuball(req.http.Cookie, &quot;(^|;\s*)(_[_a-z]+|has_js)=[^;]*&quot;, &quot;&quot;);
# Remove a &quot;;&quot; prefix, if present.
set req.http.Cookie = regsub(req.http.Cookie, &quot;^;\s*&quot;, &quot;&quot;);
</pre></div>
</div>
Lets look at an example where we remove everything except the
cookies named &quot;COOKIE1&quot; and &quot;COOKIE2&quot; and you can marvel at the &quot;beauty&quot; of it:
<div class="highlight-default"><div class="highlight"><pre>sub vcl_recv {
 if (req.http.Cookie) {
 set req.http.Cookie = &quot;;&quot; + req.http.Cookie;
 set req.http.Cookie = regsuball(req.http.Cookie, &quot;; +&quot;, &quot;;&quot;);
 set req.http.Cookie = regsuball(req.http.Cookie, &quot;;(COOKIE1|COOKIE2)=&quot;, &quot;; \1=&quot;);
 set req.http.Cookie = regsuball(req.http.Cookie, &quot;;[^ ][^;]*&quot;, &quot;&quot;);
 set req.http.Cookie = regsuball(req.http.Cookie, &quot;^[; ]+|[; ]+$&quot;, &quot;&quot;);

if (req.http.Cookie == &quot;&quot;) {
 unset req.http.Cookie;
 }
 }
}
</pre></div>
</div>
A somewhat simpler example that can accomplish almost the same functionality can be
found below. Instead of filtering out &quot;other&quot; cookies it instead picks out
&quot;the one&quot; cookie that is needed, copies it to another header and then
copies it back to the request, deleting the original cookie header.
<div class="highlight-default"><div class="highlight"><pre>sub vcl_recv {
 # save the original cookie header so we can mangle it
 set req.http.X-Varnish-PHP_SID = req.http.Cookie;
 # using a capturing sub pattern, extract the continuous string of
 # alphanumerics that immediately follows &quot;PHPSESSID=&quot;
 set req.http.X-Varnish-PHP_SID =
 regsuball(req.http.X-Varnish-PHP_SID, &quot;;? ?PHPSESSID=([a-zA-Z0-9]+)( |;| ;).*&quot;,&quot;\1&quot;);
 set req.http.Cookie = req.X-Varnish-PHP_SID;
 unset req.X-Varnish-PHP_SID;
}
</pre></div>
</div>
There are other scary examples of what can be done in VCL in the
Varnish Cache Wiki.
</div>
<div class="section" id="cookies-coming-from-the-backend">
<h3>Cookies coming from the backend<a class="headerlink" href="#cookies-coming-from-the-backend" title="Permalink to this headline">¶</a></h3>
If your backend server sets a cookie using the 'Set-Cookie' header
Varnish will not cache the page when using the default configuration.
A <cite>hit-for-miss</cite> object (see <a class="reference internal" href="vcl-actions.html#user-guide-vcl-actions">actions</a>) is
created. So, if the backend server acts silly and sets unwanted
cookies just unset the 'Set-Cookie' header and all should be fine.
</div>
</div>
<div class="section" id="cache-control">
<h2>Cache-Control<a class="headerlink" href="#cache-control" title="Permalink to this headline">¶</a></h2>
The 'Cache-Control' header instructs caches how to handle the content. Varnish
cares about the max-age parameter and uses it to calculate the TTL
for an object.
So make sure you issue a 'Cache-Control' header with a max-age
header. You can have a look at what Varnish Software's Drupal server
issues:
<div class="highlight-default"><div class="highlight"><pre>$ GET -Used http://www.varnish-software.com/|grep ^Cache-Control
Cache-Control: public, max-age=600
</pre></div>
</div>
</div>
<div class="section" id="age">
<h2>Age<a class="headerlink" href="#age" title="Permalink to this headline">¶</a></h2>
Varnish adds an 'Age' header to indicate how long the object has been
kept inside Varnish. You can grep out 'Age' from <a class="reference internal" href="../reference/varnishlog.html#varnishlog-1">varnishlog</a>
with <code class="docutils literal">varnishlog -I RespHeader:^Age</code>.
</div>
<div class="section" id="pragma">
<h2>Pragma<a class="headerlink" href="#pragma" title="Permalink to this headline">¶</a></h2>
An HTTP 1.0 server might send the header <code class="docutils literal">Pragma: nocache</code>. Varnish ignores this
header. You could easily add support for this header in VCL.
In <cite>vcl_backend_response</cite>:
<div class="highlight-default"><div class="highlight"><pre>if (beresp.http.Pragma ~ &quot;nocache&quot;) {
 set beresp.uncacheable = true;
 set beresp.ttl = 120s; # how long not to cache this url.
}
</pre></div>
</div>
</div>
<div class="section" id="authorization">
<h2>Authorization<a class="headerlink" href="#authorization" title="Permalink to this headline">¶</a></h2>
If Varnish sees an 'Authorization' header it will pass the request. If
this is not what you want you can unset the header.
</div>
<div class="section" id="overriding-the-time-to-live-ttl">
<h2>Overriding the time-to-live (TTL)<a class="headerlink" href="#overriding-the-time-to-live-ttl" title="Permalink to this headline">¶</a></h2>
Sometimes your backend will misbehave. It might, depending on your
setup, be easier to override the TTL in Varnish then to fix your
somewhat cumbersome backend.
You need VCL to identify the objects you want and then you set the
'beresp.ttl' to whatever you want:
<div class="highlight-default"><div class="highlight"><pre>sub vcl_backend_response {
 if (bereq.url ~ &quot;^/legacy_broken_cms/&quot;) {
 set beresp.ttl = 5d;
 }
}
</pre></div>
</div>
This example will set the TTL to 5 days for the old legacy stuff on
your site.
</div>
<div class="section" id="forcing-caching-for-certain-requests-and-certain-responses">
<h2>Forcing caching for certain requests and certain responses<a class="headerlink" href="#forcing-caching-for-certain-requests-and-certain-responses" title="Permalink to this headline">¶</a></h2>
Since you still might have this cumbersome backend that isn't very friendly
to work with you might want to override more stuff in Varnish. We
recommend that you rely as much as you can on the default caching
rules. It is perfectly easy to force Varnish to lookup an object in
the cache but it isn't really recommended.
</div>
<div class="section" id="normalizing-your-namespace">
<h2>Normalizing your namespace<a class="headerlink" href="#normalizing-your-namespace" title="Permalink to this headline">¶</a></h2>
Some sites are accessed via lots of hostnames.
<a class="reference external" href="http://www.varnish-software.com/">http://www.varnish-software.com/</a>, <a class="reference external" href="http://varnish-software.com/">http://varnish-software.com/</a> and
<a class="reference external" href="http://varnishsoftware.com/">http://varnishsoftware.com/</a> all point at the same site. Since Varnish
doesn't know they are the same, Varnish will cache different versions of
every page for every hostname. You can mitigate this in your web server
configuration by setting up redirects or by using the following VCL:
<div class="highlight-default"><div class="highlight"><pre>if (req.http.host ~ &quot;(?i)^(www.)?varnish-?software.com&quot;) {
 set req.http.host = &quot;varnish-software.com&quot;;
}
</pre></div>
</div>
</div>
</div>
<div class="section" id="http-vary">
<h1>HTTP Vary<a class="headerlink" href="#http-vary" title="Permalink to this headline">¶</a></h1>
HTTP Vary is not a trivial concept. It is by far the most misunderstood
HTTP header.
A lot of the response headers tell the client something about the
HTTP object being delivered. Clients can request different variants
of a HTTP object, based on their preference. Their preferences might
cover stuff like encoding or language. When a client prefers UK
English this is indicated through <code class="docutils literal">Accept-Language: en-uk</code>. Caches
need to keep these different variants apart and this is done through
the HTTP response header 'Vary'.
When a backend server issues a <code class="docutils literal">Vary: Accept-Language</code> it tells
Varnish that its needs to cache a separate version for every different
Accept-Language that is coming from the clients.
If two clients say they accept the languages &quot;en-us, en-uk&quot; and
&quot;da, de&quot; respectively, Varnish will cache and serve two different
versions of the page if the backend indicated that Varnish needs
to vary on the 'Accept-Language' header.
Please note that the headers that 'Vary' refer to need to match
exactly for there to be a match. So Varnish will keep two copies
of a page if one of them was created for &quot;en-us, en-uk&quot; and the
other for &quot;en-us,en-uk&quot;. Just the lack of a whitespace will force
Varnish to cache another version.
To achieve a high hitrate whilst using Vary is there therefore
crucial to normalize the headers the backends varies on. Remember,
just a difference in casing can force different cache entries.
The following VCL code will normalize the 'Accept-Language' header to
either &quot;en&quot;, &quot;de&quot; or &quot;fr&quot;, in this order of precedence:
<div class="highlight-default"><div class="highlight"><pre>if (req.http.Accept-Language) {
 if (req.http.Accept-Language ~ &quot;en&quot;) {
 set req.http.Accept-Language = &quot;en&quot;;
 } elsif (req.http.Accept-Language ~ &quot;de&quot;) {
 set req.http.Accept-Language = &quot;de&quot;;
 } elsif (req.http.Accept-Language ~ &quot;fr&quot;) {
 set req.http.Accept-Language = &quot;fr&quot;;
 } else {
 # unknown language. Remove the accept-language header and
 # use the backend default.
 unset req.http.Accept-Language
 }
}
</pre></div>
</div>
<div class="section" id="vary-parse-errors">
<h2>Vary parse errors<a class="headerlink" href="#vary-parse-errors" title="Permalink to this headline">¶</a></h2>
Varnish will return a &quot;503 internal server error&quot; page when it fails
to parse the 'Vary' header, or if any of the client headers listed
in the Vary header exceeds the limit of 65k characters. An 'SLT_Error'
log entry is added in these cases.
</div>
<div class="section" id="pitfall-vary-user-agent">
<h2>Pitfall - Vary: User-Agent<a class="headerlink" href="#pitfall-vary-user-agent" title="Permalink to this headline">¶</a></h2>
Some applications or application servers send <code class="docutils literal">Vary: User-Agent</code>
along with their content. This instructs Varnish to cache a separate
copy for every variation of 'User-Agent' there is and there are
plenty. Even a single patchlevel of the same browser will generate
at least 10 different 'User-Agent' headers based just on what
operating system they are running.
So if you really need to vary based on 'User-Agent' be sure to
normalize the header or your hit rate will suffer badly. Use the
above code as a template.
</div>
</div>
<div class="section" id="cache-misses">
<h1>Cache misses<a class="headerlink" href="#cache-misses" title="Permalink to this headline">¶</a></h1>
When Varnish does not find an object for a request in the cache, then
by default it performs a fetch from the backend on the hypothesis that
the response might be cached. This has two important consequences:
<ul class="simple">
<li>Concurrent backend requests for the same object are coalesced --
only one fetch is executed at a time, and the other pending fetches
wait for the result (unless you have brought about one of the states
described below in <a class="reference internal" href="#users-guide-uncacheable">Uncacheable content</a>). This is to
prevent your backend from being hit by a &quot;thundering herd&quot; when the
cached response has expired, or if it was never cached in the first
place. If it turns out that the response to the first fetch is
cached, then that cache object can be delivered immediately to other
pending requests.</li>
<li>The backend request for the cache miss cannot be conditional if
Varnish does not have an object in the cache to validate; that is,
it cannot contain the headers <code class="docutils literal">If-Modified-Since</code> or
<code class="docutils literal">If-None-Match</code>, which might cause the backend to return status
&quot;304 Not Modified&quot; with no response body. Otherwise, there might not
be a response to cache. If those headers were present in the client
request, they are removed from the backend request.</li>
</ul>
By setting a grace time for cached objects (default 10 seconds), you
allow Varnish to serve stale content while waiting for coalesced fetches,
which are run asynchronously while the stale response is sent to the
client. For details see <a class="reference internal" href="vcl-grace.html#users-guide-handling-misbehaving-servers">Misbehaving servers</a>.
Although the headers for a conditional request are removed from the
backend fetch on a cache miss, Varnish may nevertheless respond to the
client request with &quot;304 Not Modified&quot; if the resulting response
allows it. At delivery time, if the client request had an
<code class="docutils literal">If-None-Match</code> header that matches the <code class="docutils literal">ETag</code> header in the
response, or if the time in an <code class="docutils literal">If-Modified-Since</code> request header is
equal to or later than the time in the <code class="docutils literal">Last-Modified</code> response
header, Varnish will send the 304 response to the client. This happens
for both hits and misses.
Varnish can send conditional requests to the backend if it has an
object in the cache against which the validation can be performed. You
can ensure that an object is retained for this purpose by setting
<code class="docutils literal">beresp.keep</code> in <code class="docutils literal">vcl_backend_response</code>:
<div class="highlight-default"><div class="highlight"><pre>sub vcl_backend_response {
 # Keep the response in cache for 4 hours if the response has
 # validating headers.
 if (beresp.http.ETag || beresp.http.Last-Modified) {
 set beresp.keep = 4h;
 }
}
</pre></div>
</div>
A stale object is not removed from the cache for the duration of
<code class="docutils literal">beresp.keep</code> after its TTL and grace time have expired. This will
increase the storage requirements for your cache, but if you have the
space, it might be worth it to keep stale objects that can be
validated for a fairly long time. If the backend can send a 304
response long after the TTL has expired, you save bandwith on the
fetch and reduce pressure on the storage; if not, then it's no
different from any other cache miss.
If, however, you would prefer that backend fetches are not
conditional, just remove the If-* headers in <code class="docutils literal">vcl_backend_fetch</code>:
<div class="highlight-default"><div class="highlight"><pre>sub vcl_backend_fetch {
 # To prevent conditional backend fetches.
 unset bereq.http.If-None-Match;
 unset bereq.http.If-Modified-Since;
}
</pre></div>
</div>
That should only be necessary if the conditional fetches are
problematic for the backend, for example if evaluating whether the
response is unchanged is too costly for the backend app, or if the
responses are just buggy. From the perspective of Varnish, 304
responses are clearly preferable; fetches with the empty response body
save bandwidth, and storage does not have to be allocated in the
cache, since the existing cache object is re-used.
To summarize, you can improve performance even in the case of cache
misses by:
<ul class="simple">
<li>ensuring that cached objects have a grace time during which a stale
object can be served to the client while fetches are performed in
the background, and</li>
<li>setting a keep time for cached objects that can be validated with
a 304 response after they have gone stale.</li>
</ul>
</div>
<div class="section" id="uncacheable-content">
<h1>Uncacheable content<a class="headerlink" href="#uncacheable-content" title="Permalink to this headline">¶</a></h1>
Some responses cannot be cached, for various reasons. The content may
be personalized, depending on the content of the <code class="docutils literal">Cookie</code> header, or
it might just be the sort of thing that is generated anew on each
request. The cache can't help with that, but nevertheless there are
some decisions you can make that will help Varnish deal with
uncacheable responses in a way that is best for your requirements.
The issues to consider are:
<ul class="simple">
<li>preventing request coalescing</li>
<li>whether (and how soon) the response for the same object may become
cacheable again</li>
<li>whether you want to pass along <code class="docutils literal">If-Modified-Since</code> and
<code class="docutils literal">If-None-Match</code> headers from the client request to the backend, to
allow the backend to respond with status 304</li>
</ul>
<div class="section" id="passing-client-requests">
<h2>Passing client requests<a class="headerlink" href="#passing-client-requests" title="Permalink to this headline">¶</a></h2>
Depending on how your site works, you may be able to recognize a
client request for a response that cannot be cached, for example if
the URL matches certain patterns, or due to the contents of a request
header. In that case, you can set the fetch to pass with
<code class="docutils literal">return(pass)</code> from <code class="docutils literal">vcl_recv</code>:
<div class="highlight-default"><div class="highlight"><pre>sub vcl_recv {
 if (req.url ~ &quot;^/this/is/personal/&quot;) {
 return(pass);
 }
}
</pre></div>
</div>
For passes there is no request coalescing. Since pass indicates that
the response will not be cacheable, there is no point in waiting for a
response that might be cached, and all pending fetches for the object
are concurrent. Otherwise, fetches waiting for an object that turns
out to be uncacheable after all may be serialized -- pending fetches
would wait for the first one, and when the result is not entered into
the cache, the next fetch begins while all of the others wait, and so
on.
When a request is passed, this can be recognized in the
<code class="docutils literal">vcl_backend_*</code> subroutines by the fact that <code class="docutils literal">bereq.uncacheable</code>
and <code class="docutils literal">beresp.uncachable</code> are both true. The backend response will not
be cached, even if it fulfills conditions that otherwise would allow
it, for example if <code class="docutils literal">Cache-Control</code> sets a positive TTL.
Pass is the default (that is, <code class="docutils literal">builtin.vcl</code> calls <code class="docutils literal">return(pass)</code> in
<code class="docutils literal">vcl_recv</code>) if the client request meets these conditions:
<ul class="simple">
<li>the request method is a standard HTTP/1.1 method, but not <code class="docutils literal">GET</code> or
<code class="docutils literal">HEAD</code></li>
<li>there is either a <code class="docutils literal">Cookie</code> or an <code class="docutils literal">Authorization</code> header, indicating
that the response may be personalized</li>
</ul>
If you want to override the default, say if you are certain that the
response may be cacheable despite the presence of a Cookie, make sure
that a <code class="docutils literal">return</code> gets called at the end of any path that may be taken
through your own <code class="docutils literal">vcl_recv</code>. But if you do that, no part of the
built-in <code class="docutils literal">vcl_recv</code> gets executed; so take a close look at
<code class="docutils literal">vcl_recv</code> in <code class="docutils literal">builtin.vcl</code>, and duplicate any part of it that you
require in your own <code class="docutils literal">vcl_recv</code>.
As with cache hits and misses, Varnish decides to send a 304 response
to the client after a pass if the client request headers and the
response headers allow it. This might mean that Varnish will send a
304 response to the client even after the backend saw the same request
headers (<code class="docutils literal">If-Modified-Since</code> and/or <code class="docutils literal">If-None-Match</code>), but decided
not to respond with status 304, while nevertheless setting the
response headers <code class="docutils literal">ETag</code> and/or <code class="docutils literal">Last-Modified</code> so that 304 would
appear to be warranted. If you would prefer that Varnish doesn't do
that, then remove the If-* client request headers in <code class="docutils literal">vcl_pass</code>:
<div class="highlight-default"><div class="highlight"><pre>sub vcl_pass {
 # To prevent 304 client responses after a pass.
 unset req.http.If-None-Match;
 unset req.http.If-Modified-Since;
}
</pre></div>
</div>
</div>
<div class="section" id="hit-for-miss">
<h2>hit-for-miss<a class="headerlink" href="#hit-for-miss" title="Permalink to this headline">¶</a></h2>
You may not be able to recognize all requests for uncacheable content
in <code class="docutils literal">vcl_recv</code>. You might want to allow backends to determine their
own cacheability by setting the <code class="docutils literal">Cache-Control</code> header, but that
cannot be seen until Varnish receives the backend response, so
<code class="docutils literal">vcl_recv</code> can't know about it.
By default, if a request is not passed and the backend response turns
out to be uncacheable, the cache object is set to &quot;hit-for-miss&quot;, by
setting <code class="docutils literal">beresp.uncacheable</code> to <code class="docutils literal">true</code> in
<code class="docutils literal">vcl_backend_response</code>. A minimal object is saved in the cache, so
that the &quot;hit-for-miss&quot; state can be recognized on subsequent
lookups. (The cache is used to remember that the object is
uncacheable, for a limited time.) In that case, no request coalescing
is performed, so that fetches can run concurrently. Otherwise, fetches
for hit-for-miss are just like cache misses, meaning that:
<ul class="simple">
<li>the response may become cacheable on a later request, for example
if it sets a positive TTL with <code class="docutils literal">Cache-Control</code>, and</li>
<li>fetches cannot be conditional, so <code class="docutils literal">If-Modified-Since</code> and
<code class="docutils literal">If-None-Match</code> headers are removed from the backend request.</li>
</ul>
When <code class="docutils literal">beresp.uncacheable</code> is set to <code class="docutils literal">true</code>, then <code class="docutils literal">beresp.ttl</code>
determines how long the hit-for-miss state may last at most. The
hit-for-miss state ends after this period of time elapses, or if a
cacheable response is returned by the backend before it elapses (the
elapse of <code class="docutils literal">beresp.ttl</code> just means that the minimal cache object
expires, like any other cache object expiration). If a cacheable
response is returned, then that object replaces the hit-for-miss
object, and subsequent requests for it will be cache hits. If no
cacheable response is returned before <code class="docutils literal">beresp.ttl</code> elapses, then the
next request for that object will be an ordinary miss, and hence will
be subject to request coalescing.
When Varnish sees that it has hit a hit-for-miss object on a new
request, it executes <code class="docutils literal">vcl_miss</code>, so any custom VCL you have written
for cache misses will apply in the hit-for-miss case as well.
<code class="docutils literal">builtin.vcl</code> sets <code class="docutils literal">beresp.uncacheable</code> to <code class="docutils literal">true</code>, invoking the
hit-for-miss state, under a number of conditions that indicate that
the response cannot be cached, for example if the TTL was computed to
be 0 or if there is a <code class="docutils literal">Set-Cookie</code> header. <code class="docutils literal">beresp.ttl</code> is set to
two minutes by <code class="docutils literal">builtin.vcl</code> in this case, so that is how long
hit-for-miss lasts by default.
You can set <code class="docutils literal">beresp.uncacheable</code> yourself if you need hit-for-miss
on other conditions:
<div class="highlight-default"><div class="highlight"><pre>sub vcl_backend_response {
 if (beresp.http.X-This-Is == &quot;personal&quot;) {
 set beresp.uncacheable = true;
 }
}
</pre></div>
</div>
Note that once <code class="docutils literal">beresp.uncacheable</code> has been set to <code class="docutils literal">true</code> it
cannot be set back to <code class="docutils literal">false</code>; attempts to do so in VCL are ignored.
Although the backend fetches are never conditional for hit-for-miss,
Varnish may decide (as in all other cases) to send a 304 response to
the client if the client request headers and response headers <code class="docutils literal">ETag</code>
or <code class="docutils literal">Last-Modified</code> allow it. If you want to prevent that, remove
the If-* client request headers in <code class="docutils literal">vcl_miss</code>:
<div class="highlight-default"><div class="highlight"><pre>sub vcl_miss {
 # To prevent 304 client responses on hit-for-miss.
 unset req.http.If-None-Match;
 unset req.http.If-Modified-Since;
}
</pre></div>
</div>
</div>
<div class="section" id="hit-for-pass">
<h2>hit-for-pass<a class="headerlink" href="#hit-for-pass" title="Permalink to this headline">¶</a></h2>
A consequence of hit-for-miss is that backend fetches cannot be
conditional, since hit-for-miss allows subsequent responses to be
cacheable. This may be problematic for responses that are very large
and not cacheable, but may be validated with a 304 response. For
example, you may want clients to validate an object via the backend
every time, only sending the response when it has been changed.
For a situation like this, you can set an object to &quot;hit-for-pass&quot; with
<code class="docutils literal">return(pass(DURATION))</code> from <code class="docutils literal">vcl_backend_response</code>, where the
DURATION determines how long the hit-for-pass state lasts:
<div class="highlight-default"><div class="highlight"><pre>sub vcl_backend_response {
 # Set hit-for-pass for two minutes if TTL is 0 and response headers
 # allow for validation.
 if (beresp.ttl &lt;= 0s &amp;&amp; (beresp.http.ETag || beresp.http.Last-Modified)) {
 return(pass(120s));
 }
}
</pre></div>
</div>
As with hit-for-miss, a minimal object is entered into the cache so
that the hit-for-pass state is recognized on subsequent requests. The
request is then processed as a pass, just as if <code class="docutils literal">vcl_recv</code> had
returned pass. This means that there is no request coalescing, and
that <code class="docutils literal">If-Modified-Since</code> and <code class="docutils literal">If-None-Match</code> headers in the client
request are passed along to the backend, so that the backend response
may be 304.
Varnish executes <code class="docutils literal">vcl_pass</code> when it hits a hit-for-pass object. So
again, you can arrange for your own handling of both pass and
hit-for-pass with the same code in VCL.
If you want to prevent Varnish from sending conditional requests to
the backend, then remove the If-* headers from the backend request in
<code class="docutils literal">vcl_backend_fetch</code>, as shown above for cache misses. And if you
want to prevent Varnish from deciding at delivery time to send a 304
response to the client based on the client request and response
headers, then remove the headers from the client request in
<code class="docutils literal">vcl_pass</code>, as shown above for pass.
The hit-for-pass state ends when the &quot;hit-for-pass TTL&quot; given in the
<code class="docutils literal">return</code> statement elapses. As with passes, the response to a
hit-for-pass fetch is never cached, even if it would otherwise fulfill
conditions for cacheability. So unlike hit-for-miss, it is not
possible to end the hit-for-pass state ahead of time with a cacheable
response. After the &quot;hit-for-pass TTL&quot; elapses, the next request for
that object is handled as an ordinary miss.
It is possible to end the hit-for-pass state of a cache object by
setting <code class="docutils literal">req.hash_always_miss</code> to <code class="docutils literal">true</code> in <code class="docutils literal">vcl_recv</code> for a
request that will hit the object (you'll have to write VCL that brings
that about). The request in which that happens is forced to be a cache
miss, and the state of the object afterwards depends on the
disposition of the backend response -- it may become a cache hit,
hit-for-miss, or may be set to hit-for-pass again.
hit-for-miss is the default treatment of uncacheable content. No part
of <code class="docutils literal">builtin.vcl</code> invokes hit-for-pass, so if you need it, you have to
add the necessary <code class="docutils literal">return</code> statement to your own VCL.
</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="#">Achieving a high hitrate</a><ul>
<li><a class="reference internal" href="#tool-varnishtop">Tool: varnishtop</a></li>
<li><a class="reference internal" href="#tool-varnishlog">Tool: varnishlog</a></li>
<li><a class="reference internal" href="#tool-lwp-request">Tool: lwp-request</a></li>
<li><a class="reference internal" href="#tool-live-http-headers">Tool: Live HTTP Headers</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-role-of-http-headers">The role of HTTP Headers</a><ul>
<li><a class="reference internal" href="#cookies">Cookies</a><ul>
<li><a class="reference internal" href="#cookies-from-the-client">Cookies from the client</a></li>
<li><a class="reference internal" href="#cookies-coming-from-the-backend">Cookies coming from the backend</a></li>
</ul>
</li>
<li><a class="reference internal" href="#cache-control">Cache-Control</a></li>
<li><a class="reference internal" href="#age">Age</a></li>
<li><a class="reference internal" href="#pragma">Pragma</a></li>
<li><a class="reference internal" href="#authorization">Authorization</a></li>
<li><a class="reference internal" href="#overriding-the-time-to-live-ttl">Overriding the time-to-live (TTL)</a></li>
<li><a class="reference internal" href="#forcing-caching-for-certain-requests-and-certain-responses">Forcing caching for certain requests and certain responses</a></li>
<li><a class="reference internal" href="#normalizing-your-namespace">Normalizing your namespace</a></li>
</ul>
</li>
<li><a class="reference internal" href="#http-vary">HTTP Vary</a><ul>
<li><a class="reference internal" href="#vary-parse-errors">Vary parse errors</a></li>
<li><a class="reference internal" href="#pitfall-vary-user-agent">Pitfall - Vary: User-Agent</a></li>
</ul>
</li>
<li><a class="reference internal" href="#cache-misses">Cache misses</a></li>
<li><a class="reference internal" href="#uncacheable-content">Uncacheable content</a><ul>
<li><a class="reference internal" href="#passing-client-requests">Passing client requests</a></li>
<li><a class="reference internal" href="#hit-for-miss">hit-for-miss</a></li>
<li><a class="reference internal" href="#hit-for-pass">hit-for-pass</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="performance.html"
 title="previous chapter">Varnish and Website Performance</a>
 <h4>Next topic</h4>
 <a href="purging.html"
 title="next chapter">Purging and banning</a>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../_sources/users-guide/increasing-your-hitrate.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
 </div>
<div id="searchbox" style="display: none" role="search">
 <h3>Quick search</h3>
 <form class="search" action="../search.html" method="get">
 <div><input type="text" name="q" /></div>
 <div><input type="submit" value="Go" /></div>
 <input type="hidden" name="check_keywords" value="yes" />
 <input type="hidden" name="area" value="default" />
 </form>
</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="purging.html" title="Purging and banning"
 >next</a> |</li>
 <li class="right" >
 <a href="performance.html" title="Varnish and Website Performance"
 >previous</a> |</li>
 <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 5.2.1 documentation</a> &#187;</li>
 <li class="nav-item nav-item-1"><a href="index.html" >The Varnish Users Guide</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="performance.html" >Varnish and Website Performance</a> &#187;</li> 
 </ul>
 </div>
 <div class="footer" role="contentinfo">
 &#169; Copyright 2010-2014, Varnish Software AS.
 Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.9.
 </div>
 </body>
</html>