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("^cookie1,cookie2");
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. If
167       cookiename does not exist an empty string is returned.
168
169       Example:
170
171          import std;
172          sub vcl_recv {
173              cookie.parse("cookie1: value1; cookie2: value2;");
174              std.log("cookie1 value is: " + cookie.get("cookie1"));
175          }
176
177   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
182       Example:
183
184          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
190   STRING get_string()
191       Get a Cookie string value with all cookies in  internal  vmod  storage.
192       Does not modify internal storage.
193
194       Example:
195
196          sub vcl_recv {
197              cookie.parse(req.http.cookie);
198              cookie.keep("SESSIONID,PHPSESSID");
199              set req.http.cookie = cookie.get_string();
200          }
201
202   BOOL isset(STRING cookiename)
203       Check if cookiename is set in the internal vmod storage.
204
205       Example:
206
207          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
215   VOID parse(STRING cookieheader)
216       Parse  the  cookie  string  in  cookieheader.  If state already exists,
217       clean() will be run first.
218
219       Example:
220
221          sub vcl_recv {
222              cookie.parse(req.http.Cookie);
223          }
224
225   VOID set(STRING cookiename, STRING value)
226       Set the internal vmod storage for cookiename to value.
227
228       Example:
229
230          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
239          SPDX-License-Identifier: BSD-2-Clause
240
241
242
243
244                                                                VMOD_COOKIE(3)
Impressum