1VMOD(STD) VMOD(STD)
2
3
4
6 VMOD std - Varnish Standard Module
7
9 import std [as name] [from "path"]
10
11 REAL random(REAL lo, REAL hi)
12
13 REAL round(REAL r)
14
15 VOID collect(HEADER hdr, STRING sep)
16
17 STRING querysort(STRING)
18
19 STRING toupper(STRING s)
20
21 STRING tolower(STRING s)
22
23 STRING strstr(STRING s1, STRING s2)
24
25 BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname, BOOL noescape, BOOL period)
26
27 STRING fileread(STRING)
28
29 BOOL file_exists(STRING path)
30
31 BOOL healthy(BACKEND be)
32
33 INT port(IP ip)
34
35 DURATION duration([STRING s], [DURATION fallback], [REAL real], [INT integer])
36
37 BYTES bytes([STRING s], [BYTES fallback], [REAL real], [INT integer])
38
39 INT integer([STRING s], [INT fallback], [BOOL bool], [BYTES bytes], [DURATION duration], [REAL real], [TIME time])
40
41 IP ip(STRING s, [IP fallback], BOOL resolve, [STRING p])
42
43 REAL real([STRING s], [REAL fallback], [INT integer], [BOOL bool], [BYTES bytes], [DURATION duration], [TIME time])
44
45 TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])
46
47 VOID log(STRING s)
48
49 VOID syslog(INT priority, STRING s)
50
51 VOID timestamp(STRING s)
52
53 BOOL syntax(REAL)
54
55 STRING getenv(STRING name)
56
57 BOOL cache_req_body(BYTES size)
58
59 VOID late_100_continue(BOOL late)
60
61 VOID set_ip_tos(INT tos)
62
63 VOID rollback(HTTP h)
64
65 INT real2integer(REAL r, INT fallback)
66
67 TIME real2time(REAL r, TIME fallback)
68
69 INT time2integer(TIME t, INT fallback)
70
71 REAL time2real(TIME t, REAL fallback)
72
74 vmod_std contains basic functions which are part and parcel of Varnish,
75 but which for reasons of architecture fit better in a VMOD.
76
78 REAL random(REAL lo, REAL hi)
79 Returns a random real number between lo and hi.
80
81 This function uses the "testable" random generator in varnishd which
82 enables determinstic tests to be run (See m00002.vtc). This function
83 should not be used for cryptographic applications.
84
85 Example:
86
87 set beresp.http.random-number = std.random(1, 100);
88
89 REAL round(REAL r)
90 Rounds the real r to the nearest integer, but round halfway cases away
91 from zero (see round(3)).
92
94 VOID collect(HEADER hdr, STRING sep=", )
95 Collapses multiple hdr headers into one long header. The default sepa‐
96 rator sep is the standard comma separator to use when collapsing head‐
97 ers, with an additional whitespace for pretty printing.
98
99 Care should be taken when collapsing headers. In particular collapsing
100 Set-Cookie will lead to unexpected results on the browser side.
101
102 Examples:
103
104 std.collect(req.http.accept);
105 std.collect(req.http.cookie, "; ");
106
107 STRING querysort(STRING)
108 Sorts the query string for cache normalization purposes.
109
110 Example:
111
112 set req.url = std.querysort(req.url);
113
114 STRING toupper(STRING s)
115 Converts the string s to uppercase.
116
117 Example:
118
119 set beresp.http.scream = std.toupper("yes!");
120
121 STRING tolower(STRING s)
122 Converts the string s to lowercase.
123
124 Example:
125
126 set beresp.http.nice = std.tolower("VerY");
127
128 STRING strstr(STRING s1, STRING s2)
129 Returns a string beginning at the first occurrence of the string s2 in
130 the string s1, or an empty string if s2 is not found.
131
132 Note that the comparison is case sensitive.
133
134 Example:
135
136 if (std.strstr(req.url, req.http.restrict)) {
137 ...
138 }
139
140 This will check if the content of req.http.restrict occurs anywhere in
141 req.url.
142
143 BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname, BOOL noescape,
144 BOOL period)
145 BOOL fnmatch(
146 STRING pattern,
147 STRING subject,
148 BOOL pathname=1,
149 BOOL noescape=0,
150 BOOL period=0
151 )
152
153 Shell-style pattern matching; returns true if subject matches pattern,
154 where pattern may contain wildcard characters such as * or ?.
155
156 The match is executed by the implementation of fnmatch(3) on your sys‐
157 tem. The rules for pattern matching on most systems include the follow‐
158 ing:
159
160 · * matches any sequence of characters
161
162 · ? matches a single character
163
164 · a bracket expression such as [abc] or [!0-9] is interpreted as a
165 character class according to the rules of basic regular expressions
166 (not pcre(3) regexen), except that ! is used for character class
167 negation instead of ^.
168
169 If pathname is true, then the forward slash character / is only matched
170 literally, and never matches *, ? or a bracket expression. Otherwise, /
171 may match one of those patterns. By default, pathname is true.
172
173 If noescape is true, then the backslash character \ is matched as an
174 ordinary character. Otherwise, \ is an escape character, and matches
175 the character that follows it in the pattern. For example, \\ matches \
176 when noescape is true, and \\ when false. By default, noescape is
177 false.
178
179 If period is true, then a leading period character . only matches lit‐
180 erally, and never matches *, ? or a bracket expression. A period is
181 leading if it is the first character in subject; if pathname is also
182 true, then a period that immediately follows a / is also leading (as in
183 /.). By default, period is false.
184
185 std.fnmatch() invokes VCL failure and returns false if either of pat‐
186 tern or subject is NULL -- for example, if an unset header is speci‐
187 fied.
188
189 Examples:
190
191 # Matches URLs such as /foo/bar and /foo/baz
192 if (std.fnmatch("/foo/\*", req.url)) { ... }
193
194 # Matches URLs such as /foo/bar/baz and /foo/baz/quux
195 if (std.fnmatch("/foo/\*/\*", bereq.url)) { ... }
196
197 # Matches /foo/bar/quux, but not /foo/bar/baz/quux
198 if (std.fnmatch("/foo/\*/quux", req.url)) { ... }
199
200 # Matches /foo/bar/quux and /foo/bar/baz/quux
201 if (std.fnmatch("/foo/\*/quux", req.url, pathname=false)) { ... }
202
203 # Matches /foo/bar, /foo/car and /foo/far
204 if (std.fnmatch("/foo/?ar", req.url)) { ... }
205
206 # Matches /foo/ followed by a non-digit
207 if (std.fnmatch("/foo/[!0-9]", req.url)) { ... }
208
210 STRING fileread(STRING)
211 Reads a file and returns a string with the content. The result is
212 cached indefinitely per filename.
213
214 Example:
215
216 synthetic("Response was served by " + std.fileread("/etc/hostname"));
217
218 Consider that the entire contents of the file appear in the string that
219 is returned, including newlines that may result in invalid headers if
220 std.fileread() is used to form a header. In that case, you may need to
221 modify the string, for example with regsub() (see vcl(7)):
222
223 set beresp.http.served-by = regsub(std.fileread("/etc/hostname"), "\R$", "");
224
225 BOOL file_exists(STRING path)
226 Returns true if path or the file pointed to by path exists, false oth‐
227 erwise.
228
229 Example:
230
231 if (std.file_exists("/etc/return_503")) {
232 return (synth(503, "Varnish is in maintenance"));
233 }
234
236 BOOL healthy(BACKEND be)
237 Returns true if the backend be is healthy.
238
239 INT port(IP ip)
240 Returns the port number of the IP address ip. Always returns 0 for a
241 *.ip variable when the address is a Unix domain socket.
242
244 These functions all have the same form:
245
246 TYPE type([arguments], [fallback TYPE])
247
248 Precisely one of the arguments must be provided (besides the optional
249 fallback), and it will be converted to TYPE.
250
251 If conversion fails, fallback will be returned and if no fallback was
252 specified, the VCL will be failed.
253
254 DURATION duration([STRING s], [DURATION fallback], [REAL real], [INT inte‐
255 ger])
256 DURATION duration(
257 [STRING s],
258 [DURATION fallback],
259 [REAL real],
260 [INT integer]
261 )
262
263 Returns a DURATION from a STRING, REAL or INT argument.
264
265 For a STRING s argument, s must be quantified by ms (milliseconds), s
266 (seconds), m (minutes), h (hours),``d`` (days), w (weeks) or y (years)
267 units.
268
269 real and integer arguments are taken as seconds.
270
271 If the conversion of an s argument fails, fallback will be returned if
272 provided, or a VCL failure will be triggered.
273
274 Conversions from real and integer arguments never fail.
275
276 Only one of the s, real or integer arguments may be given or a VCL
277 failure will be triggered.
278
279 Examples::
280 set beresp.ttl = std.duration("1w", 3600s); set beresp.ttl =
281 std.duration(real=1.5); set beresp.ttl = std.duration(inte‐
282 ger=10);
283
284 BYTES bytes([STRING s], [BYTES fallback], [REAL real], [INT integer])
285 BYTES bytes(
286 [STRING s],
287 [BYTES fallback],
288 [REAL real],
289 [INT integer]
290 )
291
292 Returns BYTES from a STRING, REAL or INT argument.
293
294 A STRING s argument can be quantified with a multiplier (k (kilo), m
295 (mega), g (giga), t (tera) or p (peta)).
296
297 real and integer arguments are taken as bytes.
298
299 If the conversion of an s argument fails, fallback will be returned if
300 provided, or a VCL failure will be triggered.
301
302 Other conversions may fail if the argument can not be represented,
303 because it is negative, too small or too large. Again, fallback will be
304 returned if provided, or a VCL failure will be triggered.
305
306 real arguments will be rounded down.
307
308 Only one of the s, real or integer arguments may be given or a VCL
309 failure will be triggered.
310
311 Example::
312 std.cache_req_body(std.bytes(something.somewhere, 10K));
313 std.cache_req_body(std.bytes(integer=10*1024));
314 std.cache_req_body(std.bytes(real=10.0*1024));
315
316 INT integer([STRING s], [INT fallback], [BOOL bool], [BYTES bytes], [DURA‐
317 TION duration], [REAL real], [TIME time])
318 INT integer(
319 [STRING s],
320 [INT fallback],
321 [BOOL bool],
322 [BYTES bytes],
323 [DURATION duration],
324 [REAL real],
325 [TIME time]
326 )
327
328 Returns an INT from a STRING, BOOL or other quantity.
329
330 If the conversion of an s argument fails, fallback will be returned if
331 provided, or a VCL failure will be triggered.
332
333 A bool argument will be returned as 0 for false and 1 for true. This
334 conversion will never fail.
335
336 For a bytes argument, the number of bytes will be returned. This con‐
337 version will never fail.
338
339 A duration argument will be rounded down to the number of seconds and
340 returned.
341
342 A real argument will be rounded down and returned.
343
344 For a time argument, the number of seconds since the UNIX epoch
345 (1970-01-01 00:00:00 UTC) will be returned.
346
347 duration, real and time conversions may fail if the argument can not be
348 represented because it is too small or too large. If so, fallback will
349 be returned if provided, or a VCL failure will be triggered.
350
351 Only one of the s, bool, bytes, duration, real or time arguments may be
352 given or a VCL failure will be triggered.
353
354 Examples:
355
356 if (std.integer(req.http.foo, 0) > 5) {
357 ...
358 }
359
360 set resp.http.answer = std.integer(real=126.42/3);
361
362 IP ip(STRING s, [IP fallback], BOOL resolve=1, [STRING p])
363 Converts the string s to the first IP number returned by the system
364 library function getaddrinfo(3). If conversion fails, fallback will be
365 returned or VCL failure will happen.
366
367 The IP address includes a port number that can be found with std.port()
368 that defaults to 80. The default port can be set to a different value
369 with the p argument. It will be overriden if s contains both an IP
370 address and a port number or service name.
371
372 When s contains both, the syntax is either address:port or address
373 port. If the address is a numerical IPv6 address it must be enclosed
374 between brackets, for example [::1] 80 or [::1]:http. The fallback may
375 also contain both an address and a port, but its default port is always
376 80.
377
378 If resolve is false, getaddrinfo(3) is called using AI_NUMERICHOST and
379 AI_NUMERICSERV to avoid network lookups depending on the system's
380 getaddrinfo(3) or nsswitch configuration. This makes "numerical" IP
381 strings and services cheaper to convert.
382
383 Example:
384
385 if (std.ip(req.http.X-forwarded-for, "0.0.0.0") ~ my_acl) {
386 ...
387 }
388
389 REAL real([STRING s], [REAL fallback], [INT integer], [BOOL bool], [BYTES
390 bytes], [DURATION duration], [TIME time])
391 REAL real(
392 [STRING s],
393 [REAL fallback],
394 [INT integer],
395 [BOOL bool],
396 [BYTES bytes],
397 [DURATION duration],
398 [TIME time]
399 )
400
401 Returns a REAL from a STRING, BOOL or other quantity.
402
403 If the conversion of an s argument fails, fallback will be returned if
404 provided, or a VCL failure will be triggered.
405
406 A bool argument will be returned as 0.0 for false and 1.0 for true.
407
408 For a bytes argument, the number of bytes will be returned.
409
410 For a duration argument, the number of seconds will be returned.
411
412 An integer argument will be returned as a REAL.
413
414 For a time argument, the number of seconds since the UNIX epoch
415 (1970-01-01 00:00:00 UTC) will be returned.
416
417 None of these conversions other than s will fail.
418
419 Only one of the s, integer, bool, bytes, duration or time arguments may
420 be given or a VCL failure will be triggered.
421
422 Example:
423
424 if (std.real(req.http.foo, 0.0) > 5.5) {
425 ...
426 }
427
428 TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])
429 TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])
430
431 Returns a TIME from a STRING, REAL or INT argument.
432
433 For a STRING s argument, the following formats are supported:
434
435 "Sun, 06 Nov 1994 08:49:37 GMT"
436 "Sunday, 06-Nov-94 08:49:37 GMT"
437 "Sun Nov 6 08:49:37 1994"
438 "1994-11-06T08:49:37"
439 "784111777.00"
440 "784111777"
441
442 real and integer arguments are taken as seconds since the epoch.
443
444 If the conversion of an s argument fails or a negative real or integer
445 argument is given, fallback will be returned if provided, or a VCL
446 failure will be triggered.
447
448 Examples:
449
450 if (std.time(resp.http.last-modified, now) < now - 1w) {
451 ...
452 }
453
454 if (std.time(int=2147483647) < now - 1w) {
455 ...
456 }
457
459 VOID log(STRING s)
460 Logs the string s to the shared memory log, using vsl(7) tag
461 SLT_VCL_Log.
462
463 Example:
464
465 std.log("Something fishy is going on with the vhost " + req.http.host);
466
467 VOID syslog(INT priority, STRING s)
468 Logs the string s to syslog tagged with priority. priority is formed by
469 ORing the facility and level values. See your system's syslog.h file
470 for possible values.
471
472 Notice: Unlike VCL and other functions in the std vmod, this function
473 will not fail VCL processing for workspace overflows: For an out of
474 workspace condition, the std.syslog() function has no effect.
475
476 Example:
477
478 std.syslog(9, "Something is wrong");
479
480 This will send a message to syslog using LOG_USER | LOG_ALERT.
481
482 VOID timestamp(STRING s)
483 Introduces a timestamp in the log with the current time, using the
484 string s as the label. This is useful to time the execution of lengthy
485 VCL procedures, and makes the timestamps inserted automatically by Var‐
486 nish more accurate.
487
488 Example:
489
490 std.timestamp("curl-request");
491
493 BOOL syntax(REAL)
494 Returns true if VCL version is at least REAL.
495
496 STRING getenv(STRING name)
497 Return environment variable name or the empty string. See getenv(3).
498
499 Example:
500
501 set req.http.My-Env = std.getenv("MY_ENV");
502
503 BOOL cache_req_body(BYTES size)
504 Caches the request body if it is smaller than size. Returns true if
505 the body was cached, false otherwise.
506
507 Normally the request body can only be sent once. Caching it enables
508 retrying backend requests with a request body, as usually the case with
509 POST and PUT.
510
511 Example:
512
513 if (std.cache_req_body(1KB)) {
514 ...
515 }
516
517 VOID late_100_continue(BOOL late)
518 Controls when varnish reacts to an Expect: 100-continue client request
519 header.
520
521 Varnish always generates a 100 Continue response if requested by the
522 client trough the Expect: 100-continue header when waiting for request
523 body data.
524
525 But, by default, the 100 Continue response is already generated immedi‐
526 ately after vcl_recv returns to reduce latencies under the assumption
527 that the request body will be read eventually.
528
529 Calling std.late_100_continue(true) in vcl_recv will cause the 100 Con‐
530 tinue response to only be sent when needed. This may cause additional
531 latencies for processing request bodies, but is the correct behavior by
532 strict interpretation of RFC7231.
533
534 This function has no effect outside vcl_recv and after calling
535 std.cache_req_body() or any other function consuming the request body.
536
537 Example:
538
539 vcl_recv {
540 std.late_100_continue(true);
541
542 if (req.method == "POST") {
543 std.late_100_continue(false);
544 return (pass);
545 }
546 ...
547 }
548
549 VOID set_ip_tos(INT tos)
550 Sets the IP type-of-service (TOS) field for the current session to tos.
551 Silently ignored if the listen address is a Unix domain socket.
552
553 Please note that the TOS field is not removed by the end of the request
554 so probably want to set it on every request should you utilize it.
555
556 Example:
557
558 if (req.url ~ "^/slow/") {
559 std.set_ip_tos(0);
560 }
561
562 VOID rollback(HTTP h)
563 Restores the h HTTP headers to their original state.
564
565 Example:
566
567 std.rollback(bereq);
568
570 INT real2integer(REAL r, INT fallback)
571 DEPRECATED: This function will be removed in a future version of var‐
572 nish, use std.integer() with a real argument and the std.round() func‐
573 tion instead, for example:
574
575 std.integer(real=std.round(...), fallback=...)
576
577 Rounds the real r to the nearest integer, but round halfway cases away
578 from zero (see round(3)). If conversion fails, fallback will be
579 returned.
580
581 Examples:
582
583 set req.http.integer = std.real2integer(1140618699.00, 0);
584 set req.http.posone = real2integer( 0.5, 0); # = 1.0
585 set req.http.negone = real2integer(-0.5, 0); # = -1.0
586
587 TIME real2time(REAL r, TIME fallback)
588 DEPRECATED: This function will be removed in a future version of var‐
589 nish, use std.time() with a real argument and the std.round() function
590 instead, for example:
591
592 std.time(real=std.round(...), fallback=...)
593
594 Rounds the real r to the nearest integer (see std.real2integer()) and
595 returns the corresponding time when interpreted as a unix epoch. If
596 conversion fails, fallback will be returned.
597
598 Example:
599
600 set req.http.time = std.real2time(1140618699.00, now);
601
602 INT time2integer(TIME t, INT fallback)
603 DEPRECATED: This function will be removed in a future version of var‐
604 nish, use std.integer() with a time argument instead, for example:
605
606 std.integer(time=..., fallback=...)
607
608 Converts the time t to a integer. If conversion fails, fallback will be
609 returned.
610
611 Example:
612
613 set req.http.int = std.time2integer(now, 0);
614
615 REAL time2real(TIME t, REAL fallback)
616 DEPRECATED: This function will be removed in a future version of var‐
617 nish, use std.real() with a time argument instead, for example:
618
619 std.real(time=..., fallback=...)
620
621 Converts the time t to a real. If conversion fails, fallback will be
622 returned.
623
624 Example:
625
626 set req.http.real = std.time2real(now, 1.0);
627
629 · varnishd(1)
630
631 · vsl(7)
632
633 · fnmatch(3)
634
636 Copyright (c) 2010-2017 Varnish Software AS
637 All rights reserved.
638
639 Author: Poul-Henning Kamp <phk@FreeBSD.org>
640
641 Redistribution and use in source and binary forms, with or without
642 modification, are permitted provided that the following conditions
643 are met:
644 1. Redistributions of source code must retain the above copyright
645 notice, this list of conditions and the following disclaimer.
646 2. Redistributions in binary form must reproduce the above copyright
647 notice, this list of conditions and the following disclaimer in the
648 documentation and/or other materials provided with the distribution.
649
650 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
651 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
652 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
653 ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
654 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
655 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
656 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
657 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
658 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
659 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
660 SUCH DAMAGE.
661
662
663
664
665 3 VMOD(STD)