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/usr/share/doc/varnish/html/reference

Free Space:

81.58 GB

🔧 Quick Actions

✏️ Editing: cli_protocol.html

<!DOCTYPE html>

<title>VCLI protocol - Scripting the CLI interface &#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="VTLA - Varnish Three Letter Acronyms" href="vtla.html" />
    <link rel="prev" title="Writing a Director" href="directors.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="vtla.html" title="VTLA - Varnish Three Letter Acronyms"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="directors.html" title="Writing a Director"
             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="">VCLI protocol - Scripting the CLI interface</a></li> 
      </ul>
    </div>

<div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="vcli-protocol-scripting-the-cli-interface">
<span id="ref-cli-api"></span><h1>VCLI protocol - Scripting the CLI interface<a class="headerlink" href="#vcli-protocol-scripting-the-cli-interface" title="Link to this heading">¶</a></h1>
<p>The Varnish CLI has a few bells&amp;whistles when used as an API.</p>
<p>First: <cite>vcli.h</cite> contains magic numbers.</p>
<p>Second: If you use <cite>varnishadm</cite> to connect to <cite>varnishd</cite> for
API purposes, use the <cite>-p</cite> argument to get “pass” mode.</p>
<p>In “pass” mode, or with direct CLI connections (more below), the
first line of responses is always exactly 13 bytes long, including
the NL, and it contains two numbers:  The status code and the count
of bytes in the “body” of the response:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>200␣19␣␣␣␣␣␣␤
PONG␣1613397488␣1.0
</pre></div>
</div>
<p>This makes parsing the response unambiguous, even in cases like this
where the response does not end with a NL.</p>
<p>The varnishapi library contains functions to implement the basics of
the CLI protocol, for more, see the <cite>vcli.h</cite> include file.</p>
<section id="local-and-remote-cli-connections">
<span id="ref-remote-cli"></span><h2>Local and remote CLI connections<a class="headerlink" href="#local-and-remote-cli-connections" title="Link to this heading">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> process receives the CLI commands via TCP connections
which require PSK authentication (see below), but which provide no secrecy.</p>
<p>“No secrecy” means that if you configure these TCP connections to run
across a network, anybody who can sniff packets can see your CLI
commands.  If you need secrecy, use <code class="docutils literal notranslate"><span class="pre">ssh</span></code> to run <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code> or
to tunnel the TCP connection.</p>
<p>By default <cite>varnishd</cite> binds to <code class="docutils literal notranslate"><span class="pre">localhost</span></code> and ask the kernel to
assign a random port number.  The resulting listen address is
stored in the shared memory, where the <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code> program finds it.</p>
<p>You can configure <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> to listen to a specific address with
the <code class="docutils literal notranslate"><span class="pre">-T</span></code> argument, this will also be written to shared memory, so
<code class="docutils literal notranslate"><span class="pre">varnishadm</span></code> keeps working:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Bind to internal network</span>
<span class="n">varnishd</span> <span class="o">-</span><span class="n">T</span> <span class="mf">192.168.10.21</span><span class="p">:</span><span class="mi">3245</span>
</pre></div>
</div>
<p>You can also configure <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> to actively open a TCP connection
to another “controller” program, with the <code class="docutils literal notranslate"><span class="pre">-M</span></code> argument.</p>
<p>Finally, when run in “debug mode” with the <code class="docutils literal notranslate"><span class="pre">-d</span></code> argument, <code class="docutils literal notranslate"><span class="pre">varnishd</span></code>
will stay in the foreground and turn stdin/stdout into a CLI connection.</p>
</section>
<section id="authentication-cli-connections">
<span id="ref-psk-auth"></span><h2>Authentication CLI connections<a class="headerlink" href="#authentication-cli-connections" title="Link to this heading">¶</a></h2>
<p>CLI connections to <cite>varnishd</cite> are authenticated with a “pre-shared-key”
authentication scheme, where the other end must prove they know
<em>the contents of</em> the secret file <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> uses.</p>
<p>They do not have to read the precise same file on that specific
computer, they could read an entirely different file on a different
computer or fetch the secret from a server.</p>
<p>The name of the file can be configured with the <code class="docutils literal notranslate"><span class="pre">-S</span></code> option, and
<code class="docutils literal notranslate"><span class="pre">varnishd</span></code> records the name in shared memory, so <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code>
can find it.</p>
<p>As a bare minimum <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> needs to be able to read the file,
but other than that, it can be restricted any way you want.</p>
<p>Since it is not the file, but only the content of it that matter,
you can make the file unreadable by everybody, and instead place
a copy of the file in the home directories of the authorized users.</p>
<p>The file is read only at the moment when the <cite>auth</cite> CLI command is
issued and the contents is not cached in <cite>varnishd</cite>, so you can
change it as often as you want.</p>
<p>An authenticated session looks like this:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>critter phk&gt; telnet localhost 1234
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is &#39;^]&#39;.
107 59
ixslvvxrgkjptxmcgnnsdxsvdmvfympg

