Once varnishd is started, you can control it using the command line interface.
The easiest way to do this, is using varnishadm on the same machine as varnishd is running:
varnishadm help
If you want to run varnishadm from a remote system, you can do it two ways.
You can SSH into the varnishd computer and run varnishadm:
ssh $http_front_end varnishadm help
But you can also configure varnishd to accept remote CLI connections (using the ‘-T’ and ‘-S’ arguments):
varnishd -T :6082 -S /etc/varnish_secret
And then on the remote system run varnishadm:
varnishadm -T $http_front_end -S /etc/copy_of_varnish_secret help
but as you can see, SSH is much more convenient.
If you run varnishadm without arguments, it will read CLI commands from stdin, if you give it arguments, it will treat those as the single CLI command to execute.
The CLI always returns a status code to tell how it went: ‘200’ means OK, anything else means there were some kind of trouble.
varnishadm will exit with status 1 and print the status code on standard error if it is not 200.
The CLI gives you almost total control over varnishd some of the more important tasks you can perform are:
We will discuss each of these briefly below.
All caching and policy decisions are made by VCL programs.
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.
To load new VCL program:
varnish> vcl.load some_name some_filename
Loading will read the VCL program from the file, and compile it. If the compilation fails, you will get an error messages:
.../mask is not numeric.
('input' Line 4 Pos 17)
"192.168.2.0/24x",
----------------#################-
Running VCC-compiler failed, exit 1
VCL compilation failed
If compilation succeeds, the VCL program is loaded, and you can now make it the active VCL, whenever you feel like it:
varnish> vcl.use some_name
If you find out that was a really bad idea, you can switch back to the previous VCL program again:
varnish> vcl.use old_name
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.
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.
Varnish offers “purges” to remove things from cache, provided that you know exactly what they are.
But sometimes it is useful to be able to throw things out of cache without having an exact list of what to throw out.
Imagine for instance that the company logo changed and now you need Varnish to stop serving the old logo out of the cache:
varnish> ban req.url ~ "logo.*[.]png"
should do that, and yes, that is a regular expression.
We call this “banning” because the objects are still in the cache, but they are banned from delivery.
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.
Banning stuff is much cheaper than restarting Varnish to get rid of wronly cached content.
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:
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
In general it is not a good idea to modify parameters unless you have a good reason, such as performance tuning or security configuration.
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.
In general you should just leave the worker process running, but if you need to stop and/or start it, the obvious commands work:
varnish> stop
and:
varnish> start
If you start varnishd with the ‘-d’ (debugging) argument, you will always need to start the child process explicitly.
Should the child process die, the master process will automatically restart it, but you can disable that with the ‘auto_restart’ parameter.
Besides accessing the CLI via its interface or via varnishadm there is the matter of actually running the varnishd command line, usually via a shell. See Security first for security concerns around the varnishd command line. See also Syntax about the CLI syntax and quoting pitfalls when using varnishadm.
The programs shipped with Varnish can expose their optstring 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 varnishtest and varnishadm, you can write Shell wrappers for varnishd using the -x option and other programs using the --optstring long option.
This way, when writing a wrapper script you don’t need to maintain the optstring in sync when you only need a subset of the options, usually -n or -P:
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
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 varnishd from starting if the -S option is inadvertently set to not challenge access to the CLI.
Copyright © 2006 Verdens Gang AS
Copyright © 2006–2020 Varnish Software AS
Licensed under the BSD-2-Clause License.
https://varnish-cache.org/docs/6.5/users-guide/run_cli.html