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 [-j] <param> <value>
357          Set parameter value.
358
359          The JSON output is the same as param.show -j  <param>  and  contains
360          the  updated value as it would be represented by a subsequent execu‐
361          tion of param.show.
362
363          This can be useful to later verify that  a  parameter  value  didn't
364          change and to use the value from the JSON output to reset the param‐
365          eter to the desired value.
366
367   param.show [-l|-j] [<param>|changed]
368          Show parameters and their values.
369
370          The long form with -l shows additional information, including  docu‐
371          mentation  and  minimum,  maximum and default values, if defined for
372          the parameter. JSON output is specified with -j, in which the infor‐
373          mation  for  the long form is included; only one of -l or -j is per‐
374          mitted. If a parameter is specified with <param>, show only that pa‐
375          rameter.  If  changed is specified, show only those parameters whose
376          values differ from their defaults.
377
378   pid [-j]
379          Show the pid of the master process, and the worker if it's running.
380
381          -j specifies JSON output.
382
383   ping [-j] [<timestamp>]
384          Keep connection alive.
385
386          The response is formatted as JSON if -j is specified.
387
388   quit
389          Close connection.
390
391   start
392          Start the Varnish cache process.
393
394   status [-j]
395          Check status of Varnish cache process.
396
397          -j specifies JSON output.
398
399   stop
400          Stop the Varnish cache process.
401
402   storage.list [-j]
403          List storage devices.
404
405          -j specifies JSON output.
406
407   vcl.deps [-j]
408          List all loaded configuration and their dependencies.
409
410          Unless -j is specified for JSON output, the output format is  up  to
411          two  columns  of  dynamic  width  separated  by white space with the
412          fields:
413
414          • VCL: a VCL program
415
416          • Dependency: another VCL program it depends on
417
418          Only direct dependencies are listed, and VCLs with  multiple  depen‐
419          dencies are listed multiple times.
420
421   vcl.discard <name_pattern>...
422          Unload the named configurations (when possible).
423
424          Unload  the  named  configurations  and labels matching at least one
425          name pattern. All matching configurations and labels  are  discarded
426          in  the correct order with respect to potential dependencies. If one
427          configuration or label could not be discarded because one of its de‐
428          pendencies  would remain, nothing is discarded. Each individual name
429          pattern must match at least one named configuration or label.
430
431   vcl.inline <configname> <quoted_VCLstring> [auto|cold|warm]
432          Compile and load the VCL data under the name provided.
433
434          Multi-line VCL can be input using the here document ref_syntax.
435
436   vcl.label <label> <configname>
437          Apply label to configuration.
438
439          A VCL label is like a UNIX symbolic link,  a name without substance,
440          which points to another VCL.
441
442          Labels are mandatory whenever one VCL references another.
443
444   vcl.list [-j]
445          List all loaded configuration.
446
447          Unless  -j  is specified for JSON output,  the output format is five
448          or seven columns of dynamic width,  separated by  white  space  with
449          the fields:
450
451          • status: active, available or discarded
452
453          • state: label, cold, warm, or auto
454
455          • temperature: init, cold, warm, busy or cooling
456
457          • busy: number of references to this vcl (integer)
458
459          • name: the name given to this vcl or label
460
461          • [ <- | -> ] and label info last two fields)
462
463-> <vcl> : label "points to" the named <vcl>
464
465<- (<n> label[s]): the vcl has <n> label(s)
466
467   vcl.load <configname> <filename> [auto|cold|warm]
468          Compile and load the VCL file under the name provided.
469
470   vcl.show [-v] [<configname>]
471          Display the source code for the specified configuration.
472
473   vcl.state <configname> [auto|cold|warm]
474          Force the state of the named configuration.
475
476   vcl.symtab
477          Dump the VCL symbol-tables.
478
479   vcl.use <configname|label>
480          Switch to the named configuration immediately.
481
482   Backend Pattern
483       A  backend pattern can be a backend name or a combination of a VCL name
484       and backend name in "VCL.backend" format.  If the VCL name is  omitted,
485       the  active  VCL  is  assumed.  Partial matching on the backend and VCL
486       names is supported using shell-style wildcards, e.g. asterisk (*).
487
488       Examples:
489
490          backend.list def*
491          backend.list b*.def*
492          backend.set_health default sick
493          backend.set_health def* healthy
494          backend.set_health * auto
495
496   Ban Expressions
497       A ban expression consists of one or more conditions.  A condition  con‐
498       sists  of  a  field,  an  operator, and an argument.  Conditions can be
499       ANDed together with "&&".
500
501       A field can be any of the variables from  VCL,  for  instance  req.url,
502       req.http.host or obj.http.set-cookie.
503
504       Operators  are "==" for direct comparison, "~" for a regular expression
505       match, and ">" or "<" for size  comparisons.   Prepending  an  operator
506       with "!" negates the expression.
507
508       The  argument could be a quoted string, a regexp, or an integer.  Inte‐
509       gers can have "KB", "MB",  "GB"  or  "TB"  appended  for  size  related
510       fields.
511
512   VCL Temperature
513       A VCL program goes through several states related to the different com‐
514       mands: it can be loaded, used, and later discarded. You can  load  sev‐
515       eral  VCL programs and switch at any time from one to another. There is
516       only one active VCL, but the previous active VCL will be maintained ac‐
517       tive until all its transactions are over.
518
519       Over time, if you often refresh your VCL and keep the previous versions
520       around, resource consumption will increase, you can't escape that. How‐
521       ever,  most  of  the time you want to pay the price only for the active
522       VCL and keep older VCLs in case you'd need to rollback  to  a  previous
523       version.
524
525       The  VCL  temperature  allows you to minimize the footprint of inactive
526       VCLs. Once a VCL becomes cold, Varnish will release all  the  resources
527       that  can  be be later reacquired. You can manually set the temperature
528       of a VCL or let varnish automatically handle it.
529

EXAMPLES

531       Load a multi-line VCL using shell-style here document:
532
533          vcl.inline example << EOF
534          vcl 4.0;
535
536          backend www {
537              .host = "127.0.0.1";
538              .port = "8080";
539          }
540          EOF
541
542       Ban all requests where req.url exactly matches the string /news:
543
544          ban req.url == "/news"
545
546       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
550          ban req.http.host ~ "^(?i)(www\\.)?example\\.com$" && obj.http.set-cookie ~ "USERID=1663"
551

AUTHORS

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

SEE ALSO

558varnishadm(1)
559
560varnishd(1)
561
562vcl(7)
563
564       • For API use of the CLI: The Reference Manual.
565
566
567
568
569                                                                VARNISH-CLI(7)
Impressum