Search
Varnish Cache Plus

Standard (std)

Description

The standard vmod 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.

API

toupper

STRING toupper(STRING_LIST s)

Converts the string s to uppercase.

set beresp.http.scream = std.toupper("yes!");

Arguments:

  • s accepts type STRING_LIST

Type: Function

Returns: String

tolower

STRING tolower(STRING_LIST s)

Converts the string s to lowercase.

set beresp.http.nice = std.tolower("VerY");

Arguments:

  • s accepts type STRING_LIST

Type: Function

Returns: String

set_ip_tos

VOID set_ip_tos(INT tos)

Sets the IP type-of-service (TOS) field for the current session to tos. Silently ignored if the listen address is a Unix domain socket. 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.

if (req.url ~ "^/slow/") {
	std.set_ip_tos(0);
}

Arguments:

  • tos accepts type INT

Type: Function

Returns: None

random

REAL random(REAL lo, REAL hi)

Returns a random real number between lo and hi. This function uses the “testable” random generator in varnishd which enables deterministic tests to be run (See m00002.vtc). This function should not be used for cryptographic applications.

set beresp.http.random-number = std.random(1, 100);

Arguments:

  • lo accepts type REAL

  • hi accepts type REAL

Type: Function

Returns: Real

log

VOID log(STRING_LIST s)

Logs the string s to the shared memory log, using VSL tag SLT_VCL_Log.

std.log("Something fishy is going on with the vhost " + req.http.host);

Arguments:

  • s accepts type STRING_LIST

Type: Function

Returns: None

syslog

VOID syslog(INT priority, STRING_LIST s)

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.

Notice: Unlike VCL and other functions in the std vmod, this function will not fail VCL processing for workspace overflows: For an out of workspace condition, the syslog() function has no effect.

std.syslog(9, "Something is wrong");

This will send a message to syslog using LOG_USER | LOG_ALERT.

Arguments:

  • priority accepts type INT

  • s accepts type STRING_LIST

Type: Function

Returns: None

fileread

STRING fileread(STRING)

Reads a file and returns a string with the content. The result is cached indefinitely per filename.

synthetic("Response was served by " + std.fileread("/etc/hostname"));

Consider that the entire contents of the file appear in the string that is returned, including newlines that may result in invalid headers if std.fileread() is used to form a header. In that case, you may need to modify the string, for example with regsub():

set beresp.http.served-by = regsub(std.fileread("/etc/hostname"), "\R$", "");

Arguments: None

Type: Function

Returns: String

file_exists

BOOL file_exists(STRING path)

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

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

Arguments:

  • path accepts type STRING

Type: Function

Returns: Bool

collect

VOID collect(HEADER hdr, STRING sep = ", ")

Collapses multiple hdr headers into one long header. The default separator sep is the standard comma separator to use when collapsing headers, with an additional whitespace for pretty printing.

Care should be taken when collapsing headers. In particular collapsing Set-Cookie will lead to unexpected results on the browser side.

std.collect(req.http.accept);
std.collect(req.http.cookie, "; ");

Arguments:

  • hdr accepts type HEADER

  • sep accepts type STRING with a default value of , optional

Type: Function

Returns: None

duration

DURATION duration(STRING s, DURATION fallback)

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.

set beresp.ttl = std.duration("1w", 3600s);

Arguments:

  • s accepts type STRING

  • fallback accepts type DURATION

Type: Function

Returns: Duration

bytes

BYTES bytes(STRING s, BYTES fallback)

Converts the string s to bytes. s can be quantified with a multiplier (k, m, g, t, p). If conversion fails, fallback will be returned.

std.cache_req_body(std.bytes(something.somewhere, 10K));

Arguments:

  • s accepts type STRING

  • fallback accepts type BYTES

Type: Function

Returns: Bytes

integer

INT integer(STRING s, INT fallback)

Converts the string s to an integer. If conversion fails, fallback will be returned.

if (std.integer(req.http.foo, 0) > 5) {
	...
}

Arguments:

  • s accepts type STRING

  • fallback accepts type INT

Type: Function

Returns: Int

ip

IP ip(STRING s, IP fallback, BOOL resolve = 1, STRING p = "80")

