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. vmod-cookieplus also allows you to remove unused client side Cookies.

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

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.

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.

    • default

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

add

VOID add(STRING name, STRING value, BOOL keep = 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.

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.

    • 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.

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.

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.

    • 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)

  • 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.

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.

    • 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.

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.