vmod_std man page

vmod_std — Varnish Standard Module

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)
·
STRING tolower(STRING)
·
VOID set_ip_tos(INT)
·
Real random(Real, Real)
·
VOID log(STRING)
·
VOID syslog(INT, STRING)
·
STRING fileread(PRIV_CALL, STRING)
·
VOID collect(HEADER)
·
Duration duration(STRING, Duration)
·
INT integer(STRING, INT)
·
IP ip(STRING, IP)
·
Real real(STRING, Real)
·
INT real2integer(Real, INT)
·
Time real2time(Real, Time)
·
INT time2integer(Time, INT)
·
Real time2real(Time, Real)
·
BOOL healthy(BACKEND)
·
INT port(IP)
·
VOID rollback(HTTP)
·
VOID timestamp(STRING)
·
STRING querysort(STRING)
·
BOOL cache_req_body(BYTES)
·
STRING strstr(STRING, STRING)
·
Time time(STRING, Time)

toupper

STRING toupper(STRING s)
Description
Converts the string s to uppercase.
Example
set beresp.http.scream = std.toupper("yes!");

tolower

STRING tolower(STRING s)
Description
Converts the string s to lowercase.
Example
set beresp.http.nice = std.tolower("VerY");

set_ip_tos

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

random

REAL random(REAL lo, REAL hi)
Description
Returns a random real number between lo and hi. This function uses the "testable" random generator in varnishd which enables determinstic tests to be run (See m00002.vtc). This function should not be used for cryptographic applications.
Example
set beresp.http.random-number = std.random(1, 100);

log

VOID log(STRING 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);

syslog

VOID syslog(INT priority, STRING 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.

fileread

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

collect

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

integer

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 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 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) {
...
}

real2integer

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

real2time

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

time2integer

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

time2real

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

healthy

BOOL healthy(BACKEND be)
Description
Returns true if the backend be is healthy.

port

INT port(IP ip)
Description
Returns the port number of the IP address ip.

rollback

VOID rollback(HTTP h)
Description
Restores the h HTTP headers to their original state.
Example
std.rollback(bereq);

timestamp

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

querysort

STRING querysort(STRING)
Description
Sorts the query string for cache normalization purposes.
Example
set req.url = std.querysort(req.url);

cache_req_body

BOOL cache_req_body(BYTES size)
Description
Caches the request body if it is smaller than size. Returns true if the body was cached, false otherwise.

Normally the request body is not available after sending it to the backend. By caching it is possible to retry pass operations, e.g. POST and PUT.
Example
if (std.cache_req_body(1KB)) {
...
}

strstr

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

Referenced By

vcl(7).