vmod_std(3)

1VMOD_STD(3)                                                        VMOD_STD(3)
2
3
4

NAME

6       vmod_std - Varnish Standard Module
7

SYNOPSIS

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          BLOB blobread(STRING)
30
31          BOOL file_exists(STRING path)
32
33          BOOL healthy(BACKEND be)
34
35          INT port(IP ip)
36
37          DURATION duration([STRING s], [DURATION fallback], [REAL real], [INT integer])
38
39          BYTES bytes([STRING s], [BYTES fallback], [REAL real], [INT integer])
40
41          INT integer([STRING s], [INT fallback], [BOOL bool], [BYTES bytes], [DURATION duration], [REAL real], [TIME time])
42
43          IP ip(STRING s, [IP fallback], BOOL resolve, [STRING p])
44
45          REAL real([STRING s], [REAL fallback], [INT integer], [BOOL bool], [BYTES bytes], [DURATION duration], [TIME time])
46
47          TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])
48
49          VOID log(STRING s)
50
51          VOID syslog(INT priority, STRING s)
52
53          VOID timestamp(STRING s)
54
55          BOOL syntax(REAL)
56
57          STRING getenv(STRING name)
58
59          BOOL cache_req_body(BYTES size)
60
61          VOID late_100_continue(BOOL late)
62
63          VOID set_ip_tos(INT tos)
64
65          VOID rollback(HTTP h)
66
67          INT real2integer(REAL r, INT fallback)
68
69          TIME real2time(REAL r, TIME fallback)
70
71          INT time2integer(TIME t, INT fallback)
72
73          REAL time2real(TIME t, REAL fallback)
74

DESCRIPTION

76       vmod_std contains basic functions which are part and parcel of Varnish,
77       but which for reasons of architecture fit better in a VMOD.
78

NUMERIC FUNCTIONS

80   REAL random(REAL lo, REAL hi)
81       Returns a random real number between lo and hi.
82
83       This function uses the "testable" random generator  in  varnishd  which
84       enables  determinstic  tests to be run (See m00002.vtc).  This function
85       should not be used for cryptographic applications.
86
87       Example:
88
89          set beresp.http.random-number = std.random(1, 100);
90
91   REAL round(REAL r)
92       Rounds the real r to the nearest integer, but round halfway cases  away
93       from zero (see round(3)).
94

STRING FUNCTIONS

96   VOID collect(HEADER hdr, STRING sep=", )
97       Collapses  multiple hdr headers into one long header. The default sepa‐
98       rator sep is the standard comma separator to use when collapsing  head‐
99       ers, with an additional whitespace for pretty printing.
100
101       Care  should be taken when collapsing headers. In particular collapsing
102       Set-Cookie will lead to unexpected results on the browser side.
103
104       Examples:
105
106          std.collect(req.http.accept);
107          std.collect(req.http.cookie, "; ");
108
109   STRING querysort(STRING)
110       Sorts the query string for cache normalization purposes.
111
112       Example:
113
114          set req.url = std.querysort(req.url);
115
116   STRING toupper(STRING s)
117       Converts the string s to uppercase.
118
119       Example:
120
121          set beresp.http.scream = std.toupper("yes!");
122
123   STRING tolower(STRING s)
124       Converts the string s to lowercase.
125
126       Example:
127
128          set beresp.http.nice = std.tolower("VerY");
129
130   STRING strstr(STRING s1, STRING s2)
131       Returns a string beginning at the first occurrence of the string s2  in
132       the string s1, or an empty string if s2 is not found.
133
134       Note that the comparison is case sensitive.
135
136       Example:
137
138          if (std.strstr(req.url, req.http.restrict)) {
139                  ...
140          }
141
142       This  will check if the content of req.http.restrict occurs anywhere in
143       req.url.
144
145   BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname, BOOL  noescape,
146       BOOL period)
147          BOOL fnmatch(
148             STRING pattern,
149             STRING subject,
150             BOOL pathname=1,
151             BOOL noescape=0,
152             BOOL period=0
153          )
154
155       Shell-style  pattern matching; returns true if subject matches pattern,
156       where pattern may contain wildcard characters such as * or ?.
157
158       The match is executed by the implementation of fnmatch(3) on your  sys‐
159       tem. The rules for pattern matching on most systems include the follow‐
160       ing:
161
162       • * matches any sequence of characters
163
164       • ? matches a single character
165
166       • a bracket expression such as [abc] or  [!0-9]  is  interpreted  as  a
167         character  class  according to the rules of basic regular expressions
168         (not pcre(3) regexen), except that !  is  used  for  character  class
169         negation instead of ^.
170
171       If pathname is true, then the forward slash character / is only matched
172       literally, and never matches *, ? or a bracket expression. Otherwise, /
173       may match one of those patterns.  By default, pathname is true.
174
175       If  noescape  is  true, then the backslash character \ is matched as an
176       ordinary character. Otherwise, \ is an escape  character,  and  matches
177       the character that follows it in the pattern. For example, \\ matches \
178       when noescape is true, and \\  when  false.  By  default,  noescape  is
179       false.
180
181       If  period is true, then a leading period character . only matches lit‐
182       erally, and never matches *, ? or a bracket  expression.  A  period  is
183       leading  if  it  is the first character in subject; if pathname is also
184       true, then a period that immediately follows a / is also leading (as in
185       /.).  By default, period is false.
186
187       std.fnmatch()  invokes  VCL failure and returns false if either of pat‐
188       tern or subject is NULL -- for example, if an unset  header  is  speci‐
189       fied.
190
191       Examples:
192
193          # Matches URLs such as /foo/bar and /foo/baz
194          if (std.fnmatch("/foo/\*", req.url)) { ... }
195
196          # Matches URLs such as /foo/bar/baz and /foo/baz/quux
197          if (std.fnmatch("/foo/\*/\*", bereq.url)) { ... }
198
199          # Matches /foo/bar/quux, but not /foo/bar/baz/quux
200          if (std.fnmatch("/foo/\*/quux", req.url)) { ... }
201
202          # Matches /foo/bar/quux and /foo/bar/baz/quux
203          if (std.fnmatch("/foo/\*/quux", req.url, pathname=false)) { ... }
204
205          # Matches /foo/bar, /foo/car and /foo/far
206          if (std.fnmatch("/foo/?ar", req.url)) { ... }
207
208          # Matches /foo/ followed by a non-digit
209          if (std.fnmatch("/foo/[!0-9]", req.url)) { ... }
210

