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 reponse 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 Import statement
162 The import statement is used to load Varnish Modules (VMODs.)
163 Example:
165 import std;
167 sub vcl_recv {
168 std.log("foo");
169 }
170 Comments
172 Single lines of VCL can be commented out using // or #. Multi-line
173 blocks can be commented out with /*block*/.
174 Example:
176 sub vcl_recv {
178 // Single line of out-commented VCL.
179 # Another way of commenting out a single line.
180 /*
181 Multi-line block of commented-out VCL.
182 */
183 }
184 Backends and health probes
186 Please see vcl-backend(7) and vcl-probe(7)
187 Access Control List (ACL)
189 An Access Control List (ACL) declaration creates and initialises a
190 named access control list which can later be used to match client ad‐
191 dresses:
192 acl localnetwork {
194 "localhost"; # myself
195 "192.0.2.0"/24; # and everyone on the local network
196 ! "192.0.2.23"; # except for the dial-in router
197 }
198 If an ACL entry specifies a host name which Varnish is unable to re‐
200 solve, it will match any address it is compared to. Consequently, if it
201 is preceded by a negation mark, it will reject any address it is com‐
202 pared to, which may not be what you intended. If the entry is enclosed
203 in parentheses, however, it will simply be ignored.
204 To match an IP address against an ACL, simply use the match operator:
206 if (client.ip ~ localnetwork) {
208 return (pipe);
209 }
210 VCL objects
212 A VCL object can be instantiated with the new keyword:
213 sub vcl_init {
215 new b = directors.round_robin()
216 b.add_backend(node1);
217 }
218 This is only available in vcl_init.
220 Subroutines
222 A subroutine is used to group code for legibility or reusability:
223 sub pipe_if_local {
225 if (client.ip ~ localnetwork) {
226 return (pipe);
227 }
228 }
229 Subroutines in VCL do not take arguments, nor do they return values.
231 The built in subroutines all have names beginning with vcl_, which is
232 reserved.
233 To call a subroutine, use the call keyword followed by the subroutine's
235 name:
236 sub vcl_recv {
238 call pipe_if_local;
239 }
240 Return statements
242 The ongoing vcl_* subroutine execution ends when a return(<action>)
243 statement is made.
244 The <action> specifies how execution should proceed. The context de‐
246 fines which actions are available.
247 It is possible to exit a subroutine that is not part of the built-in
249 ones using a simple return statement without specifying an action. It
250 exits the subroutine without transitioning to a different state:
251 sub filter_cookies {
253 if (!req.http.cookie) {
254 return;
255 }
256 # complex cookie filtering
257 }
258 Multiple subroutines
260 If multiple subroutines with the name of one of the built-in ones are
261 defined, they are concatenated in the order in which they appear in the
262 source.
263 The built-in VCL distributed with Varnish will be implicitly concate‐
265 nated when the VCL is compiled.
266 Functions
268 The following built-in functions are available:
269 ban(STRING)
271 Deprecated. See std.ban().
272 The ban() function is identical to std.ban(), but does not provide
274 error reporting.
275 hash_data(input)
277 Adds an input to the hash input. In the built-in VCL hash_data() is
278 called on the host and URL of the request. Available in vcl_hash.
279 synthetic(STRING)
281 Prepare a synthetic response body containing the STRING. Available
282 in vcl_synth and vcl_backend_error.
283 Identical to set resp.body / set beresp.body.
285 regsub(str, regex, sub)
287 Returns a copy of str with the first occurrence of the regular ex‐
288 pression regex replaced with sub. Within sub, \0 (which can also be
289 spelled \&) is replaced with the entire matched string, and \n is
290 replaced with the contents of subgroup n in the matched string.
291 regsuball(str, regex, sub)
293 As regsub(), but this replaces all occurrences.
294 For converting or casting VCL values between data types use the func‐
296 tions available in the std VMOD.
297
299 Multiple versions of the VCL syntax can coexist within certain con‐
300 straints.
301 The VCL syntax version at the start of VCL file specified with -f sets
303 the hard limit that cannot be exceeded anywhere, and it selects the ap‐
304 propriate version of the builtin VCL.
305 That means that you can never include vcl 9.1; from vcl 8.7;, but the
307 opposite may be possible, to the extent the compiler supports it.
308 Files pulled in via include do not need to have a vcl X.Y; but it may
310 be a good idea to do it anyway, to not have surprises in the future.
311 The syntax version set in an included file only applies to that file
312 and any files it includes - unless these set their own VCL syntax ver‐
313 sion.
314 The version of Varnish this file belongs to supports syntax 4.0 and
316 4.1.
317
319 For examples, please see the online documentation.
320
322 • varnishd(1)
323 • vcl-backend(7)
325 • vcl-probe(7)
327 • vcl-var(7)
329 • vmod_directors(3)
331 • vmod_std(3)
333
335 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
336 AS, Redpill Linpro and Varnish Software. This manual page is written
337 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
338 gstøl, Lasse Karstensen and others.
339
341 This document is licensed under the same license as Varnish itself. See
342 LICENSE for details.
343 • Copyright (c) 2006 Verdens Gang AS
345 • Copyright (c) 2006-2015 Varnish Software AS
347 VCL(7)