Default page

Edit File: vmod_directors.html

<!DOCTYPE html>

<title>VMOD directors - Varnish Directors Module — 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="VMOD h2 - Module to control the built-in HTTP2 transport" href="vmod_h2.html" />
    <link rel="prev" title="VMOD cookie - Varnish Cookie Module" href="vmod_cookie.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="vmod_h2.html" title="VMOD h2 - Module to control the built-in HTTP2 transport"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="vmod_cookie.html" title="VMOD cookie - Varnish Cookie Module"
             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="">VMOD directors - Varnish Directors Module</a></li> 
      </ul>
    </div>

<div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="vmod-directors-varnish-directors-module">
<span id="vmod-directors-3"></span><h1>VMOD directors - Varnish Directors Module<a class="headerlink" href="#vmod-directors-varnish-directors-module" title="Link to this heading">¶</a></h1>
<section id="synopsis">
<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Link to this heading">¶</a></h2>
<pre class="literal-block">import directors [as name] [from "path"]

<a class="reference internal" href="#directors-round-robin"><span class="std std-ref">new xround_robin = directors.round_robin()</span></a>

<a class="reference internal" href="#xround-robin-add-backend"><span class="std std-ref">VOID xround_robin.add_backend(BACKEND)</span></a>

<a class="reference internal" href="#xround-robin-remove-backend"><span class="std std-ref">VOID xround_robin.remove_backend(BACKEND)</span></a>

<a class="reference internal" href="#xround-robin-backend"><span class="std std-ref">BACKEND xround_robin.backend()</span></a>

<a class="reference internal" href="#directors-fallback"><span class="std std-ref">new xfallback = directors.fallback(BOOL sticky=0)</span></a>

<a class="reference internal" href="#xfallback-add-backend"><span class="std std-ref">VOID xfallback.add_backend(BACKEND)</span></a>

<a class="reference internal" href="#xfallback-remove-backend"><span class="std std-ref">VOID xfallback.remove_backend(BACKEND)</span></a>

<a class="reference internal" href="#xfallback-backend"><span class="std std-ref">BACKEND xfallback.backend()</span></a>

<a class="reference internal" href="#directors-random"><span class="std std-ref">new xrandom = directors.random()</span></a>

<a class="reference internal" href="#xrandom-add-backend"><span class="std std-ref">VOID xrandom.add_backend(BACKEND, REAL)</span></a>

<a class="reference internal" href="#xrandom-remove-backend"><span class="std std-ref">VOID xrandom.remove_backend(BACKEND)</span></a>

<a class="reference internal" href="#xrandom-backend"><span class="std std-ref">BACKEND xrandom.backend()</span></a>

<a class="reference internal" href="#directors-hash"><span class="std std-ref">new xhash = directors.hash()</span></a>

<a class="reference internal" href="#xhash-add-backend"><span class="std std-ref">VOID xhash.add_backend(BACKEND, REAL weight=1.0)</span></a>

<a class="reference internal" href="#xhash-remove-backend"><span class="std std-ref">VOID xhash.remove_backend(BACKEND)</span></a>

<a class="reference internal" href="#xhash-backend"><span class="std std-ref">BACKEND xhash.backend(STRING)</span></a>

<a class="reference internal" href="#directors-shard"><span class="std std-ref">new xshard = directors.shard()</span></a>

<a class="reference internal" href="#xshard-set-warmup"><span class="std std-ref">VOID xshard.set_warmup(REAL probability=0.0)</span></a>

<a class="reference internal" href="#xshard-set-rampup"><span class="std std-ref">VOID xshard.set_rampup(DURATION duration=0)</span></a>

<a class="reference internal" href="#xshard-associate"><span class="std std-ref">VOID xshard.associate(BLOB param=0)</span></a>

<a class="reference internal" href="#xshard-add-backend"><span class="std std-ref">BOOL xshard.add_backend(BACKEND backend, [STRING ident], [DURATION rampup], [REAL weight])</span></a>

<a class="reference internal" href="#xshard-remove-backend"><span class="std std-ref">BOOL xshard.remove_backend([BACKEND backend], [STRING ident])</span></a>

<a class="reference internal" href="#xshard-clear"><span class="std std-ref">BOOL xshard.clear()</span></a>

<a class="reference internal" href="#xshard-reconfigure"><span class="std std-ref">BOOL xshard.reconfigure(INT replicas=67)</span></a>

<a class="reference internal" href="#xshard-key"><span class="std std-ref">INT xshard.key(STRING)</span></a>

<a class="reference internal" href="#xshard-backend"><span class="std std-ref">BACKEND xshard.backend([ENUM by], [INT key], [BLOB key_blob], [INT alt], [REAL warmup], [BOOL rampup], [ENUM healthy], [BLOB param], [ENUM resolve])</span></a>

<a class="reference internal" href="#xshard-debug"><span class="std std-ref">VOID xshard.debug(INT)</span></a>

<a class="reference internal" href="#directors-shard-param"><span class="std std-ref">new xshard_param = directors.shard_param()</span></a>

<a class="reference internal" href="#xshard-param-clear"><span class="std std-ref">VOID xshard_param.clear()</span></a>

<a class="reference internal" href="#xshard-param-set"><span class="std std-ref">VOID xshard_param.set([ENUM by], [INT key], [BLOB key_blob], [INT alt], [REAL warmup], [BOOL rampup], [ENUM healthy])</span></a>

<a class="reference internal" href="#xshard-param-get-by"><span class="std std-ref">STRING xshard_param.get_by()</span></a>

<a class="reference internal" href="#xshard-param-get-key"><span class="std std-ref">INT xshard_param.get_key()</span></a>

<a class="reference internal" href="#xshard-param-get-alt"><span class="std std-ref">INT xshard_param.get_alt()</span></a>

<a class="reference internal" href="#xshard-param-get-warmup"><span class="std std-ref">REAL xshard_param.get_warmup()</span></a>

<a class="reference internal" href="#xshard-param-get-rampup"><span class="std std-ref">BOOL xshard_param.get_rampup()</span></a>

<a class="reference internal" href="#xshard-param-get-healthy"><span class="std std-ref">STRING xshard_param.get_healthy()</span></a>

<a class="reference internal" href="#xshard-param-use"><span class="std std-ref">BLOB xshard_param.use()</span></a>

