1VARNISH-CLI(7)                                                  VARNISH-CLI(7)
2
3
4

NAME

6       varnish-cli - Varnish Command Line Interface
7

DESCRIPTION

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
257healthy: Set healthy through backend.set_health.
258
259sick: Set sick through backend.set_health.
260
261probe:  Health state determined by a probe or some other dynamic
262              mechanism.
263
264deleted: 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
278healthy
279
280sick
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
302healthy sets the backend as usable
303
304sick 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
320C if ban is completed = no further testing against it.
321
322          • if lurker debugging is enabled:
323
324R for req.* tests
325
326O 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

EXAMPLES

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

AUTHORS

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

SEE ALSO

550varnishadm(1)
551
552varnishd(1)
553
554vcl(7)
555
556       • For API use of the CLI: The Reference Manual.
557
558
559
560
561                                                                VARNISH-CLI(7)
Impressum