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          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

DESCRIPTION

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

NUMERIC FUNCTIONS

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

STRING FUNCTIONS

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

FILE(SYSTEM) FUNCTIONS

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       This function should not be used for reading binary files.
215
216       Example:
217
218          synthetic("Response was served by " + std.fileread("/etc/hostname"));
219
220       Consider that the entire contents of the file appear in the string that
221       is  returned,  including newlines that may result in invalid headers if
222       std.fileread() is used to form a header. In that case, you may need  to
223       modify the string, for example with regsub() (see vcl(7)):
224
225          set beresp.http.served-by = regsub(std.fileread("/etc/hostname"), "\R$", "");
226
227   BOOL file_exists(STRING path)
228       Returns  true if path or the file pointed to by path exists, false oth‐
229       erwise.
230
231       Example:
232
233          if (std.file_exists("/etc/return_503")) {
234                  return (synth(503, "Varnish is in maintenance"));
235          }
236

TYPE INSPECTION FUNCTIONS

238   BOOL healthy(BACKEND be)
239       Returns true if the backend be is healthy.
240
241   INT port(IP ip)
242       Returns the port number of the IP address ip. Always returns  0  for  a
243       *.ip variable when the address is a Unix domain socket.
244

TYPE CONVERSION FUNCTIONS

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

LOGGING FUNCTIONS

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

CONTROL AND INFORMATION FUNCTIONS

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

DEPRECATED FUNCTIONS

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

COPYRIGHT

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