File indexing completed on 2024-05-12 04:02:10
0001 <!DOCTYPE html> 0002 <html><head> 0003 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> 0004 <title>vmod.vcc</title> 0005 <meta name="generator" content="KF5::SyntaxHighlighting - Definition (Varnish module spec file) - Theme (Breeze Light)"/> 0006 </head><body style="background-color:#ffffff;color:#1f1c1b"><pre> 0007 <span style="color:#898887">#-</span> 0008 <span style="color:#898887"># Copyright (c) 2010-2017 Varnish Software AS</span> 0009 <span style="color:#898887"># All rights reserved.</span> 0010 <span style="color:#898887">#</span> 0011 <span style="color:#898887"># Author: Poul-Henning Kamp <phk@FreeBSD.org></span> 0012 <span style="color:#898887">#</span> 0013 <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> 0014 <span style="color:#898887">#</span> 0015 <span style="color:#898887"># Redistribution and use in source and binary forms, with or without</span> 0016 <span style="color:#898887"># modification, are permitted provided that the following conditions</span> 0017 <span style="color:#898887"># are met:</span> 0018 <span style="color:#898887"># 1. Redistributions of source code must retain the above copyright</span> 0019 <span style="color:#898887"># notice, this list of conditions and the following disclaimer.</span> 0020 <span style="color:#898887"># 2. Redistributions in binary form must reproduce the above copyright</span> 0021 <span style="color:#898887"># notice, this list of conditions and the following disclaimer in the</span> 0022 <span style="color:#898887"># documentation and/or other materials provided with the distribution.</span> 0023 <span style="color:#898887">#</span> 0024 <span style="color:#898887"># THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND</span> 0025 <span style="color:#898887"># ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE</span> 0026 <span style="color:#898887"># IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE</span> 0027 <span style="color:#898887"># ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE</span> 0028 <span style="color:#898887"># FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL</span> 0029 <span style="color:#898887"># DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS</span> 0030 <span style="color:#898887"># OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)</span> 0031 <span style="color:#898887"># HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT</span> 0032 <span style="color:#898887"># LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY</span> 0033 <span style="color:#898887"># OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF</span> 0034 <span style="color:#898887"># SUCH DAMAGE.</span> 0035 0036 $ABI strict 0037 <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> 0038 0039 DESCRIPTION 0040 =========== 0041 0042 <span style="color:#898887">.. note: not using :ref:`vmod_std(3)` because it expands to "VMOD</span> 0043 <span style="color:#0057ae"> </span><span style="color:#898887">std - Varnish Standard Module" and here just the plan vmod name</span> 0044 <span style="color:#0057ae"> </span><span style="color:#898887">makes more sense.</span> 0045 0046 <span style="font-style:italic">*vmod_std*</span> contains basic functions which are part and parcel of 0047 Varnish, but which for reasons of architecture fit better in a VMOD. 0048 0049 Numeric functions 0050 ================= 0051 0052 <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) 0053 0054 Returns a random real number between <span style="font-style:italic">*lo*</span> and <span style="font-style:italic">*hi*</span>. 0055 0056 This function uses the "testable" random generator in varnishd which 0057 enables determinstic tests to be run (See <span style="color:#0057ae">``m00002.vtc``</span>). This 0058 function should not be used for cryptographic applications. 0059 0060 Example<span style="color:#0057ae">::</span> 0061 0062 <span style="color:#0057ae"> set beresp.http.random-number = std.random(1, 100);</span> 0063 0064 <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) 0065 0066 Rounds the real <span style="font-style:italic">*r*</span> to the nearest integer, but round halfway cases 0067 away from zero (see <span style="color:#b08000">`round(3)`</span>). 0068 0069 0070 String functions 0071 ================ 0072 0073 <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=", ") 0074 0075 Collapses multiple <span style="font-style:italic">*hdr*</span> headers into one long header. The default 0076 separator <span style="font-style:italic">*sep*</span> is the standard comma separator to use when collapsing 0077 headers, with an additional whitespace for pretty printing. 0078 0079 Care should be taken when collapsing headers. In particular collapsing 0080 <span style="color:#0057ae">``Set-Cookie``</span> will lead to unexpected results on the browser side. 0081 0082 Examples<span style="color:#0057ae">::</span> 0083 0084 <span style="color:#0057ae"> std.collect(req.http.accept);</span> 0085 <span style="color:#0057ae"> std.collect(req.http.cookie, "; ");</span> 0086 0087 <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>) 0088 0089 Sorts the query string for cache normalization purposes. 0090 0091 Example<span style="color:#0057ae">::</span> 0092 0093 <span style="color:#0057ae"> set req.url = std.querysort(req.url);</span> 0094 0095 <span style="font-weight:bold">$Function</span> <span style="color:#0057ae">STRING</span> <span style="color:#644a9b">toupper</span>(STRANDS s) 0096 0097 Converts the string <span style="font-style:italic">*s*</span> to uppercase. 0098 0099 Example<span style="color:#0057ae">::</span> 0100 0101 <span style="color:#0057ae"> set beresp.http.scream = std.toupper("yes!");</span> 0102 0103 <span style="font-weight:bold">$Function</span> <span style="color:#0057ae">STRING</span> <span style="color:#644a9b">tolower</span>(STRANDS s) 0104 0105 Converts the string <span style="font-style:italic">*s*</span> to lowercase. 0106 0107 Example<span style="color:#0057ae">::</span> 0108 0109 <span style="color:#0057ae"> set beresp.http.nice = std.tolower("VerY");</span> 0110 0111 <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) 0112 0113 Returns a string beginning at the first occurrence of the string <span style="font-style:italic">*s2*</span> 0114 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. 0115 0116 Note that the comparison is case sensitive. 0117 0118 Example<span style="color:#0057ae">::</span> 0119 0120 <span style="color:#0057ae"> if (std.strstr(req.url, req.http.restrict)) {</span> 0121 <span style="color:#0057ae"> ...</span> 0122 <span style="color:#0057ae"> }</span> 0123 0124 This will check if the content of <span style="color:#0057ae">``req.http.restrict``</span> occurs 0125 anywhere in <span style="color:#0057ae">``req.url``</span>. 0126 0127 <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, 0128 BOOL noescape=0, BOOL period=0) 0129 0130 Shell-style pattern matching; returns <span style="color:#0057ae">``true``</span> if <span style="font-style:italic">*subject*</span> matches 0131 <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> 0132 or <span style="color:#0057ae">``?``</span>. 0133 0134 The match is executed by the implementation of <span style="color:#b08000">`fnmatch(3)`</span> on your 0135 system. The rules for pattern matching on most systems include the 0136 following: 0137 0138 * <span style="color:#0057ae">``*``</span> matches any sequence of characters 0139 0140 * <span style="color:#0057ae">``?``</span> matches a single character 0141 0142 * a bracket expression such as <span style="color:#0057ae">``[abc]``</span> or <span style="color:#0057ae">``[!0-9]``</span> is interpreted 0143 as a character class according to the rules of basic regular 0144 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 0145 character class negation instead of <span style="color:#0057ae">``^``</span>. 0146 0147 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 0148 only matched literally, and never matches <span style="color:#0057ae">``*``</span>, <span style="color:#0057ae">``?``</span> or a bracket 0149 expression. Otherwise, <span style="color:#0057ae">``/``</span> may match one of those patterns. By 0150 default, <span style="font-style:italic">*pathname*</span> is <span style="color:#0057ae">``true``</span>. 0151 0152 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 0153 matched as an ordinary character. Otherwise, <span style="color:#0057ae">``\``</span> is an escape 0154 character, and matches the character that follows it in the 0155 <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 0156 <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 0157 <span style="color:#0057ae">``false``</span>. 0158 0159 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 0160 matches literally, and never matches <span style="color:#0057ae">``*``</span>, <span style="color:#0057ae">``?``</span> or a bracket 0161 expression. A period is leading if it is the first character in 0162 <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 0163 immediately follows a <span style="color:#0057ae">``/``</span> is also leading (as in <span style="color:#0057ae">``/.``</span>). By 0164 default, <span style="font-style:italic">*period*</span> is <span style="color:#0057ae">``false``</span>. 0165 0166 <span style="color:#006e28">`std.fnmatch()`_</span> invokes VCL failure and returns <span style="color:#0057ae">``false``</span> if 0167 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 0168 unset header is specified. 0169 0170 Examples<span style="color:#0057ae">::</span> 0171 0172 <span style="color:#0057ae"> # Matches URLs such as /foo/bar and /foo/baz</span> 0173 <span style="color:#0057ae"> if (std.fnmatch("/foo/\*", req.url)) { ... }</span> 0174 0175 <span style="color:#0057ae"> # Matches URLs such as /foo/bar/baz and /foo/baz/quux</span> 0176 <span style="color:#0057ae"> if (std.fnmatch("/foo/\*/\*", bereq.url)) { ... }</span> 0177 0178 <span style="color:#0057ae"> # Matches /foo/bar/quux, but not /foo/bar/baz/quux</span> 0179 <span style="color:#0057ae"> if (std.fnmatch("/foo/\*/quux", req.url)) { ... }</span> 0180 0181 <span style="color:#0057ae"> # Matches /foo/bar/quux and /foo/bar/baz/quux</span> 0182 <span style="color:#0057ae"> if (std.fnmatch("/foo/\*/quux", req.url, pathname=false)) { ... }</span> 0183 0184 <span style="color:#0057ae"> # Matches /foo/bar, /foo/car and /foo/far</span> 0185 <span style="color:#0057ae"> if (std.fnmatch("/foo/?ar", req.url)) { ... }</span> 0186 0187 <span style="color:#0057ae"> # Matches /foo/ followed by a non-digit</span> 0188 <span style="color:#0057ae"> if (std.fnmatch("/foo/[!0-9]", req.url)) { ... }</span> 0189 0190 0191 File(system) functions 0192 ====================== 0193 0194 <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>) 0195 0196 Reads a file and returns a string with the content. The result is 0197 cached indefinitely per filename. 0198 0199 This function should not be used for reading binary files. 0200 0201 Example<span style="color:#0057ae">::</span> 0202 0203 <span style="color:#0057ae"> synthetic("Response was served by " + std.fileread("/etc/hostname"));</span> 0204 0205 Consider that the entire contents of the file appear in the string 0206 that is returned, including newlines that may result in invalid 0207 headers if <span style="color:#006e28">`std.fileread()`_</span> is used to form a header. In that 0208 case, you may need to modify the string, for example with 0209 <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> 0210 0211 <span style="color:#0057ae"> set beresp.http.served-by = regsub(std.fileread("/etc/hostname"), "\R$", "");</span> 0212 0213 <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) 0214 0215 Returns <span style="color:#0057ae">``true``</span> if path or the file pointed to by path exists, 0216 <span style="color:#0057ae">``false``</span> otherwise. 0217 0218 Example<span style="color:#0057ae">::</span> 0219 0220 <span style="color:#0057ae"> if (std.file_exists("/etc/return_503")) {</span> 0221 <span style="color:#0057ae"> return (synth(503, "Varnish is in maintenance"));</span> 0222 <span style="color:#0057ae"> }</span> 0223 0224 0225 Type Inspection functions 0226 ========================= 0227 0228 <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) 0229 0230 Returns <span style="color:#0057ae">``true``</span> if the backend <span style="font-style:italic">*be*</span> is healthy. 0231 0232 <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) 0233 0234 Returns the port number of the IP address <span style="font-style:italic">*ip*</span>. Always returns <span style="color:#0057ae">``0``</span> 0235 for a <span style="color:#0057ae">``*.ip``</span> variable when the address is a Unix domain socket. 0236 0237 Type Conversion functions 0238 ========================= 0239 0240 These functions all have the same form<span style="color:#0057ae">::</span> 0241 0242 <span style="color:#0057ae"> TYPE type([arguments], [fallback TYPE])</span> 0243 0244 Precisely one of the <span style="font-style:italic">*arguments*</span> must be provided (besides the 0245 optional <span style="font-style:italic">*fallback*</span>), and it will be converted to <span style="font-style:italic">*TYPE*</span>. 0246 0247 If conversion fails, <span style="font-style:italic">*fallback*</span> will be returned and if no 0248 fallback was specified, the VCL will be failed. 0249 0250 <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], 0251 [REAL real], [INT integer]) 0252 0253 Returns a DURATION from a STRING, REAL or INT argument. 0254 0255 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> 0256 (milliseconds), <span style="color:#0057ae">``s``</span> (seconds), <span style="color:#0057ae">``m``</span> (minutes), <span style="color:#0057ae">``h``</span> (hours),``d`` 0257 (days), <span style="color:#0057ae">``w``</span> (weeks) or <span style="color:#0057ae">``y``</span> (years) units. 0258 0259 <span style="font-style:italic">*real*</span> and <span style="font-style:italic">*integer*</span> arguments are taken as seconds. 0260 0261 If the conversion of an <span style="font-style:italic">*s*</span> argument fails, <span style="font-style:italic">*fallback*</span> will be 0262 returned if provided, or a VCL failure will be triggered. 0263 0264 Conversions from <span style="font-style:italic">*real*</span> and <span style="font-style:italic">*integer*</span> arguments never fail. 0265 0266 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 0267 failure will be triggered. 0268 0269 Examples<span style="color:#0057ae">::</span> 0270 <span style="color:#0057ae"> set beresp.ttl = std.duration("1w", 3600s);</span> 0271 <span style="color:#0057ae"> set beresp.ttl = std.duration(real=1.5);</span> 0272 <span style="color:#0057ae"> set beresp.ttl = std.duration(integer=10);</span> 0273 0274 <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]) 0275 0276 Returns BYTES from a STRING, REAL or INT argument. 0277 0278 A STRING <span style="font-style:italic">*s*</span> argument can be quantified with a multiplier (<span style="color:#0057ae">``k``</span> 0279 (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)). 0280 0281 <span style="font-style:italic">*real*</span> and <span style="font-style:italic">*integer*</span> arguments are taken as bytes. 0282 0283 If the conversion of an <span style="font-style:italic">*s*</span> argument fails, <span style="font-style:italic">*fallback*</span> will be 0284 returned if provided, or a VCL failure will be triggered. 0285 0286 Other conversions may fail if the argument can not be represented, 0287 because it is negative, too small or too large. Again, <span style="font-style:italic">*fallback*</span> will 0288 be returned if provided, or a VCL failure will be triggered. 0289 0290 <span style="font-style:italic">*real*</span> arguments will be rounded down. 0291 0292 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 0293 failure will be triggered. 0294 0295 Example<span style="color:#0057ae">::</span> 0296 <span style="color:#0057ae"> std.cache_req_body(std.bytes(something.somewhere, 10K));</span> 0297 <span style="color:#0057ae"> std.cache_req_body(std.bytes(integer=10*1024));</span> 0298 <span style="color:#0057ae"> std.cache_req_body(std.bytes(real=10.0*1024));</span> 0299 0300 <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], 0301 [BOOL bool], [BYTES bytes], [DURATION duration], [REAL real], 0302 [TIME time]) 0303 0304 Returns an INT from a STRING, BOOL or other quantity. 0305 0306 If the conversion of an <span style="font-style:italic">*s*</span> argument fails, <span style="font-style:italic">*fallback*</span> will be 0307 returned if provided, or a VCL failure will be triggered. 0308 0309 A <span style="font-style:italic">*bool*</span> argument will be returned as 0 for <span style="color:#0057ae">``false``</span> and 1 for 0310 <span style="color:#0057ae">``true``</span>. This conversion will never fail. 0311 0312 For a <span style="font-style:italic">*bytes*</span> argument, the number of bytes will be returned. This 0313 conversion will never fail. 0314 0315 A <span style="font-style:italic">*duration*</span> argument will be rounded down to the number of seconds 0316 and returned. 0317 0318 A <span style="font-style:italic">*real*</span> argument will be rounded down and returned. 0319 0320 For a <span style="font-style:italic">*time*</span> argument, the number of seconds since the UNIX epoch 0321 (1970-01-01 00:00:00 UTC) will be returned. 0322 0323 <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 0324 not be represented because it is too small or too large. If so, 0325 <span style="font-style:italic">*fallback*</span> will be returned if provided, or a VCL failure will be 0326 triggered. 0327 0328 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> 0329 arguments may be given or a VCL failure will be triggered. 0330 0331 Examples<span style="color:#0057ae">::</span> 0332 0333 <span style="color:#0057ae"> if (std.integer(req.http.foo, 0) > 5) {</span> 0334 <span style="color:#0057ae"> ...</span> 0335 <span style="color:#0057ae"> }</span> 0336 0337 <span style="color:#0057ae"> set resp.http.answer = std.integer(real=126.42/3);</span> 0338 0339 0340 <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]) 0341 0342 Converts the string <span style="font-style:italic">*s*</span> to the first IP number returned by the system 0343 library function <span style="color:#b08000">`getaddrinfo(3)`</span>. If conversion fails, <span style="font-style:italic">*fallback*</span> will 0344 be returned or VCL failure will happen. 0345 0346 The IP address includes a port number that can be found with <span style="color:#0057ae">``std.port()``</span> 0347 that defaults to 80. The default port can be set to a different value with 0348 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 0349 and a port number or service name. 0350 0351 When <span style="font-style:italic">*s*</span> contains both, the syntax is either <span style="color:#0057ae">``address:port``</span> or 0352 <span style="color:#0057ae">``address port``</span>. If the address is a numerical IPv6 address it must be 0353 enclosed between brackets, for example <span style="color:#0057ae">``[::1] 80``</span> or <span style="color:#0057ae">``[::1]:http``</span>. 0354 The <span style="font-style:italic">*fallback*</span> may also contain both an address and a port, but its default 0355 port is always 80. 0356 0357 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> 0358 and <span style="color:#0057ae">``AI_NUMERICSERV``</span> to avoid network lookups depending on the system's 0359 <span style="color:#b08000">`getaddrinfo(3)`</span> or nsswitch configuration. This makes "numerical" IP 0360 strings and services cheaper to convert. 0361 0362 Example<span style="color:#0057ae">::</span> 0363 0364 <span style="color:#0057ae"> if (std.ip(req.http.X-forwarded-for, "0.0.0.0") ~ my_acl) {</span> 0365 <span style="color:#0057ae"> ...</span> 0366 <span style="color:#0057ae"> }</span> 0367 0368 <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], 0369 [BOOL bool], [BYTES bytes], [DURATION duration], 0370 [TIME time]) 0371 0372 Returns a REAL from a STRING, BOOL or other quantity. 0373 0374 If the conversion of an <span style="font-style:italic">*s*</span> argument fails, <span style="font-style:italic">*fallback*</span> will be 0375 returned if provided, or a VCL failure will be triggered. 0376 0377 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 0378 <span style="color:#0057ae">``true``</span>. 0379 0380 For a <span style="font-style:italic">*bytes*</span> argument, the number of bytes will be returned. 0381 0382 For a <span style="font-style:italic">*duration*</span> argument, the number of seconds will be returned. 0383 0384 An <span style="font-style:italic">*integer*</span> argument will be returned as a REAL. 0385 0386 For a <span style="font-style:italic">*time*</span> argument, the number of seconds since the UNIX epoch 0387 (1970-01-01 00:00:00 UTC) will be returned. 0388 0389 None of these conversions other than <span style="font-style:italic">*s*</span> will fail. 0390 0391 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> 0392 arguments may be given or a VCL failure will be triggered. 0393 0394 Example<span style="color:#0057ae">::</span> 0395 0396 <span style="color:#0057ae"> if (std.real(req.http.foo, 0.0) > 5.5) {</span> 0397 <span style="color:#0057ae"> ...</span> 0398 <span style="color:#0057ae"> }</span> 0399 0400 <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]) 0401 0402 Returns a TIME from a STRING, REAL or INT argument. 0403 0404 For a STRING <span style="font-style:italic">*s*</span> argument, the following formats are supported<span style="color:#0057ae">::</span> 0405 0406 <span style="color:#0057ae"> "Sun, 06 Nov 1994 08:49:37 GMT"</span> 0407 <span style="color:#0057ae"> "Sunday, 06-Nov-94 08:49:37 GMT"</span> 0408 <span style="color:#0057ae"> "Sun Nov 6 08:49:37 1994"</span> 0409 <span style="color:#0057ae"> "1994-11-06T08:49:37"</span> 0410 <span style="color:#0057ae"> "784111777.00"</span> 0411 <span style="color:#0057ae"> "784111777"</span> 0412 0413 <span style="font-style:italic">*real*</span> and <span style="font-style:italic">*integer*</span> arguments are taken as seconds since the epoch. 0414 0415 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 0416 <span style="font-style:italic">*integer*</span> argument is given, <span style="font-style:italic">*fallback*</span> will be returned if provided, 0417 or a VCL failure will be triggered. 0418 0419 Examples<span style="color:#0057ae">::</span> 0420 0421 <span style="color:#0057ae"> if (std.time(resp.http.last-modified, now) < now - 1w) {</span> 0422 <span style="color:#0057ae"> ...</span> 0423 <span style="color:#0057ae"> }</span> 0424 0425 <span style="color:#0057ae"> if (std.time(int=2147483647) < now - 1w) {</span> 0426 <span style="color:#0057ae"> ...</span> 0427 <span style="color:#0057ae"> }</span> 0428 0429 LOGGING functions 0430 ================= 0431 0432 <span style="font-weight:bold">$Function</span> <span style="color:#0057ae">VOID</span> <span style="color:#644a9b">log</span>(STRANDS s) 0433 0434 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 0435 <span style="color:#0057ae">``SLT_VCL_Log``</span>. 0436 0437 Example<span style="color:#0057ae">::</span> 0438 0439 <span style="color:#0057ae"> std.log("Something fishy is going on with the vhost " + req.http.host);</span> 0440 0441 <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) 0442 0443 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 0444 formed by ORing the facility and level values. See your system's 0445 <span style="color:#0057ae">``syslog.h``</span> file for possible values. 0446 0447 Notice: Unlike VCL and other functions in the std vmod, this function 0448 will not fail VCL processing for workspace overflows: For an out of 0449 workspace condition, the <span style="color:#006e28">`std.syslog()`_</span> function has no effect. 0450 0451 Example<span style="color:#0057ae">::</span> 0452 0453 <span style="color:#0057ae"> std.syslog(9, "Something is wrong");</span> 0454 0455 This will send a message to syslog using <span style="color:#0057ae">``LOG_USER | LOG_ALERT``</span>. 0456 0457 <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) 0458 0459 Introduces a timestamp in the log with the current time, using the 0460 string <span style="font-style:italic">*s*</span> as the label. This is useful to time the execution of lengthy 0461 VCL subroutines, and makes the timestamps inserted automatically by 0462 Varnish more accurate. 0463 0464 Example<span style="color:#0057ae">::</span> 0465 0466 <span style="color:#0057ae"> std.timestamp("curl-request");</span> 0467 0468 0469 CONTROL and INFORMATION functions 0470 ================================= 0471 0472 <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>) 0473 0474 Returns <span style="color:#0057ae">``true``</span> if VCL version is at least <span style="font-style:italic">*REAL*</span>. 0475 0476 <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) 0477 0478 Return environment variable <span style="font-style:italic">*name*</span> or the empty string. See <span style="color:#b08000">`getenv(3)`</span>. 0479 0480 Example<span style="color:#0057ae">::</span> 0481 0482 <span style="color:#0057ae"> set req.http.My-Env = std.getenv("MY_ENV");</span> 0483 0484 0485 <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) 0486 0487 Caches the request body if it is smaller than <span style="font-style:italic">*size*</span>. Returns 0488 <span style="color:#0057ae">``true``</span> if the body was cached, <span style="color:#0057ae">``false``</span> otherwise. 0489 0490 Normally the request body can only be sent once. Caching it enables 0491 retrying backend requests with a request body, as usually the case 0492 with <span style="color:#0057ae">``POST``</span> and <span style="color:#0057ae">``PUT``</span>. 0493 0494 Example<span style="color:#0057ae">::</span> 0495 0496 <span style="color:#0057ae"> if (std.cache_req_body(1KB)) {</span> 0497 <span style="color:#0057ae"> ...</span> 0498 <span style="color:#0057ae"> }</span> 0499 0500 <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) 0501 0502 Controls when varnish reacts to an <span style="color:#0057ae">``Expect: 100-continue``</span> client 0503 request header. 0504 0505 Varnish always generates a <span style="color:#0057ae">``100 Continue``</span> response if requested by 0506 the client trough the <span style="color:#0057ae">``Expect: 100-continue``</span> header when waiting for 0507 request body data. 0508 0509 But, by default, the <span style="color:#0057ae">``100 Continue``</span> response is already generated 0510 immediately after <span style="color:#0057ae">``vcl_recv``</span> returns to reduce latencies under the 0511 assumption that the request body will be read eventually. 0512 0513 Calling <span style="color:#0057ae">``std.late_100_continue(true)``</span> in <span style="color:#0057ae">``vcl_recv``</span> will cause the 0514 <span style="color:#0057ae">``100 Continue``</span> response to only be sent when needed. This may cause 0515 additional latencies for processing request bodies, but is the correct 0516 behavior by strict interpretation of RFC7231. 0517 0518 This function has no effect outside <span style="color:#0057ae">``vcl_recv``</span> and after calling 0519 <span style="color:#0057ae">``std.cache_req_body()``</span> or any other function consuming the request 0520 body. 0521 0522 Example<span style="color:#0057ae">::</span> 0523 0524 <span style="color:#0057ae"> vcl_recv {</span> 0525 <span style="color:#0057ae"> std.late_100_continue(true);</span> 0526 0527 <span style="color:#0057ae"> if (req.method == "POST") {</span> 0528 <span style="color:#0057ae"> std.late_100_continue(false);</span> 0529 <span style="color:#0057ae"> return (pass);</span> 0530 <span style="color:#0057ae"> }</span> 0531 <span style="color:#0057ae"> ...</span> 0532 <span style="color:#0057ae"> }</span> 0533 0534 <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) 0535 0536 Sets the IP type-of-service (TOS) field for the current session to 0537 <span style="font-style:italic">*tos*</span>. Silently ignored if the listen address is a Unix domain socket. 0538 0539 Please note that the TOS field is not removed by the end of the 0540 request so probably want to set it on every request should you utilize 0541 it. 0542 0543 Example<span style="color:#0057ae">::</span> 0544 0545 <span style="color:#0057ae"> if (req.url ~ "^/slow/") {</span> 0546 <span style="color:#0057ae"> std.set_ip_tos(0);</span> 0547 <span style="color:#0057ae"> }</span> 0548 0549 <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) 0550 0551 Restores the <span style="font-style:italic">*h*</span> HTTP headers to their original state. 0552 0553 Example<span style="color:#0057ae">::</span> 0554 0555 <span style="color:#0057ae"> std.rollback(bereq);</span> 0556 0557 0558 DEPRECATED functions 0559 ==================== 0560 0561 <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) 0562 0563 <span style="font-weight:bold">**DEPRECATED**</span>: This function will be removed in a future version of 0564 varnish, use <span style="color:#006e28">`std.integer()`_</span> with a <span style="font-style:italic">*real*</span> argument and the 0565 <span style="color:#006e28">`std.round()`_</span> function instead, for example<span style="color:#0057ae">::</span> 0566 0567 <span style="color:#0057ae"> std.integer(real=std.round(...), fallback=...)</span> 0568 0569 Rounds the real <span style="font-style:italic">*r*</span> to the nearest integer, but round halfway cases 0570 away from zero (see <span style="color:#b08000">`round(3)`</span>). If conversion fails, <span style="font-style:italic">*fallback*</span> will 0571 be returned. 0572 0573 Examples<span style="color:#0057ae">::</span> 0574 0575 <span style="color:#0057ae"> set req.http.integer = std.real2integer(1140618699.00, 0);</span> 0576 <span style="color:#0057ae"> set req.http.posone = real2integer( 0.5, 0); # = 1.0</span> 0577 <span style="color:#0057ae"> set req.http.negone = real2integer(-0.5, 0); # = -1.0</span> 0578 0579 <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) 0580 0581 <span style="font-weight:bold">**DEPRECATED**</span>: This function will be removed in a future version of 0582 varnish, use <span style="color:#006e28">`std.time()`_</span> with a <span style="font-style:italic">*real*</span> argument and the 0583 <span style="color:#006e28">`std.round()`_</span> function instead, for example<span style="color:#0057ae">::</span> 0584 0585 <span style="color:#0057ae"> std.time(real=std.round(...), fallback=...)</span> 0586 0587 Rounds the real <span style="font-style:italic">*r*</span> to the nearest integer (see 0588 <span style="color:#006e28">`std.real2integer()`_</span>) and returns the corresponding time when 0589 interpreted as a unix epoch. If conversion fails, <span style="font-style:italic">*fallback*</span> will be 0590 returned. 0591 0592 Example<span style="color:#0057ae">::</span> 0593 0594 <span style="color:#0057ae"> set req.http.time = std.real2time(1140618699.00, now);</span> 0595 0596 <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) 0597 0598 <span style="font-weight:bold">**DEPRECATED**</span>: This function will be removed in a future version of 0599 varnish, use <span style="color:#006e28">`std.integer()`_</span> with a <span style="font-style:italic">*time*</span> argument instead, for 0600 example<span style="color:#0057ae">::</span> 0601 0602 <span style="color:#0057ae"> std.integer(time=..., fallback=...)</span> 0603 0604 Converts the time <span style="font-style:italic">*t*</span> to a integer. If conversion fails, 0605 <span style="font-style:italic">*fallback*</span> will be returned. 0606 0607 Example<span style="color:#0057ae">::</span> 0608 0609 <span style="color:#0057ae"> set req.http.int = std.time2integer(now, 0);</span> 0610 0611 <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) 0612 0613 <span style="font-weight:bold">**DEPRECATED**</span>: This function will be removed in a future version of 0614 varnish, use <span style="color:#006e28">`std.real()`_</span> with a <span style="font-style:italic">*time*</span> argument instead, for 0615 example<span style="color:#0057ae">::</span> 0616 0617 <span style="color:#0057ae"> std.real(time=..., fallback=...)</span> 0618 0619 Converts the time <span style="font-style:italic">*t*</span> to a real. If conversion fails, <span style="font-style:italic">*fallback*</span> will 0620 be returned. 0621 0622 Example<span style="color:#0057ae">::</span> 0623 0624 <span style="color:#0057ae"> set req.http.real = std.time2real(now, 1.0);</span> 0625 0626 0627 0628 SEE ALSO 0629 ======== 0630 0631 * <span style="font-weight:bold">:ref:</span><span style="color:#b08000">`varnishd(1)`</span> 0632 * <span style="font-weight:bold">:ref:</span><span style="color:#b08000">`vsl(7)`</span> 0633 * <span style="color:#b08000">`fnmatch(3)`</span> 0634 </pre></body></html>