Varnish standard module
import std [from "path"] ;
Vmod_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 functions 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.
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)
TIME real2time(REAL)
VOID rollback(HTTP)
VOID set_ip_tos(INT)
STRING strstr(STRING, STRING)
VOID syslog(INT, STRING_LIST)
INT time2integer(TIME)
REAL time2real(TIME)
VOID timestamp(STRING)
STRING tolower(STRING_LIST)
STRING toupper(STRING_LIST)
Prototype
STRING toupper(STRING_LIST)
Description
Converts the string s to upper case.
Example
set beresp.http.x-scream = std.toupper("yes!");
Prototype
STRING tolower(STRING_LIST)
Description
Converts the string s to lower case.
Example
set beresp.http.x-nice = std.tolower("VerY");
Prototype
VOID set_ip_tos(INT)
Description
Sets the Type-of-Service flag for the current session. Please note that the TOS flag 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(0x0);
}
Prototype
REAL random(REAL, REAL)
Description
Returns a random REAL number between a and b.
Example
set beresp.http.x-random-number = std.random(1, 100);
Prototype
VOID log(STRING_LIST)
Description
Logs string to the shared memory log, using VSL tag SLT_VCL_Log.
Example
std.log("Something fishy is going on with the vhost " + req.host);
Prototype
VOID syslog(INT, STRING_LIST)
Description
Logs string to syslog marked with priority. See your system's syslog.h file for the legal values of priority.
Example
std.syslog(8 + 1, "Something is wrong");
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.x-served-by = std.fileread("/etc/hostname");
Prototype
VOID collect(HEADER)
Description
Collapses the header, joining the headers into one.
Example
std.collect(req.http.cookie); This will collapse several Cookie: headers into one, long cookie header.
Prototype
DURATION duration(STRING, DURATION)
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 s fails to parse, fallback will be returned.
Example
set beresp.ttl = std.duration("1w", 3600s);
Prototype
INT integer(STRING, INT)
Description
Converts the string s to an integer. If s fails to parse, fallback will be returned.
Example
if (std.integer(beresp.http.x-foo, 0) > 5) { ... }
Prototype
IP ip(STRING, IP)
Description
Converts 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) { ... }
Prototype
REAL real(STRING, REAL)
Description
Converts the string s to a real. If s fails to parse, fallback will be returned.
Example
set req.http.x-real = std.real(req.http.x-foo, 0.0);
Prototype
TIME real2time(REAL)
Description
Converts the real r to a time.
Example
set req.http.x-time = std.real2time(1140618699.00);
Prototype
INT time2integer(TIME)
Description
Converts the time t to a integer.
Example
set req.http.x-int = std.time2integer(now);
Prototype
REAL time2real(TIME)
Description
Converts the time t to a real.
Example
set req.http.x-real = std.time2real(now);
Prototype
BOOL healthy(BACKEND)
Description
Returns true if the backend is healthy.
Prototype
INT port(IP)
Description
Returns the port number of an IP address.
Prototype
VOID rollback(HTTP)
Description
Restore h HTTP headers to their original state.
Example
std.rollback(bereq);
Prototype
VOID timestamp(STRING)
Description
Introduces a timestamp in the log with the current time. Uses the argument as the timespamp 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");
Prototype
STRING querysort(STRING)
Description
Sorts the querystring for cache normalization purposes.
Example
set req.url = std.querysort(req.url);
Prototype
STRING strstr(STRING, STRING)
Description
Returns the substring if the second string is a substring of the first string. Note that the comparison is case sensitive. You can use the tolower function on both strings if you want case insensitivity.
If there is no match a NULL pointer is returned which would evaluate to false in an if-test.
Example
if (std.strstr(req.url, req.http.x-restrict))
vcl(7)
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.
This document is licensed under the same licence as Varnish itself. See LICENCE for details.