vmod_std

Varnish Standard Module

Manual section

3

SYNOPSIS

import std [from “path”] ;

DESCRIPTION

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.

CONTENTS

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”);

BOOL file_exists(STRING)

Prototype

BOOL file_exists(STRING path)

Description

Returns true if path or the file pointed to by path exists, false otherwise.

Example
if (std.file_exists(“/etc/return_503”)) {
return (synth(503, “Varnish is in maintenance”));
}

VOID collect(HEADER)

Prototype

VOID collect(HEADER hdr)

Description

Collapses multiple hdr headers into one long header. The header values are joined with a comma (“,”).

Care should be taken when collapsing headers. In particular collapsing 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, fallback 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 anywhere 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) {
…
}

STRING getenv(STRING)

Prototype

STRING getenv(STRING name)

Description

Return environment variable name or the empty string.

See getenv(3)

Example
set req.http.My-Env = std.getenv(“MY_ENV”);

SEE ALSO

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.