Enhanced PHP File Manager

⬆️ Go Up (..)

📊 Server Information

Server:

nginx/1.28.0

System:

Linux 6.8.0-90-generic

PHP Version:

8.4.15

User:

alqudsvolunteers

Directory:

/home/alqudsvolunteers/rootlink/proc/thread-self/root/usr/share/doc/varnish/html/reference

Free Space:

79.58 GB

🔧 Quick Actions

✏️ Editing: directors.html

<!DOCTYPE html>

<title>Writing a Director &#8212; 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="VCLI protocol - Scripting the CLI interface" href="cli_protocol.html" />
    <link rel="prev" title="VSM: Shared Memory Logging and Statistics" href="vsm.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="cli_protocol.html" title="VCLI protocol - Scripting the CLI interface"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="vsm.html" title="VSM: Shared Memory Logging and Statistics"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Varnish Reference Manual</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Writing a Director</a></li> 
      </ul>
    </div>

<div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="writing-a-director">
<span id="ref-writing-a-director"></span><h1>Writing a Director<a class="headerlink" href="#writing-a-director" title="Link to this heading">¶</a></h1>
<p>Varnish already provides a set of general-purpose directors, and since Varnish
4, it is bundled in the built-in <a class="reference internal" href="vmod_directors.html#vmod-directors-3"><span class="std std-ref">VMOD directors - Varnish Directors Module</span></a>. Writing a director
boils down to writing a VMOD, using the proper data structures and APIs. Not
only can you write your own director if none of the built-ins fit your needs,
but since Varnish 4.1 you can even write your own backends.</p>
<p>Backends can be categorized as such:</p>
<ul class="simple">
<li><p>static: native backends declared in VCL</p></li>
<li><p>dynamic: native backends created by VMODs</p></li>
<li><p>custom: backends created and fully managed by VMODs</p></li>
</ul>
<section id="backends-vs-directors">
<h2>Backends vs Directors<a class="headerlink" href="#backends-vs-directors" title="Link to this heading">¶</a></h2>
<p>The intuitive classification for backend and director is an endpoint for the
former and a loadbalancer for the latter, but the actual implementation is a bit
more subtle. VMODs can accept backend arguments and return backends in VCL (see
<a class="reference internal" href="vmod.html#ref-vmod-vcl-c-types"><span class="std std-ref">VCL and C data types</span></a>), but the underlying C type is <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">director</span></code>
aka the <code class="docutils literal notranslate"><span class="pre">VCL_BACKEND</span></code> typedef.
Under the hood director is a generic concept, and a backend is a kind of
director.</p>
<p>The line between the two is somewhat blurry at this point, let’s look at some
code instead:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">//</span> <span class="n">VRT</span> <span class="n">interface</span> <span class="kn">from</span> <span class="nn">vrt.h</span>

<span class="n">struct</span> <span class="n">vdi_methods</span> <span class="p">{</span>
    <span class="n">unsigned</span>                        <span class="n">magic</span><span class="p">;</span>
<span class="c1">#define VDI_METHODS_MAGIC           0x4ec0c4bb</span>
    <span class="n">const</span> <span class="n">char</span>                      <span class="o">*</span><span class="nb">type</span><span class="p">;</span>
    <span class="n">vdi_http1pipe_f</span>                 <span class="o">*</span><span class="n">http1pipe</span><span class="p">;</span>
    <span class="n">vdi_healthy_f</span>                   <span class="o">*</span><span class="n">healthy</span><span class="p">;</span>
    <span class="n">vdi_resolve_f</span>                   <span class="o">*</span><span class="n">resolve</span><span class="p">;</span>
    <span class="n">vdi_gethdrs_f</span>                   <span class="o">*</span><span class="n">gethdrs</span><span class="p">;</span>
    <span class="n">vdi_getip_f</span>                     <span class="o">*</span><span class="n">getip</span><span class="p">;</span>
    <span class="n">vdi_finish_f</span>                    <span class="o">*</span><span class="n">finish</span><span class="p">;</span>
    <span class="n">vdi_event_f</span>                     <span class="o">*</span><span class="n">event</span><span class="p">;</span>
    <span class="n">vdi_release_f</span>                   <span class="o">*</span><span class="n">release</span><span class="p">;</span>
    <span class="n">vdi_destroy_f</span>                   <span class="o">*</span><span class="n">destroy</span><span class="p">;</span>
    <span class="n">vdi_panic_f</span>                     <span class="o">*</span><span class="n">panic</span><span class="p">;</span>
    <span class="n">vdi_list_f</span>                      <span class="o">*</span><span class="nb">list</span><span class="p">;</span>
<span class="p">};</span>