FILE(SYSTEM) FUNCTIONS

212   STRING fileread(STRING)
213       Reads a text file and returns a string with the content.
214
215       The  entire file is cached on the first call, and subsequent calls will
216       return this cached contents, even if the file has changed in the  mean‐
217       time.
218
219       For binary files, use std.blobread() instead.
220
221       Example:
222
223          synthetic("Response was served by " + std.fileread("/etc/hostname"));
224
225       Consider that the entire contents of the file appear in the string that
226       is returned, including newlines that may result in invalid  headers  if
227       std.fileread()  is used to form a header. In that case, you may need to
228       modify the string, for example with regsub() (see vcl(7)):
229
230          set beresp.http.served-by = regsub(std.fileread("/etc/hostname"), "\R$", "");
231
232   BLOB blobread(STRING)
233       Reads any file and returns a blob with the content.
234
235       The entire file is cached on the first call, and subsequent calls  will
236       return  this cached contents, even if the file has changed in the mean‐
237       time.
238
239   BOOL file_exists(STRING path)
240       Returns true if path or the file pointed to by path exists, false  oth‐
241       erwise.
242
243       Example:
244
245          if (std.file_exists("/etc/return_503")) {
246                  return (synth(503, "Varnish is in maintenance"));
247          }
248

TYPE INSPECTION FUNCTIONS

250   BOOL healthy(BACKEND be)
251       Returns true if the backend be is healthy.
252
253   INT port(IP ip)
254       Returns  the  port  number of the IP address ip. Always returns 0 for a
255       *.ip variable when the address is a Unix domain socket.
256

TYPE CONVERSION FUNCTIONS

