1VARNISH-CLI(7) VARNISH-CLI(7)
2
3
4
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
13 The CLI can be used for the following tasks:
14
15 configuration
16 You can upload, change and delete VCL files from the CLI.
17
18 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
23 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
28 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
33 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
39 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
46 It means that command parsing of
47
48 help banner
49
50 is equivalent to
51
52 "help" banner
53
54 because the double quotes only indicate the boundaries of the help to‐
55 ken.
56
57 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
62 To enter characters in octals use the \nnn syntax. Hexadecimals can be
63 entered with the \xnn syntax.
64
65 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
68 << word
69 here document
70 word
71
72 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
76 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
81 cat <<EOF
82 hello
83 world
84 EOF
85 hello
86 world
87
88 With the Varnish CLI, the << and EOF tokens must be separated by at
89 least one blank:
90
91 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
102 Running VCC-compiler failed, exited with 2
103 VCL compilation failed
104
105 With the missing space, the here document can be added and the actual
106 VCL can be loaded:
107
108 vcl.inline test << EOF
109 vcl 4.0;
110
111 backend be {
112 .host = "localhost";
113 }
114 EOF
115 200 14
116 VCL compiled.
117
118 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
122 vcl.inline test "<<" EOF
123 vcl 4.0;
124
125 backend be {
126 .host = "localhost";
127 }
128 EOF
129 200 14
130 VCL compiled.
131
132 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
138 varnishadm param.set cc_command '"my alternate cc command"'
139
140 Change will take effect when VCL script is reloaded
141
142 Otherwise if you don't quote the quotes, you may get a seemingly unre‐
143 lated error message:
144
145 varnishadm param.set cc_command "my alternate cc command"
146 Unknown request.
147 Type 'help' for more info.
148 Too many parameters
149
150 Command failed with error code 105
151
152 If you are quoting with a here document, you must wrap it inside a
153 shell multi-line argument:
154
155 varnishadm vcl.inline test '<< EOF
156 vcl 4.0;
157
158 backend be {
159 .host = "localhost";
160 }
161 EOF'
162 VCL compiled.
163
164 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
168 #!/bin/sh
169
170 cat << EOF1 ; cat << EOF2
171 hello
172 EOF1
173 world
174 EOF2
175
176 The expected output is:
177
178 hello
179 world
180
181 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
186 For example:
187
188 command argument << EOF1 << EOF2
189 heredoc1
190 EOF1
191 heredoc2
192 EOF2
193
194 This conceptually results in the following command line:
195
196 • "command"
197
198 • "argument"
199
200 • "<<"
201
202 • "EOF1"
203
204 • "heredoc1\nEOF1\nheredoc2\n"
205
206 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
210 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
215 • A version number for the JSON format (integer)
216
217 • An array of strings that comprise the CLI command just received
218
219 • The time at which the response was generated, as a Unix epoch time in
220 seconds with millisecond precision (floating point)
221
222 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
225 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
229 [ 2, ["status", "-j"], 1538031732.632, "running"
230 ]
231
232 The JSON responses to other commands may have longer lists of elements,
233 which may have simple data types or form structured objects.
234
235 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
239 Commands
240 auth <response>
241 Authenticate.
242
243 backend.list [-j] [-p] [<backend_pattern>]
244 List backends.
245
246 -p also shows probe status.
247
248 -j specifies JSON output.
249
250 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
253 • Backend name
254
255 • Admin: How health state is determined:
256
257 • healthy: Set healthy through backend.set_health.
258
259 • sick: Set sick through backend.set_health.
260
261 • probe: Health state determined by a probe or some other dynamic
262 mechanism.
263
264 • deleted: Backend has been deleted, but not yet cleaned up.
265
266 Admin has precedence over Health
267
268 • Probe X/Y: X out of Y checks have succeeded
269
270 X and Y are backend specific and may represent probe checks, other
271 backends or any other metric.
272
273 If there is no probe or the director does not provide details on
274 probe check results, 0/0 is output.
275
276 • Health: Probe health state
277
278 • healthy
279
280 • sick
281
282 If there is no probe, healthy is output.
283
284 • Last change: Timestamp when the health state last changed.
285
286 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
291 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
296 backend.set_health <backend_pattern> [auto|healthy|sick]
297 Set health status of backend(s) matching <backend_pattern>.
298
299 • With auto, the health status is determined by a probe or some
300 other dynamic mechanism, if any
301
302 • healthy sets the backend as usable
303
304 • sick sets the backend as unsable
305
306 ban <field> <operator> <arg> [&& <field> <oper> <arg> ...]
307 Mark obsolete all objects where all the conditions match.
308
309 See vcl(7)_ban for details
310
311 ban.list [-j]
312 List the active bans.
313
314 Unless -j is specified for JSON output, the output format is:
315
316 • Time the ban was issued.
317
318 • Objects referencing this ban.
319
320 • C if ban is completed = no further testing against it.
321
322 • if lurker debugging is enabled:
323
324 • R for req.* tests
325
326 • O for obj.* tests
327
328 • Pointer to ban object
329
330 • Ban specification
331
332 Durations of ban specifications get normalized, for example "7d"
333 gets changed into "1w".
334
335 banner
336 Print welcome banner.
337
338 help [-j] [<command>]
339 Show command/protocol help.
340
341 -j specifies JSON output.
342
343 panic.clear [-z]
344 Clear the last panic, if any, -z will clear related varnishstat
345 counter(s)
346
347 panic.show [-j]
348 Return the last panic, if any.
349
350 -j specifies JSON output -- the panic message is returned as an un‐
351 structured JSON string.
352
353 param.reset <param>
354 Reset parameter to default value.
355
356 param.set <param> <value>
357 Set parameter value.
358
359 param.show [-l|-j] [<param>|changed]
360 Show parameters and their values.
361
362 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
370 pid [-j]
371 Show the pid of the master process, and the worker if it's running.
372
373 -j specifies JSON output.
374
375 ping [-j] [<timestamp>]
376 Keep connection alive.
377
378 The response is formatted as JSON if -j is specified.
379
380 quit
381 Close connection.
382
383 start
384 Start the Varnish cache process.
385
386 status [-j]
387 Check status of Varnish cache process.
388
389 -j specifies JSON output.
390
391 stop
392 Stop the Varnish cache process.
393
394 storage.list [-j]
395 List storage devices.
396
397 -j specifies JSON output.
398
399 vcl.deps [-j]
400 List all loaded configuration and their dependencies.
401
402 Unless -j is specified for JSON output, the output format is up to
403 two columns of dynamic width separated by white space with the
404 fields:
405
406 • VCL: a VCL program
407
408 • Dependency: another VCL program it depends on
409
410 Only direct dependencies are listed, and VCLs with multiple dependen‐
411 cies are listed multiple times.
412
413 vcl.discard <name_pattern>...
414 Unload the named configurations (when possible).
415
416 Unload the named configurations and labels matching at least one name
417 pattern. All matching configurations and labels are discarded in the
418 correct order with respect to potential dependencies. If one configura‐
419 tion or label could not be discarded because one of its dependencies
420 would remain, nothing is discarded. Each individual name pattern must
421 match at least one named configuration or label.
422
423 vcl.inline <configname> <quoted_VCLstring> [auto|cold|warm]
424 Compile and load the VCL data under the name provided.
425
426 Multi-line VCL can be input using the here document ref_syntax.
427
428 vcl.label <label> <configname>
429 Apply label to configuration.
430
431 A VCL label is like a UNIX symbolic link, a name without substance,
432 which points to another VCL.
433
434 Labels are mandatory whenever one VCL references another.
435
436 vcl.list [-j]
437 List all loaded configuration.
438
439 Unless -j is specified for JSON output, the output format is five
440 or seven columns of dynamic width, separated by white space with
441 the fields:
442
443 • status: active, available or discarded
444
445 • state: label, cold, warm, or auto
446
447 • temperature: init, cold, warm, busy or cooling
448
449 • busy: number of references to this vcl (integer)
450
451 • name: the name given to this vcl or label
452
453 • [ <- | -> ] and label info last two fields)
454
455 • -> <vcl> : label "points to" the named <vcl>
456
457 • <- (<n> label[s]): the vcl has <n> label(s)
458
459 vcl.load <configname> <filename> [auto|cold|warm]
460 Compile and load the VCL file under the name provided.
461
462 vcl.show [-v] <configname>
463 Display the source code for the specified configuration.
464
465 vcl.state <configname> [auto|cold|warm]
466 Force the state of the named configuration.
467
468 vcl.symtab
469 Dump the VCL symbol-tables.
470
471 vcl.use <configname|label>
472 Switch to the named configuration immediately.
473
474 Backend Pattern
475 A backend pattern can be a backend name or a combination of a VCL name
476 and backend name in "VCL.backend" format. If the VCL name is omitted,
477 the active VCL is assumed. Partial matching on the backend and VCL
478 names is supported using shell-style wildcards, e.g. asterisk (*).
479
480 Examples:
481
482 backend.list def*
483 backend.list b*.def*
484 backend.set_health default sick
485 backend.set_health def* healthy
486 backend.set_health * auto
487
488 Ban Expressions
489 A ban expression consists of one or more conditions. A condition con‐
490 sists of a field, an operator, and an argument. Conditions can be
491 ANDed together with "&&".
492
493 A field can be any of the variables from VCL, for instance req.url,
494 req.http.host or obj.http.set-cookie.
495
496 Operators are "==" for direct comparison, "~" for a regular expression
497 match, and ">" or "<" for size comparisons. Prepending an operator
498 with "!" negates the expression.
499
500 The argument could be a quoted string, a regexp, or an integer. Inte‐
501 gers can have "KB", "MB", "GB" or "TB" appended for size related
502 fields.
503
504 VCL Temperature
505 A VCL program goes through several states related to the different com‐
506 mands: it can be loaded, used, and later discarded. You can load sev‐
507 eral VCL programs and switch at any time from one to another. There is
508 only one active VCL, but the previous active VCL will be maintained ac‐
509 tive until all its transactions are over.
510
511 Over time, if you often refresh your VCL and keep the previous versions
512 around, resource consumption will increase, you can't escape that. How‐
513 ever, most of the time you want to pay the price only for the active
514 VCL and keep older VCLs in case you'd need to rollback to a previous
515 version.
516
517 The VCL temperature allows you to minimize the footprint of inactive
518 VCLs. Once a VCL becomes cold, Varnish will release all the resources
519 that can be be later reacquired. You can manually set the temperature
520 of a VCL or let varnish automatically handle it.
521
523 Load a multi-line VCL using shell-style here document:
524
525 vcl.inline example << EOF
526 vcl 4.0;
527
528 backend www {
529 .host = "127.0.0.1";
530 .port = "8080";
531 }
532 EOF
533
534 Ban all requests where req.url exactly matches the string /news:
535
536 ban req.url == "/news"
537
538 Ban all documents where the serving host is "example.com" or "www.exam‐
539 ple.com", and where the Set-Cookie header received from the backend
540 contains "USERID=1663":
541
542 ban req.http.host ~ "^(?i)(www\\.)?example\\.com$" && obj.http.set-cookie ~ "USERID=1663"
543
545 This manual page was originally written by Per Buer and later modified
546 by Federico G. Schwindt, Dridi Boukelmoune, Lasse Karstensen and
547 Poul-Henning Kamp.
548
550 • varnishadm(1)
551
552 • varnishd(1)
553
554 • vcl(7)
555
556 • For API use of the CLI: The Reference Manual.
557
558
559
560
561 VARNISH-CLI(7)