.\" Man page generated from reStructuredText.
.
.TH VMOD_COOKIE 3 "" "" ""
.SH NAME
vmod_cookie \- Varnish Cookie Module
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" 
.
.\" NB:  This file is machine generated, DO NOT EDIT!
.
.\" 
.
.\" Edit vmod.vcc and run make instead
.
.\" 
.
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import cookie [from "path"] ;

VOID clean()

VOID delete(STRING cookiename)

VOID filter(STRING filterstring)

VOID filter_except(STRING filterstring)

STRING format_rfc1123(TIME now, DURATION timedelta)

STRING get(STRING cookiename)

STRING get_string()

BOOL isset(STRING cookiename)

VOID parse(STRING cookieheader)

VOID set(STRING cookiename, STRING value)
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
Handle HTTP cookies easier in Varnish VCL. (without regex)
.sp
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 filter() method removes a comma\-
separated list of cookies.
.sp
A convenience function for formatting the Set\-Cookie Expires date field
is also included. If there are multiple Set\-Cookie headers vmod\-header
should be used.
.sp
The state loaded with cookie.parse() has a lifetime of the current request
or backend request context. To pass variables to the backend request, store
the contents as fake bereq headers.
.\" vcl-start
.
.sp
Filtering example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vcl 4.0;

import cookie;

backend default { .host = "192.0.2.11"; .port = "8080"; }

sub vcl_recv {
    if (req.http.cookie) {
        cookie.parse(req.http.cookie);
        # Either delete the ones you want to get rid of:
        cookie.delete("cookie2");
        # or filter everything but a few:
        cookie.filter_except("SESSIONID,PHPSESSID");

        # Store it back into req so it will be passed to the backend.
        set req.http.cookie = cookie.get_string();

        # If empty, unset so the builtin VCL can consider it for caching.
        if (req.http.cookie == "") {
            unset req.http.cookie;
        }
    }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.\" vcl-end
.
.SS VOID clean()
.INDENT 0.0
.TP
.B Description
Clean up previously parsed cookies. It is not necessary to run clean()
in normal operations.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sub vcl_recv {
        cookie.clean();
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS VOID delete(STRING cookiename)
.INDENT 0.0
.TP
.B Description
Delete \fIcookiename\fP from internal vmod storage if it exists.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sub vcl_recv {
    cookie.parse("cookie1: value1; cookie2: value2;");
    cookie.delete("cookie2");
    // get_string() will now yield "cookie1: value1";
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS VOID filter(STRING filterstring)
.INDENT 0.0
.TP
.B Description
Delete all cookies from internal vmod storage that are in the
comma\-separated argument cookienames.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sub vcl_recv {
        cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
        cookie.filter("cookie1,cookie2");
        // get_string() will now yield
        // "cookie3: value3";
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS VOID filter_except(STRING filterstring)
.INDENT 0.0
.TP
.B Description
Delete all cookies from internal vmod storage that is not in the
comma\-separated argument cookienames.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
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;";
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS STRING format_rfc1123(TIME now, DURATION timedelta)
.INDENT 0.0
.TP
.B Description
Get a RFC1123 formatted date string suitable for inclusion in a
Set\-Cookie response header.
.sp
Care should be taken if the response has multiple Set\-Cookie headers.
In that case the header vmod should be used.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
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";
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS STRING get(STRING cookiename)
.INDENT 0.0
.TP
.B Description
Get the value of \fIcookiename\fP, as stored in internal vmod storage. If \fIcookiename\fP does not exist an empty string is returned.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import std;
sub vcl_recv {
        cookie.parse("cookie1: value1; cookie2: value2;");
        std.log("cookie1 value is: " + cookie.get("cookie1"));
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS STRING get_string()
.INDENT 0.0
.TP
.B Description
Get a Cookie string value with all cookies in internal vmod storage. Does
not modify internal storage.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sub vcl_recv {
        cookie.parse(req.http.cookie);
        cookie.filter_except("SESSIONID,PHPSESSID");
        set req.http.cookie = cookie.get_string();
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS BOOL isset(STRING cookiename)
.INDENT 0.0
.TP
.B Description
Check if \fIcookiename\fP is set in the internal vmod storage.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import std;
sub vcl_recv {
        cookie.parse("cookie1: value1; cookie2: value2;");
        if (cookie.isset("cookie2")) {
                std.log("cookie2 is set.");
        }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS VOID parse(STRING cookieheader)
.INDENT 0.0
.TP
.B Description
Parse the cookie string in \fIcookieheader\fP\&. If state already exists, clean() will be run first.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sub vcl_recv {
        cookie.parse(req.http.Cookie);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS VOID set(STRING cookiename, STRING value)
.INDENT 0.0
.TP
.B Description
Set the internal vmod storage for \fIcookiename\fP to \fIvalue\fP\&.
.TP
.B Example
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sub vcl_recv {
        cookie.set("cookie1", "value1");
        std.log("cookie1 value is: " + cookie.get("cookie1"));
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.\" Generated by docutils manpage writer.
.