1VMOD_COOKIE(3)                                                  VMOD_COOKIE(3)
2
3
4

NAME

6       vmod_cookie - Varnish Cookie Module
7

SYNOPSIS

9          import cookie [as name] [from "path"]
10
11          VOID clean()
12
13          VOID delete(STRING cookiename)
14
15          VOID filter(STRING filterstring)
16
17          VOID filter_re(REGEX expression)
18
19          VOID keep(STRING filterstring)
20
21          VOID keep_re(REGEX expression)
22
23          STRING format_rfc1123(TIME now, DURATION timedelta)
24
25          STRING get(STRING cookiename)
26
27          STRING get_re(REGEX expression)
28
29          STRING get_string()
30
31          BOOL isset(STRING cookiename)
32
33          VOID parse(STRING cookieheader)
34
35          VOID set(STRING cookiename, STRING value)
36

DESCRIPTION

38       Handle HTTP cookies more easily in Varnish VCL.
39
40       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
45       Regular expressions can be used for either selecting cookies,  deleting
46       matching cookies and deleting non-matching cookie names.
47
48       A convenience function for formatting the Set-Cookie Expires date field
49       is also included.
50
51       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
55       Filtering example:
56
57          import cookie;
58
59          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
67                  # Store it back into req so it will be passed to the backend.
68                  set req.http.cookie = cookie.get_string();
69
70                  # 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
77   VOID clean()
78       Clean up previously parsed cookies. It is not necessary to run  clean()
79       in normal operations.
80
81       Example:
82
83          sub vcl_recv {
84              cookie.clean();
85          }
86
87   VOID delete(STRING cookiename)
88       Delete cookiename from internal vmod storage if it exists.
89
90       Example:
91
92          sub vcl_recv {
93              cookie.parse("cookie1: value1; cookie2: value2;");
94              cookie.delete("cookie2");
95              # get_string() will now yield "cookie1: value1";
96          }
97
98   VOID filter(STRING filterstring)
99       Delete  all  cookies  from  internal  vmod  storage  that  are  in  the
100       comma-separated argument cookienames.
101
102       Example:
103
104          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
111   VOID filter_re(REGEX expression)
112       Delete all cookies from internal vmod storage that matches the  regular
113       expression expression.
114
115       Example:
116
117          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
124   VOID keep(STRING filterstring)
125       Delete  all  cookies  from  internal  vmod  storage  that is not in the
126       comma-separated argument cookienames.
127
128       Example:
129
130          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
137   VOID keep_re(REGEX expression)
138       Delete all cookies from internal vmod storage that does not  match  ex‐
139       pression expression.
140
141       Example:
142
143          sub vcl_recv {
144              cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
145              cookie.keep_re("^cookie[12]$");
146              # get_string() will now yield
147              # "cookie1: value1; cookie2: value2;";
148          }
149
150   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
154       Care should be taken if the response has multiple  Set-Cookie  headers.
155       In that case the header vmod should be used.
156
157       Example:
158
159          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
165   STRING get(STRING cookiename)
166       Get the value of cookiename, as stored in internal vmod storage.
167
168       Example:
169
170          import std;
171          sub vcl_recv {
172              cookie.parse("cookie1: value1; cookie2: value2;");
173              std.log("cookie1 value is: " + cookie.get("cookie1"));
174          }
175
176       If  cookiename does not exist, the NULL string is returned. Note that a
177       NULL string is converted to an empty string when assigned to a  header.
178       This means that the following is correct:
179
180          if (req.http.Cookie) {
181                  cookie.parse(req.http.Cookie);
182                  set req.http.X-tmp = cookie.get("a_cookie");
183          } else {
184                  set req.http.X-tmp = "";
185          }
186          if (req.http.X-tmp != "") {
187                  // do something with the X-tmp header...
188          } else {
189                  // fallback case
190          }
191
192       However,  using cookie.isset() is often a better way to check if a par‐
193       ticular cookie is present, like this:
194
195          unset req.http.X-tmp; # unnecessary if no fallback is needed
196          if (req.http.Cookie) {
197                  cookie.parse(req.http.Cookie);
198                  if (cookie.isset("a_cookie")) {
199                          set req.http.X-tmp = cookie.get("a_cookie");
200                          # do something with the X-tmp header...
201                  }
202          }
203          # if necessary, do something when a_cookie is not there
204          if (!req.http.X-tmp) {
205                  # fallback case
206          }
207
208   STRING get_re(REGEX expression)
209       Get the value of the first cookie in internal vmod storage that matches
210       the  regular expression expression. If nothing matches, the NULL string
211       is returned.
212
213       Example:
214
215          import std;
216          sub vcl_recv {
217              cookie.parse("cookie1: value1; cookie2: value2;");
218              std.log("cookie1 value is: " + cookie.get_re("^cookie1$"));
219          }
220
221   STRING get_string()
222       Get a Cookie string value with all cookies in  internal  vmod  storage.
223       Does not modify internal storage.
224
225       Example:
226
227          sub vcl_recv {
228              cookie.parse(req.http.cookie);
229              cookie.keep("SESSIONID,PHPSESSID");
230              set req.http.cookie = cookie.get_string();
231          }
232
233   BOOL isset(STRING cookiename)
234       Check if cookiename is set in the internal vmod storage.
235
236       Example:
237
238          import std;
239          sub vcl_recv {
240              cookie.parse("cookie1: value1; cookie2: value2;");
241              if (cookie.isset("cookie2")) {
242                  std.log("cookie2 is set.");
243              }
244          }
245
246   VOID parse(STRING cookieheader)
247       Parse  the  cookie  string  in  cookieheader.  If state already exists,
248       clean() will be run first.
249
250       Example:
251
252          sub vcl_recv {
253              cookie.parse(req.http.Cookie);
254          }
255
256   VOID set(STRING cookiename, STRING value)
257       Set the internal vmod storage for cookiename to value.
258
259       Example:
260
261          sub vcl_recv {
262              cookie.set("cookie1", "value1");
263              std.log("cookie1 value is: " + cookie.get("cookie1"));
264          }
265

267          This document is licensed under the same conditions as Varnish itself.
268          See LICENSE for details.
269
270          SPDX-License-Identifier: BSD-2-Clause
271
272
273
274
275                                                                VMOD_COOKIE(3)
Impressum