Default page

Edit File: vmod_cookie.html

<!DOCTYPE html>

<title>VMOD cookie - Varnish Cookie Module — Varnish version 7.5.0 documentation</title>
 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=e2714048" />
 
 <script src="../_static/documentation_options.js?v=8214db13"></script>
 <script src="../_static/doctools.js?v=888ff710"></script>
 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
 
 <link rel="index" title="Index" href="../genindex.html" />
 <link rel="search" title="Search" href="../search.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" role="navigation" aria-label="related navigation">
 <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 class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> »</li>
 <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Varnish Reference Manual</a> »</li>
 <li class="nav-item nav-item-this"><a href="">VMOD cookie - Varnish Cookie Module</a></li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="vmod-cookie-varnish-cookie-module">
<h1>VMOD cookie - Varnish Cookie Module<a class="headerlink" href="#vmod-cookie-varnish-cookie-module" title="Link to this heading">¶</a></h1>
<section id="synopsis">
<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Link to this heading">¶</a></h2>
<pre class="literal-block">import cookie [as name] [from "path"]

<a class="reference internal" href="#cookie-clean">VOID clean()</a>

<a class="reference internal" href="#cookie-delete">VOID delete(STRING cookiename)</a>

<a class="reference internal" href="#cookie-filter">VOID filter(STRING filterstring)</a>

<a class="reference internal" href="#cookie-filter-re">VOID filter_re(REGEX expression)</a>

<a class="reference internal" href="#cookie-keep">VOID keep(STRING filterstring)</a>

<a class="reference internal" href="#cookie-keep-re">VOID keep_re(REGEX expression)</a>

<a class="reference internal" href="#cookie-format-date">STRING format_date(TIME now, DURATION timedelta)</a>

<a class="reference internal" href="#cookie-get">STRING get(STRING cookiename)</a>

<a class="reference internal" href="#cookie-get-re">STRING get_re(REGEX expression)</a>

<a class="reference internal" href="#cookie-get-string">STRING get_string()</a>

<a class="reference internal" href="#cookie-isset">BOOL isset(STRING cookiename)</a>

<a class="reference internal" href="#cookie-parse">VOID parse(STRING cookieheader)</a>

