Varnish Cache Plus

Cookie Plus (cookieplus)

Description

vmod-cookieplus is an advanced Cookie VMOD for interacting with request and response Cookies. vmod-cookieplus allows you to get, add, delete, and keep Cookie and Set-Cookie values. It also allows you to remove unused client side Cookies.

All functions will by default parse Cookies from the req.http.Cookie and Set-Cookies from resp.http.Set-Cookie, unless otherwise specified. Backend context is supported.

All functions keep an internal state of Cookies and Set-Cookies until written out using write() or setcookie_write().

Set-Cookie operations all have a setcookie prefix and can only be used where a resp or beresp object exists.

Example VCL

Only allow application specific Cookies.

vcl 4.0;

import cookieplus;

sub vcl_recv
{
    // Keep these Cookies
    cookieplus.keep("JSESSIONID");
    cookieplus.keep_regex("^BNES_SSESS");
    cookieplus.keep_regex("^SSESS[a-zA-Z0-9]+$");
    cookieplus.keep_regex("^SESS[a-zA-Z0-9]+$");

    // Any Cookie that is not kept will be removed
    cookieplus.write();
}

Conditionally allow application specific Cookies.

vcl 4.0;

import cookieplus;

sub vcl_recv
{
    // Mark all Cookies for removal
    cookieplus.keep("");

    // Only allow these Cookies if the URL allows for it
    if (req.url ~ "^/admin") {
        cookieplus.keep("JSESSIONID");
        cookieplus.keep_regex("^BNES_SSESS");
        cookieplus.keep_regex("^SSESS[a-zA-Z0-9]+$");
        cookieplus.keep_regex("^SESS[a-zA-Z0-9]+$");
    }

    // Any Cookie that is not kept will be removed
    cookieplus.write();
}

VCL Cookies

Add a VCL cookie.

vcl 4.0;

import cookieplus;
import std;

sub vcl_deliver
{
    // Get the vcpsess Cookie value
    set req.http.X-vcpsess = cookieplus.get("vcpsess", "");

    if (req.http.X-vcpsess == "") {
        // Create a new random vcpsess value
        set req.http.X-vcpsess = std.random(1, 10000000) + "." + std.random(1, 10000000);

        // Create a vcpsess Set-Cookie, valid for 30 days
        cookieplus.setcookie_add("vcpsess", req.http.X-vcpsess, 30d, req.http.Host, "/");

        // Write the Set-Cookie to the response
        cookieplus.setcookie_write();
    }

    // req.http.X-vcpsess now contains the vcpsess cookie value
}

Only allow application specific Set-Cookie values from the backend.

vcl 4.0;

import cookieplus;

sub vcl_backend_response
{
    // Mark all Set-Cookies for removal
    cookieplus.setcookie_keep("");

    // Only allow these Set-Cookies if the URL allows for it
    if (bereq.url ~ "^/admin") {
        cookieplus.setcookie_keep("JSESSIONID");
        cookieplus.setcookie_keep_regex("^BNES_SSESS");
        cookieplus.setcookie_keep_regex("^SSESS[a-zA-Z0-9]+$");
        cookieplus.setcookie_keep_regex("^SESS[a-zA-Z0-9]+$");
    }

    // Any Set-Cookie that is not kept will be removed
    cookieplus.setcookie_write();
}

Conditionally allow application specific Cookies and remove all other Cookies from client.

vcl 4.0;

import cookieplus;

sub vcl_recv
{
    // Mark all Cookies for removal
    cookieplus.keep("");

    // Only allow these Cookies if the URL allows for it
    if (req.url ~ "^/admin") {
        cookieplus.keep("JSESSIONID");
        cookieplus.keep_regex("^BNES_SSESS");
        cookieplus.keep_regex("^SSESS[a-zA-Z0-9]+$");
        cookieplus.keep_regex("^SESS[a-zA-Z0-9]+$");
    }

    // Any Cookie that is not kept will be removed
    cookieplus.write();
}

sub vcl_backend_response
{
    // Mark all Set-Cookies for removal
    cookieplus.setcookie_keep("");

    // Only allow these Set-Cookies if the URL allows for it
    if (bereq.url ~ "^/admin") {
        cookieplus.setcookie_keep("JSESSIONID");
        cookieplus.setcookie_keep_regex("^BNES_SSESS");
        cookieplus.setcookie_keep_regex("^SSESS[a-zA-Z0-9]+$");
        cookieplus.setcookie_keep_regex("^SESS[a-zA-Z0-9]+$");
    }

    // Any Set-Cookie that is not kept will be removed
    cookieplus.setcookie_write();
}

