June 27, 2016
3 min read time

Configure saint mode & grace in Varnish 4.1


How to configure saint mode and grace in Varnish 4.1
A very important feature of Varnish is the ability to deal with misbehaving servers. In this blog I will explain how to properly configure saint mode and grace.

Saint mode and grace have been present since Varnish 2.1, but to make this blog post easier I will cover the differences between Varnish 3 (EOL for real!)  and the current stable Varnish 4.1.

What is saint mode?
Saint mode lets you deal with a backend that is failing for specific requests. It maintains a blacklist per backend, marking the backend as sick for specific requests for a period of time. Varnish would try to fulfill the request either trying another server or serving stale content from cache.

In Varnish 3.x saint mode was a core functionality and was meant to complement your regular health checks.

What is grace mode?
Grace mode allows you to instruct Varnish to keep an object in cache beyond its TTL and serve this stale content if your backend is not healthy or if fresh content hasn’t been fetched yet.

Here’s a VCL snippet for Varnish 3.x where saintmode and grace are implemented together:

sub vcl_recv {
  #we accept serving 15s old object
  set req.grace = 15s;

sub vcl_fetch {
  if (beresp.status == 500) {
   set beresp.saintmode = 10s;
  #the object will stay in cache for 5 mins after its TTL
  set beresp.grace = 5m;

In this simple example, when we set beresp.saintmode to 10 seconds Varnish will not ask that server (the one that returned a 500 as response status) for the URL for 10 seconds. A restart is performed so if you have more than a backend capable of serving that content Varnish will try those. If no other backend is defined Varnish will try to serve a stale object.

Starting from Varnish 4.1 saint mode is no longer a core functionality, but instead it’s implemented as a VMOD (https://github.com/varnish/varnish-modules). We instantiate a saint mode object and give it a backend as argument, and the resulting object can be used as backend with saintmode capabilities.

From Varnish 4.0 grace follows a stale-while-revalidate logic by default, meaning that Varnish will always prefer a fresh object, but if it isn’t present then a stale one will be served.

The logic for saint mode and grace hasn’t changed dramatically from Varnish 3.0 to Varnish 4.1, but the VCL language has and it might require some thinking to get this implemented in the most efficient way.

Here’s a basic VCL snippet for saint mode and grace:

import directors;
sub vcl_init {
  # we create two saint-mode backends

  new sm1 = saintmode.saintmode(server1, 5);
  new sm2 = saintmode.saintmode(server2, 5);
  #we group the backends in the same cluster
  new fb = directors.fallback();

sub vcl_backend_fetch {
  set bereq.backend = fb.backend();

sub vcl_backend_response {
  #we set both TTL and grace values which will be used by the default vcl_hit subroutine
  set beresp.ttl = 1s;
  set beresp.grace = 10s;
  if (beresp.status > 500) {
  #the failing backend is blacklisted and we try to fetch content from another server
   return (retry);

Learn more about Grace in Varnish 

Photo (c) 2010 Ricky Montalvo used under Creative Commons license.