Converts the string s to the first IP number returned by the system library function getaddrinfo(3). If conversion fails, fallback will be returned or VCL failure will happen.

The IP address includes a port number that can be found with std.port() that defaults to 80. The default port can be set to a different value with the p argument. It will be overridden if s contains both an IP address and a port number or service name.

When s contains both, the syntax is either address:port or address port. If the address is a numerical IPv6 address it must be enclosed between brackets, for example [::1] 80 or [::1]:http. The fallback may also contain both an address and a port, but its default port is always 80.

If resolve is false, getaddrinfo(3) is called using AI_NUMERICHOST and AI_NUMERICSERV to avoid network lookups depending on the system’s getaddrinfo(3) or nsswitch configuration. This makes “numerical” IP strings and services cheaper to convert.

if (std.ip(req.http.X-forwarded-for, "0.0.0.0") ~ my_acl) {
	...
}

Arguments:

  • s accepts type STRING

  • fallback accepts type IP

  • resolve accepts type BOOL with a default value of 1 optional

  • p accepts type STRING with a default value of 80 optional

Type: Function

Returns: Ip

real

REAL real(STRING s, REAL fallback)

Converts the string s to a real. If conversion fails, fallback will be returned.

if (std.real(req.http.foo, 0.0) > 5.5) {
	...
}

Arguments:

  • s accepts type STRING

  • fallback accepts type REAL

Type: Function

Returns: Real

real2integer

INT real2integer(REAL r, INT fallback)

Rounds the real r to the nearest integer, but round halfway cases away from zero (see round(3)). If conversion fails, fallback will be returned.

set req.http.integer = std.real2integer(1140618699.00, 0);
set req.http.posone = real2integer( 0.5, 0);	# =  1.0
set req.http.negone = real2integer(-0.5, 0);	# = -1.0

Arguments:

  • r accepts type REAL

  • fallback accepts type INT

Type: Function

Returns: Int

real2time

TIME real2time(REAL r, TIME fallback)

Rounds the real r to the nearest integer (see func_real2integer) and returns the corresponding time when interpreted as a unix epoch. If conversion fails, fallback will be returned.

set req.http.time = std.real2time(1140618699.00, now);

Arguments:

  • r accepts type REAL

  • fallback accepts type TIME

Type: Function

Returns: Time

time2integer

INT time2integer(TIME t, INT fallback)

Converts the time t to a integer. If conversion fails, fallback will be returned.

set req.http.int = std.time2integer(now, 0);

Arguments:

  • t accepts type TIME

  • fallback accepts type INT

Type: Function

Returns: Int

time2real

REAL time2real(TIME t, REAL fallback)

Converts the time t to a real. If conversion fails, fallback will be returned.

set req.http.real = std.time2real(now, 1.0);

Arguments:

  • t accepts type TIME

  • fallback accepts type REAL

Type: Function

Returns: Real

healthy

BOOL healthy(BACKEND be)

Returns true if the backend be is healthy.

Arguments:

  • be accepts type BACKEND

Type: Function

Returns: Bool

port

INT port(IP ip)

Returns the port number of the IP address ip. Always returns 0 for a *.ip variable whose value is 0.0.0.0 because the listen address is a Unix domain socket.

Arguments:

  • ip accepts type IP

Type: Function

Returns: Int

rollback

VOID rollback(HTTP h)

Restores the h HTTP headers to their original state.

std.rollback(bereq);

Arguments:

  • h accepts type HTTP

Type: Function

Returns: None

timestamp

VOID timestamp(STRING s)

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.

std.timestamp("curl-request");

Arguments:

  • s accepts type STRING

Type: Function

Returns: None

querysort

STRING querysort(STRING)

Sorts the query string for cache normalization purposes.

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

Arguments: None

Type: Function

Returns: String

cache_req_body

BOOL cache_req_body(BYTES size)

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.

if (std.cache_req_body(1KB)) {
	...
}

Arguments:

  • size accepts type BYTES

Type: Function

Returns: Bool

strstr

STRING strstr(STRING s1, STRING s2)

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.

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

This will check if the content of req.http.restrict occurs anywhere in req.url.