258       These functions all have the same form:
259
260          TYPE type([arguments], [fallback TYPE])
261
262       Precisely one of the arguments must be provided (besides  the  optional
263       fallback), and it will be converted to TYPE.
264
265       If  conversion  fails, fallback will be returned and if no fallback was
266       specified, the VCL will be failed.
267
268   DURATION duration([STRING s], [DURATION fallback], [REAL real], [INT  inte‐
269       ger])
270          DURATION duration(
271             [STRING s],
272             [DURATION fallback],
273             [REAL real],
274             [INT integer]
275          )
276
277       Returns a DURATION from a STRING, REAL or INT argument.
278
279       For  a  STRING s argument, s must be quantified by ms (milliseconds), s
280       (seconds), m (minutes), h (hours),``d`` (days), w (weeks) or y  (years)
281       units.
282
283       real and integer arguments are taken as seconds.
284
285       If  the conversion of an s argument fails, fallback will be returned if
286       provided, or a VCL failure will be triggered.
287
288       Conversions from real and integer arguments never fail.
289
290       Only one of the s, real or integer arguments may  be  given  or  a  VCL
291       failure will be triggered.
292
293       Examples::
294              set  beresp.ttl  =  std.duration("1w",  3600s); set beresp.ttl =
295              std.duration(real=1.5);  set  beresp.ttl  =   std.duration(inte‐
296              ger=10);
297
298   BYTES bytes([STRING s], [BYTES fallback], [REAL real], [INT integer])
299          BYTES bytes(
300             [STRING s],
301             [BYTES fallback],
302             [REAL real],
303             [INT integer]
304          )
305
306       Returns BYTES from a STRING, REAL or INT argument.
307
308       A  STRING  s  argument can be quantified with a multiplier (k (kilo), m
309       (mega), g (giga), t (tera) or p (peta)).
310
311       real and integer arguments are taken as bytes.
312
313       If the conversion of an s argument fails, fallback will be returned  if
314       provided, or a VCL failure will be triggered.
315
316       Other  conversions may fail if the argument can not be represented, be‐
317       cause it is negative, too small or too large. Again, fallback  will  be
318       returned if provided, or a VCL failure will be triggered.
319
320       real arguments will be rounded down.
321
322       Only  one  of  the  s,  real or integer arguments may be given or a VCL
323       failure will be triggered.
324
325       Example::
326              std.cache_req_body(std.bytes(something.somewhere,         10K));
327              std.cache_req_body(std.bytes(integer=10*1024));
328              std.cache_req_body(std.bytes(real=10.0*1024));
329
330   INT integer([STRING s], [INT fallback], [BOOL bool], [BYTES bytes],  [DURA‐
331       TION duration], [REAL real], [TIME time])
332          INT integer(
333             [STRING s],
334             [INT fallback],
335             [BOOL bool],
336             [BYTES bytes],
337             [DURATION duration],
338             [REAL real],
339             [TIME time]
340          )
341
342       Returns an INT from a STRING, BOOL or other quantity.
343
344       If  the conversion of an s argument fails, fallback will be returned if
345       provided, or a VCL failure will be triggered.
346
347       A bool argument will be returned as 0 for false and 1  for  true.  This
348       conversion will never fail.
349
350       For  a bytes argument, the number of bytes will be returned.  This con‐
351       version will never fail.
352
353       A duration argument will be rounded down to the number of  seconds  and
354       returned.
355
356       A real argument will be rounded down and returned.
357
358       For  a  time  argument,  the  number  of  seconds  since the UNIX epoch
359       (1970-01-01 00:00:00 UTC) will be returned.
360
361       duration, real and time conversions may fail if the argument can not be
362       represented  because it is too small or too large. If so, fallback will
363       be returned if provided, or a VCL failure will be triggered.
364
365       Only one of the s, bool, bytes, duration, real or time arguments may be
366       given or a VCL failure will be triggered.
367
368       Examples:
369
370          if (std.integer(req.http.foo, 0) > 5) {
371                  ...
372          }
373
374          set resp.http.answer = std.integer(real=126.42/3);
375
376   IP ip(STRING s, [IP fallback], BOOL resolve=1, [STRING p])
377       Converts the string s to the first IP number returned by the system li‐
378       brary function getaddrinfo(3). If conversion fails,  fallback  will  be
379       returned or VCL failure will happen.
380
381       The IP address includes a port number that can be found with std.port()
382       that defaults to 80. The default port can be set to a  different  value
383       with  the p argument. It will be overriden if s contains both an IP ad‐
384       dress and a port number or service name.
385
386       When s contains both, the syntax  is  either  address:port  or  address
387       port.  If  the  address is a numerical IPv6 address it must be enclosed
388       between brackets, for example [::1] 80 or [::1]:http.  The fallback may
389       also contain both an address and a port, but its default port is always
390       80.
391
392       If resolve is false, getaddrinfo(3) is called using AI_NUMERICHOST  and
393       AI_NUMERICSERV  to  avoid  network  lookups  depending  on the system's
394       getaddrinfo(3) or nsswitch configuration.  This  makes  "numerical"  IP
395       strings and services cheaper to convert.
396
397       Example:
398
399          if (std.ip(req.http.X-forwarded-for, "0.0.0.0") ~ my_acl) {
400                  ...
401          }
402
403   REAL  real([STRING  s], [REAL fallback], [INT integer], [BOOL bool], [BYTES
404       bytes], [DURATION duration], [TIME time])
405          REAL real(
406             [STRING s],
407             [REAL fallback],
408             [INT integer],
409             [BOOL bool],
410             [BYTES bytes],
411             [DURATION duration],
412             [TIME time]
413          )
414
415       Returns a REAL from a STRING, BOOL or other quantity.
416
417       If the conversion of an s argument fails, fallback will be returned  if
418       provided, or a VCL failure will be triggered.
419
420       A bool argument will be returned as 0.0 for false and 1.0 for true.
421
422       For a bytes argument, the number of bytes will be returned.
423
424       For a duration argument, the number of seconds will be returned.
425
426       An integer argument will be returned as a REAL.
427
428       For  a  time  argument,  the  number  of  seconds  since the UNIX epoch
429       (1970-01-01 00:00:00 UTC) will be returned.
430
431       None of these conversions other than s will fail.
432
433       Only one of the s, integer, bool, bytes, duration or time arguments may
434       be given or a VCL failure will be triggered.
435
436       Example:
437
438          if (std.real(req.http.foo, 0.0) > 5.5) {
439                  ...
440          }
441
442   TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])
443          TIME time([STRING s], [TIME fallback], [REAL real], [INT integer])
444
445       Returns a TIME from a STRING, REAL or INT argument.
446
447       For a STRING s argument, the following formats are supported:
448
449          "Sun, 06 Nov 1994 08:49:37 GMT"
450          "Sunday, 06-Nov-94 08:49:37 GMT"
451          "Sun Nov  6 08:49:37 1994"
452          "1994-11-06T08:49:37"
453          "784111777.00"
454          "784111777"
455
456       real and integer arguments are taken as seconds since the epoch.
457
458       If  the conversion of an s argument fails or a negative real or integer
459       argument is given, fallback will be returned  if  provided,  or  a  VCL
460       failure will be triggered.
461
462       Examples:
463
464          if (std.time(resp.http.last-modified, now) < now - 1w) {
465                  ...
466          }
467
468          if (std.time(int=2147483647) < now - 1w) {
469                  ...
470          }
471