<a class="reference internal" href="#cookie-set">VOID set(STRING cookiename, STRING value)</a></pre>
</section>
<section id="description">
<h2>DESCRIPTION<a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>
Handle HTTP cookies more easily in Varnish VCL.
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.
Regular expressions can be used for either selecting cookies, deleting matching
cookies and deleting non-matching cookie names.
A convenience function for formatting the Set-Cookie Expires date field
is also included.
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.
Filtering example:
<div class="highlight-default notranslate"><div class="highlight"><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>
<section id="void-clean">
<h3>VOID clean()<a class="headerlink" href="#void-clean" title="Link to this heading">¶</a></h3>
Clean up previously parsed cookies. It is not necessary to run clean()
in normal operations.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>sub vcl_recv {
 cookie.clean();
}
</pre></div>
</div>
</section>
<section id="void-delete-string-cookiename">
<h3>VOID delete(STRING cookiename)<a class="headerlink" href="#void-delete-string-cookiename" title="Link to this heading">¶</a></h3>
Delete <code class="docutils literal notranslate">cookiename</code> from internal vmod storage if it exists.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>sub vcl_recv {
 cookie.parse("cookie1=value1; cookie2=value2");
 cookie.delete("cookie2");
 # get_string() will now yield "cookie1=value1"
}
</pre></div>
</div>
</section>
<section id="void-filter-string-filterstring">
<h3>VOID filter(STRING filterstring)<a class="headerlink" href="#void-filter-string-filterstring" title="Link to this heading">¶</a></h3>
Delete all cookies from internal vmod storage that are in the
comma-separated argument cookienames.
Example:
<div class="highlight-default notranslate"><div class="highlight"><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>
</section>
<section id="void-filter-re-regex-expression">
<h3>VOID filter_re(REGEX expression)<a class="headerlink" href="#void-filter-re-regex-expression" title="Link to this heading">¶</a></h3>
Delete all cookies from internal vmod storage that matches the
regular expression <code class="docutils literal notranslate">expression</code>.
Example:
<div class="highlight-default notranslate"><div class="highlight"><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>
</section>
<section id="void-keep-string-filterstring">
<h3>VOID keep(STRING filterstring)<a class="headerlink" href="#void-keep-string-filterstring" title="Link to this heading">¶</a></h3>
Delete all cookies from internal vmod storage that is not in the
comma-separated argument cookienames.
Example:
<div class="highlight-default notranslate"><div class="highlight"><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>
</section>
<section id="void-keep-re-regex-expression">
<h3>VOID keep_re(REGEX expression)<a class="headerlink" href="#void-keep-re-regex-expression" title="Link to this heading">¶</a></h3>
Delete all cookies from internal vmod storage that does not match
expression <code class="docutils literal notranslate">expression</code>.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>sub vcl_recv {
 cookie.parse("cookie1=value1; cookie2=value2; cookie3=value3");
 cookie.keep_re("^cookie[12]$");
 # get_string() will now yield "cookie1=value1; cookie2=value2"
}
</pre></div>
</div>
</section>
<section id="string-format-date-time-now-duration-timedelta">
<h3>STRING format_date(TIME now, DURATION timedelta)<a class="headerlink" href="#string-format-date-time-now-duration-timedelta" title="Link to this heading">¶</a></h3>
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:
<div class="highlight-default notranslate"><div class="highlight"><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_date(now, 5m) + "; httpOnly";
}
</pre></div>
</div>
</section>
<section id="string-get-string-cookiename">
<h3>STRING get(STRING cookiename)<a class="headerlink" href="#string-get-string-cookiename" title="Link to this heading">¶</a></h3>
Get the value of <code class="docutils literal notranslate">cookiename</code>, as stored in internal vmod storage.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>import std;
sub vcl_recv {
 cookie.parse("cookie1=value1; cookie2=value2");
 std.log("cookie1 value is: " + cookie.get("cookie1"));
}
</pre></div>
</div>
If <code class="docutils literal notranslate">cookiename</code> does not exist, the <cite>NULL</cite> string is returned. Note
that a <cite>NULL</cite> string is converted to an empty string when assigned to
a header. This means that the following is correct:
<div class="highlight-default notranslate"><div class="highlight"><pre>if (req.http.Cookie) {
 cookie.parse(req.http.Cookie);
 set req.http.X-tmp = cookie.get("a_cookie");
} else {
 set req.http.X-tmp = "";
}
if (req.http.X-tmp != "") {
 // do something with the X-tmp header...
} else {
 // fallback case
}
</pre></div>
</div>
However, using <cite>cookie.isset()</cite> is often a better way to check if a
particular cookie is present, like this:
<div class="highlight-default notranslate"><div class="highlight"><pre>unset req.http.X-tmp; # unnecessary if no fallback is needed
if (req.http.Cookie) {
 cookie.parse(req.http.Cookie);
 if (cookie.isset("a_cookie")) {
 set req.http.X-tmp = cookie.get("a_cookie");
 # do something with the X-tmp header...
 }
}
# if necessary, do something when a_cookie is not there
if (!req.http.X-tmp) {
 # fallback case
}
</pre></div>
</div>
</section>
<section id="string-get-re-regex-expression">
<h3>STRING get_re(REGEX expression)<a class="headerlink" href="#string-get-re-regex-expression" title="Link to this heading">¶</a></h3>
Get the value of the first cookie in internal vmod storage that matches the
regular expression <code class="docutils literal notranslate">expression</code>. If nothing matches, the <cite>NULL</cite> string
is returned.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>import std;
sub vcl_recv {
 cookie.parse("cookie1=value1; cookie2=value2");
 std.log("cookie1 value is: " + cookie.get_re("^cookie1$"));
}
</pre></div>
</div>
</section>
<section id="string-get-string">
<h3>STRING get_string()<a class="headerlink" href="#string-get-string" title="Link to this heading">¶</a></h3>
Get a Cookie string value with all cookies in internal vmod storage. Does
not modify internal storage.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>sub vcl_recv {
 cookie.parse(req.http.cookie);
 cookie.keep("SESSIONID,PHPSESSID");
 set req.http.cookie = cookie.get_string();
}
</pre></div>
</div>
</section>
<section id="bool-isset-string-cookiename">
<h3>BOOL isset(STRING cookiename)<a class="headerlink" href="#bool-isset-string-cookiename" title="Link to this heading">¶</a></h3>
Check if <code class="docutils literal notranslate">cookiename</code> is set in the internal vmod storage.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>import std;
sub vcl_recv {
 cookie.parse("cookie1=value1; cookie2=value2");
 if (cookie.isset("cookie2")) {
 std.log("cookie2 is set.");
 }
}
</pre></div>
</div>
</section>
<section id="void-parse-string-cookieheader">
<h3>VOID parse(STRING cookieheader)<a class="headerlink" href="#void-parse-string-cookieheader" title="Link to this heading">¶</a></h3>
Parse the cookie string in <code class="docutils literal notranslate">cookieheader</code>. If state already exists,
<code class="docutils literal notranslate">clean()</code> will be run first.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>sub vcl_recv {
 cookie.parse(req.http.Cookie);
}
</pre></div>
</div>
</section>
<section id="void-set-string-cookiename-string-value">
<h3>VOID set(STRING cookiename, STRING value)<a class="headerlink" href="#void-set-string-cookiename-string-value" title="Link to this heading">¶</a></h3>
Set the internal vmod storage for <code class="docutils literal notranslate">cookiename</code> to <code class="docutils literal notranslate">value</code>.
Example:
<div class="highlight-default notranslate"><div class="highlight"><pre>sub vcl_recv {
 cookie.set("cookie1", "value1");
 std.log("cookie1 value is: " + cookie.get("cookie1"));
}
</pre></div>
</div>
</section>
</section>
<section id="deprecated">
<h2>DEPRECATED<a class="headerlink" href="#deprecated" title="Link to this heading">¶</a></h2>
<section id="alias-format-rfc1123">
<h3>ALIAS format_rfc1123()<a class="headerlink" href="#alias-format-rfc1123" title="Link to this heading">¶</a></h3>
Deprecated alias for <code class="docutils literal notranslate">format_date()</code>.
</section>
</section>
<section id="copyright">
<h2>COPYRIGHT<a class="headerlink" href="#copyright" title="Link to this heading">¶</a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre>This document is licensed under the same conditions as Varnish itself.
See LICENSE for details.

