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_rfc1123(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
108 # "cookie3: value3";
109 }
110 VOID filter_re(REGEX expression)
112 Delete all cookies from internal vmod storage that matches the regular
113 expression expression.
114 Example:
116 sub vcl_recv {
118 cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
119 cookie.filter_re("^cookie[12]$");
120 # get_string() will now yield
121 # "cookie3: value3";
122 }
123 VOID keep(STRING filterstring)
125 Delete all cookies from internal vmod storage that is not in the
126 comma-separated argument cookienames.
127 Example:
129 sub vcl_recv {
131 cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
132 cookie.keep("cookie1,cookie2");
133 # get_string() will now yield
134 # "cookie1: value1; cookie2: value2;";
135 }
136 VOID keep_re(REGEX expression)
138 Delete all cookies from internal vmod storage that does not match ex‐
139 pression expression.
140 Example:
142 sub vcl_recv {
144 cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
145 cookie.keep_re("^cookie1,cookie2");
146 # get_string() will now yield
147 # "cookie1: value1; cookie2: value2;";
148 }
149 STRING format_rfc1123(TIME now, DURATION timedelta)
151 Get a RFC1123 formatted date string suitable for inclusion in a
152 Set-Cookie response header.
153 Care should be taken if the response has multiple Set-Cookie headers.
155 In that case the header vmod should be used.
156 Example:
158 sub vcl_deliver {
160 # Set a userid cookie on the client that lives for 5 minutes.
161 set resp.http.Set-Cookie = "userid=" + req.http.userid +
162 "; Expires=" + cookie.format_rfc1123(now, 5m) + "; httpOnly";
163 }
164 STRING get(STRING cookiename)
166 Get the value of cookiename, as stored in internal vmod storage. If
167 cookiename does not exist an empty string is returned.
168 Example:
170 import std;
172 sub vcl_recv {
173 cookie.parse("cookie1: value1; cookie2: value2;");
174 std.log("cookie1 value is: " + cookie.get("cookie1"));
175 }
176 STRING get_re(REGEX expression)
178 Get the value of the first cookie in internal vmod storage that matches
179 regular expression expression. If nothing matches, an empty string is
180 returned.
181 Example:
183 import std;
185 sub vcl_recv {
186 cookie.parse("cookie1: value1; cookie2: value2;");
187 std.log("cookie1 value is: " + cookie.get_re("^cookie1$"));
188 }
189 STRING get_string()
191 Get a Cookie string value with all cookies in internal vmod storage.
192 Does not modify internal storage.
193 Example:
195 sub vcl_recv {
197 cookie.parse(req.http.cookie);
198 cookie.keep("SESSIONID,PHPSESSID");
199 set req.http.cookie = cookie.get_string();
200 }
201 BOOL isset(STRING cookiename)
203 Check if cookiename is set in the internal vmod storage.
204 Example:
206 import std;
208 sub vcl_recv {
209 cookie.parse("cookie1: value1; cookie2: value2;");
210 if (cookie.isset("cookie2")) {
211 std.log("cookie2 is set.");
212 }
213 }
214 VOID parse(STRING cookieheader)
216 Parse the cookie string in cookieheader. If state already exists,
217 clean() will be run first.
218 Example:
220 sub vcl_recv {
222 cookie.parse(req.http.Cookie);
223 }
224 VOID set(STRING cookiename, STRING value)
226 Set the internal vmod storage for cookiename to value.
227 Example:
229 sub vcl_recv {
231 cookie.set("cookie1", "value1");
232 std.log("cookie1 value is: " + cookie.get("cookie1"));
233 }
234
236 This document is licensed under the same conditions as Varnish itself.
237 See LICENSE for details.
238 SPDX-License-Identifier: BSD-2-Clause
240 VMOD_COOKIE(3)