Arguments:

  • s1 accepts type STRING

  • s2 accepts type STRING

Type: Function

Returns: String

time

TIME time(STRING s, TIME fallback)

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”

    if (std.time(resp.http.last-modified, now) < now - 1w) {
    	...
    }
    

Arguments:

  • s accepts type STRING

  • fallback accepts type TIME

Type: Function

Returns: Time

getenv

STRING getenv(STRING name)

Return environment variable name or the empty string.

set req.http.My-Env = std.getenv("MY_ENV");

Arguments:

  • name accepts type STRING

Type: Function

Returns: String

late_100_continue

VOID late_100_continue(BOOL late)

Controls when varnish reacts to an Expect: 100-continue client request header.

Varnish always generates a 100 Continue response if requested by the client trough the Expect: 100-continue header when waiting for request body data.

But, by default, the 100 Continue response is already generated immediately after sub vcl_recv returns to reduce latencies under the assumption that the request body will be read eventually.

Calling std.late_100_continue(true) in sub vcl_recv will cause the 100 Continue response to only be sent when needed. This may cause additional latencies for processing request bodies, but is the correct behavior by strict interpretation of RFC7231.

This function has no effect outside sub vcl_recv and after calling std.cache_req_body() or any other function consuming the request body.

vcl_recv {
	std.late_100_continue(true);

	if (req.method == "POST") {
		std.late_100_continue(false);
		return (pass);
	}
	...
}

Arguments:

  • late accepts type BOOL

Type: Function

Returns: None

syntax

BOOL syntax(REAL)

Returns the true if VCL version is at least REAL.

Arguments: None

Type: Function

Returns: Bool

fnmatch

BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname = 1, BOOL noescape = 0, BOOL period = 0)

Shell-style pattern matching; returns true if subject matches pattern, where pattern may contain wildcard characters such as * or ?.

The match is executed by the implementation of fnmatch(3) on your system. The rules for pattern matching on most systems include the following:

  • * matches any sequence of characters
  • ? matches a single character
  • a bracket expression such as [abc] or [!0-9] is interpreted as a character class according to the rules of basic regular expressions (not PCRE regexen), except that ! is used for character class negation instead of ^.

If pathname is true, then the forward slash character / is only matched literally, and never matches *, ? or a bracket expression. Otherwise, / may match one of those patterns. By default, pathname is true.

If noescape is true, then the backslash character \ is matched as an ordinary character. Otherwise, \ is an escape character, and matches the character that follows it in the pattern. For example, \\ matches \ when noescape is true, and \\ when false. By default, noescape is false.

If period is true, then a leading period character . only matches literally, and never matches *, ? or a bracket expression. A period is leading if it is the first character in subject; if pathname is also true, then a period that immediately follows a / is also leading (as in “/.”). By default, period is false.

fnmatch() invokes VCL failure and returns false if either of pattern or subject is NULL – for example, if an unset header is specified.

# Matches URLs such as /foo/bar and /foo/baz
if (std.fnmatch("/foo/\*", req.url)) { ... }

# Matches URLs such as /foo/bar/baz and /foo/baz/quux
if (std.fnmatch("/foo/\*/\*", bereq.url)) { ... }

# Matches /foo/bar/quux, but not /foo/bar/baz/quux
if (std.fnmatch("/foo/\*/quux", req.url)) { ... }

# Matches /foo/bar/quux and /foo/bar/baz/quux
if (std.fnmatch("/foo/\*/quux", req.url, pathname=false)) { ... }

# Matches /foo/bar, /foo/car and /foo/far
if (std.fnmatch("/foo/?ar", req.url)) { ... }

# Matches /foo/ followed by a non-digit
if (std.fnmatch("/foo/[!0-9]", req.url)) { ... }

Arguments:

  • pattern accepts type STRING

  • subject accepts type STRING

  • pathname accepts type BOOL with a default value of 1 optional

  • noescape accepts type BOOL with a default value of 0 optional

  • period accepts type BOOL with a default value of 0 optional

Type: Function

Returns: Bool

Availability

The std VMOD is available in Varnish Cache Plus version 6.0.0r0 and later.