SearchVarnish Enterprise
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.
STRING toupper(STRING_LIST s)
Converts the string s to uppercase.
set beresp.http.scream = std.toupper("yes!");
Arguments:
s accepts type STRING_LISTType: Function
Returns: String
STRING tolower(STRING_LIST s)
Converts the string s to lowercase.
set beresp.http.nice = std.tolower("VerY");
Arguments:
s accepts type STRING_LISTType: Function
Returns: String
VOID set_ip_tos(INT tos)
Sets the Differentiated Services Codepoint (DSCP) / IPv4 Type of Service (TOS) / IPv6 Traffic Class (TCLASS) byte for the current session to tos. Silently ignored if the listen address is a Unix domain socket.
Please note that setting the traffic class affects all requests on the same http1.1 / http2 TCP connection and, in particular, is not removed at the end of the request.
Example
if (req.url ~ "^/slow/") {
std.set_ip_tos(0);
}
Arguments:
tos accepts type INTType: Function
Returns: None
Restricted to: client
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
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_LISTType: Function
Returns: None
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
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
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 STRINGType: Function
Returns: Bool
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(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(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
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(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(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
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
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
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
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
BOOL healthy(BACKEND be)
Returns true if the backend be is healthy.
Arguments:
be accepts type BACKENDType: Function
Returns: Bool
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 IPType: Function
Returns: Int
VOID rollback(HTTP h)
Restores the h HTTP headers to their original state.
std.rollback(bereq);
Arguments:
h accepts type HTTPType: Function
Returns: None
Restricted to: backend, client
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 STRINGType: Function
Returns: None
STRING querysort(STRING)
Sorts the query string for cache normalization purposes.
set req.url = std.querysort(req.url);
Arguments: None
Type: Function
Returns: String
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 BYTESType: Function
Returns: Bool
Restricted to: vcl_recv
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(STRING s, TIME fallback)
Converts the string s to a time. If conversion fails, fallback will be returned.
Supported formats:
if (std.time(resp.http.last-modified, now) < now - 1w) {
...
}
Arguments:
s accepts type STRING
fallback accepts type TIME
Type: Function
Returns: Time
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 STRINGType: Function
Returns: String
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 BOOLType: Function
Returns: None
Restricted to: vcl_recv
BOOL syntax(REAL)
Returns the true if VCL version is at least REAL.
Arguments: None
Type: Function
Returns: Bool
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:
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
The std VMOD is available in Varnish Enterprise version 6.0.0r0 and later.