1VCL(7) BSD Miscellaneous Information Manual VCL(7)
2
4 VCL — Varnish Configuration Language
5
7 The VCL language is a small domain-specific language designed to be used
8 to define request handling and document caching policies for the Varnish
9 HTTP accelerator.
10 When a new configuration is loaded, the varnishd management process
12 translates the VCL code to C and compiles it to a shared object which is
13 then dynamically linked into the server process.
14 Syntax
16 The VCL syntax is very simple, and deliberately similar to C and Perl.
17 Blocks are delimited by curly braces, statements end with semicolons, and
18 comments may be written as in C, C++ or Perl according to your own pref‐
19 erences.
20 In addition to the C-like assignment (=), comparison (==) and boolean (!,
22 && and ||) operators, VCL supports regular expression and ACL matching
23 using the ~ operator.
24 Unlike C and Perl, the backslash (\) character has no special meaning in
26 strings in VCL, so it can be freely used in regular expressions without
27 doubling.
28 Assignments are introduced with the set keyword. There are no user-
30 defined variables; values can only be assigned to variables attached to
31 backend, request or document objects. Most of these are typed, and the
32 values assigned to them must have a compatible unit suffix.
33 VCL has if tests, but no loops.
35 The contents of another VCL file may be inserted at any point in the code
37 by using the include keyword followed by the name of the other file as a
38 quoted string.
39 Backend declarations
41 A backend declaration creates and initializes a named backend object:
42 backend www {
44 set backend.host = "www.example.com";
45 set backend.port = "http";
46 }
47 The backend object can later be used to select a backend at request time:
49 if (req.http.host ~ "^(www.)?example.com$") {
51 set req.backend = www;
52 }
53 ACLs
55 An ACL declaration creates and initializes a named access control list
56 which can later be used to match client addresses:
57 acl local {
59 "locahost"; /* myself */
60 "10.0.0.1"/8; /* and everyone on the local network */
61 ! "10.0.0.23"; /* except for the dialin router */
62 }
63 If an ACL entry specifies a host name which Varnish is unable to resolve,
65 it will match any address it is compared to. Consequently, if it is pre‐
66 ceded by a negation mark, it will reject any address it is compared to,
67 which may not be what you intended. If the entry is enclosed in paren‐
68 theses, however, it will simply be ignored.
69 To match an IP address against an ACL, simply use the match operator:
71 if (client.ip ~ local) {
73 pipe;
74 }
75 Functions
77 The following built-in functions are available:
78 regsub(str, regex, sub)
80 Returns a copy of str with all occurrences of the regular expres‐
81 sion regex replaced with sub. Within sub, $0 (which can also be
82 spelled &) is replaced with the entire matched string, and $n is
83 replaced with the contents of subgroup n in the matched string.
84 purge_url(regex)
86 Purge all objects in cache whose URLs match regex.
87 Subroutines
89 A subroutine is used to group code for legibility or reusability:
90 sub pipe_if_local {
92 if (client.ip ~ local) {
93 pipe;
94 }
95 }
96 Subroutines in VCL do not take arguments, nor do they return values.
98 If multiple subroutines with the same name are defined, they are concate‐
100 nated in the order in which the appear in the source.
101 To call a subroutine, use the call keyword followed by the subroutine's
103 name:
104 call pipe_if_local;
106 There are a number of special subroutines which hook into the Varnish
108 workflow. These subroutines may inspect and manipulate HTTP headers and
109 various other aspects of each request, and to a certain extent decide how
110 the request should be handled. Each subroutine terminates by calling one
111 of a small number of keywords which indicates the desired outcome.
112 vcl_recv
114 Called at the beginning of a request, after the complete request
115 has been received and parsed. Its purpose is to decide whether
116 or not to serve the request, how to do it, and, if applicable,
117 which backend to use.
118 The vcl_recv subroutine may terminate with one of the following
120 keywords:
121 error code [reason]
123 Return the specified error code to the client and abandon
124 the request.
125 pass Switch to pass mode. Control will eventually pass to
127 vcl_pass.
128 pipe Switch to pipe mode. Control will eventually pass to
130 vcl_pipe.
131 lookup Look up the requested object in the cache. Control will
133 eventually pass to vcl_hit or vcl_miss, depending on
134 whether the object is in the cache.
135 vcl_pipe
137 Called upon entering pipe mode. In this mode, the request is
138 passed on to the backend, and any further data from either client
139 or backend is passed on unaltered until either end closes the
140 connection.
141 The vcl_pipe subroutine may terminate with one of the following
143 keywords:
144 error code [reason]
146 Return the specified error code to the client and abandon
147 the request.
148 pipe Proceed with pipe mode.
150 vcl_pass
152 Called upon entering pass mode. In this mode, the request is
153 passed on to the backend, and the backend's response is passed on
154 to the client, but is not entered into the cache. Subsequent
155 requests submitted over the same client connection are handled
156 normally.
157 The vcl_pass subroutine may terminate with one of the following
159 keywords:
160 error code [reason]
162 Return the specified error code to the client and abandon
163 the request.
164 pass Proceed with pass mode.
166 vcl_hash
168 Currently not used. The vcl_hash subroutine may terminate with
169 one of the following keywords:
170 hash Proceed.
172 vcl_hit
174 Called after a cache lookup if the requested document was found
175 in the cache.
176 The vcl_hit subroutine may terminate with one of the following
178 keywords:
179 error code [reason]
181 Return the specified error code to the client and abandon
182 the request.
183 pass Switch to pass mode. Control will eventually pass to
185 vcl_pass.
186 deliver
188 Deliver the cached object to the client. Control will
189 eventually pass to vcl_deliver.
190 vcl_miss
192 Called after a cache lookup if the requested document was not
193 found in the cache. Its purpose is to decide whether or not to
194 attempt to retrieve the document from the backend, and which
195 backend to use.
196 The vcl_miss subroutine may terminate with one of the following
198 keywords:
199 error code [reason]
201 Return the specified error code to the client and abandon
202 the request.
203 pass Switch to pass mode. Control will eventually pass to
205 vcl_pass.
206 fetch Retrieve the requested object from the backend. Control
208 will eventually pass to vcl_fetch.
209 vcl_fetch
211 Called after a document has been successfully retrieved from the
212 backend.
213 The vcl_fetch subroutine may terminate with one of the following
215 keywords:
216 error code [reason]
218 Return the specified error code to the client and abandon
219 the request.
220 pass Switch to pass mode. Control will eventually pass to
222 vcl_pass.
223 insert Insert the object into the cache, then deliver it to the
225 client. Control will eventually pass to vcl_deliver.
226 vcl_deliver
228 Called before a cached object is delivered to the client.
229 The vcl_deliver subroutine may terminate with one of the follow‐
231 ing keywords:
232 error code [reason]
234 Return the specified error code to the client and abandon
235 the request.
236 deliver
238 Deliver the object to the client.
239 vcl_timeout
241 Called by the reaper thread shortly before a cached document
242 reaches its expiry time.
243 The vcl_timeout subroutine may terminate with one of the follow‐
245 ing keywords:
246 fetch Request a fresh copy of the object from the backend.
248 discard
250 Discard the object.
251 vcl_discard
253 Called by the reaper thread when a cached document is about to be
254 discarded, either because it has expired or because space is run‐
255 ning low.
256 The vcl_discard subroutine may terminate with one of the follow‐
258 ing keywords:
259 discard
261 Discard the object.
262 keep Keep the object in cache.
264 If one of these subroutines is left undefined or terminates without
266 reaching a handling decision, control will be handed over to the builtin
267 default. See the EXAMPLES section for a listing of the default code.
268 Variables
270 Although subroutines take no arguments, the necessary information is made
271 available to the handler subroutines through global variables.
272 The following variables are always available:
274 now The current time, in seconds since the epoch.
276 The following variables are available in backend declarations:
278 backend.host
280 Host name or IP address of a backend.
281 backend.port
283 Service name or port number of a backend.
284 The following variables are available while processing a request:
286 client.ip
288 The client's IP address.
289 server.ip
291 The IP address of the socket on which the client connection was
292 received.
293 req.request
295 The request type (e.g. "GET", "HEAD").
296 req.url
298 The requested URL.
299 req.proto
301 The HTTP protocol version used by the client.
302 req.backend
304 The backend to use to service the request.
305 req.http.header
307 The corresponding HTTP header.
308 The following variables are available while preparing a backend request
310 (either for a cache miss or for pass or pipe mode):
311 bereq.request
313 The request type (e.g. "GET", "HEAD").
314 bereq.url
316 The requested URL.
317 bereq.proto
319 The HTTP protocol version used to talk to the server.
320 bereq.http.header
322 The corresponding HTTP header.
323 The following variables are available after the requested object has been
325 retrieved from cache or from the backend:
326 obj.proto
328 The HTTP protocol version used when the object was retrieved.
329 obj.status
331 The HTTP status code returned by the server.
332 obj.response
334 The HTTP status message returned by the server.
335 obj.valid
337 True if the request resulted in a valid HTTP response.
338 obj.cacheable
340 True if the request resulted in a cacheable response. A response
341 is considered cacheable if it is valid (see above), the HTTP status
342 code is 200, 203, 300, 301, 302, 404 or 410 and it has a non-zero
343 time-to-live when Expires and Cache-Control headers are taken into
344 account.
345 obj.ttl
347 The object's remaining time to live, in seconds.
348 obj.lastuse
350 The approximate time elapsed since the object was last requests, in
351 seconds.
352 The following variables are available while preparing a response to the
354 client:
355 resp.proto
357 The HTTP protocol version to use for the response.
358 resp.status
360 The HTTP status code that will be returned.
361 resp.response
363 The HTTP status message that will be returned.
364 resp.http.header
366 The corresponding HTTP header.
367 Values may be assigned to variables using the set keyword:
369 sub vcl_recv {
371 # Normalize the Host: header
372 if (req.http.host ~ "^(www.)?example.com$") {
373 set req.http.host = "www.example.com";
374 }
375 }
376 HTTP headers can be removed entirely using the remove keyword:
378 sub vcl_fetch {
380 # Don't cache cookies
381 remove obj.http.Set-Cookie;
382 }
383
385 The following code is the equivalent of the default configuration with
386 the backend address set to "backend.example.com" and no backend port
387 specified.
388 backend default {
390 set backend.host = "backend.example.com";
391 set backend.port = "http";
392 }
393 sub vcl_recv {
395 if (req.request != "GET" && req.request != "HEAD") {
396 pipe;
397 }
398 if (req.http.Expect) {
399 pipe;
400 }
401 if (req.http.Authenticate || req.http.Cookie) {
402 pass;
403 }
404 lookup;
405 }
406 sub vcl_pipe {
408 pipe;
409 }
410 sub vcl_pass {
412 pass;
413 }
414 sub vcl_hash {
416 set req.hash += req.url;
417 set req.hash += req.http.host;
418 hash;
419 }
420 sub vcl_hit {
422 if (!obj.cacheable) {
423 pass;
424 }
425 deliver;
426 }
427 sub vcl_miss {
429 fetch;
430 }
431 sub vcl_fetch {
433 if (!obj.valid) {
434 error;
435 }
436 if (!obj.cacheable) {
437 pass;
438 }
439 if (obj.http.Set-Cookie) {
440 pass;
441 }
442 insert;
443 }
444 sub vcl_deliver {
446 deliver;
447 }
448 sub vcl_timeout {
450 discard;
451 }
452 sub vcl_discard {
454 discard;
455 }
456 The following example shows how to support multiple sites running on sep‐
458 arate backends in the same Varnish instance, by selecting backends based
459 on the request URL.
460 backend www {
462 set backend.host = "www.example.com";
463 set backend.port = "80";
464 }
465 backend images {
467 set backend.host = "images.example.com";
468 set backend.port = "80";
469 }
470 sub vcl_recv {
472 if (req.http.host ~ "^(www.)?example.com$") {
473 set req.http.host = "www.example.com";
474 set req.backend = www;
475 } elsif (req.http.host ~ "^images.example.com$") {
476 set req.backend = images;
477 } else {
478 error 404 "Unknown virtual host";
479 }
480 }
481 The following snippet demonstrates how to force a minimum TTL for all
483 documents. Note that this is not the same as setting the default_ttl
484 run-time parameter, as that only affects document for which the backend
485 did not specify a TTL.
486 sub vcl_fetch {
488 if (obj.ttl < 120s) {
489 set obj.ttl = 120s;
490 }
491 }
492 The following snippet demonstrates how to force Varnish to cache docu‐
494 ments even when cookies are present.
495 sub vcl_recv {
497 if (req.request == "GET" && req.http.cookie) {
498 lookup;
499 }
500 }
501 sub vcl_fetch {
503 if (obj.http.Set-Cookie) {
504 insert;
505 }
506 }
507 The following code implements the HTTP PURGE method as used by Squid for
509 object invalidation:
510 acl purge {
512 "localhost";
513 "10.0.0.1"/8;
514 }
515 sub vcl_recv {
517 if (req.request == "PURGE") {
518 if (!client.ip ~ purge) {
519 error 405 "Not allowed.";
520 }
521 lookup;
522 }
523 }
524 sub vcl_hit {
526 if (req.request == "PURGE") {
527 set obj.ttl = 0s;
528 error 200 "Purged.";
529 }
530 }
531 sub vcl_miss {
533 if (req.request == "PURGE") {
534 error 404 "Not in cache.";
535 }
536 }
537
539 varnishd(1)
540
542 The VCL language was developed by Poul-Henning Kamp <phk@phk.freebsd.dk>
543 in cooperation with Verdens Gang AS and Linpro AS. This manual page was
544 written by Dag-Erling Smørgrav <des@linpro.no>.
545BSD August 3, 2007 BSD