SPDX-License-Identifier: BSD-2-Clause
</pre></div>
</div>
</section>
</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <div>
 <h3><a href="../index.html">Table of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#">VMOD cookie - Varnish Cookie Module</a></li>
</ul>

</div>
 <div>
 <h4>Previous topic</h4>
 <a href="vmod_blob.html"
 title="previous chapter">VMOD blob - Utilities for the VCL blob type, encoding and decoding</a>
 </div>
 <div>
 <h4>Next topic</h4>
 <a href="vmod_directors.html"
 title="next chapter">VMOD directors - Varnish Directors Module</a>
 </div>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../_sources/reference/vmod_cookie.rst.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
 </div>
<div id="searchbox" style="display: none" role="search">
 <h3 id="searchlabel">Quick search</h3>
 <div class="searchformwrapper">
 <form class="search" action="../search.html" method="get">
 <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
 <input type="submit" value="Go" />
 </form>
 </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div>
 <div class="related" role="navigation" aria-label="related navigation">
 <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 class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> »</li>
 <li class="nav-item nav-item-1"><a href="index.html" >The Varnish Reference Manual</a> »</li>
 <li class="nav-item nav-item-this"><a href="">VMOD cookie - Varnish Cookie Module</a></li> 
 </ul>
 </div>
 <div class="footer" role="contentinfo">
 © Copyright 2010-2014, Varnish Software AS.
 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
 </div>
 </body>
</html>