File: //usr/share/doc/varnish/html/reference/vmod_cookie.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>VMOD cookie - Varnish Cookie Module — Varnish version 6.4.0 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '6.4.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Varnish version 6.4.0 documentation" href="../index.html" />
<link rel="up" title="The Varnish Reference Manual" href="index.html" />
<link rel="next" title="VMOD directors - Varnish Directors Module" href="vmod_directors.html" />
<link rel="prev" title="VMOD blob - Utilities for the VCL blob type, encoding and decoding" href="vmod_blob.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="vmod_directors.html" title="VMOD directors - Varnish Directors Module"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="vmod_blob.html" title="VMOD blob - Utilities for the VCL blob type, encoding and decoding"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Varnish version 6.4.0 documentation</a> »</li>
<li><a href="index.html" accesskey="U">The Varnish Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="vmod-cookie-varnish-cookie-module">
<span id="vmod-cookie-3"></span><h1>VMOD cookie - Varnish Cookie Module<a class="headerlink" href="#vmod-cookie-varnish-cookie-module" title="Permalink to this headline">¶</a></h1>
<div class="section" id="synopsis">
<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
<pre class="literal-block">
import cookie [as name] [from "path"]
<a class="reference internal" href="#cookie-clean"><em>VOID clean()</em></a>
<a class="reference internal" href="#cookie-delete"><em>VOID delete(STRING cookiename)</em></a>
<a class="reference internal" href="#cookie-filter"><em>VOID filter(STRING filterstring)</em></a>
<a class="reference internal" href="#cookie-filter-re"><em>VOID filter_re(STRING expression)</em></a>
<a class="reference internal" href="#cookie-keep"><em>VOID keep(STRING filterstring)</em></a>
<a class="reference internal" href="#cookie-keep-re"><em>VOID keep_re(STRING expression)</em></a>
<a class="reference internal" href="#cookie-format-rfc1123"><em>STRING format_rfc1123(TIME now, DURATION timedelta)</em></a>
<a class="reference internal" href="#cookie-get"><em>STRING get(STRING cookiename)</em></a>
<a class="reference internal" href="#cookie-get-re"><em>STRING get_re(STRING expression)</em></a>
<a class="reference internal" href="#cookie-get-string"><em>STRING get_string()</em></a>
<a class="reference internal" href="#cookie-isset"><em>BOOL isset(STRING cookiename)</em></a>
<a class="reference internal" href="#cookie-parse"><em>VOID parse(STRING cookieheader)</em></a>
<a class="reference internal" href="#cookie-set"><em>VOID set(STRING cookiename, STRING value)</em></a>
</pre>
</div>
<div class="section" id="description">
<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Handle HTTP cookies more easily in Varnish VCL.</p>
<p>Parses a cookie header into an internal data store, where per-cookie
get/set/delete functions are available. A keep() function removes all
but a set comma-separated list of cookies. A filter() function removes a comma-
separated list of cookies.</p>
<p>Regular expressions can be used for either selecting cookies, deleting matching
cookies and deleting non-matching cookie names.</p>
<p>A convenience function for formatting the Set-Cookie Expires date field
is also included.</p>
<p>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.</p>
<p>Filtering example:</p>
<div class="highlight-python"><pre>import cookie;
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 delete all but a few:
cookie.keep("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;
}
}
}</pre>
</div>
<div class="section" id="void-clean">
<span id="cookie-clean"></span><h3>VOID clean()<a class="headerlink" href="#void-clean" title="Permalink to this headline">¶</a></h3>
<p>Clean up previously parsed cookies. It is not necessary to run clean()
in normal operations.</p>
<p>Example:</p>
<div class="highlight-python"><pre>sub vcl_recv {
cookie.clean();
}</pre>
</div>
</div>
<div class="section" id="void-delete-string-cookiename">
<span id="cookie-delete"></span><h3>VOID delete(STRING cookiename)<a class="headerlink" href="#void-delete-string-cookiename" title="Permalink to this headline">¶</a></h3>
<p>Delete <tt class="docutils literal"><span class="pre">cookiename</span></tt> from internal vmod storage if it exists.</p>
<p>Example:</p>
<div class="highlight-python"><pre>sub vcl_recv {
cookie.parse("cookie1: value1; cookie2: value2;");
cookie.delete("cookie2");
# get_string() will now yield "cookie1: value1";
}</pre>
</div>
</div>
<div class="section" id="void-filter-string-filterstring">
<span id="cookie-filter"></span><h3>VOID filter(STRING filterstring)<a class="headerlink" href="#void-filter-string-filterstring" title="Permalink to this headline">¶</a></h3>
<p>Delete all cookies from internal vmod storage that are in the
comma-separated argument cookienames.</p>
<p>Example:</p>
<div class="highlight-python"><pre>sub vcl_recv {
cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
cookie.filter("cookie1,cookie2");
# get_string() will now yield
# "cookie3: value3";
}</pre>
</div>
</div>
<div class="section" id="void-filter-re-string-expression">
<span id="cookie-filter-re"></span><h3>VOID filter_re(STRING expression)<a class="headerlink" href="#void-filter-re-string-expression" title="Permalink to this headline">¶</a></h3>
<p>Delete all cookies from internal vmod storage that matches the
regular expression <tt class="docutils literal"><span class="pre">expression</span></tt>.</p>
<p>Example:</p>
<div class="highlight-python"><pre>sub vcl_recv {
cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
cookie.filter_re("^cookie[12]$");
# get_string() will now yield
# "cookie3: value3";
}</pre>
</div>
</div>
<div class="section" id="void-keep-string-filterstring">
<span id="cookie-keep"></span><h3>VOID keep(STRING filterstring)<a class="headerlink" href="#void-keep-string-filterstring" title="Permalink to this headline">¶</a></h3>
<p>Delete all cookies from internal vmod storage that is not in the
comma-separated argument cookienames.</p>
<p>Example:</p>
<div class="highlight-python"><pre>sub vcl_recv {
cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
cookie.keep("cookie1,cookie2");
# get_string() will now yield
# "cookie1: value1; cookie2: value2;";
}</pre>
</div>
</div>
<div class="section" id="void-keep-re-string-expression">
<span id="cookie-keep-re"></span><h3>VOID keep_re(STRING expression)<a class="headerlink" href="#void-keep-re-string-expression" title="Permalink to this headline">¶</a></h3>
<p>Delete all cookies from internal vmod storage that does not match
expression <tt class="docutils literal"><span class="pre">expression</span></tt>.</p>
<p>Example:</p>
<div class="highlight-python"><pre>sub vcl_recv {
cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
cookie.keep_re("^cookie1,cookie2");
# get_string() will now yield
# "cookie1: value1; cookie2: value2;";
}</pre>
</div>
</div>
<div class="section" id="string-format-rfc1123-time-now-duration-timedelta">
<span id="cookie-format-rfc1123"></span><h3>STRING format_rfc1123(TIME now, DURATION timedelta)<a class="headerlink" href="#string-format-rfc1123-time-now-duration-timedelta" title="Permalink to this headline">¶</a></h3>
<p>Get a RFC1123 formatted date string suitable for inclusion in a
Set-Cookie response header.</p>
<p>Care should be taken if the response has multiple Set-Cookie headers.
In that case the header vmod should be used.</p>
<p>Example:</p>
<div class="highlight-python"><pre>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";
}</pre>
</div>
</div>
<div class="section" id="string-get-string-cookiename">
<span id="cookie-get"></span><h3>STRING get(STRING cookiename)<a class="headerlink" href="#string-get-string-cookiename" title="Permalink to this headline">¶</a></h3>
<p>Get the value of <tt class="docutils literal"><span class="pre">cookiename</span></tt>, as stored in internal vmod storage. If
<tt class="docutils literal"><span class="pre">cookiename</span></tt> does not exist an empty string is returned.</p>
<p>Example:</p>
<div class="highlight-python"><pre>import std;
sub vcl_recv {
cookie.parse("cookie1: value1; cookie2: value2;");
std.log("cookie1 value is: " + cookie.get("cookie1"));
}</pre>
</div>
</div>
<div class="section" id="string-get-re-string-expression">
<span id="cookie-get-re"></span><h3>STRING get_re(STRING expression)<a class="headerlink" href="#string-get-re-string-expression" title="Permalink to this headline">¶</a></h3>
<p>Get the value of the first cookie in internal vmod storage that matches
regular expression <tt class="docutils literal"><span class="pre">expression</span></tt>. If nothing matches, an empty string
is returned.</p>
<p>Example:</p>
<div class="highlight-python"><pre>import std;
sub vcl_recv {
cookie.parse("cookie1: value1; cookie2: value2;");
std.log("cookie1 value is: " + cookie.get_re("^cookie1$"));
}</pre>
</div>
</div>
<div class="section" id="string-get-string">
<span id="cookie-get-string"></span><h3>STRING get_string()<a class="headerlink" href="#string-get-string" title="Permalink to this headline">¶</a></h3>
<p>Get a Cookie string value with all cookies in internal vmod storage. Does
not modify internal storage.</p>
<p>Example:</p>
<div class="highlight-python"><pre>sub vcl_recv {
cookie.parse(req.http.cookie);
cookie.keep("SESSIONID,PHPSESSID");
set req.http.cookie = cookie.get_string();
}</pre>
</div>
</div>
<div class="section" id="bool-isset-string-cookiename">
<span id="cookie-isset"></span><h3>BOOL isset(STRING cookiename)<a class="headerlink" href="#bool-isset-string-cookiename" title="Permalink to this headline">¶</a></h3>
<p>Check if <tt class="docutils literal"><span class="pre">cookiename</span></tt> is set in the internal vmod storage.</p>
<p>Example:</p>
<div class="highlight-python"><pre>import std;
sub vcl_recv {
cookie.parse("cookie1: value1; cookie2: value2;");
if (cookie.isset("cookie2")) {
std.log("cookie2 is set.");
}
}</pre>
</div>
</div>
<div class="section" id="void-parse-string-cookieheader">
<span id="cookie-parse"></span><h3>VOID parse(STRING cookieheader)<a class="headerlink" href="#void-parse-string-cookieheader" title="Permalink to this headline">¶</a></h3>
<p>Parse the cookie string in <tt class="docutils literal"><span class="pre">cookieheader</span></tt>. If state already exists,
<tt class="docutils literal"><span class="pre">clean()</span></tt> will be run first.</p>
<p>Example:</p>
<div class="highlight-python"><pre>sub vcl_recv {
cookie.parse(req.http.Cookie);
}</pre>
</div>
</div>
<div class="section" id="void-set-string-cookiename-string-value">
<span id="cookie-set"></span><h3>VOID set(STRING cookiename, STRING value)<a class="headerlink" href="#void-set-string-cookiename-string-value" title="Permalink to this headline">¶</a></h3>
<p>Set the internal vmod storage for <tt class="docutils literal"><span class="pre">cookiename</span></tt> to <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
<p>Example:</p>
<div class="highlight-python"><pre>sub vcl_recv {
cookie.set("cookie1", "value1");
std.log("cookie1 value is: " + cookie.get("cookie1"));
}</pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="vmod_blob.html"
title="previous chapter">VMOD blob - Utilities for the VCL blob type, encoding and decoding</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="vmod_directors.html"
title="next chapter">VMOD directors - Varnish Directors Module</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/reference/vmod_cookie.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="vmod_directors.html" title="VMOD directors - Varnish Directors Module"
>next</a> |</li>
<li class="right" >
<a href="vmod_blob.html" title="VMOD blob - Utilities for the VCL blob type, encoding and decoding"
>previous</a> |</li>
<li><a href="../index.html">Varnish version 6.4.0 documentation</a> »</li>
<li><a href="index.html" >The Varnish Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010-2014, Varnish Software AS.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>