VMOD_STD(3)

NAME
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

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

•   TIME real2time(REAL)

•   VOID rollback(HTTP)

•   VOID set_ip_tos(INT)

•   STRING strstr(STRING, STRING)

•   VOID syslog(INT, STRING_LIST)

•   TIME time(STRING, TIME)

•   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 s)

Description
    Converts the string s to uppercase.

Example
    set beresp.http.x-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.x-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(0x0);
    }

  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.x-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.host);

  VOID syslog(INT, STRING_LIST)

Prototype
    VOID syslog(INT priority, STRING_LIST s)

Description
    Logs the string s 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 hdr)

Description
    Collapses the header hdr, joining them 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 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(beresp.http.x-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
    set req.http.x-real = std.real(req.http.x-foo, 0.0);

  TIME real2time(REAL)

Prototype
    TIME real2time(REAL r)

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

Description
    Converts the time t to a integer.

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

  REAL time2real(TIME)

Prototype
    REAL time2real(TIME t)

Description
    Converts the time t to a real.

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

  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 the first occurrence of the string s2 in the string s1, or an empty string if not found.

    Note that the comparison is case sensitive.

Example
    if (std.strstr(req.url, req.http.x-restrict)) {
    ...
    }

  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

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