1VCL(7) VCL(7)
2
3
4
6 VCL - Varnish Configuration Language
7
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
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
343 For examples, please see the online documentation.
344
346 • varnishd(1)
347
348 • vcl-backend(7)
349
350 • vcl-probe(7)
351
352 • vcl-var(7)
353
354 • vmod_directors(3)
355
356 • vmod_std(3)
357
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)