LOGGING FUNCTIONS

473   VOID log(STRING s)
474       Logs  the  string  s  to  the  shared  memory  log,  using  vsl(7)  tag
475       SLT_VCL_Log.
476
477       Example:
478
479          std.log("Something fishy is going on with the vhost " + req.http.host);
480
481   VOID syslog(INT priority, STRING s)
482       Logs the string s to syslog tagged with priority. priority is formed by
483       ORing  the  facility  and level values. See your system's syslog.h file
484       for possible values.
485
486       Notice: Unlike VCL and other functions in the std vmod,  this  function
487       will  not  fail  VCL  processing for workspace overflows: For an out of
488       workspace condition, the std.syslog() function has no effect.
489
490       Example:
491
492          std.syslog(9, "Something is wrong");
493
494       This will send a message to syslog using LOG_USER | LOG_ALERT.
495
496   VOID timestamp(STRING s)
497       Introduces a timestamp in the log with  the  current  time,  using  the
498       string  s as the label. This is useful to time the execution of lengthy
499       VCL subroutines, and makes the  timestamps  inserted  automatically  by
500       Varnish more accurate.
501
502       Example:
503
504          std.timestamp("curl-request");
505

CONTROL AND INFORMATION FUNCTIONS

507   BOOL syntax(REAL)
508       Returns true if VCL version is at least REAL.
509
510   STRING getenv(STRING name)
511       Return environment variable name or the empty string. See getenv(3).
512
513       Example:
514
515          set req.http.My-Env = std.getenv("MY_ENV");
516
517   BOOL cache_req_body(BYTES size)
518       Caches  the  request  body if it is smaller than size.  Returns true if
519       the body was cached, false otherwise.
520
521       Normally the request body can only be sent  once.  Caching  it  enables
522       retrying backend requests with a request body, as usually the case with
523       POST and PUT.
524
525       Example:
526
527          if (std.cache_req_body(1KB)) {
528                  ...
529          }
530
531   VOID late_100_continue(BOOL late)
532       Controls when varnish reacts to an Expect: 100-continue client  request
533       header.
534
535       Varnish  always  generates  a 100 Continue response if requested by the
536       client trough the Expect: 100-continue header when waiting for  request
537       body data.
538
539       But, by default, the 100 Continue response is already generated immedi‐
540       ately after vcl_recv returns to reduce latencies under  the  assumption
541       that the request body will be read eventually.
542
543       Calling std.late_100_continue(true) in vcl_recv will cause the 100 Con‐
544       tinue response to only be sent when needed. This may  cause  additional
545       latencies for processing request bodies, but is the correct behavior by
546       strict interpretation of RFC7231.
547
548       This  function  has  no  effect  outside  vcl_recv  and  after  calling
549       std.cache_req_body() or any other function consuming the request body.
550
551       Example:
552
553          vcl_recv {
554                  std.late_100_continue(true);
555
556                  if (req.method == "POST") {
557                          std.late_100_continue(false);
558                          return (pass);
559                  }
560                  ...
561           }
562
563   VOID set_ip_tos(INT tos)
564       Sets the IP type-of-service (TOS) field for the current session to tos.
565       Silently ignored if the listen address is a Unix domain socket.
566
567       Please note that the TOS field is not removed by the end of the request
568       so probably want to set it on every request should you utilize it.
569
570       Example:
571
572          if (req.url ~ "^/slow/") {
573                  std.set_ip_tos(0);
574          }
575
576   VOID rollback(HTTP h)
577       Restores the h HTTP headers to their original state.
578
579       Example:
580
581          std.rollback(bereq);
582

