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