1VCL(7)                                                                  VCL(7)
2
3
4

NAME

6       VCL - Varnish Configuration Language
7

DESCRIPTION

9       The  VCL  language  is  a small domain-specific language designed to be
10       used to describe request handling and  document  caching  policies  for
11       Varnish Cache.
12
13       When  a  new  configuration  is loaded, the varnishd management process
14       translates the VCL code to C and compiles it to a shared  object  which
15       is then loaded into the server process.
16
17       This document focuses on the syntax of the VCL language. For a full de‐
18       scription of syntax and semantics, with ample examples, please see  the
19       online documentation at https://www.varnish-cache.org/docs/ .
20
21       Starting  with  Varnish  4.0, each VCL file must start by declaring its
22       version with vcl <major>.<minor>; marker at the top of the  file.   See
23       more about this under Versioning below.
24
25   Operators
26       The following operators are available in VCL:
27
28          =      Assignment operator.
29
30          +, -, *, /, %
31                 Basic math on numerical values.
32
33          +=, -=, *=, /=
34                 Assign and increment/decrement/multiply/divide operator.
35
36                 For strings, += appends.
37
38          (, )   Evaluate separately.
39
40          ==, !=, <, >, <=, >=
41                 Comparisons
42
43          ~, !~  Match  /  non-match.  Can either be used with regular expres‐
44                 sions or ACLs.
45
46          !      Negation.
47
48          && / ||
49                 Logical and/or.
50
51   Conditionals
52       VCL has if and else statements. Nested logic can  be  implemented  with
53       the elseif statement (elsif/elif/else if are equivalent).
54
55       Note that there are no loops or iterators of any kind in VCL.
56
57   Variables
58       VCL  does  most  of  the work by examining, set'ing and unset'ing vari‐
59       ables:
60
61          if (req.url == "/mistyped_url.html") {
62              set req.url = "/correct_url.html";
63              unset req.http.cookie;
64          }
65
66       There are obvious limitations to what can  be  done,  for  instance  it
67       makes no sense to unset req.url; - a request must have some kind of URL
68       to be valid, and likewise trying to manipulate a backend response  when
69       there  is none (yet) makes no sense.  The VCL compiler will detect such
70       errors.
71
72       Variables have types.  Most of them a STRINGS, and anything in VCL  can
73       be  turned  into a STRING, but some variables have types like DURATION,
74       IP etc.
75
76       When setting a such variables, the right hand side of  the  equal  sign
77       must  have  the correct variables type, you cannot assign a STRING to a
78       variable of type NUMBER, even if the string is "42".
79
80       Explicit conversion functions are available in vmod_std(3).
81
82       For the complete album of VCL variables see: vcl-var(7).
83
84   Strings
85       Basic strings are enclosed in double quotes "...", and may not  contain
86       newlines.  Long  strings are enclosed in {"..."} or """...""". They may
87       contain any character including single double  quotes  ",  newline  and
88       other control characters except for the NUL (0x00) character.
89
90   Booleans
91       Booleans  can  be either true or false.  In addition, in a boolean con‐
92       text some data types will evaluate to true or false depending on  their
93       value.
94
95       String  types  will  evaluate  to false if they are unset.  This allows
96       checks of the type if (req.http.opthdr) {} to test if a header  exists,
97       even  if  it  is  empty, whereas if (req.http.opthdr == "") {} does not
98       distinguish if the header does not exist or if it is empty.
99
100       Backend types will evaluate to false if they don't have a  backend  as‐
101       signed;  integer  types  will evaluate to false if their value is zero;
102       duration types will evaluate to false if their value is equal  or  less
103       than zero.
104
105   Time
106       VCL  has  time. A duration can be added to a time to make another time.
107       In string context they return a formatted  string  in  RFC1123  format,
108       e.g. Sun, 06 Nov 1994 08:49:37 GMT.
109
110       The  keyword  now  returns  a notion of the current time, which is kept
111       consistent during VCL subroutine invocations, so during  the  execution
112       of  a  VCL state subroutine (vcl_* {}), including all user-defined sub‐
113       routines being called, now always returns the same value.
114
115   Durations
116       Durations are defined by a number followed by a unit.  The  number  can
117       include a fractional part, e.g. 1.5s. The supported units are:
118
119          ms     milliseconds
120
121          s      seconds
122
123          m      minutes
124
125          h      hours
126
127          d      days
128
129          w      weeks
130
131          y      years
132
133       In  string  context  they return a string with their value rounded to 3
134       decimal places and excluding the unit, e.g.  1.500.
135
136   Integers
137       Certain fields are integers, used as expected. In string  context  they
138       return a string, e.g. 1234.
139
140   Real numbers
141       VCL  understands  real  numbers. In string context they return a string
142       with their value rounded to 3 decimal places, e.g. 3.142.
143
144   Regular Expressions
145       Varnish uses Perl-compatible regular expressions (PCRE). For a complete
146       description please see the pcre(3) man page.
147
148       To send flags to the PCRE engine, such as to do case insensitive match‐
149       ing, add the flag within parens following a question mark, like this:
150
151          # If host is NOT example dot com..
152          if (req.http.host !~ "(?i)example\.com$") {
153              ...
154          }
155
156   Include statement
157       To include a VCL file in another file use the include keyword:
158
159          include "foo.vcl";
160
161       Optionally, the include keyword can take a +glob flag  to  include  all
162       files matching a glob pattern:
163
164          include +glob "example.org/*.vcl";
165
166   Import statement
167       The import statement is used to load Varnish Modules (VMODs.)
168
169       Example:
170
171          import std;
172          sub vcl_recv {
173              std.log("foo");
174          }
175
176   Comments
177       Single  lines  of  VCL  can  be commented out using // or #. Multi-line
178       blocks can be commented out with /*block*/.
179
180       Example:
181
182          sub vcl_recv {
183              // Single line of out-commented VCL.
184              # Another way of commenting out a single line.
185              /*
186                  Multi-line block of commented-out VCL.
187              */
188          }
189
190   Backends and health probes
191       Please see vcl-backend(7) and vcl-probe(7)
192
193   Access Control List (ACL)
194       An Access Control List (ACL)  declaration  creates  and  initialises  a
195       named  access  control list which can later be used to match client ad‐
196       dresses:
197
198          acl localnetwork {
199              "localhost";    # myself
200              "192.0.2.0"/24; # and everyone on the local network
201              ! "192.0.2.23"; # except for the dial-in router
202          }
203
204       If an ACL entry specifies a host name which Varnish is  unable  to  re‐
205       solve, it will match any address it is compared to. Consequently, if it
206       is preceded by a negation mark, it will reject any address it  is  com‐
207       pared  to, which may not be what you intended. If the entry is enclosed
208       in parentheses, however, it will simply be ignored  if  the  host  name
209       cannot be resolved.
210
211       To match an IP address against an ACL, simply use the match operator:
212
213          if (client.ip ~ localnetwork) {
214              return (pipe);
215          }
216
217       ACLs  have feature flags which can be set or cleared for each ACL indi‐
218       vidually:
219
220+log - Emit a Acl record in VSL to tell if a match was found or not.
221
222+table - Implement the ACL with a table  instead  of  compiled  code.
223         This runs a little bit slower, but compiles large ACLs much faster.
224
225-pedantic - Allow masks to cover non-zero host-bits.  This allows the
226         following to work:
227
228            acl foo -pedantic +log {
229                "firewall.example.com" / 24;
230            }
231
232         However, if the name resolves to both IPv4 and IPv6  you  will  still
233         get an error.
234
235   VCL objects
236       A VCL object can be instantiated with the new keyword:
237
238          sub vcl_init {
239              new b = directors.round_robin()
240              b.add_backend(node1);
241          }
242
243       This is only available in vcl_init.
244
245   Subroutines
246       A subroutine is used to group code for legibility or reusability:
247
248          sub pipe_if_local {
249              if (client.ip ~ localnetwork) {
250                  return (pipe);
251              }
252          }
253
254       Subroutines  in  VCL  do not take arguments, nor do they return values.
255       The built in subroutines all have names beginning with vcl_,  which  is
256       reserved.
257
258       To call a subroutine, use the call keyword followed by the subroutine's
259       name:
260
261          sub vcl_recv {
262              call pipe_if_local;
263          }
264
265   Return statements
266       The ongoing vcl_* subroutine execution  ends  when  a  return(<action>)
267       statement is made.
268
269       The  <action>  specifies  how execution should proceed. The context de‐
270       fines which actions are available.
271
272       It is possible to exit a subroutine that is not part  of  the  built-in
273       ones  using  a simple return statement without specifying an action. It
274       exits the subroutine without transitioning to a different state:
275
276          sub filter_cookies {
277              if (!req.http.cookie) {
278                  return;
279              }
280              # complex cookie filtering
281          }
282
283   Multiple subroutines
284       If multiple subroutines with the name of one of the built-in  ones  are
285       defined, they are concatenated in the order in which they appear in the
286       source.
287
288       The built-in VCL distributed with Varnish will be  implicitly  concate‐
289       nated when the VCL is compiled.
290
291   Functions
292       The following built-in functions are available:
293
294   ban(STRING)
295          Deprecated. See std.ban().
296
297          The  ban()  function is identical to std.ban(), but does not provide
298          error reporting.
299
300   hash_data(input)
301          Adds an input to the hash input. In the built-in VCL hash_data()  is
302          called on the host and URL of the request. Available in vcl_hash.
303
304   synthetic(STRING)
305          Prepare  a  synthetic response body containing the STRING. Available
306          in vcl_synth and vcl_backend_error.
307
308          Identical to set resp.body /  set beresp.body.
309
310   regsub(str, regex, sub)
311          Returns a copy of str with the first occurrence of the  regular  ex‐
312          pression  regex replaced with sub. Within sub, \0 (which can also be
313          spelled \&) is replaced with the entire matched string,  and  \n  is
314          replaced with the contents of subgroup n in the matched string.
315
316   regsuball(str, regex, sub)
317          As regsub(), but this replaces all occurrences.
318
319       For  converting  or casting VCL values between data types use the func‐
320       tions available in the std VMOD.
321