<span class="n">struct</span> <span class="n">director</span> <span class="p">{</span>
    <span class="n">unsigned</span>                        <span class="n">magic</span><span class="p">;</span>
<span class="c1">#define DIRECTOR_MAGIC              0x3336351d</span>
    <span class="n">void</span>                            <span class="o">*</span><span class="n">priv</span><span class="p">;</span>
    <span class="n">char</span>                            <span class="o">*</span><span class="n">vcl_name</span><span class="p">;</span>
    <span class="n">struct</span> <span class="n">vcldir</span>                   <span class="o">*</span><span class="n">vdir</span><span class="p">;</span>
    <span class="n">struct</span> <span class="n">lock</span>                     <span class="o">*</span><span class="n">mtx</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
<p>A director can be summed up as:</p>
<ul class="simple">
<li><p>being of a specific <code class="docutils literal notranslate"><span class="pre">type</span></code> with a set of operations which is
identical for all instances of that particular type</p></li>
<li><p>some instance specific attributes such as a <code class="docutils literal notranslate"><span class="pre">vcl_name</span></code>
and <code class="docutils literal notranslate"><span class="pre">type</span></code>-specific private data</p></li>
</ul>
<p>The difference between a <em>load balancing</em> director and a <em>backend</em>
director is mainly the functions they will implement.</p>
<p>The fundamental steps towards a director implementation are:</p>
<ul>
<li><p>implement the required functions</p></li>
<li><p>fill a <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">vdi_methods</span></code> with the name of your director type
and your function pointers</p>
<p>Existence of a <code class="docutils literal notranslate"><span class="pre">healthy</span></code> callback signifies that the director has
some means of dynamically determining its health state.</p>
</li>
<li><p>in your constructor or other initialization routine, allocate and
initialize your director-specific configuration state (aka private
data) and call <code class="docutils literal notranslate"><span class="pre">VRT_AddDirector()</span></code> with your <code class="docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">vdi_methods</span></code>, the pointer to your state and a printf format for the
name of your director instance</p></li>
<li><p>implement methods or functions returning <code class="docutils literal notranslate"><span class="pre">VCL_BACKEND</span></code></p></li>
<li><p>in your destructor or other finalizer, call <code class="docutils literal notranslate"><span class="pre">VRT_DelDirector()</span></code></p></li>
<li><p>implement a <code class="docutils literal notranslate"><span class="pre">destroy</span></code> callback to destroy the actual director
private state. It will be called when all references to the director
are gone, until then the private state must remain intact and
<code class="docutils literal notranslate"><span class="pre">vdi_methods</span></code> functions callable (but they may return errors).</p></li>
</ul>
<p>While vmods can implement functions returning directors,
<a class="reference internal" href="vmod.html#ref-vmod-vcl-c-objects"><span class="std std-ref">Objects and methods</span></a> are usually a more natural
representation with vmod object instances being or referring to the
director private data.</p>
</section>
<section id="load-balancing-directors">
<h2>Load Balancing Directors<a class="headerlink" href="#load-balancing-directors" title="Link to this heading">¶</a></h2>
<p>As in <a class="reference internal" href="vmod_directors.html#vmod-directors-3"><span class="std std-ref">VMOD directors - Varnish Directors Module</span></a>, you can write directors that will group
backends sharing the same role, and pick them according to a strategy. If you
need more than the built-in strategies (round-robin, hash, …), even though
they can be stacked, it is always possible to write your own.</p>
<p>In this case you simply need to implement the <code class="docutils literal notranslate"><span class="pre">resolve</span></code> function for the
director. Directors are walked until a leaf director is found. A leaf director
doesn’t have a <code class="docutils literal notranslate"><span class="pre">resolve</span></code> function and is used to actually make the backend
request, just like the backends you declare in VCL.</p>
<p><em>load balancing</em> directors use <code class="docutils literal notranslate"><span class="pre">VRT_Assign_Backend()</span></code> to take
references to other directors. They <em>must</em> implement a <code class="docutils literal notranslate"><span class="pre">release</span></code>
callback which has to release all references to other directors and
ensure that none are gained after it returns.</p>
</section>
<section id="static-directors">
<h2>Static Directors<a class="headerlink" href="#static-directors" title="Link to this heading">¶</a></h2>
<p>As opposed to dynamic backends covered below, directors which are
guaranteed to have VCL lifetime (that is, they do not get destroyed
before the VCL goes cold) can call <code class="docutils literal notranslate"><span class="pre">VRT_StaticDirector()</span></code> to avoid
reference counting overhead.</p>
</section>
<section id="dynamic-backends">
<h2>Dynamic Backends<a class="headerlink" href="#dynamic-backends" title="Link to this heading">¶</a></h2>
<p>If you want to speak HTTP/1 over TCP or UDS, but for some reason VCL
does not fit the bill, you can instead reuse the whole backend
facility. It allows you for instance to add and remove backends
on-demand without the need to reload your
VCL. You can then leverage your provisioning system.</p>
<p>Consider the following snippet:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">backend</span> <span class="n">default</span> <span class="p">{</span>
    <span class="o">.</span><span class="n">host</span> <span class="o">=</span> <span class="s2">&quot;localhost&quot;</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The VCL compiler turns this declaration into a <code class="docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">vrt_backend</span></code>. When the VCL is loaded, Varnish calls
<code class="docutils literal notranslate"><span class="pre">VRT_new_backend</span></code> (or rather <code class="docutils literal notranslate"><span class="pre">VRT_new_backend_clustered</span></code> for VSM
efficiency) in order to create the director. Varnish doesn’t expose
its data structure for actual backends, only the director abstraction
and dynamic backends are built just like static backends, one <em>struct</em>
at a time. You can get rid of the <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">vrt_backend</span></code> as soon as
you have the <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">director</span></code>.</p>
<p>A (dynamic) backend can’t exceed its VCL’s lifespan, because native
backends are <em>owned</em> by VCLs. Though a dynamic backend can’t outlive
its VCL, it can be deleted any time with <code class="docutils literal notranslate"><span class="pre">VRT_delete_backend</span></code>. The
VCL will delete the remaining backends once discarded, you don’t need
to take care of it.</p>
<p>Reference counting is used to ensure that backends which are no longer
referenced are destroyed.</p>
<p>Finally, Varnish will take care of event propagation for <em>all</em> native backends,
but dynamic backends can only be created when the VCL is warm. If your backends
are created by an independent thread (basically outside of VCL scope) you must
subscribe to VCL events and watch for VCL state (see
<a class="reference internal" href="vmod.html#ref-vmod-event-functions"><span class="std std-ref">Event functions</span></a>). Varnish will panic if you try to create a
backend on a cold VCL, and <code class="docutils literal notranslate"><span class="pre">VRT_new_backend</span></code> will return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if the VCL
is cooling. You are also encouraged to comply with the
<a class="reference internal" href="varnish-cli.html#ref-vcl-temperature"><span class="std std-ref">VCL Temperature</span></a> in general.</p>
</section>
<section id="health-probes">
<span id="ref-writing-a-director-loadbalancer"></span><h2>Health Probes<a class="headerlink" href="#health-probes" title="Link to this heading">¶</a></h2>
<p>It is possible in a VCL program to query the health of a director (see
<a class="reference internal" href="vmod_std.html#std-healthy"><span class="std std-ref">BOOL healthy(BACKEND be)</span></a>). A director can report its health if it implements the
<code class="docutils literal notranslate"><span class="pre">healthy</span></code> function, it is otherwise always considered healthy.</p>
<p>Unless you are making a dynamic backend, you need to take care of the
health probes yourselves. For <em>load balancing</em> directors, being
healthy typically means having at least one healthy underlying backend
or director.</p>
<p>For dynamic backends, it is just a matter of assigning the <code class="docutils literal notranslate"><span class="pre">probe</span></code> field in
the <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">vrt_backend</span></code>. Once the director is created, the probe definition
too is no longer needed. It is then Varnish that will take care of the health
probe and disable the feature on a cold VCL (see
<a class="reference internal" href="vmod.html#ref-vmod-event-functions"><span class="std std-ref">Event functions</span></a>).</p>
<p>Instead of initializing your own probe definition, you can get a <code class="docutils literal notranslate"><span class="pre">VCL_PROBE</span></code>
directly built from VCL (see <a class="reference internal" href="vmod.html#ref-vmod-vcl-c-types"><span class="std std-ref">VCL and C data types</span></a>).</p>
</section>
<section id="custom-backends">
<h2>Custom Backends<a class="headerlink" href="#custom-backends" title="Link to this heading">¶</a></h2>
<p>If you want to implement a custom backend, have a look at how Varnish
implements native backends. It is the canonical implementation, and
though it provides other services like connection pooling or
statistics, it is essentially a director which state is a <code class="docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">backend</span></code>. Varnish native backends currently speak HTTP/1 over TCP or
UDS, and as such, you need to make your own custom backend if you want
Varnish to do otherwise such as connect over UDP or speak a different
protocol.</p>
<p>If you want to leverage probes declarations in VCL, which have the advantage of
being reusable since they are only specifications, you can. However, you need
to implement the whole probing infrastructure from scratch.</p>
<p>You may also consider making your custom backend compliant with regards to the
VCL state (see <a class="reference internal" href="vmod.html#ref-vmod-event-functions"><span class="std std-ref">Event functions</span></a>).</p>
<p>If you are implementing the <cite>gethdrs</cite> method of your backend (i.e. your
backend is able to generate a backend response to be manipulated in
<cite>vcl_backend_response</cite>), you will want to log the response code, protocol and
the various headers it’ll create for easier debugging. For this, you can look
at the <cite>VSL*</cite> family of functions, listed in <cite>cache/cache.h</cite>.</p>
<section id="data-structure-considerations">
<h3>Data structure considerations<a class="headerlink" href="#data-structure-considerations" title="Link to this heading">¶</a></h3>
<p>When you are creating a custom backend, you may want to provide the semantics
of the native backends. In this case, instead of repeating the redundant fields
between data structures, you can use the macros <code class="docutils literal notranslate"><span class="pre">VRT_BACKEND_FIELDS</span></code> and
<code class="docutils literal notranslate"><span class="pre">VRT_BACKEND_PROBE_FIELDS</span></code> to declare them all at once. This is the little
dance Varnish uses to copy data between the <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">vrt_backend</span></code> and its
internal data structure for example.</p>
<p>The copy can be automated with the macros <code class="docutils literal notranslate"><span class="pre">VRT_BACKEND_HANDLE</span></code> and
<code class="docutils literal notranslate"><span class="pre">VRT_BACKEND_PROBE_HANDLE</span></code>. You can look at how they can be used in the
Varnish code base.</p>
</section>
</section>
</section>

<div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3><a href="../index.html">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">Writing a Director</a><ul>
<li><a class="reference internal" href="#backends-vs-directors">Backends vs Directors</a></li>
<li><a class="reference internal" href="#load-balancing-directors">Load Balancing Directors</a></li>
<li><a class="reference internal" href="#static-directors">Static Directors</a></li>
<li><a class="reference internal" href="#dynamic-backends">Dynamic Backends</a></li>
<li><a class="reference internal" href="#health-probes">Health Probes</a></li>
<li><a class="reference internal" href="#custom-backends">Custom Backends</a><ul>
<li><a class="reference internal" href="#data-structure-considerations">Data structure considerations</a></li>
</ul>
</li>
</ul>
</li>
</ul>

</div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="vsm.html"
                          title="previous chapter">VSM: Shared Memory Logging and Statistics</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="cli_protocol.html"
                          title="next chapter">VCLI protocol - Scripting the CLI interface</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/reference/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="cli_protocol.html" title="VCLI protocol - Scripting the CLI interface"
             >next</a> |</li>
        <li class="right" >
          <a href="vsm.html" title="VSM: Shared Memory Logging and Statistics"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" >The Varnish Reference Manual</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Writing a Director</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
    &#169; Copyright 2010-2014, Varnish Software AS.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
    </div>
  </body>
</html>

❌ Cancel

🗂️ Enhanced PHP File Manager

📊 Server Information

🔧 Quick Actions

✏️ Editing: directors.html

📤 Upload File

📁 Create Folder

📄 Create File

✏️ Rename Item

🗑️ Delete Confirmation