

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>CLI - bossing Varnish around &mdash; Varnish version 4.0.0 documentation</title>
    
    <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '4.0.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="top" title="Varnish version 4.0.0 documentation" href="../index.html" />
    <link rel="up" title="Starting and running Varnish" href="running.html" />
    <link rel="next" title="Storage backends" href="storage-backends.html" />
    <link rel="prev" title="Important command line arguments" href="command-line.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="storage-backends.html" title="Storage backends"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="command-line.html" title="Important command line arguments"
             accesskey="P">previous</a> |</li>
        <li><a href="../index.html">Varnish version 4.0.0 documentation</a> &raquo;</li>
          <li><a href="index.html" >The Varnish Users Guide</a> &raquo;</li>
          <li><a href="running.html" accesskey="U">Starting and running Varnish</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="cli-bossing-varnish-around">
<span id="run-cli"></span><h1>CLI - bossing Varnish around<a class="headerlink" href="#cli-bossing-varnish-around" title="Permalink to this headline">¶</a></h1>
<p>Once <cite>varnishd</cite> is started, you can control it using the command line
interface.</p>
<p>The easiest way to do this, is using <cite>varnishadm</cite> on the
same machine as <cite>varnishd</cite> is running:</p>
<div class="highlight-python"><pre>varnishadm help</pre>
</div>
<p>If you want to run <cite>varnishadm</cite> from a remote system, you can do it
two ways.</p>
<p>You can SSH into the <cite>varnishd</cite> computer and run <cite>varnishadm</cite>:</p>
<div class="highlight-python"><pre>ssh $http_front_end varnishadm help</pre>
</div>
<p>But you can also configure <cite>varnishd</cite> to accept remote CLI connections
(using the '-T' and '-S' arguments):</p>
<div class="highlight-python"><pre>varnishd -T :6082 -S /etc/varnish_secret</pre>
</div>
<p>And then on the remote system run <cite>varnishadm</cite>:</p>
<div class="highlight-python"><pre>varnishadm -T $http_front_end -S /etc/copy_of_varnish_secret help</pre>
</div>
<p>but as you can see, SSH is much more convenient.</p>
<p>If you run <cite>varnishadm</cite> without arguments, it will read CLI commands from
<cite>stdin</cite>, if you give it arguments, it will treat those as the single
CLI command to execute.</p>
<p>The CLI always returns a status code to tell how it went:  '200'
means OK, anything else means there were some kind of trouble.</p>
<p><cite>varnishadm</cite> will exit with status 1 and print the status code on
standard error if it is not 200.</p>
<div class="section" id="what-can-you-do-with-the-cli">
<h2>What can you do with the CLI<a class="headerlink" href="#what-can-you-do-with-the-cli" title="Permalink to this headline">¶</a></h2>
<p>The CLI gives you almost total control over <cite>varnishd</cite> some of the more important tasks you can perform are:</p>
<ul class="simple">
<li>load/use/discard VCL programs</li>
<li>ban (invalidate) cache content</li>
<li>change parameters</li>
<li>start/stop worker process</li>
</ul>
<p>We will discuss each of these briefly below.</p>
<div class="section" id="load-use-and-discard-vcl-programs">
<h3>Load, use and discard VCL programs<a class="headerlink" href="#load-use-and-discard-vcl-programs" title="Permalink to this headline">¶</a></h3>
<p>All caching and policy decisions are made by VCL programs.</p>
<p>You can have multiple VCL programs loaded, but one of them
is designated the &quot;active&quot; VCL program, and this is where
all new requests start out.</p>
<p>To load new VCL program:</p>
<div class="highlight-python"><pre>varnish&gt; vcl.load some_name some_filename</pre>
</div>
<p>Loading will read the VCL program from the file, and compile it. If
the compilation fails, you will get an error messages:</p>
<div class="highlight-python"><pre>.../mask is not numeric.
('input' Line 4 Pos 17)
                "192.168.2.0/24x",
----------------#################-

