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
55 token.
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 When using a front-end to the Varnish-CLI like varnishadm, one must
119 take into account the double expansion happening. First in the shell
120 launching the varnishadm command and then in the Varnish CLI itself.
121 When a command's parameter require spaces, you need to ensure that the
122 Varnish CLI will see the double quotes:
123 varnishadm param.set cc_command '"my alternate cc command"'
125 Change will take effect when VCL script is reloaded
127 Otherwise if you don't quote the quotes, you may get a seemingly unre‐
129 lated error message:
130 varnishadm param.set cc_command "my alternate cc command"
132 Unknown request.
133 Type 'help' for more info.
134 Too many parameters
135 Command failed with error code 105
137 If you are quoting with a here document, you must wrap it inside a
139 shell multi-line argument:
140 varnishadm vcl.inline test '<< EOF
142 vcl 4.0;
143 backend be {
145 .host = "localhost";
146 }
147 EOF'
148 VCL compiled.
149 Other pitfalls include variable expansion of the shell invoking var‐
151 nishadm but this is not directly related to the Varnish CLI. If you get
152 the quoting right you should be fine even with complex commands.
153 JSON
155 A number of commands with informational responses support a -j parame‐
156 ter for JSON output, as specified below. The top-level structure of the
157 JSON response is an array with these first three elements:
158 · A version number for the JSON format (integer)
160 · An array of strings that comprise the CLI command just received
162 · The time at which the response was generated, as a Unix epoch time in
164 seconds with millisecond precision (floating point)
165 The remaining elements of the array form the data that are specific to
167 the CLI command, and their structure and content depend on the command.
168 For example, the response to status -j just contains a string in the
170 top-level array indicating the state of the child process ("running",
171 "stopped" and so forth):
172 [ 2, ["status", "-j"], 1538031732.632, "running"
174 ]
175 The JSON responses to other commands may have longer lists of elements,
177 which may have simple data types or form structured objects.
178 JSON output is only returned if command execution was successful. The
180 output for an error response is always the same as it would have been
181 for the command without the -j parameter.
182 Commands
184 auth <response>
185 Authenticate.
186 backend.list [-j] [-p] [<backend_pattern>]
188 List backends.
189 -p also shows probe status.
191 -j specifies JSON output.
193 Unless -j is specified for JSON output, the output format is five
195 columns of dynamic width, separated by white space with the fields:
196 · Backend name
198 · Admin: How health state is determined:
200 · healthy: Set healthy through backend.set_health.
202 · sick: Set sick through backend.set_health.
204 · probe: Health state determined by a probe or some other dynamic
206 mechanism.
207 · deleted: Backend has been deleted, but not yet cleaned up.
209 Admin has precedence over Health
211 · Probe X/Y: X out of Y checks have succeeded
213 X and Y are backend specific and may represent probe checks, other
215 backends or any other metric.
216 If there is no probe or the director does not provide details on
218 probe check results, 0/0 is output.
219 · Health: Probe health state
221 · healthy
223 · sick
225 If there is no probe, healthy is output.
227 · Last change: Timestamp when the health state last changed.
229 The health state reported here is generic. A backend's health may
231 also depend on the context it is being used in (e.g. the object's
232 hash), so the actual health state as visible from VCL (e.g. using
233 std.healthy()) may differ.
234 For -j, the object members should be self explanatory, matching the
236 fields described above. probe_message has the format [X, Y, "state"]
237 as described above for Probe. JSON Probe details (-j -p arguments)
238 are director specific.
239 backend.set_health <backend_pattern> [auto|healthy|sick]
241 Set health status on the backends.
242 ban <field> <operator> <arg> [&& <field> <oper> <arg> ...]
244 Mark obsolete all objects where all the conditions match.
245 See vcl(7)_ban for details
247 ban.list [-j]
249 List the active bans.
250 Unless -j is specified for JSON output, the output format is:
252 · Time the ban was issued.
254 · Objects referencing this ban.
256 · C if ban is completed = no further testing against it.
258 · if lurker debugging is enabled:
260 · R for req.* tests
262 · O for obj.* tests
264 · Pointer to ban object
266 · Ban specification
268 Durations of ban specifications get normalized, for example "7d"
270 gets changed into "1w".
271 banner
273 Print welcome banner.
274 help [-j] [<command>]
276 Show command/protocol help.
277 -j specifies JSON output.
279 panic.clear [-z]
281 Clear the last panic, if any, -z will clear related varnishstat
282 counter(s)
283 panic.show [-j]
285 Return the last panic, if any.
286 -j specifies JSON output -- the panic message is returned as an
288 unstructured JSON string.
289 param.reset <param>
291 Reset parameter to default value.
292 param.set <param> <value>
294 Set parameter value.
295 param.show [-l|-j] [<param>|changed]
297 Show parameters and their values.
298 The long form with -l shows additional information, including docu‐
300 mentation and minimum, maximum and default values, if defined for
301 the parameter. JSON output is specified with -j, in which the infor‐
302 mation for the long form is included; only one of -l or -j is per‐
303 mitted. If a parameter is specified with <param>, show only that
304 parameter. If changed is specified, show only those parameters whose
305 values differ from their defaults.
306 pid [-j]
308 Show the pid of the master process, and the worker if it's running.
309 -j specifies JSON output.
311 ping [-j] [<timestamp>]
313 Keep connection alive.
314 The response is formatted as JSON if -j is specified.
316 quit
318 Close connection.
319 start
321 Start the Varnish cache process.
322 status [-j]
324 Check status of Varnish cache process.
325 -j specifies JSON output.
327 stop
329 Stop the Varnish cache process.
330 storage.list [-j]
332 List storage devices.
333 -j specifies JSON output.
335 vcl.discard <configname|label>
337 Unload the named configuration (when possible).
338 vcl.inline <configname> <quoted_VCLstring> [auto|cold|warm]
340 Compile and load the VCL data under the name provided.
341 Multi-line VCL can be input using the here document ref_syntax.
343 vcl.label <label> <configname>
345 Apply label to configuration.
346 A VCL label is like a UNIX symbolic link, a name without substance,
348 which points to another VCL.
349 Labels are mandatory whenever one VCL references another.
351 vcl.list [-j]
353 List all loaded configuration.
354 Unless -j is specified for JSON output, the output format is five
356 or seven columns of dynamic width, separated by white space with
357 the fields:
358 · status: active, available or discarded
360 · state: label, cold, warm, or auto
362 · temperature: init, cold, warm, busy or cooling
364 · busy: number of references to this vcl (integer)
366 · name: the name given to this vcl or label
368 · [ <- | -> ] and label info last two fields)
370 · -> <vcl> : label "points to" the named <vcl>
372 · <- (<n> label[s]): the vcl has <n> label(s)
374 vcl.load <configname> <filename> [auto|cold|warm]
376 Compile and load the VCL file under the name provided.
377 vcl.show [-v] <configname>
379 Display the source code for the specified configuration.
380 vcl.state <configname> [auto|cold|warm]
382 Force the state of the named configuration.
383 vcl.symtab
385 Dump the VCL symbol-tables.
386 vcl.use <configname|label>
388 Switch to the named configuration immediately.
389 Backend Pattern
391 A backend pattern can be a backend name or a combination of a VCL name
392 and backend name in "VCL.backend" format. If the VCL name is omitted,
393 the active VCL is assumed. Partial matching on the backend and VCL
394 names is supported using shell-style wilcards, e.g. asterisk (*).
395 Examples:
397 backend.list def*
399 backend.list b*.def*
400 backend.set_health default sick
401 backend.set_health def* healthy
402 backend.set_health * auto
403 Ban Expressions
405 A ban expression consists of one or more conditions. A condition con‐
406 sists of a field, an operator, and an argument. Conditions can be
407 ANDed together with "&&".
408 A field can be any of the variables from VCL, for instance req.url,
410 req.http.host or obj.http.set-cookie.
411 Operators are "==" for direct comparison, "~" for a regular expression
413 match, and ">" or "<" for size comparisons. Prepending an operator
414 with "!" negates the expression.
415 The argument could be a quoted string, a regexp, or an integer. Inte‐
417 gers can have "KB", "MB", "GB" or "TB" appended for size related
418 fields.
419 VCL Temperature
421 A VCL program goes through several states related to the different com‐
422 mands: it can be loaded, used, and later discarded. You can load sev‐
423 eral VCL programs and switch at any time from one to another. There is
424 only one active VCL, but the previous active VCL will be maintained
425 active until all its transactions are over.
426 Over time, if you often refresh your VCL and keep the previous versions
428 around, resource consumption will increase, you can't escape that. How‐
429 ever, most of the time you want only one to pay the price only for the
430 active VCL and keep older VCLs in case you'd need to rollback to a pre‐
431 vious version.
432 The VCL temperature allows you to minimize the footprint of inactive
434 VCLs. Once a VCL becomes cold, Varnish will release all the resources
435 that can be be later reacquired. You can manually set the temperature
436 of a VCL or let varnish automatically handle it.
437 Scripting
439 If you are going to write a script that talks CLI to varnishd, the
440 include/cli.h contains the relevant magic numbers.
441 One particular magic number to know, is that the line with the status
443 code and length field always is exactly 13 characters long, including
444 the NL character.
445 The varnishapi library contains functions to implement the basics of
447 the CLI protocol, see the vcli.h include file.
448 Authentication with -S
450 If the -S secret-file is given as argument to varnishd, all network CLI
451 connections must authenticate, by proving they know the contents of
452 that file.
453 The file is read at the time the auth command is issued and the con‐
455 tents is not cached in varnishd, so it is possible to update the file
456 on the fly.
457 Use the unix file permissions to control access to the file.
459 An authenticated session looks like this:
461 critter phk> telnet localhost 1234
463 Trying ::1...
464 Trying 127.0.0.1...
465 Connected to localhost.
466 Escape character is '^]'.
467 107 59
468 ixslvvxrgkjptxmcgnnsdxsvdmvfympg
469 Authentication required.
471 auth 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
473 200 279
474 -----------------------------
475 Varnish Cache CLI 1.0
476 -----------------------------
477 Linux,4.4.0-1-amd64,x86_64,-jnone,-smalloc,-smalloc,-hcritbit
478 varnish-trunk revision dc360a4
479 Type 'help' for command list.
481 Type 'quit' to close CLI session.
482 Type 'start' to launch worker process.
483 The CLI status of 107 indicates that authentication is necessary. The
485 first 32 characters of the response text is the challenge "ixsl...mpg".
486 The challenge is randomly generated for each CLI connection, and
487 changes each time a 107 is emitted.
488 The most recently emitted challenge must be used for calculating the
490 authenticator "455c...c89a".
491 The authenticator is calculated by applying the SHA256 function to the
493 following byte sequence:
494 · Challenge string
496 · Newline (0x0a) character.
498 · Contents of the secret file
500 · Challenge string
502 · Newline (0x0a) character.
504 and dumping the resulting digest in lower-case hex.
506 In the above example, the secret file contained foon and thus:
508 critter phk> cat > _
510 ixslvvxrgkjptxmcgnnsdxsvdmvfympg
511 foo
512 ixslvvxrgkjptxmcgnnsdxsvdmvfympg
513 ^D
514 critter phk> hexdump -C _
515 00000000 69 78 73 6c 76 76 78 72 67 6b 6a 70 74 78 6d 63 |ixslvvxrgkjptxmc|
516 00000010 67 6e 6e 73 64 78 73 76 64 6d 76 66 79 6d 70 67 |gnnsdxsvdmvfympg|
517 00000020 0a 66 6f 6f 0a 69 78 73 6c 76 76 78 72 67 6b 6a |.foo.ixslvvxrgkj|
518 00000030 70 74 78 6d 63 67 6e 6e 73 64 78 73 76 64 6d 76 |ptxmcgnnsdxsvdmv|
519 00000040 66 79 6d 70 67 0a |fympg.|
520 00000046
521 critter phk> sha256 _
522 SHA256 (_) = 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
523 critter phk> openssl dgst -sha256 < _
524 455ce847f0073c7ab3b1465f74507b75d3dc064c1e7de3b71e00de9092fdc89a
525 The sourcefile lib/libvarnish/cli_auth.c contains a useful function
527 which calculates the response, given an open filedescriptor to the
528 secret file, and the challenge string.
529
531 Load a multi-line VCL using shell-style here document:
532 vcl.inline example << EOF
534 vcl 4.0;
535 backend www {
537 .host = "127.0.0.1";
538 .port = "8080";
539 }
540 EOF
541 Ban all requests where req.url exactly matches the string /news:
543 ban req.url == "/news"
545 Ban all documents where the serving host is "example.com" or "www.exam‐
547 ple.com", and where the Set-Cookie header received from the backend
548 contains "USERID=1663":
549 ban req.http.host ~ "^(?i)(www\\.)?example\\.com$" && obj.http.set-cookie ~ "USERID=1663"
551
553 This manual page was originally written by Per Buer and later modified
554 by Federico G. Schwindt, Dridi Boukelmoune, Lasse Karstensen and
555 Poul-Henning Kamp.
556
558 · varnishadm(1)
559 · varnishd(1)
561 · vcl(7)
563 VARNISH-CLI(7)