1VCL(7) VCL(7)
2
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 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 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 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 Operators
26 The following operators are available in VCL:
27 = Assignment operator.
29 +, -, *, /, %
31 Basic math on numerical values.
32 +=, -=, *=, /=
34 Assign and increment/decrement/multiply/divide operator.
35 For strings, += appends.
37 (, ) Evaluate separately.
39 ==, !=, <, >, <=, >=
41 Comparisons
42 ~, !~ Match / non-match. Can either be used with regular expres‐
44 sions or ACLs.
45 ! Negation.
47 && / ||
49 Logical and/or.
50 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 Note that there are no loops or iterators of any kind in VCL.
56 Variables
58 VCL does most of the work by examining, set'ing and unset'ing vari‐
59 ables:
60 if (req.url == "/mistyped_url.html") {
62 set req.url = "/correct_url.html";
63 unset req.http.cookie;
64 }
65 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 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 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 Explicit conversion functions are available in vmod_std(3).
81 For the complete album of VCL variables see: vcl-var(7).
83 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 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 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 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 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 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 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 ms milliseconds
120 s seconds
122 m minutes
124 h hours
126 d days
128 w weeks
130 y years
132 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 Integers
137 Certain fields are integers, used as expected. In string context they
138 return a string, e.g. 1234.
139 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 Regular Expressions
145 Varnish uses Perl-compatible regular expressions (PCRE). For a complete
146 description please see the pcre(3) man page.
147 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 # If host is NOT example dot com..
152 if (req.http.host !~ "(?i)example\.com$") {
153 ...
154 }
155 Include statement
157 To include a VCL file in another file use the include keyword:
158 include "foo.vcl";
160 Optionally, the include keyword can take a +glob flag to include all
162 files matching a glob pattern:
163 include +glob "example.org/*.vcl";
165 Import statement
167 The import statement is used to load Varnish Modules (VMODs.)
168 Example:
170 import std;
172 sub vcl_recv {
173 std.log("foo");
174 }
175 Comments
177 Single lines of VCL can be commented out using // or #. Multi-line
178 blocks can be commented out with /*block*/.
179 Example:
181 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 Backends and health probes
191 Please see vcl-backend(7) and vcl-probe(7)
192 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 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 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 To match an IP address against an ACL, simply use the match operator:
212 if (client.ip ~ localnetwork) {
214 return (pipe);
215 }
216 ACLs have feature flags which can be set or cleared for each ACL indi‐
218 vidually:
219 • +log - Emit a Acl record in VSL to tell if a match was found or not.
221 • +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 • -pedantic - Allow masks to cover non-zero host-bits. This allows the
226 following to work:
227 acl foo -pedantic +log {
229 "firewall.example.com" / 24;
230 }
231 However, if the name resolves to both IPv4 and IPv6 you will still
233 get an error.
234 VCL objects
236 A VCL object can be instantiated with the new keyword:
237 sub vcl_init {
239 new b = directors.round_robin()
240 b.add_backend(node1);
241 }
242 This is only available in vcl_init.
244 Subroutines
246 A subroutine is used to group code for legibility or reusability:
247 sub pipe_if_local {
249 if (client.ip ~ localnetwork) {
250 return (pipe);
251 }
252 }
253 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 To call a subroutine, use the call keyword followed by the subroutine's
259 name:
260 sub vcl_recv {
262 call pipe_if_local;
263 }
264 Return statements
266 The ongoing vcl_* subroutine execution ends when a return(<action>)
267 statement is made.
268 The <action> specifies how execution should proceed. The context de‐
270 fines which actions are available.
271 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 sub filter_cookies {
277 if (!req.http.cookie) {
278 return;
279 }
280 # complex cookie filtering
281 }
282 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 The built-in VCL distributed with Varnish will be implicitly concate‐
289 nated when the VCL is compiled.
290 Functions
292 The following built-in functions are available:
293 ban(STRING)
295 Deprecated. See std.ban().
296 The ban() function is identical to std.ban(), but does not provide
298 error reporting.
299 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 synthetic(STRING)
305 Prepare a synthetic response body containing the STRING. Available
306 in vcl_synth and vcl_backend_error.
307 Identical to set resp.body / set beresp.body.
309 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 regsuball(str, regex, sub)
317 As regsub(), but this replaces all occurrences.
318 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 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 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 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 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 • vcl-backend(7)
349 • vcl-probe(7)
351 • vcl-var(7)
353 • vmod_directors(3)
355 • 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 • Copyright (c) 2006 Verdens Gang AS
369 • Copyright (c) 2006-2015 Varnish Software AS
371 VCL(7)