<a class="reference internal" href="#directors-lookup"><span class="std std-ref">BACKEND lookup(STRING)</span></a></pre>
</section>
<section id="description">
<h2>DESCRIPTION<a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>
<p><em>vmod_directors</em> enables backend load balancing in Varnish.</p>
<p>The module implements load balancing techniques, and also serves as an
example on how one could extend the load balancing capabilities of
Varnish.</p>
<p>To enable load balancing you must import this vmod (directors).</p>
<p>Then you define your backends. Once you have the backends declared you
can add them to a director. This happens in executed VCL code. If you
want to emulate the previous behavior of Varnish 3.0 you can just
initialize the directors in <code class="docutils literal notranslate"><span class="pre">vcl_init{}</span></code>, like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sub</span> <span class="n">vcl_init</span> <span class="p">{</span>
    <span class="n">new</span> <span class="n">vdir</span> <span class="o">=</span> <span class="n">directors</span><span class="o">.</span><span class="n">round_robin</span><span class="p">();</span>
    <span class="n">vdir</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span><span class="n">backend1</span><span class="p">);</span>
    <span class="n">vdir</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span><span class="n">backend2</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>As you can see there is nothing keeping you from manipulating the
directors elsewhere in VCL. So, you could have VCL code that would add
more backends to a director when a certain URL is called.</p>
<p>Note that directors can use other directors as backends.</p>
<section id="new-xround-robin-directors-round-robin">
<span id="directors-round-robin"></span><h3>new xround_robin = directors.round_robin()<a class="headerlink" href="#new-xround-robin-directors-round-robin" title="Link to this heading">¶</a></h3>
<p>Create a round robin director.</p>
<p>This director will pick backends in a round robin fashion.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">new</span> <span class="n">vdir</span> <span class="o">=</span> <span class="n">directors</span><span class="o">.</span><span class="n">round_robin</span><span class="p">();</span>
</pre></div>
</div>
</section>
<section id="void-xround-robin-add-backend-backend">
<span id="xround-robin-add-backend"></span><h3>VOID xround_robin.add_backend(BACKEND)<a class="headerlink" href="#void-xround-robin-add-backend-backend" title="Link to this heading">¶</a></h3>
<p>Add a backend to the round-robin director.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vdir</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span><span class="n">backend1</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="void-xround-robin-remove-backend-backend">
<span id="xround-robin-remove-backend"></span><h3>VOID xround_robin.remove_backend(BACKEND)<a class="headerlink" href="#void-xround-robin-remove-backend-backend" title="Link to this heading">¶</a></h3>
<p>Remove a backend from the round-robin director.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vdir</span><span class="o">.</span><span class="n">remove_backend</span><span class="p">(</span><span class="n">backend1</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="backend-xround-robin-backend">
<span id="xround-robin-backend"></span><h3>BACKEND xround_robin.backend()<a class="headerlink" href="#backend-xround-robin-backend" title="Link to this heading">¶</a></h3>
<p>Pick a backend from the director.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">set</span> <span class="n">req</span><span class="o">.</span><span class="n">backend_hint</span> <span class="o">=</span> <span class="n">vdir</span><span class="o">.</span><span class="n">backend</span><span class="p">();</span>
</pre></div>
</div>
</section>
<section id="new-xfallback-directors-fallback-bool-sticky-0">
<span id="directors-fallback"></span><h3>new xfallback = directors.fallback(BOOL sticky=0)<a class="headerlink" href="#new-xfallback-directors-fallback-bool-sticky-0" title="Link to this heading">¶</a></h3>
<p>Create a fallback director.</p>
<p>A fallback director will try each of the added backends in turn, and
return the first one that is healthy.</p>
<p>If <em>sticky</em> is set to <code class="docutils literal notranslate"><span class="pre">true</span></code>, the director will keep using the
healthy backend, even if a higher-priority backend becomes
available. Once the whole backend list is exhausted, it’ll start over
at the beginning.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">new</span> <span class="n">vdir</span> <span class="o">=</span> <span class="n">directors</span><span class="o">.</span><span class="n">fallback</span><span class="p">();</span>
</pre></div>
</div>
</section>
<section id="void-xfallback-add-backend-backend">
<span id="xfallback-add-backend"></span><h3>VOID xfallback.add_backend(BACKEND)<a class="headerlink" href="#void-xfallback-add-backend-backend" title="Link to this heading">¶</a></h3>
<p>Add a backend to the director.</p>
<p>Note that the order in which this is done matters for the fallback
director.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vdir</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span><span class="n">backend1</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="void-xfallback-remove-backend-backend">
<span id="xfallback-remove-backend"></span><h3>VOID xfallback.remove_backend(BACKEND)<a class="headerlink" href="#void-xfallback-remove-backend-backend" title="Link to this heading">¶</a></h3>
<p>Remove a backend from the director.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vdir</span><span class="o">.</span><span class="n">remove_backend</span><span class="p">(</span><span class="n">backend1</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="backend-xfallback-backend">
<span id="xfallback-backend"></span><h3>BACKEND xfallback.backend()<a class="headerlink" href="#backend-xfallback-backend" title="Link to this heading">¶</a></h3>
<p>Pick a backend from the director.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">set</span> <span class="n">req</span><span class="o">.</span><span class="n">backend_hint</span> <span class="o">=</span> <span class="n">vdir</span><span class="o">.</span><span class="n">backend</span><span class="p">();</span>
</pre></div>
</div>
</section>
<section id="new-xrandom-directors-random">
<span id="directors-random"></span><h3>new xrandom = directors.random()<a class="headerlink" href="#new-xrandom-directors-random" title="Link to this heading">¶</a></h3>
<p>Create a random backend director.</p>
<p>The random director distributes load over the backends using a
weighted random probability distribution.</p>
<p>The “testable” random generator in varnishd is used, which enables
deterministic tests to be run (See: <code class="docutils literal notranslate"><span class="pre">d00004.vtc</span></code>).</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">new</span> <span class="n">vdir</span> <span class="o">=</span> <span class="n">directors</span><span class="o">.</span><span class="n">random</span><span class="p">();</span>
</pre></div>
</div>
</section>
<section id="void-xrandom-add-backend-backend-real">
<span id="xrandom-add-backend"></span><h3>VOID xrandom.add_backend(BACKEND, REAL)<a class="headerlink" href="#void-xrandom-add-backend-backend-real" title="Link to this heading">¶</a></h3>
<p>Add a backend to the director with a given weight.</p>
<p>Each backend will receive approximately 100 * (weight /
(sum(all_added_weights))) per cent of the traffic sent to this
director.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># 2/3 to backend1, 1/3 to backend2.</span>
<span class="n">vdir</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span><span class="n">backend1</span><span class="p">,</span> <span class="mf">10.0</span><span class="p">);</span>
<span class="n">vdir</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span><span class="n">backend2</span><span class="p">,</span> <span class="mf">5.0</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="void-xrandom-remove-backend-backend">
<span id="xrandom-remove-backend"></span><h3>VOID xrandom.remove_backend(BACKEND)<a class="headerlink" href="#void-xrandom-remove-backend-backend" title="Link to this heading">¶</a></h3>
<p>Remove a backend from the director.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vdir</span><span class="o">.</span><span class="n">remove_backend</span><span class="p">(</span><span class="n">backend1</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="backend-xrandom-backend">
<span id="xrandom-backend"></span><h3>BACKEND xrandom.backend()<a class="headerlink" href="#backend-xrandom-backend" title="Link to this heading">¶</a></h3>
<p>Pick a backend from the director.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">set</span> <span class="n">req</span><span class="o">.</span><span class="n">backend_hint</span> <span class="o">=</span> <span class="n">vdir</span><span class="o">.</span><span class="n">backend</span><span class="p">();</span>
</pre></div>
</div>
</section>
<section id="new-xhash-directors-hash">
<span id="directors-hash"></span><h3>new xhash = directors.hash()<a class="headerlink" href="#new-xhash-directors-hash" title="Link to this heading">¶</a></h3>
<p>Create a hashing backend director.</p>
<p>The director chooses the backend server by computing a hash/digest of
the string given to <a class="reference internal" href="#xhash-backend">xhash.backend()</a>.</p>
<p>Commonly used with <code class="docutils literal notranslate"><span class="pre">client.ip</span></code> or a session cookie to get sticky
sessions.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">new</span> <span class="n">vdir</span> <span class="o">=</span> <span class="n">directors</span><span class="o">.</span><span class="n">hash</span><span class="p">();</span>
</pre></div>
</div>
</section>
<section id="void-xhash-add-backend-backend-real-weight-1-0">
<span id="xhash-add-backend"></span><h3>VOID xhash.add_backend(BACKEND, REAL weight=1.0)<a class="headerlink" href="#void-xhash-add-backend-backend-real-weight-1-0" title="Link to this heading">¶</a></h3>
<p>Add a backend to the director with a certain weight.</p>
<p>Weight is used as in the random director. Recommended and default value
is 1.0 unless you have special needs.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vdir</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span><span class="n">normal_backend</span><span class="p">);</span>
<span class="n">vdir</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span><span class="n">larger_backend</span><span class="p">,</span> <span class="mf">1.5</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="void-xhash-remove-backend-backend">
<span id="xhash-remove-backend"></span><h3>VOID xhash.remove_backend(BACKEND)<a class="headerlink" href="#void-xhash-remove-backend-backend" title="Link to this heading">¶</a></h3>
<p>Remove a backend from the director.</p>
<dl class="simple">
<dt>Example::</dt><dd><p>vdir.remove_backend(larger_backend);</p>
</dd>
</dl>
</section>
<section id="backend-xhash-backend-string">
<span id="xhash-backend"></span><h3>BACKEND xhash.backend(STRING)<a class="headerlink" href="#backend-xhash-backend-string" title="Link to this heading">¶</a></h3>
<p>Pick a backend from the hash director.</p>
<p>Use the string or list of strings provided to pick the backend.</p>
<dl class="simple">
<dt>Example::</dt><dd><p># pick a backend based on the cookie header from the client
set req.backend_hint = vdir.backend(req.http.cookie);</p>
</dd>
</dl>
</section>
<section id="new-xshard-directors-shard">
<span id="directors-shard"></span><h3>new xshard = directors.shard()<a class="headerlink" href="#new-xshard-directors-shard" title="Link to this heading">¶</a></h3>
<p>Create a shard director.</p>
<section id="introduction">
<h4>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h4>
<p>The shard director selects backends by a key, which can be provided
directly or derived from strings. For the same key, the shard director
will always return the same backend, unless the backend configuration
or health state changes. Conversely, for differing keys, the shard
director will likely choose different backends. In the default
configuration, unhealthy backends are not selected.</p>
<p>The shard director resembles the hash director, but its main advantage
is that, when the backend configuration or health states change, the
association of keys to backends remains as stable as possible.</p>
<p>In addition, the rampup and warmup features can help to further
improve user-perceived response times.</p>
</section>
<section id="sharding">
<h4>Sharding<a class="headerlink" href="#sharding" title="Link to this heading">¶</a></h4>
<p>This basic technique allows for numerous applications like optimizing
backend server cache efficiency, Varnish clustering or persisting
sessions to servers without keeping any state, and, in particular,
without the need to synchronize state between nodes of a cluster of
Varnish servers:</p>
<ul>
<li><p>Many applications use caches for data objects, so, in a cluster of
application servers, requesting similar objects from the same server
may help to optimize efficiency of such caches.</p>
<p>For example, sharding by URL or some <em>id</em> component of the url has
been shown to drastically improve the efficiency of many content
management systems.</p>
</li>
<li><p>As special case of the previous example, in clusters of Varnish
servers without additional request distribution logic, each cache
will need store all hot objects, so the effective cache size is
approximately the smallest cache size of any server in the cluster.</p>
<p>Sharding allows to segregate objects within the cluster such that
each object is only cached on one of the servers (or on one primary
and one backup, on a primary for long and others for short
etc…). Effectively, this will lead to a cache size in the order of
the sum of all individual caches, with the potential to drastically
increase efficiency (scales by the number of servers).</p>
</li>
<li><p>Another application is to implement persistence of backend requests,
such that all requests sharing a certain criterion (such as an IP
address or session ID) get forwarded to the same backend server.</p></li>
</ul>
<p>When used with clusters of varnish servers, the shard director will,
if otherwise configured equally, make the same decision on all
servers. In other words, requests sharing a common criterion used as
the shard key will be balanced onto the same backend server(s) no
matter which Varnish server handles the request.</p>
<p>The drawbacks are:</p>
<ul class="simple">
<li><p>the distribution of requests depends on the number of requests per
key and the uniformity of the distribution of key values. In short,
while this technique may lead to much better efficiency overall, it
may also lead to less good load balancing for specific cases.</p></li>
<li><p>When a backend server becomes unavailable, every persistence
technique has to reselect a new backend server, but this technique
will also switch back to the preferred server once it becomes
healthy again, so when used for persistence, it is generally less
stable compared to stateful techniques (which would continue to use
a selected server for as long as possible (or dictated by a TTL)).</p></li>
</ul>
</section>
<section id="method">
<h4>Method<a class="headerlink" href="#method" title="Link to this heading">¶</a></h4>
<p>When <a class="reference internal" href="#xshard-reconfigure">xshard.reconfigure()</a> is called explicitly (or implicitly at
the end of any task containing reconfigurations like
<a class="reference internal" href="#xshard-add-backend">xshard.add_backend()</a>), a consistent hashing circular data structure
gets built from the last 32 bits of SHA256 hash values of <em><ident></em><em><n></em> (default <em>ident</em> being the backend name) for each backend and
for a running number <em>n</em> from 1 to the <em>replicas</em> argument to
<a class="reference internal" href="#xshard-reconfigure">xshard.reconfigure()</a>. Hashing creates the seemingly random order
for placement of backends on the consistent hashing ring. When
<a class="reference internal" href="#xshard-add-backend">xshard.add_backend()</a> was called with a <em>weight</em> argument,
<em>replicas</em> is scaled by that weight to add proportionally more copies
of the that backend on the ring.</p>
<p>When <a class="reference internal" href="#xshard-backend">xshard.backend()</a> is called, a load balancing key
gets generated unless provided. The smallest hash value in the circle
is looked up that is larger than the key (searching clockwise and
wrapping around as necessary). The backend for this hash value is the
preferred backend for the given key.</p>
<p>If a healthy backend is requested, the search is continued linearly on
the ring as long as backends found are unhealthy or all backends have
been checked. The order of these “alternative backends” on the ring is
likely to differ for different keys. Alternative backends can also be
selected explicitly.</p>
<p>On consistent hashing see:</p>
<ul class="simple">
<li><p><a class="reference external" href="http://www8.org/w8-papers/2a-webserver/caching/paper2.html">http://www8.org/w8-papers/2a-webserver/caching/paper2.html</a></p></li>
<li><p><a class="reference external" href="http://www.audioscrobbler.net/development/ketama/">http://www.audioscrobbler.net/development/ketama/</a></p></li>
<li><p>svn://svn.audioscrobbler.net/misc/ketama</p></li>
<li><p><a class="reference external" href="http://en.wikipedia.org/wiki/Consistent_hashing">http://en.wikipedia.org/wiki/Consistent_hashing</a></p></li>
</ul>
</section>
<section id="error-reporting">
<h4>Error Reporting<a class="headerlink" href="#error-reporting" title="Link to this heading">¶</a></h4>
<p>Failing methods should report errors to VSL with the Error tag, so
when configuring the shard director, you are advised to check:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnishlog</span> <span class="o">-</span><span class="n">I</span> <span class="n">Error</span><span class="p">:</span><span class="o">^</span><span class="n">vmod_directors</span><span class="o">.</span><span class="n">shard</span>
</pre></div>
</div>
<p>Additional information may be provided as Notices, which can be
checked using</p>
<blockquote>
<div><p>varnishlog -I Notice:^vmod_directors.shard</p>
</div></blockquote>
</section>
</section>
<section id="void-xshard-set-warmup-real-probability-0-0">
<span id="xshard-set-warmup"></span><h3>VOID xshard.set_warmup(REAL probability=0.0)<a class="headerlink" href="#void-xshard-set-warmup-real-probability-0-0" title="Link to this heading">¶</a></h3>
<p>Set the default warmup probability. See the <em>warmup</em> parameter of
<a class="reference internal" href="#xshard-backend">xshard.backend()</a>. If <em>probability</em> is 0.0 (default),
warmup is disabled.</p>
</section>
<section id="void-xshard-set-rampup-duration-duration-0">
<span id="xshard-set-rampup"></span><h3>VOID xshard.set_rampup(DURATION duration=0)<a class="headerlink" href="#void-xshard-set-rampup-duration-duration-0" title="Link to this heading">¶</a></h3>
<p>Set the default rampup duration. See <em>rampup</em> parameter of
<a class="reference internal" href="#xshard-backend">xshard.backend()</a>. If <em>duration</em> is 0 (default), rampup
is disabled.</p>
</section>
<section id="void-xshard-associate-blob-param-0">
<span id="xshard-associate"></span><h3>VOID xshard.associate(BLOB param=0)<a class="headerlink" href="#void-xshard-associate-blob-param-0" title="Link to this heading">¶</a></h3>
<p>Associate a default <a class="reference internal" href="#directors-shard-param">directors.shard_param()</a> object or clear an
association.</p>
<p>The value of the <em>param</em> argument must be a call to the
<a class="reference internal" href="#xshard-param-use">xshard_param.use()</a> method. No argument clears the
association.</p>
<p>The association can be changed per backend request using the <em>param</em>
argument of <a class="reference internal" href="#xshard-backend">xshard.backend()</a>.</p>
</section>
<section id="bool-xshard-add-backend-backend-backend-string-ident-duration-rampup-real-weight">
<span id="xshard-add-backend"></span><h3>BOOL xshard.add_backend(BACKEND backend, [STRING ident], [DURATION rampup], [REAL weight])<a class="headerlink" href="#bool-xshard-add-backend-backend-backend-string-ident-duration-rampup-real-weight" title="Link to this heading">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">BOOL</span> <span class="n">xshard</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span>
      <span class="n">BACKEND</span> <span class="n">backend</span><span class="p">,</span>
      <span class="p">[</span><span class="n">STRING</span> <span class="n">ident</span><span class="p">],</span>
      <span class="p">[</span><span class="n">DURATION</span> <span class="n">rampup</span><span class="p">],</span>
      <span class="p">[</span><span class="n">REAL</span> <span class="n">weight</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Add a backend <em>backend</em> to the director.</p>
<p><em>ident</em>: Optionally specify an identification string for this backend,
which will be hashed by <a class="reference internal" href="#xshard-reconfigure">xshard.reconfigure()</a> to
construct the consistent hashing ring. The identification string
defaults to the backend name.</p>
<p><em>ident</em> allows to add multiple instances of the same backend.</p>
<p><em>rampup</em>: Optionally specify a specific rampup time for this
backend. Otherwise, the per-director rampup time is used (see
<a class="reference internal" href="#xshard-set-rampup">xshard.set_rampup()</a>).</p>
<p><em>weight</em>: Optionally specify a weight to scale the
<a class="reference internal" href="#xshard-reconfigure">xshard.reconfigure()</a> <em>replicas</em> parameter. <em>weight</em> is limited to
at least 1. Values above 10 probably do not make much sense. The
effect of <em>weight</em> is also capped such that the total number of
replicas does not exceed <cite>UINT32_MAX</cite>.</p>
</section>
<section id="bool-xshard-remove-backend-backend-backend-string-ident">
<span id="xshard-remove-backend"></span><h3>BOOL xshard.remove_backend([BACKEND backend], [STRING ident])<a class="headerlink" href="#bool-xshard-remove-backend-backend-backend-string-ident" title="Link to this heading">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">BOOL</span> <span class="n">xshard</span><span class="o">.</span><span class="n">remove_backend</span><span class="p">(</span>
      <span class="p">[</span><span class="n">BACKEND</span> <span class="n">backend</span><span class="o">=</span><span class="mi">0</span><span class="p">],</span>
      <span class="p">[</span><span class="n">STRING</span> <span class="n">ident</span><span class="o">=</span><span class="mi">0</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Remove backend(s) from the director. Either <em>backend</em> or <em>ident</em> must
be specified. <em>ident</em> removes a specific instance. If <em>backend</em> is
given without <em>ident</em>, all instances of this backend are removed.</p>
</section>
<section id="bool-xshard-clear">
<span id="xshard-clear"></span><h3>BOOL xshard.clear()<a class="headerlink" href="#bool-xshard-clear" title="Link to this heading">¶</a></h3>
<p>Remove all backends from the director.</p>
</section>
<section id="bool-xshard-reconfigure-int-replicas-67">
<span id="xshard-reconfigure"></span><h3>BOOL xshard.reconfigure(INT replicas=67)<a class="headerlink" href="#bool-xshard-reconfigure-int-replicas-67" title="Link to this heading">¶</a></h3>
<p>Explicitly reconfigure the consistent hashing ring to reflect backend
changes to become effective immediately.</p>
<p>If this method is not called explicitly, reconfiguration happens at
the end of the current task (after <code class="docutils literal notranslate"><span class="pre">vcl_init</span> <span class="pre">{}</span></code> or when the current
client or backend task is finished).</p>
</section>
<section id="int-xshard-key-string">
<span id="xshard-key"></span><h3>INT xshard.key(STRING)<a class="headerlink" href="#int-xshard-key-string" title="Link to this heading">¶</a></h3>
<p>Convenience method to generate a sharding key for use with the <em>key</em>
argument to the <a class="reference internal" href="#xshard-backend">xshard.backend()</a> method by hashing the
given string with SHA256.</p>
<p>To generate sharding keys using other hashes, use a custom vmod like
<a class="reference external" href="https://code.uplex.de/uplex-varnish/libvmod-blobdigest/blob/master/README.rst">vmod blobdigest</a> with the <em>key_blob</em> argument of the
<a class="reference internal" href="#xshard-backend">xshard.backend()</a> method.</p>
</section>
<section id="backend-xshard-backend-enum-by-int-key-blob-key-blob-int-alt-real-warmup-bool-rampup-enum-healthy-blob-param-enum-resolve">
<span id="xshard-backend"></span><h3>BACKEND xshard.backend([ENUM by], [INT key], [BLOB key_blob], [INT alt], [REAL warmup], [BOOL rampup], [ENUM healthy], [BLOB param], [ENUM resolve])<a class="headerlink" href="#backend-xshard-backend-enum-by-int-key-blob-key-blob-int-alt-real-warmup-bool-rampup-enum-healthy-blob-param-enum-resolve" title="Link to this heading">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">BACKEND</span> <span class="n">xshard</span><span class="o">.</span><span class="n">backend</span><span class="p">(</span>
      <span class="p">[</span><span class="n">ENUM</span> <span class="p">{</span><span class="n">HASH</span><span class="p">,</span> <span class="n">URL</span><span class="p">,</span> <span class="n">KEY</span><span class="p">,</span> <span class="n">BLOB</span><span class="p">}</span> <span class="n">by</span><span class="o">=</span><span class="n">HASH</span><span class="p">],</span>
      <span class="p">[</span><span class="n">INT</span> <span class="n">key</span><span class="p">],</span>
      <span class="p">[</span><span class="n">BLOB</span> <span class="n">key_blob</span><span class="p">],</span>
      <span class="p">[</span><span class="n">INT</span> <span class="n">alt</span><span class="o">=</span><span class="mi">0</span><span class="p">],</span>
      <span class="p">[</span><span class="n">REAL</span> <span class="n">warmup</span><span class="o">=-</span><span class="mi">1</span><span class="p">],</span>
      <span class="p">[</span><span class="n">BOOL</span> <span class="n">rampup</span><span class="o">=</span><span class="mi">1</span><span class="p">],</span>
      <span class="p">[</span><span class="n">ENUM</span> <span class="p">{</span><span class="n">CHOSEN</span><span class="p">,</span> <span class="n">IGNORE</span><span class="p">,</span> <span class="n">ALL</span><span class="p">}</span> <span class="n">healthy</span><span class="o">=</span><span class="n">CHOSEN</span><span class="p">],</span>
      <span class="p">[</span><span class="n">BLOB</span> <span class="n">param</span><span class="p">],</span>
      <span class="p">[</span><span class="n">ENUM</span> <span class="p">{</span><span class="n">NOW</span><span class="p">,</span> <span class="n">LAZY</span><span class="p">}</span> <span class="n">resolve</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Lookup a backend on the consistent hashing ring.</p>
<p>This documentation uses the notion of an order of backends for a
particular shard key. This order is deterministic but seemingly random
as determined by the consistent hashing algorithm and is likely to
differ for different keys, depending on the number of backends and the
number of replicas. In particular, the backend order referred to here
is _not_ the order given when backends are added.</p>
<ul>
<li><p><em>by</em> how to determine the sharding key</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">HASH</span></code>:</p>
<ul>
<li><p>when called in backend context and in <code class="docutils literal notranslate"><span class="pre">vcl_pipe</span> <span class="pre">{}</span></code>: Use the
varnish hash value as set by <code class="docutils literal notranslate"><span class="pre">vcl_hash{}</span></code></p></li>
<li><p>when called in client context other than <code class="docutils literal notranslate"><span class="pre">vcl_pipe</span> <span class="pre">{}</span></code>: hash
<code class="docutils literal notranslate"><span class="pre">req.url</span></code></p></li>
</ul>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">URL</span></code>: hash req.url / bereq.url</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">KEY</span></code>: use the <em>key</em> argument</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">BLOB</span></code>: use the <em>key_blob</em> argument</p></li>
</ul>
</li>
<li><p><em>key</em> lookup key with <code class="docutils literal notranslate"><span class="pre">by=KEY</span></code></p>
<p>the <a class="reference internal" href="#xshard-key">xshard.key()</a> method may come handy to generate a
sharding key from custom strings.</p>
</li>
<li><p><em>key_blob</em> lookup key with <code class="docutils literal notranslate"><span class="pre">by=BLOB</span></code></p>
<p>Currently, this uses the first 4 bytes from the given blob in
network byte order (big endian), left-padded with zeros for blobs
smaller than 4 bytes.</p>
</li>
<li><p><em>alt</em> alternative backend selection</p>
<p>Select the <em>alt</em>-th alternative backend for the given <em>key</em>.</p>
<p>This is particularly useful for retries / restarts due to backend
errors: By setting <code class="docutils literal notranslate"><span class="pre">alt=req.restarts</span></code> or <code class="docutils literal notranslate"><span class="pre">alt=bereq.retries</span></code> with
healthy=ALL, another server gets selected.</p>
<p>The rampup and warmup features are only active for <code class="docutils literal notranslate"><span class="pre">alt==0</span></code></p>
</li>
<li><p><em>rampup</em> slow start for servers which just went healthy</p>
<p>If <code class="docutils literal notranslate"><span class="pre">alt==0</span></code> and the chosen backend is in its rampup period, with a
probability proportional to the fraction of time since the backup
became healthy to the rampup period, return the next alternative
backend, unless this is also in its rampup period.</p>
<p>The default rampup interval can be set per shard director using the
<a class="reference internal" href="#xshard-set-rampup">xshard.set_rampup()</a> method or specifically per
backend with the <a class="reference internal" href="#xshard-add-backend">xshard.add_backend()</a> method.</p>
</li>
<li><p><em>warmup</em> probabilistic alternative server selection</p>
<p>possible values: -1, 0..1</p>
<p><code class="docutils literal notranslate"><span class="pre">-1</span></code>: use the warmup probability from the director definition</p>
<p>Only used for <code class="docutils literal notranslate"><span class="pre">alt==0</span></code>: Sets the ratio of requests (0.0 to 1.0)
that goes to the next alternate backend to warm it up when the
preferred backend is healthy. Not active if any of the preferred or
alternative backend are in rampup.</p>
<p><code class="docutils literal notranslate"><span class="pre">warmup=0.5</span></code> is a convenient way to spread the load for each key
over two backends under normal operating conditions.</p>
</li>
<li><p><em>healthy</em></p>
<ul>
<li><p>CHOSEN: Return a healthy backend if possible.</p>
<p>For <code class="docutils literal notranslate"><span class="pre">alt==0</span></code>, return the first healthy backend or none.</p>
<p>For <code class="docutils literal notranslate"><span class="pre">alt</span> <span class="pre">></span> <span class="pre">0</span></code>, ignore the health state of backends skipped for
alternative backend selection, then return the next healthy
backend. If this does not exist, return the last healthy backend
of those skipped or none.</p>
</li>
<li><p>IGNORE: Completely ignore backend health state</p>
<p>Just return the first or <em>alt</em>-th alternative backend, ignoring
health state, <em>rampup</em> and <em>warmup</em>.</p>
</li>
<li><p>ALL: Check health state also for alternative backend selection</p>
<p>For <code class="docutils literal notranslate"><span class="pre">alt</span> <span class="pre">></span> <span class="pre">0</span></code>, return the <em>alt</em>-th alternative backend of all
those healthy, the last healthy backend found or none.</p>
</li>
</ul>
</li>
<li><p><em>resolve</em></p>
<p>default: <code class="docutils literal notranslate"><span class="pre">LAZY</span></code> in <code class="docutils literal notranslate"><span class="pre">vcl_init{}</span></code>, <code class="docutils literal notranslate"><span class="pre">NOW</span></code> otherwise</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">NOW</span></code>: look up a backend and return it.</p>
<p>Can not be used in <code class="docutils literal notranslate"><span class="pre">vcl_init{}</span></code>.</p>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">LAZY</span></code>: return an instance of this director for later backend resolution.</p>
<p><code class="docutils literal notranslate"><span class="pre">LAZY</span></code> mode is required for referencing shard director instances,
for example as backends for other directors (director layering).</p>
<p>In <code class="docutils literal notranslate"><span class="pre">vcl_init{}</span></code> and on the client side, <code class="docutils literal notranslate"><span class="pre">LAZY</span></code> mode can not be
used with any other argument.</p>
<p>On the backend side and in <code class="docutils literal notranslate"><span class="pre">vcl_pipe</span> <span class="pre">{}</span></code>, parameters from
arguments or an associated parameter set affect the shard director
instance for the backend request irrespective of where it is
referenced.</p>
</li>
</ul>
</li>
<li><p><em>param</em></p>
<p>Use or associate a parameter set. The value of the <em>param</em> argument
must be a call to the <a class="reference internal" href="#xshard-param-use">xshard_param.use()</a> method.</p>
<p>default: as set by <a class="reference internal" href="#xshard-associate">xshard.associate()</a> or unset.</p>
<ul>
<li><p>for <code class="docutils literal notranslate"><span class="pre">resolve=NOW</span></code> take parameter defaults from the
<a class="reference internal" href="#directors-shard-param">directors.shard_param()</a> parameter set</p></li>
<li><p>for <code class="docutils literal notranslate"><span class="pre">resolve=LAZY</span></code> associate the <a class="reference internal" href="#directors-shard-param">directors.shard_param()</a>
parameter set for this backend request</p>
<p>Implementation notes for use of parameter sets with
<code class="docutils literal notranslate"><span class="pre">resolve=LAZY</span></code>:</p>
<ul class="simple">
<li><p>A <em>param</em> argument remains associated and any changes to the
associated parameter set affect the sharding decision once the
director resolves to an actual backend.</p></li>
<li><p>If other parameter arguments are also given, they have
preference and are kept even if the parameter set given by the
<em>param</em> argument is subsequently changed within the same backend
request.</p></li>
<li><p>Each call to <a class="reference internal" href="#xshard-backend">xshard.backend()</a> overrides any
previous call.</p></li>
</ul>
</li>
</ul>
</li>
</ul>
</section>
<section id="void-xshard-debug-int">
<span id="xshard-debug"></span><h3>VOID xshard.debug(INT)<a class="headerlink" href="#void-xshard-debug-int" title="Link to this heading">¶</a></h3>
<p><em>intentionally undocumented</em></p>
</section>
<section id="new-xshard-param-directors-shard-param">
<span id="directors-shard-param"></span><h3>new xshard_param = directors.shard_param()<a class="headerlink" href="#new-xshard-param-directors-shard-param" title="Link to this heading">¶</a></h3>
<p>Create a shard parameter set.</p>
<p>A parameter set allows for re-use of <a class="reference internal" href="#xshard-backend">xshard.backend()</a>
arguments across many shard director instances and simplifies advanced
use cases (e.g. shard director with custom parameters layered below
other directors).</p>
<p>Parameter sets have two scopes:</p>
<ul class="simple">
<li><p>per-VCL scope defined in <code class="docutils literal notranslate"><span class="pre">vcl_init{}</span></code></p></li>
<li><p>per backend request scope</p></li>
</ul>
<p>The per-VCL scope defines defaults for the per backend scope. Any
changes to a parameter set in backend context and in <code class="docutils literal notranslate"><span class="pre">vcl_pipe</span> <span class="pre">{}</span></code>
only affect the respective backend request.</p>
<p>Parameter sets can not be used in client context except for
<code class="docutils literal notranslate"><span class="pre">vcl_pipe</span> <span class="pre">{}</span></code>.</p>
<p>The following example is a typical use case: A parameter set is
associated with several directors. Director choice happens on the
client side and parameters are changed on the backend side to
implement retries on alternative backends:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sub</span> <span class="n">vcl_init</span> <span class="p">{</span>
  <span class="n">new</span> <span class="n">shard_param</span> <span class="o">=</span> <span class="n">directors</span><span class="o">.</span><span class="n">shard_param</span><span class="p">();</span>

<span class="n">new</span> <span class="n">dir_A</span> <span class="o">=</span> <span class="n">directors</span><span class="o">.</span><span class="n">shard</span><span class="p">();</span>
  <span class="n">dir_A</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span><span class="o">...</span><span class="p">);</span>
  <span class="n">dir_A</span><span class="o">.</span><span class="n">reconfigure</span><span class="p">();</span>
  <span class="n">dir_A</span><span class="o">.</span><span class="n">associate</span><span class="p">(</span><span class="n">shard_param</span><span class="o">.</span><span class="n">use</span><span class="p">());</span> <span class="c1"># <-- !</span>

<span class="n">new</span> <span class="n">dir_B</span> <span class="o">=</span> <span class="n">directors</span><span class="o">.</span><span class="n">shard</span><span class="p">();</span>
  <span class="n">dir_B</span><span class="o">.</span><span class="n">add_backend</span><span class="p">(</span><span class="o">...</span><span class="p">);</span>
  <span class="n">dir_B</span><span class="o">.</span><span class="n">reconfigure</span><span class="p">();</span>
  <span class="n">dir_B</span><span class="o">.</span><span class="n">associate</span><span class="p">(</span><span class="n">shard_param</span><span class="o">.</span><span class="n">use</span><span class="p">());</span> <span class="c1"># <-- !</span>
<span class="p">}</span>

<span class="n">sub</span> <span class="n">vcl_recv</span> <span class="p">{</span>
  <span class="k">if</span> <span class="p">(</span><span class="o">...</span><span class="p">)</span> <span class="p">{</span>
    <span class="nb">set</span> <span class="n">req</span><span class="o">.</span><span class="n">backend_hint</span> <span class="o">=</span> <span class="n">dir_A</span><span class="o">.</span><span class="n">backend</span><span class="p">(</span><span class="n">resolve</span><span class="o">=</span><span class="n">LAZY</span><span class="p">);</span>
  <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
    <span class="nb">set</span> <span class="n">req</span><span class="o">.</span><span class="n">backend_hint</span> <span class="o">=</span> <span class="n">dir_B</span><span class="o">.</span><span class="n">backend</span><span class="p">(</span><span class="n">resolve</span><span class="o">=</span><span class="n">LAZY</span><span class="p">);</span>
  <span class="p">}</span>
<span class="p">}</span>

<span class="n">sub</span> <span class="n">vcl_backend_fetch</span> <span class="p">{</span>
  <span class="c1"># changes dir_A and dir_B behaviour</span>
  <span class="n">shard_param</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">alt</span><span class="o">=</span><span class="n">bereq</span><span class="o">.</span><span class="n">retries</span><span class="p">,</span> <span class="n">by</span><span class="o">=</span><span class="n">URL</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
<section id="void-xshard-param-clear">
<span id="xshard-param-clear"></span><h3>VOID xshard_param.clear()<a class="headerlink" href="#void-xshard-param-clear" title="Link to this heading">¶</a></h3>
<p>Reset the parameter set to default values as documented for
<a class="reference internal" href="#xshard-backend">xshard.backend()</a>.</p>
<ul class="simple">
<li><p>in <code class="docutils literal notranslate"><span class="pre">vcl_init{}</span></code>, resets the parameter set default for this VCL in</p></li>
<li><p>backend context and in <code class="docutils literal notranslate"><span class="pre">vcl_pipe</span> <span class="pre">{}</span></code>, resets the parameter set for
this backend request to the VCL defaults</p></li>
</ul>
<p>Restricted to: <code class="docutils literal notranslate"><span class="pre">vcl_pipe</span></code>, <code class="docutils literal notranslate"><span class="pre">backend</span></code>, <code class="docutils literal notranslate"><span class="pre">housekeeping</span></code>.</p>
</section>
<section id="void-xshard-param-set-enum-by-int-key-blob-key-blob-int-alt-real-warmup-bool-rampup-enum-healthy">
<span id="xshard-param-set"></span><h3>VOID xshard_param.set([ENUM by], [INT key], [BLOB key_blob], [INT alt], [REAL warmup], [BOOL rampup], [ENUM healthy])<a class="headerlink" href="#void-xshard-param-set-enum-by-int-key-blob-key-blob-int-alt-real-warmup-bool-rampup-enum-healthy" title="Link to this heading">¶</a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">VOID</span> <span class="n">xshard_param</span><span class="o">.</span><span class="n">set</span><span class="p">(</span>
      <span class="p">[</span><span class="n">ENUM</span> <span class="p">{</span><span class="n">HASH</span><span class="p">,</span> <span class="n">URL</span><span class="p">,</span> <span class="n">KEY</span><span class="p">,</span> <span class="n">BLOB</span><span class="p">}</span> <span class="n">by</span><span class="p">],</span>
      <span class="p">[</span><span class="n">INT</span> <span class="n">key</span><span class="p">],</span>
      <span class="p">[</span><span class="n">BLOB</span> <span class="n">key_blob</span><span class="p">],</span>
      <span class="p">[</span><span class="n">INT</span> <span class="n">alt</span><span class="p">],</span>
      <span class="p">[</span><span class="n">REAL</span> <span class="n">warmup</span><span class="p">],</span>
      <span class="p">[</span><span class="n">BOOL</span> <span class="n">rampup</span><span class="p">],</span>
      <span class="p">[</span><span class="n">ENUM</span> <span class="p">{</span><span class="n">CHOSEN</span><span class="p">,</span> <span class="n">IGNORE</span><span class="p">,</span> <span class="n">ALL</span><span class="p">}</span> <span class="n">healthy</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Change the given parameters of a parameter set as documented for
<a class="reference internal" href="#xshard-backend">xshard.backend()</a>.</p>
<ul class="simple">
<li><p>in <code class="docutils literal notranslate"><span class="pre">vcl_init{}</span></code>, changes the parameter set default for this VCL</p></li>
<li><p>in backend context and in <code class="docutils literal notranslate"><span class="pre">vcl_pipe</span> <span class="pre">{}</span></code>, changes the parameter set
for this backend request, keeping the defaults set for this VCL for
unspecified arguments.</p></li>
</ul>
<p>Restricted to: <code class="docutils literal notranslate"><span class="pre">vcl_pipe</span></code>, <code class="docutils literal notranslate"><span class="pre">backend</span></code>, <code class="docutils literal notranslate"><span class="pre">housekeeping</span></code>.</p>
</section>
<section id="string-xshard-param-get-by">
<span id="xshard-param-get-by"></span><h3>STRING xshard_param.get_by()<a class="headerlink" href="#string-xshard-param-get-by" title="Link to this heading">¶</a></h3>
<p>Get a string representation of the <em>by</em> enum argument which denotes
how a shard director using this parameter object would derive the
shard key. See <a class="reference internal" href="#xshard-backend">xshard.backend()</a>.</p>
</section>
<section id="int-xshard-param-get-key">
<span id="xshard-param-get-key"></span><h3>INT xshard_param.get_key()<a class="headerlink" href="#int-xshard-param-get-key" title="Link to this heading">¶</a></h3>
<p>Get the key which a shard director using this parameter object would
use. See <a class="reference internal" href="#xshard-backend">xshard.backend()</a>.</p>
</section>
<section id="int-xshard-param-get-alt">
<span id="xshard-param-get-alt"></span><h3>INT xshard_param.get_alt()<a class="headerlink" href="#int-xshard-param-get-alt" title="Link to this heading">¶</a></h3>
<p>Get the <em>alt</em> parameter which a shard director using this parameter
object would use. See <a class="reference internal" href="#xshard-backend">xshard.backend()</a>.</p>
</section>
<section id="real-xshard-param-get-warmup">
<span id="xshard-param-get-warmup"></span><h3>REAL xshard_param.get_warmup()<a class="headerlink" href="#real-xshard-param-get-warmup" title="Link to this heading">¶</a></h3>
<p>Get the <em>warmup</em> parameter which a shard director using this parameter
object would use. See <a class="reference internal" href="#xshard-backend">xshard.backend()</a>.</p>
</section>
<section id="bool-xshard-param-get-rampup">
<span id="xshard-param-get-rampup"></span><h3>BOOL xshard_param.get_rampup()<a class="headerlink" href="#bool-xshard-param-get-rampup" title="Link to this heading">¶</a></h3>
<p>Get the <em>rampup</em> parameter which a shard director using this parameter
object would use. See <a class="reference internal" href="#xshard-backend">xshard.backend()</a>.</p>
</section>
<section id="string-xshard-param-get-healthy">
<span id="xshard-param-get-healthy"></span><h3>STRING xshard_param.get_healthy()<a class="headerlink" href="#string-xshard-param-get-healthy" title="Link to this heading">¶</a></h3>
<p>Get a string representation of the <em>healthy</em> enum argument which a
shard director using this parameter object would use. See
<a class="reference internal" href="#xshard-backend">xshard.backend()</a>.</p>
</section>
<section id="blob-xshard-param-use">
<span id="xshard-param-use"></span><h3>BLOB xshard_param.use()<a class="headerlink" href="#blob-xshard-param-use" title="Link to this heading">¶</a></h3>
<p>For use with the <em>param</em> argument of <a class="reference internal" href="#xshard-backend">xshard.backend()</a>
to associate this shard parameter set with a shard director.</p>
<p>Restricted to: <code class="docutils literal notranslate"><span class="pre">vcl_pipe</span></code>, <code class="docutils literal notranslate"><span class="pre">backend</span></code>, <code class="docutils literal notranslate"><span class="pre">housekeeping</span></code>.</p>
</section>
<section id="backend-lookup-string">
<span id="directors-lookup"></span><h3>BACKEND lookup(STRING)<a class="headerlink" href="#backend-lookup-string" title="Link to this heading">¶</a></h3>
<p>Lookup a backend by its name.</p>
<p>Restricted to: <code class="docutils literal notranslate"><span class="pre">housekeeping</span></code>.</p>
</section>
</section>
<section id="acknowledgements">
<h2>ACKNOWLEDGEMENTS<a class="headerlink" href="#acknowledgements" title="Link to this heading">¶</a></h2>
<p>Development of a previous version of the shard director was partly
sponsored by Deutsche Telekom AG - Products & Innovation.</p>
<p>Development of a previous version of the shard director was partly
sponsored by BILD GmbH & Co KG.</p>
</section>
<section id="copyright">
<h2>COPYRIGHT<a class="headerlink" href="#copyright" title="Link to this heading">¶</a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>This document is licensed under the same licence as Varnish
itself. See LICENCE for details.

SPDX-License-Identifier: BSD-2-Clause

Authors: Poul-Henning Kamp <phk@FreeBSD.org>
         Julian Wiesener <jw@uplex.de>
         Nils Goroll <slink@uplex.de>
         Geoffrey Simmons <geoff@uplex.de>

SPDX-License-Identifier: BSD-2-Clause

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
</pre></div>
</div>
</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="#">VMOD directors - Varnish Directors Module</a></li>
</ul>

</div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="vmod_cookie.html"
                          title="previous chapter">VMOD cookie - Varnish Cookie Module</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="vmod_h2.html"
                          title="next chapter">VMOD h2 - Module to control the built-in HTTP2 transport</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/reference/vmod_directors.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="vmod_h2.html" title="VMOD h2 - Module to control the built-in HTTP2 transport"
             >next</a> |</li>
        <li class="right" >
          <a href="vmod_cookie.html" title="VMOD cookie - Varnish Cookie Module"
             >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="">VMOD directors - Varnish Directors Module</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>