1VMOD_COOKIE(3) VMOD_COOKIE(3)
2
6 vmod_cookie - Varnish Cookie Module
7
9 import cookie [as name] [from "path"]
10 VOID clean()
12 VOID delete(STRING cookiename)
14 VOID filter(STRING filterstring)
16 VOID filter_re(REGEX expression)
18 VOID keep(STRING filterstring)
20 VOID keep_re(REGEX expression)
22 STRING format_date(TIME now, DURATION timedelta)
24 STRING get(STRING cookiename)
26 STRING get_re(REGEX expression)
28 STRING get_string()
30 BOOL isset(STRING cookiename)
32 VOID parse(STRING cookieheader)
34 VOID set(STRING cookiename, STRING value)
36
38 Handle HTTP cookies more easily in Varnish VCL.
39 Parses a cookie header into an internal data store, where per-cookie
41 get/set/delete functions are available. A keep() function removes all
42 but a set comma-separated list of cookies. A filter() function removes
43 a comma- separated list of cookies.
44 Regular expressions can be used for either selecting cookies, deleting
46 matching cookies and deleting non-matching cookie names.
47 A convenience function for formatting the Set-Cookie Expires date field
49 is also included.
50 The state loaded with cookie.parse() has a lifetime of the current re‐
52 quest or backend request context. To pass variables to the backend re‐
53 quest, store the contents as fake bereq headers.
54 Filtering example:
56 import cookie;
58 sub vcl_recv {
60 if (req.http.cookie) {
61 cookie.parse(req.http.cookie);
62 # Either delete the ones you want to get rid of:
63 cookie.delete("cookie2");
64 # or delete all but a few:
65 cookie.keep("SESSIONID,PHPSESSID");
66 # Store it back into req so it will be passed to the backend.
68 set req.http.cookie = cookie.get_string();
69 # If empty, unset so the builtin VCL can consider it for caching.
71 if (req.http.cookie == "") {
72 unset req.http.cookie;
73 }
74 }
75 }
76 VOID clean()
78 Clean up previously parsed cookies. It is not necessary to run clean()
79 in normal operations.
80 Example:
82 sub vcl_recv {
84 cookie.clean();
85 }
86 VOID delete(STRING cookiename)
88 Delete cookiename from internal vmod storage if it exists.
89 Example:
91 sub vcl_recv {
93 cookie.parse("cookie1=value1; cookie2=value2");
94 cookie.delete("cookie2");
95 # get_string() will now yield "cookie1=value1"
96 }
97 VOID filter(STRING filterstring)
99 Delete all cookies from internal vmod storage that are in the
100 comma-separated argument cookienames.
101 Example:
103 sub vcl_recv {
105 cookie.parse("cookie1=value1; cookie2=value2; cookie3=value3");
106 cookie.filter("cookie1,cookie2");
107 # get_string() will now yield "cookie3=value3"
108 }
109 VOID filter_re(REGEX expression)
111 Delete all cookies from internal vmod storage that matches the regular
112 expression expression.
113 Example:
115 sub vcl_recv {
117 cookie.parse("cookie1=value1; cookie2=value2; cookie3=value3");
118 cookie.filter_re("^cookie[12]$");
119 # get_string() will now yield "cookie3=value3"
120 }
121 VOID keep(STRING filterstring)
123 Delete all cookies from internal vmod storage that is not in the
124 comma-separated argument cookienames.
125 Example:
127 sub vcl_recv {
129 cookie.parse("cookie1=value1; cookie2=value2; cookie3=value3");
130 cookie.keep("cookie1,cookie2");
131 # get_string() will now yield "cookie1=value1; cookie2=value2"
132 }
133 VOID keep_re(REGEX expression)
135 Delete all cookies from internal vmod storage that does not match ex‐
136 pression expression.
137 Example:
139 sub vcl_recv {
141 cookie.parse("cookie1=value1; cookie2=value2; cookie3=value3");
142 cookie.keep_re("^cookie[12]$");
143 # get_string() will now yield "cookie1=value1; cookie2=value2"
144 }
145 STRING format_date(TIME now, DURATION timedelta)
147 Get a RFC1123 formatted date string suitable for inclusion in a
148 Set-Cookie response header.
149 Care should be taken if the response has multiple Set-Cookie headers.
151 In that case the header vmod should be used.
152 Example:
154 sub vcl_deliver {
156 # Set a userid cookie on the client that lives for 5 minutes.
157 set resp.http.Set-Cookie = "userid=" + req.http.userid +
158 "; Expires=" + cookie.format_date(now, 5m) + "; httpOnly";
159 }
160 STRING get(STRING cookiename)
162 Get the value of cookiename, as stored in internal vmod storage.
163 Example:
165 import std;
167 sub vcl_recv {
168 cookie.parse("cookie1=value1; cookie2=value2");
169 std.log("cookie1 value is: " + cookie.get("cookie1"));
170 }
171 If cookiename does not exist, the NULL string is returned. Note that a
173 NULL string is converted to an empty string when assigned to a header.
174 This means that the following is correct:
175 if (req.http.Cookie) {
177 cookie.parse(req.http.Cookie);
178 set req.http.X-tmp = cookie.get("a_cookie");
179 } else {
180 set req.http.X-tmp = "";
181 }
182 if (req.http.X-tmp != "") {
183 // do something with the X-tmp header...
184 } else {
185 // fallback case
186 }
187 However, using cookie.isset() is often a better way to check if a par‐
189 ticular cookie is present, like this:
190 unset req.http.X-tmp; # unnecessary if no fallback is needed
192 if (req.http.Cookie) {
193 cookie.parse(req.http.Cookie);
194 if (cookie.isset("a_cookie")) {
195 set req.http.X-tmp = cookie.get("a_cookie");
196 # do something with the X-tmp header...
197 }
198 }
199 # if necessary, do something when a_cookie is not there
200 if (!req.http.X-tmp) {
201 # fallback case
202 }
203 STRING get_re(REGEX expression)
205 Get the value of the first cookie in internal vmod storage that matches
206 the regular expression expression. If nothing matches, the NULL string
207 is returned.
208 Example:
210 import std;
212 sub vcl_recv {
213 cookie.parse("cookie1=value1; cookie2=value2");
214 std.log("cookie1 value is: " + cookie.get_re("^cookie1$"));
215 }
216 STRING get_string()
218 Get a Cookie string value with all cookies in internal vmod storage.
219 Does not modify internal storage.
220 Example:
222 sub vcl_recv {
224 cookie.parse(req.http.cookie);
225 cookie.keep("SESSIONID,PHPSESSID");
226 set req.http.cookie = cookie.get_string();
227 }
228 BOOL isset(STRING cookiename)
230 Check if cookiename is set in the internal vmod storage.
231 Example:
233 import std;
235 sub vcl_recv {
236 cookie.parse("cookie1=value1; cookie2=value2");
237 if (cookie.isset("cookie2")) {
238 std.log("cookie2 is set.");
239 }
240 }
241 VOID parse(STRING cookieheader)
243 Parse the cookie string in cookieheader. If state already exists,
244 clean() will be run first.
245 Example:
247 sub vcl_recv {
249 cookie.parse(req.http.Cookie);
250 }
251 VOID set(STRING cookiename, STRING value)
253 Set the internal vmod storage for cookiename to value.
254 Example:
256 sub vcl_recv {
258 cookie.set("cookie1", "value1");
259 std.log("cookie1 value is: " + cookie.get("cookie1"));
260 }
261
263 ALIAS format_rfc1123()
264 Deprecated alias for format_date().
265
267 This document is licensed under the same conditions as Varnish itself.
268 See LICENSE for details.
269 SPDX-License-Identifier: BSD-2-Clause
271 VMOD_COOKIE(3)