VMOD_STD(3)VMOD_STD(3)NAMEvmod_std - Varnish Standard Module
SYNOPSIS
import std [from "path"] ;
DESCRIPTIONvmod_std contains basic functions which are part and parcel of Varnish,
but which for reasons of architecture fit better in a VMOD.
One particular class of functions in vmod_std is the conversions func‐
tions which all have the form:
TYPE type(STRING, TYPE)
These functions attempt to convert STRING to the TYPE, and if that
fails, they return the second argument, which must have the given TYPE.
CONTENTS
· VOID cache_req_body(BYTES)
· VOID collect(HEADER)
· DURATION duration(STRING, DURATION)
· STRING fileread(PRIV_CALL, STRING)
· BOOL healthy(BACKEND)
· INT integer(STRING, INT)
· IP ip(STRING, IP)
· VOID log(STRING_LIST)
· INT port(IP)
· STRING querysort(STRING)
· REAL random(REAL, REAL)
· REAL real(STRING, REAL)
· INT real2integer(REAL, INT)
· TIME real2time(REAL, TIME)
· VOID rollback(HTTP)
· VOID set_ip_tos(INT)
· STRING strstr(STRING, STRING)
· VOID syslog(INT, STRING_LIST)
· TIME time(STRING, TIME)
· INT time2integer(TIME, INT)
· REAL time2real(TIME, REAL)
· VOID timestamp(STRING)
· STRING tolower(STRING_LIST)
· STRING toupper(STRING_LIST)
STRING toupper(STRING_LIST)
Prototype
STRING toupper(STRING_LIST s)
Description
Converts the string s to uppercase.
Example
set beresp.http.scream = std.toupper("yes!");
STRING tolower(STRING_LIST)
Prototype
STRING tolower(STRING_LIST s)
Description
Converts the string s to lowercase.
Example
set beresp.http.nice = std.tolower("VerY");
VOID set_ip_tos(INT)
Prototype
VOID set_ip_tos(INT tos)
Description
Sets the IP type-of-service (TOS) field for the current session
to tos. Please note that the TOS field is not removed by the
end of the request so probably want to set it on every request
should you utilize it.
Example
if (req.url ~ "^/slow/") {
std.set_ip_tos(0);
}
REAL random(REAL, REAL)
Prototype
REAL random(REAL lo, REAL hi)
Description
Returns a random real number between lo and hi.
Example
set beresp.http.random-number = std.random(1, 100);
VOID log(STRING_LIST)
Prototype
VOID log(STRING_LIST s)
Description
Logs the string s to the shared memory log, using VSL tag
SLT_VCL_Log.
Example
std.log("Something fishy is going on with the vhost " +
req.http.host);
VOID syslog(INT, STRING_LIST)
Prototype
VOID syslog(INT priority, STRING_LIST s)
Description
Logs the string s to syslog tagged with priority. priority is
formed by ORing the facility and level values. See your system's
syslog.h file for possible values.
Example
std.syslog(9, "Something is wrong");
This will send a message to syslog using LOG_USER | LOG_ALERT.
STRING fileread(PRIV_CALL, STRING)
Prototype
STRING fileread(PRIV_CALL, STRING)
Description
Reads a file and returns a string with the content. Please note
that it is not recommended to send variables to this function
the caching in the function doesn't take this into account.
Also, files are not re-read.
Example
set beresp.http.served-by = std.fileread("/etc/hostname");
VOID collect(HEADER)
Prototype
VOID collect(HEADER hdr)
Description
Collapses multiple hdr headers into one long header.
Care should be taken when collapsing headers. In particular col‐
lapsing Set-Cookie will lead to unexpected results on the
browser side.
Example
std.collect(req.http.cookie);
DURATION duration(STRING, DURATION)
Prototype
DURATION duration(STRING s, DURATION fallback)
Description
Converts the string s to seconds. s must be quantified with ms
(milliseconds), s (seconds), m (minutes), h (hours), d (days), w
(weeks) or y (years) units. If conversion fails, fallback will
be returned.
Example
set beresp.ttl = std.duration("1w", 3600s);
INT integer(STRING, INT)
Prototype
INT integer(STRING s, INT fallback)
Description
Converts the string s to an integer. If conversion fails, fall‐
back will be returned.
Example
if (std.integer(req.http.foo, 0) > 5) {
}
IP ip(STRING, IP)
Prototype
IP ip(STRING s, IP fallback)
Description
Converts the string s to the first IP number returned by the
system library function getaddrinfo(3). If conversion fails,
fallback will be returned.
Example
if (std.ip(req.http.X-forwarded-for, "0.0.0.0") ~ my_acl) {
}
REAL real(STRING, REAL)
Prototype
REAL real(STRING s, REAL fallback)
Description
Converts the string s to a real. If conversion fails, fallback
will be returned.
Example
if (std.real(req.http.foo, 0.0) > 5.5) {
}
INT real2integer(REAL, INT)
Prototype
INT real2integer(REAL r, INT fallback)
Description
Converts the real r to an integer. If conversion fails, fallback
will be returned.
Example
set req.http.integer = std.real2integer(1140618699.00, 0);
TIME real2time(REAL, TIME)
Prototype
TIME real2time(REAL r, TIME fallback)
Description
Converts the real r to a time. If conversion fails, fallback
will be returned.
Example
set req.http.time = std.real2time(1140618699.00, now);
INT time2integer(TIME, INT)
Prototype
INT time2integer(TIME t, INT fallback)
Description
Converts the time t to a integer. If conversion fails, fallback
will be returned.
Example
set req.http.int = std.time2integer(now, 0);
REAL time2real(TIME, REAL)
Prototype
REAL time2real(TIME t, REAL fallback)
Description
Converts the time t to a real. If conversion fails, fallback
will be returned.
Example
set req.http.real = std.time2real(now, 1.0);
BOOL healthy(BACKEND)
Prototype
BOOL healthy(BACKEND be)
Description
Returns true if the backend be is healthy.
INT port(IP)
Prototype
INT port(IP ip)
Description
Returns the port number of the IP address ip.
VOID rollback(HTTP)
Prototype
VOID rollback(HTTP h)
Description
Restores the h HTTP headers to their original state.
Example
std.rollback(bereq);
VOID timestamp(STRING)
Prototype
VOID timestamp(STRING s)
Description
Introduces a timestamp in the log with the current time, using
the string s as the label. This is useful to time the execution
of lengthy VCL procedures, and makes the timestamps inserted
automatically by Varnish more accurate.
Example
std.timestamp("curl-request");
STRING querysort(STRING)
Prototype
STRING querysort(STRING)
Description
Sorts the query string for cache normalization purposes.
Example
set req.url = std.querysort(req.url);
VOID cache_req_body(BYTES)
Prototype
VOID cache_req_body(BYTES size)
Description
Cache the req.body if it is smaller than size.
Caching the req.body makes it possible to retry pass operations
(POST, PUT).
Example
std.cache_req_body(1KB);
This will cache the req.body if its size is smaller than 1KB.
STRING strstr(STRING, STRING)
Prototype
STRING strstr(STRING s1, STRING s2)
Description
Returns a string beginning at the first occurrence of the string
s2 in the string s1, or an empty string if s2 is not found.
Note that the comparison is case sensitive.
Example
if (std.strstr(req.url, req.http.restrict)) {
}
This will check if the content of req.http.restrict occurs any‐
where in req.url.
TIME time(STRING, TIME)
Prototype
TIME time(STRING s, TIME fallback)
Description
Converts the string s to a time. If conversion fails, fallback
will be returned.
Supported formats:
"Sun, 06 Nov 1994 08:49:37 GMT"
"Sunday, 06-Nov-94 08:49:37 GMT"
"Sun Nov 6 08:49:37 1994"
"1994-11-06T08:49:37"
"784111777.00"
"784111777"
Example
if (std.time(resp.http.last-modified, now) < now - 1w) {
}
SEE ALSO
· varnishd(1)
· vsl(7)HISTORY
The Varnish standard module was released along with Varnish Cache 3.0.
This manual page was written by Per Buer with help from Martin Blix
Grydeland.
COPYRIGHT
This document is licensed under the same licence as Varnish itself. See
LICENCE for details.
· Copyright (c) 2010-2015 Varnish Software AS
VMOD_STD(3)