sub vcl_deliver
{
    // Do not attempt to delete these Cookies from the client
    // as they may have been conditionally removed, but we want
    // to keep them.
    cookieplus.remove_deleted("JSESSIONID");
    cookieplus.remove_deleted_regex("^BNES_SSESS");
    cookieplus.remove_deleted_regex("^SSESS[a-zA-Z0-9]+$");
    cookieplus.remove_deleted_regex("^SESS[a-zA-Z0-9]+$");

    // Do not delete Google Analytic Cookies
    cookieplus.remove_deleted("_ga");
    cookieplus.remove_deleted("_git");
    cookieplus.remove_deleted("_gat");
    cookieplus.remove_deleted_regex("^__ut..$");

    // Delete all other Cookies that were sent in the request
    cookieplus.setcookie_add_deleted();
    cookieplus.setcookie_write();
}

Functions

get

STRING get(STRING name, STRING default)

  • Description

    Get the Cookie value for name.

  • Return value

    The Cookie value for name. If not found, default is returned.

    • name

      The name of the Cookie. The first Cookie to match is used.

    • default

      The return value if name is not found. Optional.

get_regex

STRING get_regex(STRING regex, STRING default)

  • Description

    Get the Cookie value where the name matches regex.

  • Return value

    The Cookie value where the name matches regex. If not found, default is returned.

    • regex

      The regular expression used to match on the name. Only the first matching Cookie is used. This value is static and cannot change between calls.

    • default

      The return value if no matching Cookie is not found. Optional.

add

VOID add(STRING name, STRING value, BOOL keep = true, BOOL override = true)

  • Description

    Add a Cookie with name and value.

  • Return value

    None

    • name

      The name of the Cookie to add.

    • value

      The value of the Cookie to add.

    • keep

      If in keep_mode and keep is true, the Cookie is always kept when writing. Defaults to true.

    • override

      If the cookie exists, override it. Defaults to true.

delete

VOID delete(STRING name, BOOL delete_keep = false)

  • Description

    Delete all Cookies that match name.

  • Return value

    None.

    • name

      The name of the Cookie to delete. All Cookies which match name are deleted.

    • delete_keep

      If delete_keep is true, delete kept Cookies. Defaults to false.

delete_regex

VOID delete_regex(STRING regex, BOOL delete_keep = false)

  • Description

    Delete all Cookies that match regex.

  • Return value

    None.

    • regex

      The regular expression used to match on the name. All Cookies which match regex are deleted. This value is static and cannot change between calls.

    • delete_keep

      If delete_keep is true, delete kept Cookies. Defaults to false.

keep

VOID keep(STRING name)

  • Description

    Keep Cookies which match name. This enables keep_mode. When writing, only Cookies which have been kept are written.

  • Return value

    None.

    • name

      The name of the Cookie to keep. All Cookies which match name are kept.

keep_regex

VOID keep_regex(STRING regex)

  • Description

    Keep Cookies which match regex. This enables keep_mode. When writing, only Cookies which have been kept are written.

  • Return value

    None.

    • regex

      The regular expression used to match on the name. All Cookies which match regex are kept. This value is static and cannot change between calls.

remove_deleted

VOID remove_deleted(STRING name)

  • Description

    vmod-cookieplus keeps track of what Cookies have been deleted. This is so you can delete them from the client using setcookie_add_deleted(). This function removes a Cookie from the deleted list, so it cannot be removed from the client.

  • Return value

    None.

    • name

      The name of the Cookie to remove from the deleted Cookie list. All Cookies which match name are deleted.

remove_deleted_regex

VOID remove_deleted_regex(STRING regex)

  • Description

    vmod-cookieplus keeps track of what Cookies have been deleted. This is so you can delete them from the client using setcookie_add_deleted(). This function removes Cookies which match regex from the deleted list, so they cannot be removed from the client.

  • Return value

    None.

    • regex

      The regular expression used to match on the name of deleted Cookies. All Cookies which match regex are deleted. This value is static and cannot change between calls.

count

INT count()

  • Description

    Count the number of Cookies which will be written.

  • Return value

    The number of Cookies which will be written.

write

VOID write()

  • Description

    Write Cookies back out to the Cookie header.

  • Return value

    None.

as_string

STRING as_string()

  • Description

    Return Cookie header string. Can be used to write cookies to a different header.

  • Return value

    A Cookie header formatted string.

parse

