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

FreeBSD Manual Pages

  
 
  

home | help
VMOD_SAINTMODE(3)					     VMOD_SAINTMODE(3)

NAME
       vmod_saintmode -	Saint mode backend director

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

	  VOID blacklist(DURATION expires)

	  STRING status()

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

	      BACKEND xsaintmode.backend()

	      INT xsaintmode.blacklist_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 blacklist	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
       considered  sick	 for  all  requests. Each blacklisted object carries a
       TTL, which denotes the time it will stay	blacklisted.

       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	blacklisted 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.blacklist(20s);
		  # Retry the request. This will result	in a different backend
		  # being used.
		  return (retry);
	      }
	  }

   VOID	blacklist(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.blacklist(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
       blacklisted 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.blacklist_count()
       Returns the number of objects currently blacklisted for a saintmode di-
       rector object.

       Example:

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

   BOOL	xsaintmode.is_healthy()
       Checks if the object is currently blacklisted 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.

							     VMOD_SAINTMODE(3)

NAME | SYNOPSIS | DESCRIPTION

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

home | help