/libvmod-cookie

A varnish vmod for simpler use of the cookie header

Primary LanguageCOtherNOASSERTION

vmod_cookie

Varnish Cookie Module

Author: Lasse Karstensen
Date: 2013-07-12
Version: 1.0
Manual section:3

SYNOPSIS

import cookie;

DESCRIPTION

Functions to handle the content of the Cookie header without complex use of regular expressions.

Parses a cookie header into an internal data store, where per-cookie get/set/delete functions are available. A filter_except() method removes all but a set comma-separated list of cookies.

A convenience function for formatting the Set-Cookie Expires date field is also included. It might be needed to use libvmod-header if there might be multiple Set-Cookie response headers.

This vmod allocates memory on the session workspace. It needs twice the memory requirement of your cookie string, usually less than 2KB. If you have many long cookies, or use other vmods that use the same memory segment, you might need to increase the sess_workspace parameter.

Only within a single VMOD call is the state set by cookie.parse() / cookie.set() guaranteed to persist. This VMOD was designed to be used for cleaning up a request in vcl_recv, but works outside recv if needed. In such a case it is necessary to run cookie.parse() again.

FUNCTIONS

parse

Prototype
parse(STRING S)
Return value
VOID
Description
Parse the cookie string in string S. The parsed values are only guaranteed to exist within a single VCL function. Implicit clean() if run more than once.
Example
sub vcl_recv {
        cookie.parse(req.http.Cookie);
}

clean

Prototype
clean()
Return value
VOID
Description
Clean up all previously parse()-d cookies. Probably of limited use. It is not necessary to run clean() in normal operation.
Example
sub vcl_recv {
        cookie.clean();
}

get

Prototype
get(STRING cookiename)
Return value
STRING
Description
Get the value of a cookie, as stored in internal vmod storage. If the cookie name does not exists, an empty string is returned.
Example
import std;
sub vcl_recv {
        cookie.parse("cookie1: value1; cookie2: value2;");
        std.log("cookie1 value is: " + cookie.get("cookie1"));
}

set

Prototype
set(STRING cookiename, STRING cookievalue)
Return value
VOID
Description
Set the internal vmod storage value for a cookie to a value.
Example
sub vcl_recv {
        cookie.set("cookie1", "value1");
        std.log("cookie1 value is: " + cookie.get("cookie1"));
}

delete

Prototype
delete(STRING cookiename)
Return value
VOID
Description
Delete a cookie from internal vmod storage if it exists.
Example
sub vcl_recv {
        cookie.parse("cookie1: value1; cookie2: value2;");
        cookie.delete("cookie2");
        // get_string() will now yield "cookie1: value1";
}

filter_except

Prototype
filter_except(STRING cookienames)
Return value
VOID
Description
Delete all cookies from internal vmod storage that is not in the comma-separated argument cookienames.
Example
sub vcl_recv {
        cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
        cookie.filter_except("cookie1,cookie2");
        // get_string() will now yield
        // "cookie1: value1; cookie2: value2;";
}

get_string

Prototype
get_string()
Return value
STRING
Description
Get a Cookie string value with all cookies in internal vmod storage.
Example
sub vcl_recv {
        cookie.parse(req.http.cookie);
        cookie.filter_except("SESSIONID,PHPSESSID");
        set req.http.cookie = cookie.get_string();
}

format_rfc1123

Prototype
format_rfc1123(TIME, DURATION)
Return value
STRING
Description

Get a RFC1123 formatted date string suitable for inclusion in a Set-Cookie response header.

Care should be taken if the response has multiple Set-Cookie headers. In that case the header vmod should be used.

Example
sub vcl_deliver {
        # Set a userid cookie on the client that lives for 5 minutes.
        set resp.http.Set-Cookie = "userid=" + req.http.userid + "; Expires=" + cookie.format_rfc1123(now, 5m) + "; httpOnly";
}

INSTALLATION

The source tree is based on autotools to configure the building, and does also have the necessary bits in place to do functional unit tests using the varnishtest tool.

Usage:

./configure VARNISHSRC=DIR [VMODDIR=DIR]

VARNISHSRC is the directory of the Varnish source tree for which to compile your vmod. Both the VARNISHSRC and VARNISHSRC/include will be added to the include search paths for your module.

Optionally you can also set the vmod install directory by adding VMODDIR=DIR (defaults to the pkg-config discovered directory from your Varnish installation).

Make targets:

  • make - builds the vmod
  • make install - installs the vmod in VMODDIR
  • make check - runs the unit tests in src/tests/*.vtc

In your VCL you could then use this vmod along the following lines:

import cookie;
sub vcl_recv {
        cookie.parse(req.http.cookie);
        cookie.filter_except("SESSIONID,PHPSESSID");
        set req.http.cookie = cookie.get_string();
}

HISTORY

This manual page was released as part of the libvmod-example package, demonstrating how to create an out-of-tree Varnish vmod.

COPYRIGHT

This document is licensed under the same license as the libvmod-example project. See LICENSE for details.

  • Copyright (c) 2011-2013 Varnish Software