Running VCC-compiler failed, exit 1
VCL compilation failed</pre>
</div>
<p>If compilation succeeds, the VCL program is loaded, and you can
now make it the active VCL, whenever you feel like it:</p>
<div class="highlight-python"><pre>varnish&gt; vcl.use some_name</pre>
</div>
<p>If you find out that was a really bad idea, you can switch back
to the previous VCL program again:</p>
<div class="highlight-python"><pre>varnish&gt; vcl.use old_name</pre>
</div>
<p>The switch is instantaneous, all new requests will start using the
VCL you activated right away. The requests currently being processed complete
using whatever VCL they started with.</p>
<p>It is good idea to design an emergency-VCL before you need it,
and always have it loaded, so you can switch to it with a single
vcl.use command.</p>
</div>
<div class="section" id="ban-cache-content">
<h3>Ban cache content<a class="headerlink" href="#ban-cache-content" title="Permalink to this headline">¶</a></h3>
<p>Varnish offers &quot;purges&quot; to remove things from cache, provided that
you know exactly what they are.</p>
<p>But sometimes it is useful to be able to throw things out of cache
without having an exact list of what to throw out.</p>
<p>Imagine for instance that the company logo changed and now you need
Varnish to stop serving the old logo out of the cache:</p>
<div class="highlight-python"><pre>varnish&gt; ban req.url ~ "logo.*[.]png"</pre>
</div>
<p>should do that, and yes, that is a regular expression.</p>
<p>We call this &quot;banning&quot; because the objects are still in the cache,
but they are banned from delivery.</p>
<p>Instead of checking each and every cached object right away, we
test each object against the regular expression only if and when
an HTTP request asks for it.</p>
<p>Banning stuff is much cheaper than restarting Varnish to get rid
of wronly cached content.</p>
</div>
<div class="section" id="change-parameters">
<h3>Change parameters<a class="headerlink" href="#change-parameters" title="Permalink to this headline">¶</a></h3>
<p>Parameters can be set on the command line with the '-p' argument,
but they can also be examined and changed on the fly from the CLI:</p>
<div class="highlight-python"><pre>varnish&gt; param.show prefer_ipv6
200
prefer_ipv6         off [bool]
                    Default is off
                    Prefer IPv6 address when connecting to backends
                    which have both IPv4 and IPv6 addresses.

varnish&gt; param.set prefer_ipv6 true
200</pre>
</div>
<p>In general it is not a good idea to modify parameters unless you
have a good reason, such as performance tuning or security configuration.</p>
<p>Most parameters will take effect instantly, or with a natural delay
of some duration,</p>
<p>but a few of them requires you to restart the
child process before they take effect. This is always noted in the
description of the parameter.</p>
</div>
<div class="section" id="starting-and-stopping-the-worker-process">
<h3>Starting and stopping the worker process<a class="headerlink" href="#starting-and-stopping-the-worker-process" title="Permalink to this headline">¶</a></h3>
<p>In general you should just leave the worker process running, but
if you need to stop and/or start it, the obvious commands work:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">varnish</span><span class="o">&gt;</span> <span class="n">stop</span>
</pre></div>
</div>
<p>and:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">varnish</span><span class="o">&gt;</span> <span class="n">start</span>
</pre></div>
</div>
<p>If you start <cite>varnishd</cite> with the '-d' (debugging) argument, you will
always need to start the child process explicitly.</p>
<p>Should the child process die, the master process will automatically
restart it, but you can disable that with the 'auto_restart' parameter.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">CLI - bossing Varnish around</a><ul>
<li><a class="reference internal" href="#what-can-you-do-with-the-cli">What can you do with the CLI</a><ul>
<li><a class="reference internal" href="#load-use-and-discard-vcl-programs">Load, use and discard VCL programs</a></li>
<li><a class="reference internal" href="#ban-cache-content">Ban cache content</a></li>
<li><a class="reference internal" href="#change-parameters">Change parameters</a></li>
<li><a class="reference internal" href="#starting-and-stopping-the-worker-process">Starting and stopping the worker process</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="command-line.html"
                        title="previous chapter">Important command line arguments</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="storage-backends.html"
                        title="next chapter">Storage backends</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="../_sources/users-guide/run_cli.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="storage-backends.html" title="Storage backends"
             >next</a> |</li>
        <li class="right" >
          <a href="command-line.html" title="Important command line arguments"
             >previous</a> |</li>
        <li><a href="../index.html">Varnish version 4.0.0 documentation</a> &raquo;</li>
          <li><a href="index.html" >The Varnish Users Guide</a> &raquo;</li>
          <li><a href="running.html" >Starting and running Varnish</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2010-2014, Varnish Software AS.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
    </div>
  </body>
</html>