DEPRECATED FUNCTIONS

584   INT real2integer(REAL r, INT fallback)
585       DEPRECATED:  This  function will be removed in a future version of var‐
586       nish, use std.integer() with a real argument and the std.round()  func‐
587       tion instead, for example:
588
589          std.integer(real=std.round(...), fallback=...)
590
591       Rounds  the real r to the nearest integer, but round halfway cases away
592       from zero (see round(3)). If conversion fails,  fallback  will  be  re‐
593       turned.
594
595       Examples:
596
597          set req.http.integer = std.real2integer(1140618699.00, 0);
598          set req.http.posone = real2integer( 0.5, 0);    # =  1.0
599          set req.http.negone = real2integer(-0.5, 0);    # = -1.0
600
601   TIME real2time(REAL r, TIME fallback)
602       DEPRECATED:  This  function will be removed in a future version of var‐
603       nish, use std.time() with a real argument and the std.round()  function
604       instead, for example:
605
606          std.time(real=std.round(...), fallback=...)
607
608       Rounds  the  real r to the nearest integer (see std.real2integer()) and
609       returns the corresponding time when interpreted as  a  unix  epoch.  If
610       conversion fails, fallback will be returned.
611
612       Example:
613
614          set req.http.time = std.real2time(1140618699.00, now);
615
616   INT time2integer(TIME t, INT fallback)
617       DEPRECATED:  This  function will be removed in a future version of var‐
618       nish, use std.integer() with a time argument instead, for example:
619
620          std.integer(time=..., fallback=...)
621
622       Converts the time t to a integer. If conversion fails, fallback will be
623       returned.
624
625       Example:
626
627          set req.http.int = std.time2integer(now, 0);
628
629   REAL time2real(TIME t, REAL fallback)
630       DEPRECATED:  This  function will be removed in a future version of var‐
631       nish, use std.real() with a time argument instead, for example:
632
633          std.real(time=..., fallback=...)
634
635       Converts the time t to a real. If conversion fails,  fallback  will  be
636       returned.
637
638       Example:
639
640          set req.http.real = std.time2real(now, 1.0);
641

COPYRIGHT

650          Copyright (c) 2010-2017 Varnish Software AS
651          All rights reserved.
652
653          Author: Poul-Henning Kamp <phk@FreeBSD.org>
654
655          SPDX-License-Identifier: BSD-2-Clause
656
657          Redistribution and use in source and binary forms, with or without
658          modification, are permitted provided that the following conditions
659          are met:
660          1. Redistributions of source code must retain the above copyright
661             notice, this list of conditions and the following disclaimer.
662          2. Redistributions in binary form must reproduce the above copyright
663             notice, this list of conditions and the following disclaimer in the
664             documentation and/or other materials provided with the distribution.
665
666          THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
667          ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
668          IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
669          ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
670          FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
671          DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
672          OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
673          HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
674          LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
675          OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
676          SUCH DAMAGE.
677
678
679
680
681                                                                   VMOD_STD(3)