.\" Man page generated from reStructuredText. . .TH VMOD_STD 3 "" "" "" .SH NAME vmod_std \- Varnish Standard Module . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .\" . .\" NB: This file is machine generated, DO NOT EDIT! . .\" . .\" Edit vmod.vcc and run make instead . .\" . .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import std [from "path"] ; STRING toupper(STRING s) STRING tolower(STRING s) VOID set_ip_tos(INT tos) REAL random(REAL lo, REAL hi) VOID log(STRING s) VOID syslog(INT priority, STRING s) STRING fileread(STRING) BOOL file_exists(STRING path) VOID collect(HEADER hdr, STRING sep) DURATION duration(STRING s, DURATION fallback) INT integer(STRING s, INT fallback) IP ip(STRING s, IP fallback, BOOL resolve) REAL real(STRING s, REAL fallback) INT real2integer(REAL r, INT fallback) TIME real2time(REAL r, TIME fallback) INT time2integer(TIME t, INT fallback) REAL time2real(TIME t, REAL fallback) BOOL healthy(BACKEND be) INT port(IP ip) VOID rollback(HTTP h) VOID timestamp(STRING s) STRING querysort(STRING) BOOL cache_req_body(BYTES size) STRING strstr(STRING s1, STRING s2) TIME time(STRING s, TIME fallback) STRING getenv(STRING name) VOID late_100_continue(BOOL late) BOOL syntax(REAL) BOOL fnmatch(STRING pattern, STRING subject, BOOL pathname, BOOL noescape, BOOL period) .ft P .fi .UNINDENT .UNINDENT .SH DESCRIPTION .sp \fIvmod_std\fP contains basic functions which are part and parcel of Varnish, but which for reasons of architecture fit better in a VMOD. .sp One particular class of functions in vmod_std is the conversions functions which all have the form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C TYPE type(STRING, TYPE) .ft P .fi .UNINDENT .UNINDENT .sp These functions attempt to convert STRING to the TYPE, and if that fails, they return the second argument, which must have the given TYPE. .SS STRING toupper(STRING s) .INDENT 0.0 .TP .B Description Converts the string \fIs\fP to uppercase. .TP .B Example set beresp.http.scream = std.toupper("yes!"); .UNINDENT .SS STRING tolower(STRING s) .INDENT 0.0 .TP .B Description Converts the string \fIs\fP to lowercase. .TP .B Example set beresp.http.nice = std.tolower("VerY"); .UNINDENT .SS VOID set_ip_tos(INT tos) .INDENT 0.0 .TP .B Description Sets the IP type\-of\-service (TOS) field for the current session to \fItos\fP\&. 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. .TP .B Example .nf if (req.url ~ "^/slow/") { .in +2 std.set_ip_tos(0); .in -2 } .fi .sp .UNINDENT .SS REAL random(REAL lo, REAL hi) .INDENT 0.0 .TP .B Description Returns a random real number between \fIlo\fP and \fIhi\fP\&. 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. .TP .B Example set beresp.http.random\-number = std.random(1, 100); .UNINDENT .SS VOID log(STRING s) .INDENT 0.0 .TP .B Description Logs the string \fIs\fP to the shared memory log, using VSL tag \fISLT_VCL_Log\fP\&. .TP .B Example std.log("Something fishy is going on with the vhost " + req.http.host); .UNINDENT .SS VOID syslog(INT priority, STRING s) .INDENT 0.0 .TP .B Description Logs the string \fIs\fP to syslog tagged with \fIpriority\fP\&. \fIpriority\fP is formed by ORing the facility and level values. See your system\(aqs syslog.h file for possible values. .sp 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 \fBsyslog()\fP function has no effect. .TP .B Example std.syslog(9, "Something is wrong"); .sp This will send a message to syslog using LOG_USER | LOG_ALERT. .UNINDENT .SS STRING fileread(STRING) .INDENT 0.0 .TP .B Description Reads a file and returns a string with the content. The result is cached indefinitely per filename. .TP .B Example synthetic("Response was served by " + std.fileread("/etc/hostname")); .UNINDENT .sp Consider that the entire contents of the file appear in the string that is returned, including newlines that may result in invalid headers if \fBstd.fileread()\fP is used to form a header. In that case, you may need to modify the string, for example with \fBregsub()\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C set beresp.http.served\-by = regsub(std.fileread("/etc/hostname"), "\eR$", ""); .ft P .fi .UNINDENT .UNINDENT .SS BOOL file_exists(STRING path) .INDENT 0.0 .TP .B Description Returns \fItrue\fP if path or the file pointed to by path exists, \fIfalse\fP otherwise. .TP .B Example .nf if (std.file_exists("/etc/return_503")) { .in +2 return (synth(503, "Varnish is in maintenance")); .in -2 } .fi .sp .UNINDENT .SS VOID collect(HEADER hdr, STRING sep=", ") .INDENT 0.0 .TP .B Description Collapses multiple \fIhdr\fP headers into one long header. The default separator \fIsep\fP is the standard comma separator to use when collapsing headers, with an additional whitespace for pretty printing. .sp Care should be taken when collapsing headers. In particular collapsing Set\-Cookie will lead to unexpected results on the browser side. .TP .B Examples .nf std.collect(req.http.accept); std.collect(req.http.cookie, "; "); .fi .sp .UNINDENT .SS DURATION duration(STRING s, DURATION fallback) .INDENT 0.0 .TP .B Description Converts the string \fIs\fP to seconds. \fIs\fP must be quantified with ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) or y (years) units. If conversion fails, \fIfallback\fP will be returned. .TP .B Example set beresp.ttl = std.duration("1w", 3600s); .UNINDENT .SS INT integer(STRING s, INT fallback) .INDENT 0.0 .TP .B Description Converts the string \fIs\fP to an integer. If conversion fails, \fIfallback\fP will be returned. .TP .B Example .nf if (std.integer(req.http.foo, 0) > 5) { .in +2 \&... .in -2 } .fi .sp .UNINDENT .SS IP ip(STRING s, IP fallback, BOOL resolve=1) .INDENT 0.0 .TP .B Description Converts the string \fIs\fP to the first IP number returned by the system library function getaddrinfo(3). If conversion fails, \fIfallback\fP will be returned. .sp If \fIresolve\fP is false, getaddrinfo() is called using \fIAI_NUMERICHOST\fP to avoid network lookups. This makes "pure" IP strings cheaper to convert. .TP .B Example .nf if (std.ip(req.http.X\-forwarded\-for, "0.0.0.0") ~ my_acl) { .in +2 \&... .in -2 } .fi .sp .UNINDENT .SS REAL real(STRING s, REAL fallback) .INDENT 0.0 .TP .B Description Converts the string \fIs\fP to a real. If conversion fails, \fIfallback\fP will be returned. .TP .B Example .nf if (std.real(req.http.foo, 0.0) > 5.5) { .in +2 \&... .in -2 } .fi .sp .UNINDENT .SS INT real2integer(REAL r, INT fallback) .INDENT 0.0 .TP .B Description Rounds the real \fIr\fP to the nearest integer, but round halfway cases away from zero (see round(3)). If conversion fails, \fIfallback\fP will be returned. .TP .B Example 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 .UNINDENT .SS TIME real2time(REAL r, TIME fallback) .INDENT 0.0 .TP .B Description Rounds the real \fIr\fP to the nearest integer (see \fI\%func_real2integer\fP) and returns the corresponding time when interpreted as a unix epoch. If conversion fails, \fIfallback\fP will be returned. .TP .B Example set req.http.time = std.real2time(1140618699.00, now); .UNINDENT .SS INT time2integer(TIME t, INT fallback) .INDENT 0.0 .TP .B Description Converts the time \fIt\fP to a integer. If conversion fails, \fIfallback\fP will be returned. .TP .B Example set req.http.int = std.time2integer(now, 0); .UNINDENT .SS REAL time2real(TIME t, REAL fallback) .INDENT 0.0 .TP .B Description Converts the time \fIt\fP to a real. If conversion fails, \fIfallback\fP will be returned. .TP .B Example set req.http.real = std.time2real(now, 1.0); .UNINDENT .SS BOOL healthy(BACKEND be) .INDENT 0.0 .TP .B Description Returns \fItrue\fP if the backend \fIbe\fP is healthy. .UNINDENT .SS INT port(IP ip) .INDENT 0.0 .TP .B Description Returns the port number of the IP address \fIip\fP\&. Always returns 0 for a \fB*.ip\fP variable whose value is \fB0.0.0.0\fP because the listen address is a Unix domain socket. .UNINDENT .SS VOID rollback(HTTP h) .INDENT 0.0 .TP .B Description Restores the \fIh\fP HTTP headers to their original state. .TP .B Example std.rollback(bereq); .UNINDENT .SS VOID timestamp(STRING s) .INDENT 0.0 .TP .B Description Introduces a timestamp in the log with the current time, using the string \fIs\fP as the label. This is useful to time the execution of lengthy VCL procedures, and makes the timestamps inserted automatically by Varnish more accurate. .TP .B Example std.timestamp("curl\-request"); .UNINDENT .SS STRING querysort(STRING) .INDENT 0.0 .TP .B Description Sorts the query string for cache normalization purposes. .TP .B Example set req.url = std.querysort(req.url); .UNINDENT .SS BOOL cache_req_body(BYTES size) .INDENT 0.0 .TP .B Description Caches the request body if it is smaller than \fIsize\fP\&. Returns \fItrue\fP if the body was cached, \fIfalse\fP otherwise. .sp 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. .TP .B Example .nf if (std.cache_req_body(1KB)) { .in +2 \&... .in -2 } .fi .sp .UNINDENT .SS STRING strstr(STRING s1, STRING s2) .INDENT 0.0 .TP .B Description Returns a string beginning at the first occurrence of the string \fIs2\fP in the string \fIs1\fP, or an empty string if \fIs2\fP is not found. .sp Note that the comparison is case sensitive. .TP .B Example .nf if (std.strstr(req.url, req.http.restrict)) { .in +2 \&... .in -2 } .fi .sp .sp This will check if the content of req.http.restrict occurs anywhere in req.url. .UNINDENT .SS TIME time(STRING s, TIME fallback) .INDENT 0.0 .TP .B Description Converts the string \fIs\fP to a time. If conversion fails, \fIfallback\fP will be returned. .sp Supported formats: .nf "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" .fi .sp .TP .B Example .nf if (std.time(resp.http.last\-modified, now) < now \- 1w) { .in +2 \&... .in -2 } .fi .sp .UNINDENT .SS STRING getenv(STRING name) .INDENT 0.0 .TP .B Description Return environment variable \fIname\fP or the empty string. .sp See getenv(3) .TP .B Example .nf set req.http.My\-Env = std.getenv("MY_ENV"); .fi .sp .UNINDENT .SS VOID late_100_continue(BOOL late) .INDENT 0.0 .TP .B Description Controls when varnish reacts to an \fIExpect: 100\-continue\fP client request header. .sp Varnish always generates a \fI100 Continue\fP response if requested by the client trough the \fIExpect: 100\-continue\fP header when waiting for request body data. .sp But, by default, the \fI100 Continue\fP response is already generated immediately after \fIvcl_recv\fP returns to reduce latencies under the assumption that the request body will be read eventually. .sp Calling \fIstd.late_100_continue(true)\fP in \fIvcl_recv\fP will cause the \fI100 Continue\fP 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. .sp This function has no effect outside \fIvcl_recv\fP and after calling \fIstd.cache_req_body()\fP or any other function consuming the request body. .TP .B Example .nf vcl_recv { .in +2 std.late_100_continue(true); if (req.method == "POST") { .in +2 std.late_100_continue(false); return (pass); .in -2 } \&... .in -2 } .fi .sp .UNINDENT .SS BOOL syntax(REAL) .INDENT 0.0 .TP .B Description Returns the true if VCL version is at least REAL. .UNINDENT .SS fnmatch(...) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C BOOL fnmatch( STRING pattern, STRING subject, BOOL pathname=1, BOOL noescape=0, BOOL period=0 ) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Description Shell\-style pattern matching; returns \fItrue\fP if \fIsubject\fP matches \fIpattern\fP, where \fIpattern\fP may contain wildcard characters such as * or ?. .sp The match is executed by the implementation of \fIfnmatch(3)\fP on your system. The rules for pattern matching on most systems include the following: .INDENT 7.0 .IP \(bu 2 * matches any sequence of characters .IP \(bu 2 ? matches a single character .IP \(bu 2 a bracket expression such as [abc] or [!0\-9] is interpreted as a character class according to the rules of basic regular expressions (\fInot\fP PCRE regexen), except that ! is used for character class negation instead of ^. .UNINDENT .sp If \fIpathname\fP is \fItrue\fP, 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, \fIpathname\fP is \fItrue\fP\&. .sp If \fInoescape\fP is \fItrue\fP, then the backslash character \e is matched as an ordinary character. Otherwise, \e is an escape character, and matches the character that follows it in the \fIpattern\fP\&. For example, \e\e matches \e when \fInoescape\fP is \fItrue\fP, and \e\e when \fIfalse\fP\&. By default, \fInoescape\fP is \fIfalse\fP\&. .sp If \fIperiod\fP is \fItrue\fP, 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 \fIsubject\fP; if \fIpathname\fP is also \fItrue\fP, then a period that immediately follows a / is also leading (as in "/."). By default, \fIperiod\fP is \fIfalse\fP\&. .sp \fIfnmatch()\fP invokes VCL failure and returns \fIfalse\fP if either of \fIpattern\fP or \fIsubject\fP is NULL \-\- for example, if an unset header is specified. .TP .B Examples .nf # 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)) { ... } .fi .sp .UNINDENT .SH SEE ALSO .INDENT 0.0 .IP \(bu 2 \fIvarnishd(1)\fP .IP \(bu 2 \fIvsl(7)\fP .IP \(bu 2 \fIfnmatch(3)\fP .UNINDENT .SH COPYRIGHT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Copyright (c) 2010\-2017 Varnish Software AS All rights reserved. Author: Poul\-Henning Kamp Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS \(ga\(gaAS IS\(aq\(aq AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .ft P .fi .UNINDENT .UNINDENT .\" Generated by docutils manpage writer. .