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

• 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 set_ip_tos(INT)
• VOID syslog(INT, STRING_LIST)
• INT time2integer(TIME)
• REAL time2real(TIME)
• VOID timestamp(STRING)
• STRING tolower(STRING_LIST)
• STRING toupper(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!”);

STRING tolower(STRING_LIST)

Prototype

STRING tolower(STRING_LIST)

Description

Converts the string s to lower case.

Example

set beresp.http.x-nice = std.tolower(“VerY”);

VOID set_ip_tos(INT)

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

}

REAL random(REAL, REAL)

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

VOID log(STRING_LIST)

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

VOID syslog(INT, STRING_LIST)

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

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.x-served-by = std.fileread(“/etc/hostname”);

VOID collect(HEADER)

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.

DURATION duration(STRING, DURATION)

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

INT integer(STRING, INT)

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

IP ip(STRING, IP)

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

REAL real(STRING, REAL)

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

TIME real2time(REAL)

Prototype

TIME real2time(REAL)

Description

Converts the real r to a time.

Example

set req.http.x-time = std.real2time(1140618699.00);

INT time2integer(TIME)

Prototype

INT time2integer(TIME)

Description

Converts the time t to a integer.

Example

set req.http.x-int = std.time2integer(now);

REAL time2real(TIME)

Prototype

REAL time2real(TIME)

Description

Converts the time t to a real.

Example

set req.http.x-real = std.time2real(now);

BOOL healthy(BACKEND)

Prototype

BOOL healthy(BACKEND)

Description

Returns true if the backend is healthy.

INT port(IP)

Prototype

INT port(IP)

Description

Returns the port number of an IP address.

VOID timestamp(STRING)

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

STRING querysort(STRING)

Prototype

STRING querysort(STRING)

Description

Sorts the querystring for cache normalization purposes.

Example

set req.url = std.querysort(req.url);

SEE ALSO

• vcl(7)
• varnishd(1)

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.