Variable

This module provides enhanced variable support for VCL scripts.  It is backward-compatible with vmod_var, but doesn't share any code with it.  Compared to vmod_var, it provides the following new features:

  1. Both Varsnish 3 and 4 are supported.
  2. Variables are stored in hash tables with open addressing, to speed up accesses.
  3. Functions for testing existence and types of variables, and for unsetting a variable: defined(), type_of() and unset().
  4. The regset() and queryset() functions.
  5. Additional functions for global variables: global_clear(), global_defined() and global_unset().

The following is a short overview of the module and its features. For a detailed documentation, please refer to the manpage.

There are two kinds of variables: session-specific, which have the lifespan of one HTTP session (connection) and cease to exist when it is closed, and global, which are shared between all sessions.

Session-specific variables are typed, a pair of functions is provided for setting and retrieving variables of a particular type.  For example the function set_duration sets a duration variable, and get_duration retrieves its value:

 set beresp.ttl = variable.get_int("ttl");

Special functions are provided for testing if a variable is defined: the defined() function returns true if the variable is defined, and the type_of() function returns the type of the variable.

A special feature of this module are regset() and queryset() functions.  The regset() function allows you to parse a string (e.g. a URL or header value) according to a regular expression and to set several variables at once to selected substrings of the input string, optionally converting between different types.

For example, the fragment below sets ttl and grace parameters of the object according to the Surrogate-Control header:

  variable.regset("ttl:d=\1s,grace:d=\2s",
                  "^(?:.*,)?max-age=([0-9]+)(?:+([0-9]+))",
                   beresp.http.Surrogate-Control);
  set beresp.ttl = variable.get_duration("ttl");
  set beresp.grace = variable.get_duration("grace");

The first argument to regset declares a list of variables to be set, along with their types (:d standing for "duration") and values to be assigned (after = signs).  The latter use backreferenses to refer to the substrings captured by the regular expression and add the "s" suffix to each captured string to obtain a valid duration.

Status: 
Used in production
Licence: 
Varnish version supported: 
Commercial support: 
NXC International