File: //proc/thread-self/root/usr/share/doc/varnish-6.0.3/html/users-guide/run_cli.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>CLI - bossing Varnish around — Varnish version 6.0.3 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="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" 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="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 class="nav-item nav-item-0"><a href="../index.html">Varnish version 6.0.3 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Varnish Users Guide</a> »</li>
<li class="nav-item nav-item-2"><a href="running.html" accesskey="U">Starting and running Varnish</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<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 <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> is started, you can control it using the command line
interface.</p>
<p>The easiest way to do this, is using <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code> on the
same machine as <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> is running:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnishadm</span> <span class="n">help</span>
</pre></div>
</div>
<p>If you want to run <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code> from a remote system, you can do it
two ways.</p>
<p>You can SSH into the <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> computer and run <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>ssh $http_front_end varnishadm help
</pre></div>
</div>
<p>But you can also configure <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> to accept remote CLI connections
(using the ‘-T’ and ‘-S’ arguments):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnishd</span> <span class="o">-</span><span class="n">T</span> <span class="p">:</span><span class="mi">6082</span> <span class="o">-</span><span class="n">S</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">varnish_secret</span>
</pre></div>
</div>
<p>And then on the remote system run <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>varnishadm -T $http_front_end -S /etc/copy_of_varnish_secret help
</pre></div>
</div>
<p>but as you can see, SSH is much more convenient.</p>
<p>If you run <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code> without arguments, it will read CLI commands from
<code class="docutils literal notranslate"><span class="pre">stdin</span></code>, 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><code class="docutils literal notranslate"><span class="pre">varnishadm</span></code> 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 <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> 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 “active” VCL program, and this is where
all new requests start out.</p>
<p>To load new VCL program:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnish</span><span class="o">></span> <span class="n">vcl</span><span class="o">.</span><span class="n">load</span> <span class="n">some_name</span> <span class="n">some_filename</span>
</pre></div>
</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-default notranslate"><div class="highlight"><pre><span></span><span class="o">.../</span><span class="n">mask</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">numeric</span><span class="o">.</span>
<span class="p">(</span><span class="s1">'input'</span> <span class="n">Line</span> <span class="mi">4</span> <span class="n">Pos</span> <span class="mi">17</span><span class="p">)</span>
<span class="s2">"192.168.2.0/24x"</span><span class="p">,</span>
<span class="o">----------------</span><span class="c1">#################-</span>
<span class="n">Running</span> <span class="n">VCC</span><span class="o">-</span><span class="n">compiler</span> <span class="n">failed</span><span class="p">,</span> <span class="n">exit</span> <span class="mi">1</span>
<span class="n">VCL</span> <span class="n">compilation</span> <span class="n">failed</span>
</pre></div>
</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-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnish</span><span class="o">></span> <span class="n">vcl</span><span class="o">.</span><span class="n">use</span> <span class="n">some_name</span>
</pre></div>
</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-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnish</span><span class="o">></span> <span class="n">vcl</span><span class="o">.</span><span class="n">use</span> <span class="n">old_name</span>
</pre></div>
</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 “purges” 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnish</span><span class="o">></span> <span class="n">ban</span> <span class="n">req</span><span class="o">.</span><span class="n">url</span> <span class="o">~</span> <span class="s2">"logo.*[.]png"</span>
</pre></div>
</div>
<p>should do that, and yes, that is a regular expression.</p>
<p>We call this “banning” 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnish</span><span class="o">></span> <span class="n">param</span><span class="o">.</span><span class="n">show</span> <span class="n">prefer_ipv6</span>
<span class="mi">200</span>
<span class="n">prefer_ipv6</span> <span class="n">off</span> <span class="p">[</span><span class="nb">bool</span><span class="p">]</span>
<span class="n">Default</span> <span class="ow">is</span> <span class="n">off</span>
<span class="n">Prefer</span> <span class="n">IPv6</span> <span class="n">address</span> <span class="n">when</span> <span class="n">connecting</span> <span class="n">to</span> <span class="n">backends</span>
<span class="n">which</span> <span class="n">have</span> <span class="n">both</span> <span class="n">IPv4</span> <span class="ow">and</span> <span class="n">IPv6</span> <span class="n">addresses</span><span class="o">.</span>
<span class="n">varnish</span><span class="o">></span> <span class="n">param</span><span class="o">.</span><span class="n">set</span> <span class="n">prefer_ipv6</span> <span class="n">true</span>
<span class="mi">200</span>
</pre></div>
</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, 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnish</span><span class="o">></span> <span class="n">stop</span>
</pre></div>
</div>
<p>and:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnish</span><span class="o">></span> <span class="n">start</span>
</pre></div>
</div>
<p>If you start <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> 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 class="section" id="the-shell-the-other-cli">
<h2>The shell, the other CLI<a class="headerlink" href="#the-shell-the-other-cli" title="Permalink to this headline">¶</a></h2>
<p>Besides accessing the CLI via its interface or via <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code> there
is the matter of actually running the <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> command line, usually
via a shell. See <a class="reference internal" href="run_security.html#run-security"><span class="std std-ref">Security first</span></a> for security concerns around the
<code class="docutils literal notranslate"><span class="pre">varnishd</span></code> command line. See also <a class="reference internal" href="../reference/varnish-cli.html#ref-syntax"><span class="std std-ref">Syntax</span></a> about the CLI
syntax and quoting pitfalls when using <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code>.</p>
<p>The programs shipped with Varnish can expose their <em>optstring</em> in order
to help writing wrapper scripts, in particular to get an opportunity to
hook a task before a program daemonizes. With the exception of
<code class="docutils literal notranslate"><span class="pre">varnishtest</span></code> and <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code>, you can write Shell wrappers for
<code class="docutils literal notranslate"><span class="pre">varnishd</span></code> using the <code class="docutils literal notranslate"><span class="pre">-x</span></code> option and other programs using the
<code class="docutils literal notranslate"><span class="pre">--optstring</span></code> long option.</p>
<p>This way, when writing a wrapper script you don’t need to maintain the
<em>optstring</em> in sync when you only need a subset of the options, usually
<code class="docutils literal notranslate"><span class="pre">-n</span></code> or <code class="docutils literal notranslate"><span class="pre">-P</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>optstring=$(varnishd -x optstring)
while getopts "$optstring" opt
do
case $opt in
n)
# handle $OPTARG
;;
# handle other options
*)
# ignore unneeded options
;;
esac
done
varnishd "$@"
# do something with the options
</pre></div>
</div>
<p>You can for example write a wrapper script that blocks until the shared
memory is ready or when the child is started if you need that kind of
synchronization. You can also prevent <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> from starting if the
<code class="docutils literal notranslate"><span class="pre">-S</span></code> option is inadvertently set to not challenge access to the CLI.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">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>
<li><a class="reference internal" href="#the-shell-the-other-cli">The shell, the other CLI</a></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>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/users-guide/run_cli.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<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>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="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 class="nav-item nav-item-0"><a href="../index.html">Varnish version 6.0.3 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Varnish Users Guide</a> »</li>
<li class="nav-item nav-item-2"><a href="running.html" >Starting and running Varnish</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2010-2014, Varnish Software AS.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>