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

FreeBSD Manual Pages

  
 
  

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

NAME
       vmod_saintmode -	Saint mode backend director

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

	  VOID denylist(DURATION expires)

	  STRING status()

	  new xsaintmode = saintmode.saintmode(BACKEND backend,	INT threshold)

	      BACKEND xsaintmode.backend()

	      INT xsaintmode.denylist_count()

	      BOOL xsaintmode.is_healthy()

DESCRIPTION
       This  VMOD  provides  saintmode functionality for Varnish Cache 4.1 and
       newer. The code is in part based	on Poul-Henning	Kamp's	saintmode  im-
       plementation in Varnish 3.0.

       Saintmode  lets	you deal with a	backend	that is	failing	in random ways
       for specific requests. It maintains a denylist per backend, marking the
       backend as sick for specific objects. When the number of	objects	marked
       as sick for a backend reaches a set threshold, the backend  is  consid-
       ered sick for all requests. Each	denylisted object carries a TTL, which
       denotes the time	it will	stay denylisted.

       Saintmode  in Varnish 4.1 is implemented	as a director VMOD. We instan-
       tiate a saintmode object	and give it a backend as an argument. The  re-
       sulting	object	can then be used in place of the backend, with the ef-
       fect that it also has added saintmode capabilities.

       Any director will then be able to use the saintmode  backends,  and  as
       backends	 marked	 sick are skipped by the director, this	provides a way
       to have fine grained health status on the  backends,  and  making  sure
       that retries get	a different backend than the one which failed.

       Example:

	  vcl 4.0;

	  import saintmode;
	  import directors;

	  backend tile1	{ .host	= "192.0.2.11";	.port =	"80"; }
	  backend tile2	{ .host	= "192.0.2.12";	.port =	"80"; }

	  sub vcl_init {
	      #	Instantiate sm1, sm2 for backends tile1, tile2
	      #	with 10	denylisted objects as the threshold for	marking	the
	      #	whole backend sick.
	      new sm1 =	saintmode.saintmode(tile1, 10);
	      new sm2 =	saintmode.saintmode(tile2, 10);

	      #	Add both to a director.	Use sm0, sm1 in	place of tile1,	tile2.
	      #	Other director types can be used in place of random.
	      new imagedirector	= directors.random();
	      imagedirector.add_backend(sm1.backend(), 1);
	      imagedirector.add_backend(sm2.backend(), 1);
	  }

	  sub vcl_backend_fetch	{
	      #	Get a backend from the director.
	      #	When returning a backend, the director will only return	backends
	      #	saintmode says are healthy.
	      set bereq.backend	= imagedirector.backend();
	  }

	  sub vcl_backend_response {
	      if (beresp.status	>= 500)	{
		  # This marks the backend as sick for this specific
		  # object for the next	20s.
		  saintmode.denylist(20s);
		  # Retry the request. This will result	in a different backend
		  # being used.
		  return (retry);
	      }
	  }

   VOID	denylist(DURATION expires)
       Marks  the  backend  as	sick  for a specific object. Used in vcl_back-
       end_response.  Corresponds to the use of	 beresp.saintmode  in  Varnish
       3.0. Only available in vcl_backend_response.

       Example:

	  sub vcl_backend_response {
	      if (beresp.http.broken-app) {
		  saintmode.denylist(20s);
		  return (retry);
	      }
	  }

   STRING status()
       Returns a JSON formatted	status string suitable for use in vcl_synth.

	  sub vcl_recv {
	      if (req.url ~ "/saintmode-status") {
		  return (synth(700, "OK"));
	      }
	  }

	  sub vcl_synth	{
	      if (resp.status == 700) {
		  synthetic(saintmode.status());
		  return (deliver);
	      }
	  }

       Example JSON output:

	      {
		"saintmode" : [
		    { "name": "sm1", "backend":	"foo", "count":	"3", "threshold": "10" },
		    { "name": "sm2", "backend":	"bar", "count":	"2", "threshold": "5" }
		]
	      }

   new xsaintmode = saintmode.saintmode(BACKEND	backend, INT threshold)
	  new xsaintmode = saintmode.saintmode(
	     BACKEND backend,
	     INT threshold
	  )

       Constructs a saintmode director object. The threshold argument sets the
       saintmode  threshold,  which is the maximum number of items that	can be
       denylisted before the whole backend is regarded	as  sick.  Corresponds
       with the	saintmode_threshold parameter of Varnish 3.0.

       Example:

	  sub vcl_init {
	      new sm = saintmode.saintmode(b, 10);
	  }

   BACKEND xsaintmode.backend()
       Used for	assigning the backend from the saintmode object.

       Example:

	  sub vcl_backend_fetch	{
	      set bereq.backend	= sm.backend();
	  }

   INT xsaintmode.denylist_count()
       Returns	the number of objects currently	denylisted for a saintmode di-
       rector object.

       Example:

	  sub vcl_deliver {
	      set resp.http.troublecount = sm.denylist_count();
	  }

   BOOL	xsaintmode.is_healthy()
       Checks if the object is currently denylisted for	a  saintmode  director
       object.	 If  there are no valid	objects	available (called from vcl_hit
       or vcl_recv), the function will fall back to the	backend's health func-
       tion.

DEPRECATED
   ALIAS blacklist()
       Deprecated alias	for denylist().

   ALIAS xsaintmode.blacklist_count()
       Deprecated alias	for xsaintmode.denylist_count().

							     VMOD_SAINTMODE(3)

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

home | help