Preview: run_cli.html
Size: 14.62 KB
//usr/share/doc/varnish/html/users-guide/run_cli.html
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>CLI - bossing Varnish around — 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="Storage backends" href="storage-backends.html" />
<link rel="prev" title="Required 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="Required command line arguments"
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" >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>
<li class="nav-item nav-item-this"><a href="">CLI - bossing Varnish around</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<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="Link to this heading">¶</a></h1>
<p>Once <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> is started, you can control it using the <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code>
program and the command line interface:</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, we recommend
you use <code class="docutils literal notranslate"><span class="pre">ssh</span></code> into the system where <code class="docutils literal notranslate"><span class="pre">varnishd</span></code> runs. (But see also:
<a class="reference internal" href="../reference/cli_protocol.html#ref-remote-cli"><span class="std std-ref">Local and remote CLI connections</span></a>)</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 $hostname varnishadm help
</pre></div>
</div>
<p>If you give no command arguments, <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code> runs in interactive mode
with command-completion, command-history and other comforts:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>critter phk> ./varnishadm
200
-----------------------------
Varnish Cache CLI 1.0
-----------------------------
FreeBSD,13.0-CURRENT,amd64,-jnone,-sdefault,-sdefault,-hcritbit
varnish-trunk revision 2bd5d2adfc407216ebaa653fae882d3c8d47f5e1
Type 'help' for command list.
Type 'quit' to close CLI session.
Type 'start' to launch worker process.
varnish>
</pre></div>
</div>
<p>The CLI always returns a three digit status code to tell how things went.</p>
<p>200 and 201 means <em>OK</em>, anything else means that some kind of trouble
prevented the execution of the command.</p>
<p>(If you get 201, it means that the output was truncated,
See the <a class="reference internal" href="../reference/varnishd.html#ref-param-cli-limit"><span class="std std-ref">cli_limit</span></a> parameter.)</p>
<p>When commands are given as arguments to <code class="docutils literal notranslate"><span class="pre">varnishadm</span></code>, a status
different than 200 or 201 will cause it to exit with status 1
and print the status code on standard error.</p>
<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="Link to this heading">¶</a></h2>
<p>From the CLI you can:</p>
<ul class="simple">
<li><p>load/use/discard VCL programs</p></li>
<li><p>ban (invalidate) cache content</p></li>
<li><p>change parameters</p></li>
<li><p>start/stop worker process</p></li>
</ul>
<p>We will discuss each of these briefly below.</p>
<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="Link to this heading">¶</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-text notranslate"><div class="highlight"><pre><span></span>.../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>
</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>We highly recommend you design an emergency-VCL, and always keep
it loaded, so it can be activated with</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vcl</span><span class="o">.</span><span class="n">use</span> <span class="n">emergency</span>
</pre></div>
</div>
</section>
<section id="ban-cache-content">
<h3>Ban cache content<a class="headerlink" href="#ban-cache-content" title="Link to this heading">¶</a></h3>
<p>Varnish offers “purges” to remove things from cache, but that
requires you to know exactly what they are.</p>
<p>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-text notranslate"><div class="highlight"><pre><span></span>varnish> ban req.url ~ "logo.*[.]png"
</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 now banned from delivery, while all the rest of the
cache is unaffected.</p>
<p>Even when you want to throw out <em>all</em> the cached content, banning is
both faster and less disruptive that a restart:</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">obj</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">date</span> <span class="o">~</span> <span class="o">.*</span>
</pre></div>
</div>
</section>
<section id="change-parameters">
<h3>Change parameters<a class="headerlink" href="#change-parameters" title="Link to this heading">¶</a></h3>
<p>Parameters can be set on the command line with the ‘-p’ argument,
but almost all parameters can be examined and changed on the fly
from the CLI:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>varnish> 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> param.set prefer_ipv6 true
200
</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 short delay,
but a few of them requires you to restart the child process before
they take effect. This is always mentioned in the description of
the parameter.</p>
</section>
<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="Link to this heading">¶</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
<a class="reference internal" href="../reference/varnishd.html#ref-param-auto-restart"><span class="std std-ref">auto_restart</span></a> parameter.</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="#">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>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="command-line.html"
title="previous chapter">Required command line arguments</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="storage-backends.html"
title="next chapter">Storage backends</a></p>
</div>
<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 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="storage-backends.html" title="Storage backends"
>next</a> |</li>
<li class="right" >
<a href="command-line.html" title="Required command line arguments"
>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 Users Guide</a> »</li>
<li class="nav-item nav-item-2"><a href="running.html" >Starting and running Varnish</a> »</li>
<li class="nav-item nav-item-this"><a href="">CLI - bossing Varnish around</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>
Directory Contents
Dirs: 0 × Files: 33