Authentication required.

auth 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
200 279
-----------------------------
Varnish Cache CLI 1.0
-----------------------------
FreeBSD,13.0-CURRENT,amd64,-jnone,-sdefault,-sdefault,-hcritbit
varnish-trunk revision 89a558e56390d425c52732a6c94087eec9083115

Type &#39;help&#39; for command list.
Type &#39;quit&#39; to close CLI session.
Type &#39;start&#39; to launch worker process.
</pre></div>
</div>
<p>The CLI status of 107 indicates that authentication is necessary. The
first 32 characters of the response text is the challenge
“ixsl…mpg”. The challenge is randomly generated for each CLI
connection, and changes each time a 107 is emitted.</p>
<p>The most recently emitted challenge must be used for calculating the
authenticator “455c…c89a”.</p>
<p>The authenticator is calculated by applying the SHA256 function to the
following byte sequence:</p>
<ul class="simple">
<li><p>Challenge string</p></li>
<li><p>Newline (0x0a) character.</p></li>
<li><p>Contents of the secret file</p></li>
<li><p>Challenge string</p></li>
<li><p>Newline (0x0a) character.</p></li>
</ul>
<p>and dumping the resulting digest in lower-case hex.</p>
<p>In the above example, the secret file contains <code class="docutils literal notranslate"><span class="pre">foo\n</span></code> and thus:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>critter phk&gt; hexdump secret
00000000  66 6f 6f 0a                                       |foo.|
00000004
critter phk&gt; cat &gt; tmpfile
ixslvvxrgkjptxmcgnnsdxsvdmvfympg
foo
ixslvvxrgkjptxmcgnnsdxsvdmvfympg
^D
critter phk&gt; hexdump -C tmpfile
00000000  69 78 73 6c 76 76 78 72  67 6b 6a 70 74 78 6d 63  |ixslvvxrgkjptxmc|
00000010  67 6e 6e 73 64 78 73 76  64 6d 76 66 79 6d 70 67  |gnnsdxsvdmvfympg|
00000020  0a 66 6f 6f 0a 69 78 73  6c 76 76 78 72 67 6b 6a  |.foo.ixslvvxrgkj|
00000030  70 74 78 6d 63 67 6e 6e  73 64 78 73 76 64 6d 76  |ptxmcgnnsdxsvdmv|
00000040  66 79 6d 70 67 0a                                 |fympg.|
00000046
critter phk&gt; sha256 tmpfile
SHA256 (tmpfile) = 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
critter phk&gt; openssl dgst -sha256 &lt; tmpfile
455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
</pre></div>
</div>
<p>The sourcefile <cite>lib/libvarnish/cli_auth.c</cite> contains a useful function
which calculates the response, given an open filedescriptor to the
secret file, and the challenge string.</p>
</section>
<section id="see-also">
<h2>See also:<a class="headerlink" href="#see-also" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="varnishadm.html#varnishadm-1"><span class="std std-ref">varnishadm</span></a></p></li>
<li><p><a class="reference internal" href="varnishd.html#varnishd-1"><span class="std std-ref">varnishd</span></a></p></li>
<li><p><a class="reference internal" href="vcl.html#vcl-7"><span class="std std-ref">VCL</span></a></p></li>
</ul>
</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="#">VCLI protocol - Scripting the CLI interface</a><ul>
<li><a class="reference internal" href="#local-and-remote-cli-connections">Local and remote CLI connections</a></li>
<li><a class="reference internal" href="#authentication-cli-connections">Authentication CLI connections</a></li>
<li><a class="reference internal" href="#see-also">See also:</a></li>
</ul>
</li>
</ul>

</div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="directors.html"
                          title="previous chapter">Writing a Director</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="vtla.html"
                          title="next chapter">VTLA - Varnish Three Letter Acronyms</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/reference/cli_protocol.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="vtla.html" title="VTLA - Varnish Three Letter Acronyms"
             >next</a> |</li>
        <li class="right" >
          <a href="directors.html" title="Writing a Director"
             >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="">VCLI protocol - Scripting the CLI interface</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: cli_protocol.html

📤 Upload File

📁 Create Folder

📄 Create File

✏️ Rename Item

🗑️ Delete Confirmation