Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
VMOD_COOKIE(3)		   Library Functions Manual		VMOD_COOKIE(3)

NAME
       vmod_cookie - Varnish Cookie Module

SYNOPSIS
	  import cookie	[as name] [from	"path"]

	  VOID clean()

	  VOID delete(STRING cookiename)

	  VOID filter(STRING filterstring)

	  VOID filter_re(REGEX expression)

	  VOID keep(STRING filterstring)

	  VOID keep_re(REGEX expression)

	  STRING format_date(TIME now, DURATION	timedelta)

	  STRING get(STRING cookiename)

	  STRING get_re(REGEX expression)

	  STRING get_string()

	  BOOL isset(STRING cookiename)

	  VOID parse(STRING cookieheader)

	  VOID set(STRING cookiename, STRING value)

DESCRIPTION
       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 re-
       quest or	backend	request	context. To pass variables to the backend  re-
       quest, store the	contents as fake bereq headers.

       Filtering example:

	  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;
		  }
	      }
	  }

   VOID	clean()
       Clean  up previously parsed cookies. It is not necessary	to run clean()
       in normal operations.

       Example:

	  sub vcl_recv {
	      cookie.clean();
	  }

   VOID	delete(STRING cookiename)
       Delete cookiename from internal vmod storage if it exists.

       Example:

	  sub vcl_recv {
	      cookie.parse("cookie1=value1; cookie2=value2");
	      cookie.delete("cookie2");
	      #	get_string() will now yield "cookie1=value1"
	  }

   VOID	filter(STRING filterstring)
       Delete  all  cookies  from  internal  vmod  storage  that  are  in  the
       comma-separated argument	cookienames.

       Example:

	  sub vcl_recv {
	      cookie.parse("cookie1=value1; cookie2=value2; cookie3=value3");
	      cookie.filter("cookie1,cookie2");
	      #	get_string() will now yield "cookie3=value3"
	  }

   VOID	filter_re(REGEX	expression)
       Delete  all cookies from	internal vmod storage that matches the regular
       expression expression.

       Example:

	  sub vcl_recv {
	      cookie.parse("cookie1=value1; cookie2=value2; cookie3=value3");
	      cookie.filter_re("^cookie[12]$");
	      #	get_string() will now yield "cookie3=value3"
	  }

   VOID	keep(STRING filterstring)
       Delete all cookies from internal	 vmod  storage	that  is  not  in  the
       comma-separated argument	cookienames.

       Example:

	  sub vcl_recv {
	      cookie.parse("cookie1=value1; cookie2=value2; cookie3=value3");
	      cookie.keep("cookie1,cookie2");
	      #	get_string() will now yield "cookie1=value1; cookie2=value2"
	  }

   VOID	keep_re(REGEX expression)
       Delete  all  cookies from internal vmod storage that does not match ex-
       pression	expression.

       Example:

	  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"
	  }

   STRING format_date(TIME now,	DURATION timedelta)
       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:

	  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";
	  }

   STRING get(STRING cookiename)
       Get the value of	cookiename, as stored in internal vmod storage.

       Example:

	  import std;
	  sub vcl_recv {
	      cookie.parse("cookie1=value1; cookie2=value2");
	      std.log("cookie1 value is: " + cookie.get("cookie1"));
	  }

       If cookiename does not exist, the NULL string is	returned. Note that  a
       NULL  string is converted to an empty string when assigned to a header.
       This means that the following is	correct:

	  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
	  }

       However,	using cookie.isset() is	often a	better way to check if a  par-
       ticular cookie is present, like this:

	  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
	  }

   STRING get_re(REGEX expression)
       Get the value of	the first cookie in internal vmod storage that matches
       the  regular expression expression. If nothing matches, the NULL	string
       is returned.

       Example:

	  import std;
	  sub vcl_recv {
	      cookie.parse("cookie1=value1; cookie2=value2");
	      std.log("cookie1 value is: " + cookie.get_re("^cookie1$"));
	  }

   STRING get_string()
       Get a Cookie string value with all cookies in  internal	vmod  storage.
       Does not	modify internal	storage.

       Example:

	  sub vcl_recv {
	      cookie.parse(req.http.cookie);
	      cookie.keep("SESSIONID,PHPSESSID");
	      set req.http.cookie = cookie.get_string();
	  }

   BOOL	isset(STRING cookiename)
       Check if	cookiename is set in the internal vmod storage.

       Example:

	  import std;
	  sub vcl_recv {
	      cookie.parse("cookie1=value1; cookie2=value2");
	      if (cookie.isset("cookie2")) {
		  std.log("cookie2 is set.");
	      }
	  }

   VOID	parse(STRING cookieheader)
       Parse  the  cookie  string  in  cookieheader.  If state already exists,
       clean() will be run first.

       Example:

	  sub vcl_recv {
	      cookie.parse(req.http.Cookie);
	  }

   VOID	set(STRING cookiename, STRING value)
       Set the internal	vmod storage for cookiename to value.

       Example:

	  sub vcl_recv {
	      cookie.set("cookie1", "value1");
	      std.log("cookie1 value is: " + cookie.get("cookie1"));
	  }

DEPRECATED
   ALIAS format_rfc1123()
       Deprecated alias	for format_date().

COPYRIGHT
	  This document	is licensed under the same conditions as Varnish itself.
	  See LICENSE for details.

	  SPDX-License-Identifier: BSD-2-Clause

								VMOD_COOKIE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=vmod_cookie&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help