VERSIONING

323       Multiple versions of the VCL syntax can  coexist  within  certain  con‐
324       straints.
325
326       The  VCL syntax version at the start of VCL file specified with -f sets
327       the hard limit that cannot be exceeded anywhere, and it selects the ap‐
328       propriate version of the builtin VCL.
329
330       That  means  that you can never include vcl 9.1; from vcl 8.7;, but the
331       opposite may be possible, to the extent the compiler supports it.
332
333       Files pulled in via include do not need to have a vcl X.Y; but  it  may
334       be  a  good  idea to do it anyway, to not have surprises in the future.
335       The syntax version set in an included file only applies  to  that  file
336       and  any files it includes - unless these set their own VCL syntax ver‐
337       sion.
338
339       The version of Varnish this file belongs to  supports  syntax  4.0  and
340       4.1.
341

EXAMPLES

343       For examples, please see the online documentation.
344

SEE ALSO

346varnishd(1)
347
348vcl-backend(7)
349
350vcl-probe(7)
351
352vcl-var(7)
353
354vmod_directors(3)
355
356vmod_std(3)
357

HISTORY

359       VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
360       AS, Redpill Linpro and Varnish Software.  This manual page  is  written
361       by  Per  Buer,  Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
362       gstøl, Lasse Karstensen and others.
363
365       This document is licensed under the same license as Varnish itself. See
366       LICENSE for details.
367
368       • Copyright (c) 2006 Verdens Gang AS
369
370       • Copyright (c) 2006-2015 Varnish Software AS
371
372
373
374
375                                                                        VCL(7)
Impressum