1VARNISH-CLI(7) VARNISH-CLI(7)
2
6 varnish-cli - Varnish Command Line Interface
7
9 Varnish has a command line interface (CLI) which can control and change
10 most of the operational parameters and the configuration of Varnish,
11 without interrupting the running service.
12 The CLI can be used for the following tasks:
14 configuration
16 You can upload, change and delete VCL files from the CLI.
17 parameters
19 You can inspect and change the various parameters Varnish has
20 available through the CLI. The individual parameters are docu‐
21 mented in the varnishd(1) man page.
22 bans Bans are filters that are applied to keep Varnish from serving
24 stale content. When you issue a ban Varnish will not serve any
25 banned object from cache, but rather re-fetch it from its back‐
26 end servers.
27 process management
29 You can stop and start the cache (child) process though the CLI.
30 You can also retrieve the latest stack trace if the child
31 process has crashed.
32 If you invoke varnishd(1) with -T, -M or -d the CLI will be available.
34 In debug mode (-d) the CLI will be in the foreground, with -T you can
35 connect to it with varnishadm or telnet and with -M varnishd will con‐
36 nect back to a listening service pushing the CLI to that service.
37 Please see varnishd(1) for details.
38 Syntax
40 The Varnish CLI is similar to another command line interface, the
41 Bourne Shell. Commands are usually terminated with a newline, and they
42 may take arguments. The command and its arguments are tokenized before
43 parsing, and as such arguments containing spaces must be enclosed in
44 double quotes.
45 It means that command parsing of
47 help banner
49 is equivalent to
51 "help" banner
53 because the double quotes only indicate the boundaries of the help to‐
55 ken.
56 Within double quotes you can escape characters with \ (backslash). The
58 \n, \r, and \t get translated to newlines, carriage returns, an tabs.
59 Double quotes and backslashes themselves can be escaped with \" and \\
60 respectively.
61 To enter characters in octals use the \nnn syntax. Hexadecimals can be
63 entered with the \xnn syntax.
64 Commands may not end with a newline when a shell-style here document
66 (here-document or heredoc) is used. The format of a here document is:
67 << word
69 here document
70 word
71 word can be any continuous string chosen to make sure it doesn't appear
73 naturally in the following here document. Traditionally EOF or END is
74 used.
75 Quoting pitfalls
77 Integrating with the Varnish CLI can be sometimes surprising when quot‐
78 ing is involved. For instance in Bourne Shell the delimiter used with
79 here documents may or may not be separated by spaces from the << token:
80 cat <<EOF
82 hello
83 world
84 EOF
85 hello
86 world
87 With the Varnish CLI, the << and EOF tokens must be separated by at
89 least one blank:
90 vcl.inline boot <<EOF
92 106 258
93 Message from VCC-compiler:
94 VCL version declaration missing
95 Update your VCL to Version 4 syntax, and add
96 vcl 4.0;
97 on the first line of the VCL files.
98 ('<vcl.inline>' Line 1 Pos 1)
99 <<EOF
100 ##---
101 Running VCC-compiler failed, exited with 2
103 VCL compilation failed
104 With the missing space, the here document can be added and the actual
106 VCL can be loaded:
107 vcl.inline test << EOF
109 vcl 4.0;
110 backend be {
112 .host = "localhost";
113 }
114 EOF
115 200 14
116 VCL compiled.
117 A big difference with a shell here document is the handling of the <<
119 token. Just like command names can be quoted, the here document token
120 keeps its meaning, even quoted:
121 vcl.inline test "<<" EOF
123 vcl 4.0;
124 backend be {
126 .host = "localhost";
127 }
128 EOF
129 200 14
130 VCL compiled.
131 When using a front-end to the Varnish-CLI like varnishadm, one must
133 take into account the double expansion happening. First in the shell
134 launching the varnishadm command and then in the Varnish CLI itself.
135 When a command's parameter require spaces, you need to ensure that the
136 Varnish CLI will see the double quotes:
137 varnishadm param.set cc_command '"my alternate cc command"'
139 Change will take effect when VCL script is reloaded
141 Otherwise if you don't quote the quotes, you may get a seemingly unre‐
143 lated error message:
144 varnishadm param.set cc_command "my alternate cc command"
146 Unknown request.
147 Type 'help' for more info.
148 Too many parameters
149 Command failed with error code 105
151 If you are quoting with a here document, you must wrap it inside a
153 shell multi-line argument:
154 varnishadm vcl.inline test '<< EOF
156 vcl 4.0;
157 backend be {
159 .host = "localhost";
160 }
161 EOF'
162 VCL compiled.
163 Another difference with a shell here document is that only one here
165 document can be used on a single command line. For example, it is pos‐
166 sible to do this in a shell script:
167 #!/bin/sh
169 cat << EOF1 ; cat << EOF2
171 hello
172 EOF1
173 world
174 EOF2
175 The expected output is:
177 hello
179 world
180 With the Varnish CLI, only the last parameter may use the here document
182 form, which greatly restricts the number of commands that can effec‐
183 tively use them. Trying to use multiple here documents only takes the
184 last one into account.
185 For example:
187 command argument << EOF1 << EOF2
189 heredoc1
190 EOF1
191 heredoc2
192 EOF2
193 This conceptually results in the following command line:
195 • "command"
197 • "argument"
199 • "<<"
201 • "EOF1"
203 • "heredoc1\nEOF1\nheredoc2\n"
205 Other pitfalls include variable expansion of the shell invoking var‐
207 nishadm but this is not directly related to the Varnish CLI. If you get
208 the quoting right you should be fine even with complex commands.
209 JSON
211 A number of commands with informational responses support a -j parame‐
212 ter for JSON output, as specified below. The top-level structure of the
213 JSON response is an array with these first three elements:
214 • A version number for the JSON format (integer)
216 • An array of strings that comprise the CLI command just received
218 • The time at which the response was generated, as a Unix epoch time in
220 seconds with millisecond precision (floating point)
221 The remaining elements of the array form the data that are specific to
223 the CLI command, and their structure and content depend on the command.
224 For example, the response to status -j just contains a string in the
226 top-level array indicating the state of the child process ("running",
227 "stopped" and so forth):
228 [ 2, ["status", "-j"], 1538031732.632, "running"
230 ]
231 The JSON responses to other commands may have longer lists of elements,
233 which may have simple data types or form structured objects.
234 JSON output is only returned if command execution was successful. The
236 output for an error response is always the same as it would have been
237 for the command without the -j parameter.
238 Commands
240 auth <response>
241 Authenticate.
242 backend.list [-j] [-p] [<backend_pattern>]
244 List backends.
245 -p also shows probe status.
247 -j specifies JSON output.
249 Unless -j is specified for JSON output, the output format is five
251 columns of dynamic width, separated by white space with the fields:
252 • Backend name
254 • Admin: How health state is determined:
256 • healthy: Set healthy through backend.set_health.
258 • sick: Set sick through backend.set_health.
260 • probe: Health state determined by a probe or some other dynamic
262 mechanism.
263 • deleted: Backend has been deleted, but not yet cleaned up.
265 Admin has precedence over Health
267 • Probe X/Y: X out of Y checks have succeeded
269 X and Y are backend specific and may represent probe checks, other
271 backends or any other metric.
272 If there is no probe or the director does not provide details on
274 probe check results, 0/0 is output.
275 • Health: Probe health state
277 • healthy
279 • sick
281 If there is no probe, healthy is output.
283 • Last change: Timestamp when the health state last changed.
285 The health state reported here is generic. A backend's health may
287 also depend on the context it is being used in (e.g. the object's
288 hash), so the actual health state as visible from VCL (e.g. using
289 std.healthy()) may differ.
290 For -j, the object members should be self explanatory, matching the
292 fields described above. probe_message has the format [X, Y, "state"]
293 as described above for Probe. JSON Probe details (-j -p arguments)
294 are director specific.
295 backend.set_health <backend_pattern> [auto|healthy|sick]
297 Set health status of backend(s) matching <backend_pattern>.
298 • With auto, the health status is determined by a probe or some
300 other dynamic mechanism, if any
301 • healthy sets the backend as usable
303 • sick sets the backend as unsable
305 ban <field> <operator> <arg> [&& <field> <oper> <arg> ...]
307 Mark obsolete all objects where all the conditions match.
308 See vcl(7)_ban for details
310 ban.list [-j]
312 List the active bans.
313 Unless -j is specified for JSON output, the output format is:
315 • Time the ban was issued.
317 • Objects referencing this ban.
319 • C if ban is completed = no further testing against it.
321 • if lurker debugging is enabled:
323 • R for req.* tests
325 • O for obj.* tests
327 • Pointer to ban object
329 • Ban specification
331 Durations of ban specifications get normalized, for example "7d"
333 gets changed into "1w".
334 banner
336 Print welcome banner.
337 help [-j] [<command>]
339 Show command/protocol help.
340 -j specifies JSON output.
342 panic.clear [-z]
344 Clear the last panic, if any, -z will clear related varnishstat
345 counter(s)
346 panic.show [-j]
348 Return the last panic, if any.
349 -j specifies JSON output -- the panic message is returned as an un‐
351 structured JSON string.
352 param.reset <param>
354 Reset parameter to default value.
355 param.set <param> <value>
357 Set parameter value.
358 param.show [-l|-j] [<param>|changed]
360 Show parameters and their values.
361 The long form with -l shows additional information, including docu‐
363 mentation and minimum, maximum and default values, if defined for
364 the parameter. JSON output is specified with -j, in which the infor‐
365 mation for the long form is included; only one of -l or -j is per‐
366 mitted. If a parameter is specified with <param>, show only that pa‐
367 rameter. If changed is specified, show only those parameters whose
368 values differ from their defaults.
369 pid [-j]
371 Show the pid of the master process, and the worker if it's running.
372 -j specifies JSON output.
374 ping [-j] [<timestamp>]
376 Keep connection alive.
377 The response is formatted as JSON if -j is specified.
379 quit
381 Close connection.
382 start
384 Start the Varnish cache process.
385 status [-j]
387 Check status of Varnish cache process.
388 -j specifies JSON output.
390 stop
392 Stop the Varnish cache process.
393 storage.list [-j]
395 List storage devices.
396 -j specifies JSON output.
398 vcl.discard <configname|label>
400 Unload the named configuration (when possible).
401 vcl.inline <configname> <quoted_VCLstring> [auto|cold|warm]
403 Compile and load the VCL data under the name provided.
404 Multi-line VCL can be input using the here document ref_syntax.
406 vcl.label <label> <configname>
408 Apply label to configuration.
409 A VCL label is like a UNIX symbolic link, a name without substance,
411 which points to another VCL.
412 Labels are mandatory whenever one VCL references another.
414 vcl.list [-j]
416 List all loaded configuration.
417 Unless -j is specified for JSON output, the output format is five
419 or seven columns of dynamic width, separated by white space with
420 the fields:
421 • status: active, available or discarded
423 • state: label, cold, warm, or auto
425 • temperature: init, cold, warm, busy or cooling
427 • busy: number of references to this vcl (integer)
429 • name: the name given to this vcl or label
431 • [ <- | -> ] and label info last two fields)
433 • -> <vcl> : label "points to" the named <vcl>
435 • <- (<n> label[s]): the vcl has <n> label(s)
437 vcl.load <configname> <filename> [auto|cold|warm]
439 Compile and load the VCL file under the name provided.
440 vcl.show [-v] <configname>
442 Display the source code for the specified configuration.
443 vcl.state <configname> [auto|cold|warm]
445 Force the state of the named configuration.
446 vcl.symtab
448 Dump the VCL symbol-tables.
449 vcl.use <configname|label>
451 Switch to the named configuration immediately.
452 Backend Pattern
454 A backend pattern can be a backend name or a combination of a VCL name
455 and backend name in "VCL.backend" format. If the VCL name is omitted,
456 the active VCL is assumed. Partial matching on the backend and VCL
457 names is supported using shell-style wildcards, e.g. asterisk (*).
458 Examples:
460 backend.list def*
462 backend.list b*.def*
463 backend.set_health default sick
464 backend.set_health def* healthy
465 backend.set_health * auto
466 Ban Expressions
468 A ban expression consists of one or more conditions. A condition con‐
469 sists of a field, an operator, and an argument. Conditions can be
470 ANDed together with "&&".
471 A field can be any of the variables from VCL, for instance req.url,
473 req.http.host or obj.http.set-cookie.
474 Operators are "==" for direct comparison, "~" for a regular expression
476 match, and ">" or "<" for size comparisons. Prepending an operator
477 with "!" negates the expression.
478 The argument could be a quoted string, a regexp, or an integer. Inte‐
480 gers can have "KB", "MB", "GB" or "TB" appended for size related
481 fields.
482 VCL Temperature
484 A VCL program goes through several states related to the different com‐
485 mands: it can be loaded, used, and later discarded. You can load sev‐
486 eral VCL programs and switch at any time from one to another. There is
487 only one active VCL, but the previous active VCL will be maintained ac‐
488 tive until all its transactions are over.
489 Over time, if you often refresh your VCL and keep the previous versions
491 around, resource consumption will increase, you can't escape that. How‐
492 ever, most of the time you want only one to pay the price only for the
493 active VCL and keep older VCLs in case you'd need to rollback to a pre‐
494 vious version.
495 The VCL temperature allows you to minimize the footprint of inactive
497 VCLs. Once a VCL becomes cold, Varnish will release all the resources
498 that can be be later reacquired. You can manually set the temperature
499 of a VCL or let varnish automatically handle it.
500 Scripting
502 If you are going to write a script that talks CLI to varnishd, the in‐
503 clude/cli.h contains the relevant magic numbers.
504 One particular magic number to know, is that the line with the status
506 code and length field always is exactly 13 characters long, including
507 the NL character.
508 The varnishapi library contains functions to implement the basics of
510 the CLI protocol, see the vcli.h include file.
511 Authentication with -S
513 If the -S secret-file is given as argument to varnishd, all network CLI
514 connections must authenticate, by proving they know the contents of
515 that file.
516 The file is read at the time the auth command is issued and the con‐
518 tents is not cached in varnishd, so it is possible to update the file
519 on the fly.
520 Use the unix file permissions to control access to the file.
522 An authenticated session looks like this:
524 critter phk> telnet localhost 1234
526 Trying ::1...
527 Trying 127.0.0.1...
528 Connected to localhost.
529 Escape character is '^]'.
530 107 59
531 ixslvvxrgkjptxmcgnnsdxsvdmvfympg
532 Authentication required.
534 auth 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
536 200 279
537 -----------------------------
538 Varnish Cache CLI 1.0
539 -----------------------------
540 Linux,4.4.0-1-amd64,x86_64,-jnone,-smalloc,-smalloc,-hcritbit
541 varnish-trunk revision dc360a4
542 Type 'help' for command list.
544 Type 'quit' to close CLI session.
545 Type 'start' to launch worker process.
546 The CLI status of 107 indicates that authentication is necessary. The
548 first 32 characters of the response text is the challenge "ixsl...mpg".
549 The challenge is randomly generated for each CLI connection, and
550 changes each time a 107 is emitted.
551 The most recently emitted challenge must be used for calculating the
553 authenticator "455c...c89a".
554 The authenticator is calculated by applying the SHA256 function to the
556 following byte sequence:
557 • Challenge string
559 • Newline (0x0a) character.
561 • Contents of the secret file
563 • Challenge string
565 • Newline (0x0a) character.
567 and dumping the resulting digest in lower-case hex.
569 In the above example, the secret file contained foon and thus:
571 critter phk> cat > _
573 ixslvvxrgkjptxmcgnnsdxsvdmvfympg
574 foo
575 ixslvvxrgkjptxmcgnnsdxsvdmvfympg
576 ^D
577 critter phk> hexdump -C _
578 00000000 69 78 73 6c 76 76 78 72 67 6b 6a 70 74 78 6d 63 |ixslvvxrgkjptxmc|
579 00000010 67 6e 6e 73 64 78 73 76 64 6d 76 66 79 6d 70 67 |gnnsdxsvdmvfympg|
580 00000020 0a 66 6f 6f 0a 69 78 73 6c 76 76 78 72 67 6b 6a |.foo.ixslvvxrgkj|
581 00000030 70 74 78 6d 63 67 6e 6e 73 64 78 73 76 64 6d 76 |ptxmcgnnsdxsvdmv|
582 00000040 66 79 6d 70 67 0a |fympg.|
583 00000046
584 critter phk> sha256 _
585 SHA256 (_) = 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
586 critter phk> openssl dgst -sha256 < _
587 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
588 The sourcefile lib/libvarnish/cli_auth.c contains a useful function
590 which calculates the response, given an open filedescriptor to the se‐
591 cret file, and the challenge string.
592
594 Load a multi-line VCL using shell-style here document:
595 vcl.inline example << EOF
597 vcl 4.0;
598 backend www {
600 .host = "127.0.0.1";
601 .port = "8080";
602 }
603 EOF
604 Ban all requests where req.url exactly matches the string /news:
606 ban req.url == "/news"
608 Ban all documents where the serving host is "example.com" or "www.exam‐
610 ple.com", and where the Set-Cookie header received from the backend
611 contains "USERID=1663":
612 ban req.http.host ~ "^(?i)(www\\.)?example\\.com$" && obj.http.set-cookie ~ "USERID=1663"
614
616 This manual page was originally written by Per Buer and later modified
617 by Federico G. Schwindt, Dridi Boukelmoune, Lasse Karstensen and
618 Poul-Henning Kamp.
619
621 • varnishadm(1)
622 • varnishd(1)
624 • vcl(7)
626 VARNISH-CLI(7)