vmod_std(3)

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

NAME

6       vmod_std - Varnish Standard Module
7

SYNOPSIS

9          import std [from "path"] ;
10
11          STRING toupper(STRING s)
12
13          STRING tolower(STRING s)
14
15          VOID set_ip_tos(INT tos)
16
17          REAL random(REAL lo, REAL hi)
18
19          VOID log(STRING s)
20
21          VOID syslog(INT priority, STRING s)
22
23          STRING fileread(STRING)
24
25          BOOL file_exists(STRING path)
26
27          VOID collect(HEADER hdr, STRING sep)
28
29          DURATION duration(STRING s, DURATION fallback)
30
31          INT integer(STRING s, INT fallback)
32
33          IP ip(STRING s, IP fallback, BOOL resolve)
34
35          REAL real(STRING s, REAL fallback)
36
37          INT real2integer(REAL r, INT fallback)
38
39          TIME real2time(REAL r, TIME fallback)
40
41          INT time2integer(TIME t, INT fallback)
42
43          REAL time2real(TIME t, REAL fallback)
44
45          BOOL healthy(BACKEND be)
46
47          INT port(IP ip)
48
49          VOID rollback(HTTP h)
50
51          VOID timestamp(STRING s)
52
53          STRING querysort(STRING)
54
55          BOOL cache_req_body(BYTES size)
56
57          STRING strstr(STRING s1, STRING s2)
58
59          TIME time(STRING s, TIME fallback)
60
61          STRING getenv(STRING name)
62
63          VOID late_100_continue(BOOL late)
64
65          BOOL syntax(REAL)
66
67          BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname, BOOL noescape, BOOL period)
68

DESCRIPTION

