feat: add missing KF6 framework recipes
This commit is contained in:
@@ -0,0 +1,634 @@
|
||||
<!DOCTYPE html>
|
||||
<html><head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
|
||||
<title>vmod.vcc</title>
|
||||
<meta name="generator" content="KF5::SyntaxHighlighting - Definition (Varnish module spec file) - Theme (Breeze Light)"/>
|
||||
</head><body style="background-color:#ffffff;color:#1f1c1b"><pre>
|
||||
<span style="color:#898887">#-</span>
|
||||
<span style="color:#898887"># Copyright (c) 2010-2017 Varnish Software AS</span>
|
||||
<span style="color:#898887"># All rights reserved.</span>
|
||||
<span style="color:#898887">#</span>
|
||||
<span style="color:#898887"># Author: Poul-Henning Kamp <phk@FreeBSD.org></span>
|
||||
<span style="color:#898887">#</span>
|
||||
<span style="color:#898887"># </span><span style="color:#ca60ca;font-style:italic">SPDX-License-Identifier:</span><span style="color:#ca60ca;font-style:italic"> </span><span style="color:#ca60ca;font-style:italic">BSD-2-Clause</span>
|
||||
<span style="color:#898887">#</span>
|
||||
<span style="color:#898887"># Redistribution and use in source and binary forms, with or without</span>
|
||||
<span style="color:#898887"># modification, are permitted provided that the following conditions</span>
|
||||
<span style="color:#898887"># are met:</span>
|
||||
<span style="color:#898887"># 1. Redistributions of source code must retain the above copyright</span>
|
||||
<span style="color:#898887"># notice, this list of conditions and the following disclaimer.</span>
|
||||
<span style="color:#898887"># 2. Redistributions in binary form must reproduce the above copyright</span>
|
||||
<span style="color:#898887"># notice, this list of conditions and the following disclaimer in the</span>
|
||||
<span style="color:#898887"># documentation and/or other materials provided with the distribution.</span>
|
||||
<span style="color:#898887">#</span>
|
||||
<span style="color:#898887"># THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND</span>
|
||||
<span style="color:#898887"># ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE</span>
|
||||
<span style="color:#898887"># IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE</span>
|
||||
<span style="color:#898887"># ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE</span>
|
||||
<span style="color:#898887"># FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL</span>
|
||||
<span style="color:#898887"># DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS</span>
|
||||
<span style="color:#898887"># OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)</span>
|
||||
<span style="color:#898887"># HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT</span>
|
||||
<span style="color:#898887"># LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY</span>
|
||||
<span style="color:#898887"># OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF</span>
|
||||
<span style="color:#898887"># SUCH DAMAGE.</span>
|
||||
|
||||
$ABI strict
|
||||
<span style="font-weight:bold">$Module</span> <span style="color:#0057ae">std</span> <span style="color:#b08000">3</span><span style="color:#bf0303"> "Varnish Standard Module"</span>
|
||||
|
||||
DESCRIPTION
|
||||
===========
|
||||
|
||||
<span style="color:#898887">.. note: not using :ref:`vmod_std(3)` because it expands to "VMOD</span>
|
||||
<span style="color:#0057ae"> </span><span style="color:#898887">std - Varnish Standard Module" and here just the plan vmod name</span>
|
||||
<span style="color:#0057ae"> </span><span style="color:#898887">makes more sense.</span>
|
||||
|
||||
<span style="font-style:italic">*vmod_std*</span> contains basic functions which are part and parcel of
|
||||
Varnish, but which for reasons of architecture fit better in a VMOD.
|
||||
|
||||
Numeric functions
|
||||
=================
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">REAL</span> <span style="color:#644a9b">random</span>(<span style="color:#0057ae">REAL</span> lo, <span style="color:#0057ae">REAL</span> hi)
|
||||
|
||||
Returns a random real number between <span style="font-style:italic">*lo*</span> and <span style="font-style:italic">*hi*</span>.
|
||||
|
||||
This function uses the "testable" random generator in varnishd which
|
||||
enables determinstic tests to be run (See <span style="color:#0057ae">``m00002.vtc``</span>). This
|
||||
function should not be used for cryptographic applications.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> set beresp.http.random-number = std.random(1, 100);</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">REAL</span> <span style="color:#644a9b">round</span>(<span style="color:#0057ae">REAL</span> r)
|
||||
|
||||
Rounds the real <span style="font-style:italic">*r*</span> to the nearest integer, but round halfway cases
|
||||
away from zero (see <span style="color:#b08000">`round(3)`</span>).
|
||||
|
||||
|
||||
String functions
|
||||
================
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">VOID</span> <span style="color:#644a9b">collect</span>(<span style="color:#0057ae">HEADER</span> hdr, <span style="color:#0057ae">STRING</span> sep=", ")
|
||||
|
||||
Collapses multiple <span style="font-style:italic">*hdr*</span> headers into one long header. The default
|
||||
separator <span style="font-style:italic">*sep*</span> 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
|
||||
<span style="color:#0057ae">``Set-Cookie``</span> will lead to unexpected results on the browser side.
|
||||
|
||||
Examples<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> std.collect(req.http.accept);</span>
|
||||
<span style="color:#0057ae"> std.collect(req.http.cookie, "; ");</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">STRING</span> <span style="color:#644a9b">querysort</span>(<span style="color:#0057ae">STRING</span>)
|
||||
|
||||
Sorts the query string for cache normalization purposes.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> set req.url = std.querysort(req.url);</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">STRING</span> <span style="color:#644a9b">toupper</span>(STRANDS s)
|
||||
|
||||
Converts the string <span style="font-style:italic">*s*</span> to uppercase.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> set beresp.http.scream = std.toupper("yes!");</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">STRING</span> <span style="color:#644a9b">tolower</span>(STRANDS s)
|
||||
|
||||
Converts the string <span style="font-style:italic">*s*</span> to lowercase.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> set beresp.http.nice = std.tolower("VerY");</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">STRING</span> <span style="color:#644a9b">strstr</span>(<span style="color:#0057ae">STRING</span> s1, <span style="color:#0057ae">STRING</span> s2)
|
||||
|
||||
Returns a string beginning at the first occurrence of the string <span style="font-style:italic">*s2*</span>
|
||||
in the string <span style="font-style:italic">*s1*</span>, or an empty string if <span style="font-style:italic">*s2*</span> is not found.
|
||||
|
||||
Note that the comparison is case sensitive.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> if (std.strstr(req.url, req.http.restrict)) {</span>
|
||||
<span style="color:#0057ae"> ...</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
|
||||
This will check if the content of <span style="color:#0057ae">``req.http.restrict``</span> occurs
|
||||
anywhere in <span style="color:#0057ae">``req.url``</span>.
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">BOOL</span> <span style="color:#644a9b">fnmatch</span>(<span style="color:#0057ae">STRING</span> pattern, <span style="color:#0057ae">STRING</span> subject, <span style="color:#0057ae">BOOL</span> pathname=1,
|
||||
BOOL noescape=0, BOOL period=0)
|
||||
|
||||
Shell-style pattern matching; returns <span style="color:#0057ae">``true``</span> if <span style="font-style:italic">*subject*</span> matches
|
||||
<span style="font-style:italic">*pattern*</span>, where <span style="font-style:italic">*pattern*</span> may contain wildcard characters such as <span style="color:#0057ae">``*``</span>
|
||||
or <span style="color:#0057ae">``?``</span>.
|
||||
|
||||
The match is executed by the implementation of <span style="color:#b08000">`fnmatch(3)`</span> on your
|
||||
system. The rules for pattern matching on most systems include the
|
||||
following:
|
||||
|
||||
* <span style="color:#0057ae">``*``</span> matches any sequence of characters
|
||||
|
||||
* <span style="color:#0057ae">``?``</span> matches a single character
|
||||
|
||||
* a bracket expression such as <span style="color:#0057ae">``[abc]``</span> or <span style="color:#0057ae">``[!0-9]``</span> is interpreted
|
||||
as a character class according to the rules of basic regular
|
||||
expressions (<span style="font-style:italic">*not*</span> <span style="color:#b08000">`pcre(3)`</span> regexen), except that <span style="color:#0057ae">``!``</span> is used for
|
||||
character class negation instead of <span style="color:#0057ae">``^``</span>.
|
||||
|
||||
If <span style="font-style:italic">*pathname*</span> is <span style="color:#0057ae">``true``</span>, then the forward slash character <span style="color:#0057ae">``/``</span> is
|
||||
only matched literally, and never matches <span style="color:#0057ae">``*``</span>, <span style="color:#0057ae">``?``</span> or a bracket
|
||||
expression. Otherwise, <span style="color:#0057ae">``/``</span> may match one of those patterns. By
|
||||
default, <span style="font-style:italic">*pathname*</span> is <span style="color:#0057ae">``true``</span>.
|
||||
|
||||
If <span style="font-style:italic">*noescape*</span> is <span style="color:#0057ae">``true``</span>, then the backslash character <span style="color:#0057ae">``\``</span> is
|
||||
matched as an ordinary character. Otherwise, <span style="color:#0057ae">``\``</span> is an escape
|
||||
character, and matches the character that follows it in the
|
||||
<span style="font-style:italic">*pattern*</span>. For example, <span style="color:#0057ae">``\\``</span> matches <span style="color:#0057ae">``\``</span> when <span style="font-style:italic">*noescape*</span> is
|
||||
<span style="color:#0057ae">``true``</span>, and <span style="color:#0057ae">``\\``</span> when <span style="color:#0057ae">``false``</span>. By default, <span style="font-style:italic">*noescape*</span> is
|
||||
<span style="color:#0057ae">``false``</span>.
|
||||
|
||||
If <span style="font-style:italic">*period*</span> is <span style="color:#0057ae">``true``</span>, then a leading period character <span style="color:#0057ae">``.``</span> only
|
||||
matches literally, and never matches <span style="color:#0057ae">``*``</span>, <span style="color:#0057ae">``?``</span> or a bracket
|
||||
expression. A period is leading if it is the first character in
|
||||
<span style="font-style:italic">*subject*</span>; if <span style="font-style:italic">*pathname*</span> is also <span style="color:#0057ae">``true``</span>, then a period that
|
||||
immediately follows a <span style="color:#0057ae">``/``</span> is also leading (as in <span style="color:#0057ae">``/.``</span>). By
|
||||
default, <span style="font-style:italic">*period*</span> is <span style="color:#0057ae">``false``</span>.
|
||||
|
||||
<span style="color:#006e28">`std.fnmatch()`_</span> invokes VCL failure and returns <span style="color:#0057ae">``false``</span> if
|
||||
either of <span style="font-style:italic">*pattern*</span> or <span style="font-style:italic">*subject*</span> is <span style="color:#0057ae">``NULL``</span> -- for example, if an
|
||||
unset header is specified.
|
||||
|
||||
Examples<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> # Matches URLs such as /foo/bar and /foo/baz</span>
|
||||
<span style="color:#0057ae"> if (std.fnmatch("/foo/\*", req.url)) { ... }</span>
|
||||
|
||||
<span style="color:#0057ae"> # Matches URLs such as /foo/bar/baz and /foo/baz/quux</span>
|
||||
<span style="color:#0057ae"> if (std.fnmatch("/foo/\*/\*", bereq.url)) { ... }</span>
|
||||
|
||||
<span style="color:#0057ae"> # Matches /foo/bar/quux, but not /foo/bar/baz/quux</span>
|
||||
<span style="color:#0057ae"> if (std.fnmatch("/foo/\*/quux", req.url)) { ... }</span>
|
||||
|
||||
<span style="color:#0057ae"> # Matches /foo/bar/quux and /foo/bar/baz/quux</span>
|
||||
<span style="color:#0057ae"> if (std.fnmatch("/foo/\*/quux", req.url, pathname=false)) { ... }</span>
|
||||
|
||||
<span style="color:#0057ae"> # Matches /foo/bar, /foo/car and /foo/far</span>
|
||||
<span style="color:#0057ae"> if (std.fnmatch("/foo/?ar", req.url)) { ... }</span>
|
||||
|
||||
<span style="color:#0057ae"> # Matches /foo/ followed by a non-digit</span>
|
||||
<span style="color:#0057ae"> if (std.fnmatch("/foo/[!0-9]", req.url)) { ... }</span>
|
||||
|
||||
|
||||
File(system) functions
|
||||
======================
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">STRING</span> <span style="color:#644a9b">fileread</span>(<span style="color:#0057ae">PRIV_CALL</span>, <span style="color:#0057ae">STRING</span>)
|
||||
|
||||
Reads a file and returns a string with the content. The result is
|
||||
cached indefinitely per filename.
|
||||
|
||||
This function should not be used for reading binary files.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> synthetic("Response was served by " + std.fileread("/etc/hostname"));</span>
|
||||
|
||||
Consider that the entire contents of the file appear in the string
|
||||
that is returned, including newlines that may result in invalid
|
||||
headers if <span style="color:#006e28">`std.fileread()`_</span> is used to form a header. In that
|
||||
case, you may need to modify the string, for example with
|
||||
<span style="color:#0057ae">``regsub()``</span> (see <span style="font-weight:bold">:ref:</span><span style="color:#b08000">`vcl(7)`</span>)<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> set beresp.http.served-by = regsub(std.fileread("/etc/hostname"), "\R$", "");</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">BOOL</span> <span style="color:#644a9b">file_exists</span>(<span style="color:#0057ae">STRING</span> path)
|
||||
|
||||
Returns <span style="color:#0057ae">``true``</span> if path or the file pointed to by path exists,
|
||||
<span style="color:#0057ae">``false``</span> otherwise.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> if (std.file_exists("/etc/return_503")) {</span>
|
||||
<span style="color:#0057ae"> return (synth(503, "Varnish is in maintenance"));</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
|
||||
|
||||
Type Inspection functions
|
||||
=========================
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">BOOL</span> <span style="color:#644a9b">healthy</span>(<span style="color:#0057ae">BACKEND</span> be)
|
||||
|
||||
Returns <span style="color:#0057ae">``true``</span> if the backend <span style="font-style:italic">*be*</span> is healthy.
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">INT</span> <span style="color:#644a9b">port</span>(<span style="color:#0057ae">IP</span> ip)
|
||||
|
||||
Returns the port number of the IP address <span style="font-style:italic">*ip*</span>. Always returns <span style="color:#0057ae">``0``</span>
|
||||
for a <span style="color:#0057ae">``*.ip``</span> variable when the address is a Unix domain socket.
|
||||
|
||||
Type Conversion functions
|
||||
=========================
|
||||
|
||||
These functions all have the same form<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> TYPE type([arguments], [fallback TYPE])</span>
|
||||
|
||||
Precisely one of the <span style="font-style:italic">*arguments*</span> must be provided (besides the
|
||||
optional <span style="font-style:italic">*fallback*</span>), and it will be converted to <span style="font-style:italic">*TYPE*</span>.
|
||||
|
||||
If conversion fails, <span style="font-style:italic">*fallback*</span> will be returned and if no
|
||||
fallback was specified, the VCL will be failed.
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">DURATION</span> <span style="color:#644a9b">duration</span>([<span style="color:#0057ae">STRING</span> s], [<span style="color:#0057ae">DURATION</span> fallback],
|
||||
[REAL real], [INT integer])
|
||||
|
||||
Returns a DURATION from a STRING, REAL or INT argument.
|
||||
|
||||
For a STRING <span style="font-style:italic">*s*</span> argument, <span style="font-style:italic">*s*</span> must be quantified by <span style="color:#0057ae">``ms``</span>
|
||||
(milliseconds), <span style="color:#0057ae">``s``</span> (seconds), <span style="color:#0057ae">``m``</span> (minutes), <span style="color:#0057ae">``h``</span> (hours),``d``
|
||||
(days), <span style="color:#0057ae">``w``</span> (weeks) or <span style="color:#0057ae">``y``</span> (years) units.
|
||||
|
||||
<span style="font-style:italic">*real*</span> and <span style="font-style:italic">*integer*</span> arguments are taken as seconds.
|
||||
|
||||
If the conversion of an <span style="font-style:italic">*s*</span> argument fails, <span style="font-style:italic">*fallback*</span> will be
|
||||
returned if provided, or a VCL failure will be triggered.
|
||||
|
||||
Conversions from <span style="font-style:italic">*real*</span> and <span style="font-style:italic">*integer*</span> arguments never fail.
|
||||
|
||||
Only one of the <span style="font-style:italic">*s*</span>, <span style="font-style:italic">*real*</span> or <span style="font-style:italic">*integer*</span> arguments may be given or a VCL
|
||||
failure will be triggered.
|
||||
|
||||
Examples<span style="color:#0057ae">::</span>
|
||||
<span style="color:#0057ae"> set beresp.ttl = std.duration("1w", 3600s);</span>
|
||||
<span style="color:#0057ae"> set beresp.ttl = std.duration(real=1.5);</span>
|
||||
<span style="color:#0057ae"> set beresp.ttl = std.duration(integer=10);</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">BYTES</span> <span style="color:#644a9b">bytes</span>([<span style="color:#0057ae">STRING</span> s], [<span style="color:#0057ae">BYTES</span> fallback], [<span style="color:#0057ae">REAL</span> real], [<span style="color:#0057ae">INT</span> integer])
|
||||
|
||||
Returns BYTES from a STRING, REAL or INT argument.
|
||||
|
||||
A STRING <span style="font-style:italic">*s*</span> argument can be quantified with a multiplier (<span style="color:#0057ae">``k``</span>
|
||||
(kilo), <span style="color:#0057ae">``m``</span> (mega), <span style="color:#0057ae">``g``</span> (giga), <span style="color:#0057ae">``t``</span> (tera) or <span style="color:#0057ae">``p``</span> (peta)).
|
||||
|
||||
<span style="font-style:italic">*real*</span> and <span style="font-style:italic">*integer*</span> arguments are taken as bytes.
|
||||
|
||||
If the conversion of an <span style="font-style:italic">*s*</span> argument fails, <span style="font-style:italic">*fallback*</span> will be
|
||||
returned if provided, or a VCL failure will be triggered.
|
||||
|
||||
Other conversions may fail if the argument can not be represented,
|
||||
because it is negative, too small or too large. Again, <span style="font-style:italic">*fallback*</span> will
|
||||
be returned if provided, or a VCL failure will be triggered.
|
||||
|
||||
<span style="font-style:italic">*real*</span> arguments will be rounded down.
|
||||
|
||||
Only one of the <span style="font-style:italic">*s*</span>, <span style="font-style:italic">*real*</span> or <span style="font-style:italic">*integer*</span> arguments may be given or a VCL
|
||||
failure will be triggered.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
<span style="color:#0057ae"> std.cache_req_body(std.bytes(something.somewhere, 10K));</span>
|
||||
<span style="color:#0057ae"> std.cache_req_body(std.bytes(integer=10*1024));</span>
|
||||
<span style="color:#0057ae"> std.cache_req_body(std.bytes(real=10.0*1024));</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">INT</span> <span style="color:#644a9b">integer</span>([<span style="color:#0057ae">STRING</span> s], [<span style="color:#0057ae">INT</span> fallback],
|
||||
[BOOL bool], [BYTES bytes], [DURATION duration], [REAL real],
|
||||
[TIME time])
|
||||
|
||||
Returns an INT from a STRING, BOOL or other quantity.
|
||||
|
||||
If the conversion of an <span style="font-style:italic">*s*</span> argument fails, <span style="font-style:italic">*fallback*</span> will be
|
||||
returned if provided, or a VCL failure will be triggered.
|
||||
|
||||
A <span style="font-style:italic">*bool*</span> argument will be returned as 0 for <span style="color:#0057ae">``false``</span> and 1 for
|
||||
<span style="color:#0057ae">``true``</span>. This conversion will never fail.
|
||||
|
||||
For a <span style="font-style:italic">*bytes*</span> argument, the number of bytes will be returned. This
|
||||
conversion will never fail.
|
||||
|
||||
A <span style="font-style:italic">*duration*</span> argument will be rounded down to the number of seconds
|
||||
and returned.
|
||||
|
||||
A <span style="font-style:italic">*real*</span> argument will be rounded down and returned.
|
||||
|
||||
For a <span style="font-style:italic">*time*</span> argument, the number of seconds since the UNIX epoch
|
||||
(1970-01-01 00:00:00 UTC) will be returned.
|
||||
|
||||
<span style="font-style:italic">*duration*</span>, <span style="font-style:italic">*real*</span> and <span style="font-style:italic">*time*</span> conversions may fail if the argument can
|
||||
not be represented because it is too small or too large. If so,
|
||||
<span style="font-style:italic">*fallback*</span> will be returned if provided, or a VCL failure will be
|
||||
triggered.
|
||||
|
||||
Only one of the <span style="font-style:italic">*s*</span>, <span style="font-style:italic">*bool*</span>, <span style="font-style:italic">*bytes*</span>, <span style="font-style:italic">*duration*</span>, <span style="font-style:italic">*real*</span> or <span style="font-style:italic">*time*</span>
|
||||
arguments may be given or a VCL failure will be triggered.
|
||||
|
||||
Examples<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> if (std.integer(req.http.foo, 0) > 5) {</span>
|
||||
<span style="color:#0057ae"> ...</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
|
||||
<span style="color:#0057ae"> set resp.http.answer = std.integer(real=126.42/3);</span>
|
||||
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">IP</span> <span style="color:#644a9b">ip</span>(<span style="color:#0057ae">STRING</span> s, [<span style="color:#0057ae">IP</span> fallback], <span style="color:#0057ae">BOOL</span> resolve = 1, [<span style="color:#0057ae">STRING</span> p])
|
||||
|
||||
Converts the string <span style="font-style:italic">*s*</span> to the first IP number returned by the system
|
||||
library function <span style="color:#b08000">`getaddrinfo(3)`</span>. If conversion fails, <span style="font-style:italic">*fallback*</span> will
|
||||
be returned or VCL failure will happen.
|
||||
|
||||
The IP address includes a port number that can be found with <span style="color:#0057ae">``std.port()``</span>
|
||||
that defaults to 80. The default port can be set to a different value with
|
||||
the <span style="font-style:italic">*p*</span> argument. It will be overriden if <span style="font-style:italic">*s*</span> contains both an IP address
|
||||
and a port number or service name.
|
||||
|
||||
When <span style="font-style:italic">*s*</span> contains both, the syntax is either <span style="color:#0057ae">``address:port``</span> or
|
||||
<span style="color:#0057ae">``address port``</span>. If the address is a numerical IPv6 address it must be
|
||||
enclosed between brackets, for example <span style="color:#0057ae">``[::1] 80``</span> or <span style="color:#0057ae">``[::1]:http``</span>.
|
||||
The <span style="font-style:italic">*fallback*</span> may also contain both an address and a port, but its default
|
||||
port is always 80.
|
||||
|
||||
If <span style="font-style:italic">*resolve*</span> is false, <span style="color:#b08000">`getaddrinfo(3)`</span> is called using <span style="color:#0057ae">``AI_NUMERICHOST``</span>
|
||||
and <span style="color:#0057ae">``AI_NUMERICSERV``</span> to avoid network lookups depending on the system's
|
||||
<span style="color:#b08000">`getaddrinfo(3)`</span> or nsswitch configuration. This makes "numerical" IP
|
||||
strings and services cheaper to convert.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> if (std.ip(req.http.X-forwarded-for, "0.0.0.0") ~ my_acl) {</span>
|
||||
<span style="color:#0057ae"> ...</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">REAL</span> <span style="color:#644a9b">real</span>([<span style="color:#0057ae">STRING</span> s], [<span style="color:#0057ae">REAL</span> fallback], [<span style="color:#0057ae">INT</span> integer],
|
||||
[BOOL bool], [BYTES bytes], [DURATION duration],
|
||||
[TIME time])
|
||||
|
||||
Returns a REAL from a STRING, BOOL or other quantity.
|
||||
|
||||
If the conversion of an <span style="font-style:italic">*s*</span> argument fails, <span style="font-style:italic">*fallback*</span> will be
|
||||
returned if provided, or a VCL failure will be triggered.
|
||||
|
||||
A <span style="font-style:italic">*bool*</span> argument will be returned as 0.0 for <span style="color:#0057ae">``false``</span> and 1.0 for
|
||||
<span style="color:#0057ae">``true``</span>.
|
||||
|
||||
For a <span style="font-style:italic">*bytes*</span> argument, the number of bytes will be returned.
|
||||
|
||||
For a <span style="font-style:italic">*duration*</span> argument, the number of seconds will be returned.
|
||||
|
||||
An <span style="font-style:italic">*integer*</span> argument will be returned as a REAL.
|
||||
|
||||
For a <span style="font-style:italic">*time*</span> argument, the number of seconds since the UNIX epoch
|
||||
(1970-01-01 00:00:00 UTC) will be returned.
|
||||
|
||||
None of these conversions other than <span style="font-style:italic">*s*</span> will fail.
|
||||
|
||||
Only one of the <span style="font-style:italic">*s*</span>, <span style="font-style:italic">*integer*</span>, <span style="font-style:italic">*bool*</span>, <span style="font-style:italic">*bytes*</span>, <span style="font-style:italic">*duration*</span> or <span style="font-style:italic">*time*</span>
|
||||
arguments may be given or a VCL failure will be triggered.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> if (std.real(req.http.foo, 0.0) > 5.5) {</span>
|
||||
<span style="color:#0057ae"> ...</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">TIME</span> <span style="color:#644a9b">time</span>([<span style="color:#0057ae">STRING</span> s], [<span style="color:#0057ae">TIME</span> fallback], [<span style="color:#0057ae">REAL</span> real], [<span style="color:#0057ae">INT</span> integer])
|
||||
|
||||
Returns a TIME from a STRING, REAL or INT argument.
|
||||
|
||||
For a STRING <span style="font-style:italic">*s*</span> argument, the following formats are supported<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> "Sun, 06 Nov 1994 08:49:37 GMT"</span>
|
||||
<span style="color:#0057ae"> "Sunday, 06-Nov-94 08:49:37 GMT"</span>
|
||||
<span style="color:#0057ae"> "Sun Nov 6 08:49:37 1994"</span>
|
||||
<span style="color:#0057ae"> "1994-11-06T08:49:37"</span>
|
||||
<span style="color:#0057ae"> "784111777.00"</span>
|
||||
<span style="color:#0057ae"> "784111777"</span>
|
||||
|
||||
<span style="font-style:italic">*real*</span> and <span style="font-style:italic">*integer*</span> arguments are taken as seconds since the epoch.
|
||||
|
||||
If the conversion of an <span style="font-style:italic">*s*</span> argument fails or a negative <span style="font-style:italic">*real*</span> or
|
||||
<span style="font-style:italic">*integer*</span> argument is given, <span style="font-style:italic">*fallback*</span> will be returned if provided,
|
||||
or a VCL failure will be triggered.
|
||||
|
||||
Examples<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> if (std.time(resp.http.last-modified, now) < now - 1w) {</span>
|
||||
<span style="color:#0057ae"> ...</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
|
||||
<span style="color:#0057ae"> if (std.time(int=2147483647) < now - 1w) {</span>
|
||||
<span style="color:#0057ae"> ...</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
|
||||
LOGGING functions
|
||||
=================
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">VOID</span> <span style="color:#644a9b">log</span>(STRANDS s)
|
||||
|
||||
Logs the string <span style="font-style:italic">*s*</span> to the shared memory log, using <span style="font-weight:bold">:ref:</span><span style="color:#b08000">`vsl(7)`</span> tag
|
||||
<span style="color:#0057ae">``SLT_VCL_Log``</span>.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> std.log("Something fishy is going on with the vhost " + req.http.host);</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">VOID</span> <span style="color:#644a9b">syslog</span>(<span style="color:#0057ae">INT</span> priority, STRANDS s)
|
||||
|
||||
Logs the string <span style="font-style:italic">*s*</span> to syslog tagged with <span style="font-style:italic">*priority*</span>. <span style="font-style:italic">*priority*</span> is
|
||||
formed by ORing the facility and level values. See your system's
|
||||
<span style="color:#0057ae">``syslog.h``</span> 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 <span style="color:#006e28">`std.syslog()`_</span> function has no effect.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> std.syslog(9, "Something is wrong");</span>
|
||||
|
||||
This will send a message to syslog using <span style="color:#0057ae">``LOG_USER | LOG_ALERT``</span>.
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">VOID</span> <span style="color:#644a9b">timestamp</span>(<span style="color:#0057ae">STRING</span> s)
|
||||
|
||||
Introduces a timestamp in the log with the current time, using the
|
||||
string <span style="font-style:italic">*s*</span> as the label. This is useful to time the execution of lengthy
|
||||
VCL subroutines, and makes the timestamps inserted automatically by
|
||||
Varnish more accurate.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> std.timestamp("curl-request");</span>
|
||||
|
||||
|
||||
CONTROL and INFORMATION functions
|
||||
=================================
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">BOOL</span> <span style="color:#644a9b">syntax</span>(<span style="color:#0057ae">REAL</span>)
|
||||
|
||||
Returns <span style="color:#0057ae">``true``</span> if VCL version is at least <span style="font-style:italic">*REAL*</span>.
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">STRING</span> <span style="color:#644a9b">getenv</span>(<span style="color:#0057ae">STRING</span> name)
|
||||
|
||||
Return environment variable <span style="font-style:italic">*name*</span> or the empty string. See <span style="color:#b08000">`getenv(3)`</span>.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> set req.http.My-Env = std.getenv("MY_ENV");</span>
|
||||
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">BOOL</span> <span style="color:#644a9b">cache_req_body</span>(<span style="color:#0057ae">BYTES</span> size)
|
||||
|
||||
Caches the request body if it is smaller than <span style="font-style:italic">*size*</span>. Returns
|
||||
<span style="color:#0057ae">``true``</span> if the body was cached, <span style="color:#0057ae">``false``</span> otherwise.
|
||||
|
||||
Normally the request body can only be sent once. Caching it enables
|
||||
retrying backend requests with a request body, as usually the case
|
||||
with <span style="color:#0057ae">``POST``</span> and <span style="color:#0057ae">``PUT``</span>.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> if (std.cache_req_body(1KB)) {</span>
|
||||
<span style="color:#0057ae"> ...</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">VOID</span> <span style="color:#644a9b">late_100_continue</span>(<span style="color:#0057ae">BOOL</span> late)
|
||||
|
||||
Controls when varnish reacts to an <span style="color:#0057ae">``Expect: 100-continue``</span> client
|
||||
request header.
|
||||
|
||||
Varnish always generates a <span style="color:#0057ae">``100 Continue``</span> response if requested by
|
||||
the client trough the <span style="color:#0057ae">``Expect: 100-continue``</span> header when waiting for
|
||||
request body data.
|
||||
|
||||
But, by default, the <span style="color:#0057ae">``100 Continue``</span> response is already generated
|
||||
immediately after <span style="color:#0057ae">``vcl_recv``</span> returns to reduce latencies under the
|
||||
assumption that the request body will be read eventually.
|
||||
|
||||
Calling <span style="color:#0057ae">``std.late_100_continue(true)``</span> in <span style="color:#0057ae">``vcl_recv``</span> will cause the
|
||||
<span style="color:#0057ae">``100 Continue``</span> 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 <span style="color:#0057ae">``vcl_recv``</span> and after calling
|
||||
<span style="color:#0057ae">``std.cache_req_body()``</span> or any other function consuming the request
|
||||
body.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> vcl_recv {</span>
|
||||
<span style="color:#0057ae"> std.late_100_continue(true);</span>
|
||||
|
||||
<span style="color:#0057ae"> if (req.method == "POST") {</span>
|
||||
<span style="color:#0057ae"> std.late_100_continue(false);</span>
|
||||
<span style="color:#0057ae"> return (pass);</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
<span style="color:#0057ae"> ...</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">VOID</span> <span style="color:#644a9b">set_ip_tos</span>(<span style="color:#0057ae">INT</span> tos)
|
||||
|
||||
Sets the IP type-of-service (TOS) field for the current session to
|
||||
<span style="font-style:italic">*tos*</span>. 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.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> if (req.url ~ "^/slow/") {</span>
|
||||
<span style="color:#0057ae"> std.set_ip_tos(0);</span>
|
||||
<span style="color:#0057ae"> }</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">VOID</span> <span style="color:#644a9b">rollback</span>(<span style="color:#0057ae">HTTP</span> h)
|
||||
|
||||
Restores the <span style="font-style:italic">*h*</span> HTTP headers to their original state.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> std.rollback(bereq);</span>
|
||||
|
||||
|
||||
DEPRECATED functions
|
||||
====================
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">INT</span> <span style="color:#644a9b">real2integer</span>(<span style="color:#0057ae">REAL</span> r, <span style="color:#0057ae">INT</span> fallback)
|
||||
|
||||
<span style="font-weight:bold">**DEPRECATED**</span>: This function will be removed in a future version of
|
||||
varnish, use <span style="color:#006e28">`std.integer()`_</span> with a <span style="font-style:italic">*real*</span> argument and the
|
||||
<span style="color:#006e28">`std.round()`_</span> function instead, for example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> std.integer(real=std.round(...), fallback=...)</span>
|
||||
|
||||
Rounds the real <span style="font-style:italic">*r*</span> to the nearest integer, but round halfway cases
|
||||
away from zero (see <span style="color:#b08000">`round(3)`</span>). If conversion fails, <span style="font-style:italic">*fallback*</span> will
|
||||
be returned.
|
||||
|
||||
Examples<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> set req.http.integer = std.real2integer(1140618699.00, 0);</span>
|
||||
<span style="color:#0057ae"> set req.http.posone = real2integer( 0.5, 0); # = 1.0</span>
|
||||
<span style="color:#0057ae"> set req.http.negone = real2integer(-0.5, 0); # = -1.0</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">TIME</span> <span style="color:#644a9b">real2time</span>(<span style="color:#0057ae">REAL</span> r, <span style="color:#0057ae">TIME</span> fallback)
|
||||
|
||||
<span style="font-weight:bold">**DEPRECATED**</span>: This function will be removed in a future version of
|
||||
varnish, use <span style="color:#006e28">`std.time()`_</span> with a <span style="font-style:italic">*real*</span> argument and the
|
||||
<span style="color:#006e28">`std.round()`_</span> function instead, for example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> std.time(real=std.round(...), fallback=...)</span>
|
||||
|
||||
Rounds the real <span style="font-style:italic">*r*</span> to the nearest integer (see
|
||||
<span style="color:#006e28">`std.real2integer()`_</span>) and returns the corresponding time when
|
||||
interpreted as a unix epoch. If conversion fails, <span style="font-style:italic">*fallback*</span> will be
|
||||
returned.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> set req.http.time = std.real2time(1140618699.00, now);</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">INT</span> <span style="color:#644a9b">time2integer</span>(<span style="color:#0057ae">TIME</span> t, <span style="color:#0057ae">INT</span> fallback)
|
||||
|
||||
<span style="font-weight:bold">**DEPRECATED**</span>: This function will be removed in a future version of
|
||||
varnish, use <span style="color:#006e28">`std.integer()`_</span> with a <span style="font-style:italic">*time*</span> argument instead, for
|
||||
example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> std.integer(time=..., fallback=...)</span>
|
||||
|
||||
Converts the time <span style="font-style:italic">*t*</span> to a integer. If conversion fails,
|
||||
<span style="font-style:italic">*fallback*</span> will be returned.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> set req.http.int = std.time2integer(now, 0);</span>
|
||||
|
||||
<span style="font-weight:bold">$Function</span> <span style="color:#0057ae">REAL</span> <span style="color:#644a9b">time2real</span>(<span style="color:#0057ae">TIME</span> t, <span style="color:#0057ae">REAL</span> fallback)
|
||||
|
||||
<span style="font-weight:bold">**DEPRECATED**</span>: This function will be removed in a future version of
|
||||
varnish, use <span style="color:#006e28">`std.real()`_</span> with a <span style="font-style:italic">*time*</span> argument instead, for
|
||||
example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> std.real(time=..., fallback=...)</span>
|
||||
|
||||
Converts the time <span style="font-style:italic">*t*</span> to a real. If conversion fails, <span style="font-style:italic">*fallback*</span> will
|
||||
be returned.
|
||||
|
||||
Example<span style="color:#0057ae">::</span>
|
||||
|
||||
<span style="color:#0057ae"> set req.http.real = std.time2real(now, 1.0);</span>
|
||||
|
||||
|
||||
|
||||
SEE ALSO
|
||||
========
|
||||
|
||||
* <span style="font-weight:bold">:ref:</span><span style="color:#b08000">`varnishd(1)`</span>
|
||||
* <span style="font-weight:bold">:ref:</span><span style="color:#b08000">`vsl(7)`</span>
|
||||
* <span style="color:#b08000">`fnmatch(3)`</span>
|
||||
</pre></body></html>
|
||||
Reference in New Issue
Block a user