VOID parse(STRING cookies)

  • Description

    Parse Cookie values from cookies.

  • Return value

    None

    • cookies

      The value to parse Cookies from.

reset

VOID reset()

  • Description

    Reset the internal state for Cookies.

  • Return value

    None.

setcookie_get

STRING setcookie_get(STRING name, STRING default)

  • Description

    Get the Set-Cookie value for name.

  • Return value

    The Set-Cookie value for name. If not found, default is returned.

    • name

      The name of the Cookie. The first Set-Cookie to match is used.

    • default

      The return value if name is not found.

setcookie_get_regex

STRING setcookie_get_regex(STRING regex, STRING default)

  • Description

    Get the Set-Cookie value where the name matches regex.

  • Return value

    The Set-Cookie value where the name matches regex. If not found, default is returned.

    • regex

      The regular expression used to match on the name. Only the first matching Set-Cookie is used. This value is static and cannot change between calls.

    • default

      The return value if no matching Set-Cookie is not found.

setcookie_add

VOID setcookie_add(STRING name, STRING value, DURATION ttl = 0, STRING domain = "", STRING path = "", BOOL secure = false, BOOL httponly = false, STRING extra = "", BOOL keep = true, BOOL override = true)

  • Description

    Add a Set-Cookie.

  • Return value

    None

    • name

      The Set-Cookie name.

    • value

      The Set-Cookie value.

    • ttl

      The Cookie expiration. Defaults to 0, which is a session only Cookie. A negative ttl deletes the cookie.

    • domain

      The Cookie domain. Defaults to no domain.

    • path

      The Cookie path. Defaults to no path.

    • secure

      Is this Cookie secure (HTTPS only)? Defaults to false.

    • httponly

      Is this Cookie HTTP only (no Javascript access)? Defaults to false.

    • extra

      Extra Set-Cookie attributes which are appended to the header.

    • keep

      If in keep_mode and keep is true, the Set-Cookie is always kept when writing. Defaults to true.

    • override

      If the Set-Cookie name exists, override it. Defaults to true.

setcookie_add_deleted

VOID setcookie_add_deleted(BOOL keep = true)

  • Description

    Add a Set-Cookie delete headers for Cookies that were previously deleted.

  • Return value

    None

    • keep

      If in keep_mode and keep is true, these Set-Cookies are always kept when writing. Defaults to true.

setcookie_delete

VOID setcookie_delete(STRING name, BOOL delete_keep = false)

  • Description

    Delete all Set-Cookies that match name.

  • Return value

    None.

    • name

      The name of the Set-Cookie to delete. All Set-Cookies which match name are deleted.

    • delete_keep

      If delete_keep is true, delete kept Set-Cookies. Defaults to false.

setcookie_delete_regex

VOID setcookie_delete_regex(STRING regex, BOOL delete_keep = false)

  • Description

    Delete all Set-Cookies that match regex.

  • Return value

    None.

    • regex

      The regular expression used to match on the name. All Set-Cookies which match regex are deleted. This value is static and cannot change between calls.

    • delete_keep

      If delete_keep is true, delete kept Set-Cookies. Defaults to false.

setcookie_keep

VOID setcookie_keep(STRING name)

  • Description

    Keep Set-Cookies which match name. This enables keep_mode. When writing, only Set-Cookies which have been kept are written.

  • Return value

    None.

    • name

      The name of the Set-Cookie to keep. All Set-Cookies which match name are kept.

setcookie_keep_regex

VOID setcookie_keep_regex(STRING regex)

  • Description

    Keep Set-Cookies which match regex. This enables keep_mode. When writing, only Set-Cookies which have been kept are written.

  • Return value

    None.

    • regex

      The regular expression used to match on the name. All Set-Cookies which match regex are kept. This value is static and cannot change between calls.

setcookie_count

INT setcookie_count()

  • Description

    Count the number of Set-Cookies which will be written.

  • Return value

    The number of Set-Cookies which will be written.

setcookie_write

VOID setcookie_write(HEADER header = (be)resp.http.Set-Cookie)

  • Description

    Write Set-Cookies back out to the Set-Cookie header.

  • Return value

    None.

    • header

      The response header to write the Set-Cookie values to. Defaults to Set-Cookie.

setcookie_parse

VOID setcookie_parse(HEADER header)

  • Description

    Parse Set-Cookie values from header.

  • Return value

    None

    • header

      The header to parse Set-Cookie values from.

setcookie_reset

VOID setcookie_reset()

  • Description

    Reset the internal state for Set-Cookies.

  • Return value

    None.