70       vmod_std contains basic functions which are part and parcel of Varnish,
71       but which for reasons of architecture fit better in a VMOD.
72
73       One particular class of functions in vmod_std is the conversions  func‐
74       tions which all have the form:
75
76          TYPE type(STRING, TYPE)
77
78       These  functions  attempt  to  convert  STRING to the TYPE, and if that
79       fails, they return the second argument, which must have the given TYPE.
80
81   STRING toupper(STRING s)
82       Description
83              Converts the string s to uppercase.
84
85       Example
86              set beresp.http.scream = std.toupper("yes!");
87
88   STRING tolower(STRING s)
89       Description
90              Converts the string s to lowercase.
91
92       Example
93              set beresp.http.nice = std.tolower("VerY");
94
95   VOID set_ip_tos(INT tos)
96       Description
97              Sets the IP type-of-service (TOS) field for the current  session
98              to  tos. Silently ignored if the listen address is a Unix domain
99              socket.  Please note that the TOS field is not  removed  by  the
100              end  of  the request so probably want to set it on every request
101              should you utilize it.
102
103       Example
104              if (req.url ~ "^/slow/") {
105                std.set_ip_tos(0);
106              }
107
108
109   REAL random(REAL lo, REAL hi)
110       Description
111              Returns a random real number between lo and hi.   This  function
112              uses  the  "testable" random generator in varnishd which enables
113              determinstic tests to be run (See  m00002.vtc).   This  function
114              should not be used for cryptographic applications.
115
116       Example
117              set beresp.http.random-number = std.random(1, 100);
118
119   VOID log(STRING s)
120       Description
121              Logs  the  string  s  to  the  shared  memory log, using VSL tag
122              SLT_VCL_Log.
123
124       Example
125              std.log("Something  fishy  is  going  on  with  the  vhost  "  +
126              req.http.host);
127
128   VOID syslog(INT priority, STRING s)
129       Description
130              Logs  the  string  s to syslog tagged with priority. priority is
131              formed by ORing the facility and level values. See your system's
132              syslog.h file for possible values.
133
134              Notice:  Unlike  VCL  and  other functions in the std vmod, this
135              function will not fail VCL processing for  workspace  overflows:
136              For  an out of workspace condition, the syslog() function has no
137              effect.
138
139       Example
140              std.syslog(9, "Something is wrong");
141
142              This will send a message to syslog using LOG_USER | LOG_ALERT.
143
144   STRING fileread(STRING)
145       Description
146              Reads a file and returns a string with the content.  The  result
147              is cached indefinitely per filename.
148
149       Example
150              synthetic("Response  was  served by " + std.fileread("/etc/host‐
151              name"));
152
153       Consider that the entire contents of the file appear in the string that
154       is  returned,  including newlines that may result in invalid headers if
155       std.fileread() is used to form a header. In that case, you may need  to
156       modify the string, for example with regsub():
157
158          set beresp.http.served-by = regsub(std.fileread("/etc/hostname"), "\R$", "");
159
160   BOOL file_exists(STRING path)
161       Description
162              Returns  true  if  path  or  the file pointed to by path exists,
163              false otherwise.
164
165       Example
166              if (std.file_exists("/etc/return_503")) {
167                return (synth(503, "Varnish is in maintenance"));
168              }
169
170
171   VOID collect(HEADER hdr, STRING sep=", )
172       Description
173              Collapses multiple hdr headers into one long header. The default
174              separator  sep  is the standard comma separator to use when col‐
175              lapsing headers,  with  an  additional   whitespace  for  pretty
176              printing.
177
178              Care should be taken when collapsing headers. In particular col‐
179              lapsing Set-Cookie  will  lead  to  unexpected  results  on  the
180              browser side.
181
182       Examples
183              std.collect(req.http.accept);
184              std.collect(req.http.cookie, "; ");
185
186
187   DURATION duration(STRING s, DURATION fallback)
188       Description
189              Converts  the  string s to seconds. s must be quantified with ms
190              (milliseconds), s (seconds), m (minutes), h (hours), d (days), w
191              (weeks)  or  y (years) units. If conversion fails, fallback will
192              be returned.
193
194       Example
195              set beresp.ttl = std.duration("1w", 3600s);
196
197   INT integer(STRING s, INT fallback)
198       Description
199              Converts the string s to an integer. If conversion fails,  fall‐
200              back will be returned.
201
202       Example
203              if (std.integer(req.http.foo, 0) > 5) {
204                ...
205              }
206
207
208   IP ip(STRING s, IP fallback, BOOL resolve=1)
209       Description
210              Converts  the  string  s  to the first IP number returned by the
211              system library function  getaddrinfo(3).  If  conversion  fails,
212              fallback will be returned.
213
214              If  resolve  is  false, getaddrinfo() is called using AI_NUMERI‐
215              CHOST to avoid network lookups. This  makes  "pure"  IP  strings
216              cheaper to convert.
217
218       Example
219              if (std.ip(req.http.X-forwarded-for, "0.0.0.0") ~ my_acl) {
220                ...
221              }
222
223
224   REAL real(STRING s, REAL fallback)
225       Description
226              Converts  the  string s to a real. If conversion fails, fallback
227              will be returned.
228
229       Example
230              if (std.real(req.http.foo, 0.0) > 5.5) {
231                ...
232              }
233
234
235   INT real2integer(REAL r, INT fallback)
236       Description
237              Rounds the real r to the  nearest  integer,  but  round  halfway
238              cases  away from zero (see round(3)). If conversion fails, fall‐
239              back will be returned.
240
241       Example
242              set req.http.integer = std.real2integer(1140618699.00,  0);  set
243              req.http.posone  =  real2integer(  0.5,  0);     #  =   1.0  set
244              req.http.negone = real2integer(-0.5, 0);    # = -1.0
245
246   TIME real2time(REAL r, TIME fallback)
247       Description
248              Rounds the real r to the nearest integer (see func_real2integer)
249              and  returns  the  corresponding time when interpreted as a unix
250              epoch. If conversion fails, fallback will be returned.
251
252       Example
253              set req.http.time = std.real2time(1140618699.00, now);
254
255   INT time2integer(TIME t, INT fallback)
256       Description
257              Converts the time t to a integer. If conversion fails,  fallback
258              will be returned.
259
260       Example
261              set req.http.int = std.time2integer(now, 0);
262
263   REAL time2real(TIME t, REAL fallback)
264       Description
265              Converts  the  time  t  to a real. If conversion fails, fallback
266              will be returned.
267
268       Example
269              set req.http.real = std.time2real(now, 1.0);
270
271   BOOL healthy(BACKEND be)
272       Description
273              Returns true if the backend be is healthy.
274
275   INT port(IP ip)
276       Description
277              Returns the port number of the IP address ip. Always  returns  0
278              for  a  *.ip  variable whose value is 0.0.0.0 because the listen
279              address is a Unix domain socket.
280
281   VOID rollback(HTTP h)
282       Description
283              Restores the h HTTP headers to their original state.
284
285       Example
286              std.rollback(bereq);
287
288   VOID timestamp(STRING s)
289       Description
290              Introduces a timestamp in the log with the current  time,  using
291              the  string s as the label. This is useful to time the execution
292              of lengthy VCL procedures, and  makes  the  timestamps  inserted
293              automatically by Varnish more accurate.
294
295       Example
296              std.timestamp("curl-request");
297
298   STRING querysort(STRING)
299       Description
300              Sorts the query string for cache normalization purposes.
301
302       Example
303              set req.url = std.querysort(req.url);
304
305   BOOL cache_req_body(BYTES size)
306       Description
307              Caches  the  request  body  if it is smaller than size.  Returns
308              true if the body was cached, false otherwise.
309
310              Normally the request body is not available after sending  it  to
311              the  backend.   By  caching  it is possible to retry pass opera‐
312              tions, e.g. POST and PUT.
313
314       Example
315              if (std.cache_req_body(1KB)) {
316                ...
317              }
318
319
320   STRING strstr(STRING s1, STRING s2)
321       Description
322              Returns a string beginning at the first occurrence of the string
323              s2 in the string s1, or an empty string if s2 is not found.
324
325              Note that the comparison is case sensitive.
326
327       Example
328              if (std.strstr(req.url, req.http.restrict)) {
329                ...
330              }
331
332
333              This  will check if the content of req.http.restrict occurs any‐
334              where in req.url.
335
336   TIME time(STRING s, TIME fallback)
337       Description
338              Converts the string s to a time. If conversion  fails,  fallback
339              will be returned.
340
341              Supported formats:
342              "Sun, 06 Nov 1994 08:49:37 GMT"
343              "Sunday, 06-Nov-94 08:49:37 GMT"
344              "Sun Nov  6 08:49:37 1994"
345              "1994-11-06T08:49:37"
346              "784111777.00"
347              "784111777"
348
349
350       Example
351              if (std.time(resp.http.last-modified, now) < now - 1w) {
352                ...
353              }
354
355
356   STRING getenv(STRING name)
357       Description
358              Return environment variable name or the empty string.
359
360              See getenv(3)
361
362       Example
363              set req.http.My-Env = std.getenv("MY_ENV");
364
365
366   VOID late_100_continue(BOOL late)
367       Description
368              Controls  when  varnish reacts to an Expect: 100-continue client
369              request header.
370
371              Varnish always generates a 100 Continue response if requested by
372              the  client  trough the Expect: 100-continue header when waiting
373              for request body data.
374
375              But, by default, the 100 Continue response is already  generated
376              immediately after vcl_recv returns to reduce latencies under the
377              assumption that the request body will be read eventually.
378
379              Calling std.late_100_continue(true) in vcl_recv will  cause  the
380              100  Continue  response  to  only  be sent when needed. This may
381              cause additional latencies for processing request bodies, but is
382              the correct behavior by strict interpretation of RFC7231.
383
384              This  function  has no effect outside vcl_recv and after calling
385              std.cache_req_body() or any other function consuming the request
386              body.
387
388       Example
389              vcl_recv {
390                std.late_100_continue(true);
391
392                if (req.method == "POST") {
393                  std.late_100_continue(false);
394                  return (pass);
395                }
396                ...
397              }
398
399
400   BOOL syntax(REAL)
401       Description
402              Returns the true if VCL version is at least REAL.
403
404   fnmatch(...)
405          BOOL fnmatch(
406             STRING pattern,
407             STRING subject,
408             BOOL pathname=1,
409             BOOL noescape=0,
410             BOOL period=0
411          )
412
413       Description
414              Shell-style  pattern  matching;  returns true if subject matches
415              pattern, where pattern may contain wildcard characters such as *
416              or ?.
417
418              The  match  is  executed  by the implementation of fnmatch(3) on
419              your system. The rules for  pattern  matching  on  most  systems
420              include the following:
421
422              · * matches any sequence of characters
423
424              · ? matches a single character
425
426              · a bracket expression such as [abc] or [!0-9] is interpreted as
427                a character class according to  the  rules  of  basic  regular
428                expressions  (not  PCRE  regexen),  except  that ! is used for
429                character class negation instead of ^.
430
431              If pathname is true, then the forward slash character / is  only
432              matched  literally,  and never matches *, ? or a bracket expres‐
433              sion. Otherwise, / may match one of those patterns.  By default,
434              pathname is true.
435
436              If  noescape  is true, then the backslash character \ is matched
437              as an ordinary character. Otherwise, \ is an  escape  character,
438              and  matches  the  character that follows it in the pattern. For
439              example, \\ matches \ when noescape is true, and \\ when  false.
440              By default, noescape is false.
441
442              If  period  is  true,  then  a  leading  period character . only
443              matches literally, and never matches *, ? or a  bracket  expres‐
444              sion.  A  period is leading if it is the first character in sub‐
445              ject; if pathname is also true, then a period  that  immediately
446              follows a / is also leading (as in "/.").  By default, period is
447              false.
448
449              fnmatch() invokes VCL failure and returns  false  if  either  of
450              pattern or subject is NULL -- for example, if an unset header is
451              specified.
452
453       Examples
454              # Matches URLs such as /foo/bar and /foo/baz
455              if (std.fnmatch("/foo/*", req.url)) { ... }
456
457              # Matches URLs such as /foo/bar/baz and /foo/baz/quux
458              if (std.fnmatch("/foo/*/*", bereq.url)) { ... }
459
460              # Matches /foo/bar/quux, but not /foo/bar/baz/quux
461              if (std.fnmatch("/foo/*/quux", req.url)) { ... }
462
463              # Matches /foo/bar/quux and /foo/bar/baz/quux
464              if (std.fnmatch("/foo/*/quux", req.url, pathname=false)) { ... }
465
466              # Matches /foo/bar, /foo/car and /foo/far
467              if (std.fnmatch("/foo/?ar", req.url)) { ... }
468
469              # Matches /foo/ followed by a non-digit
470              if (std.fnmatch("/foo/[!0-9]", req.url)) { ... }
471
472

COPYRIGHT

481          Copyright (c) 2010-2017 Varnish Software AS
482          All rights reserved.
483
484          Author: Poul-Henning Kamp <phk@FreeBSD.org>
485
486          Redistribution and use in source and binary forms, with or without
487          modification, are permitted provided that the following conditions
488          are met:
489          1. Redistributions of source code must retain the above copyright
490             notice, this list of conditions and the following disclaimer.
491          2. Redistributions in binary form must reproduce the above copyright
492             notice, this list of conditions and the following disclaimer in the
493             documentation and/or other materials provided with the distribution.
494
495          THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
496          ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
497          IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
498          ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
499          FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
500          DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
501          OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
502          HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
503          LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
504          OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
505          SUCH DAMAGE.
506
507
508
509
510                                                                   VMOD_STD(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

COPYRIGHT