probes, grace, saint

git-svn-id: http://www.varnish-cache.org/svn/trunk/varnish-cache@4852 d4fa192b-c00b-0410-8231-f00ffab90ce4

doc/sphinx/tutorial/advanced_backend_servers.rst

@@ -78,6 +78,8 @@ But what if one of your servers goes down? Can Varnish direct all the
 requests to the healthy server? Sure it can. This is where the Health
 Checks come into play.
 
+.. _tutorial-advanced_backend_servers-health:
+
 Health checks
 -------------
 
@@ -124,8 +126,6 @@ window
 threshold 
  How many of the .window last polls must be good for the backend to be declared healthy.
 
-XXX: Ref to reference guide.
-
 Now we define the director.::
 
   director example_director round-robin {
@@ -141,4 +141,6 @@ Now we define the director.::
 
 You use this director just as you would use any other director or
 backend. Varnish will not send traffic to hosts that are marked as
-unhealty.
+unhealty. Varnish can also serve stale content if all the backends are
+down. See :ref:`tutorial-handling_misbehaving_servers` for more
+information on how to enable this.

doc/sphinx/tutorial/handling_misbehaving_servers.rst

+.. _tutorial-handling_misbehaving_servers:
+
+Misbehaving servers
+-------------------
+
+A key feature of Varnish is its ability to shield you from misbehaving
+web- and application servers.
+
+
+
+Grace mode
+~~~~~~~~~~
+
+When several clients are requesting the same page Varnish will send
+one request to the backend and place the others on hold while fetching
+one copy from the back end. 
+
+If you are serving thousands of hits per second this queue can get
+huge. Nobody likes to wait so there is a possibility to serve stale
+content to waiting users. In order to do this we must instruct Varnish
+to keep the objects in cache beyond their TTL. So, to keep all objects
+for 30 minutes beyond their TTL use the following VCL:::
+
+  sub vcl_fetch {
+    set beresp.grace = 30m;
+  }
+
+Varnish still won't serve the stale objects. In order to enable
+Varnish to actually serve the stale object we must enable this on the
+request. Lets us say that we accept serving 15s old object.::
+
+  sub vcl_recv {
+    set req.grace = 15s;
+  }
+
+You might wonder why we should keep the objects in the cache for 30
+minutes if we are unable to serve them? Well, if you have enabled
+:ref:`tutorial-advanced_backend_servers-health` you can check if the
+backend is healthy and serve the content for as longer.::
+
+   if (! req.backend.healthy) {
+      set req.grace = 5m;
+   } else {
+      set req.grace = 15s;
+   }
+  
+Saint mode
+~~~~~~~~~~
+
+Sometimes servers get flaky. They start throwing out random
+errors. You can instruct Varnish to try to handle this in a
+more-than-graceful way - enter *Saint mode*. Saint mode enables you to
+discard a certain page from one backend server and either try another
+server or serve stale content from cache. Lets have a look at how this
+can be enabled in VCL:::
+
+  sub vcl_fetch {
+    if (beresp.status == 500) { 
+      set beresp.saintmode = 10s;
+      restart;
+    }
+    set beresp.grace = 5m;
+  } 
+
+When we set beresp.saintmode to 10 seconds Varnish will not ask *that*
+server for URL for 10 seconds. A blacklist, more or less. Also a
+restart is performed so if you have other backends capable of serving
+that content Varnish will try those. When you are out of backends
+Varnish will serve the content from its stale cache.
+
+This can really be a life saver.
+
+God mode
+~~~~~~~~
+Not implemented yet. :-)
+

doc/sphinx/tutorial/increasing_your_hitrate.rst

@@ -25,9 +25,10 @@ vg.no was the first site to use Varnish and the people running Varnish
 there are quite clueful. So its interesting to look at their HTTP
 Headers. Lets send a GET requst for their home page.::
 
-  $ GET -H 'Host: vg.no' -Used http://vg.no/ 
-  GET http://www.vg.no/
-  User-Agent: Rickzilla 1.0
+  $ GET -H 'Host: www.vg.no' -Used http://vg.no/
+  GET http://vg.no/
+  Host: www.vg.no
+  User-Agent: lwp-request/5.834 libwww-perl/5.834
   
   200 OK
   Cache-Control: must-revalidate
@@ -59,10 +60,10 @@ So, to check whether a site sets cookies for a specific URL just do::
 Firefox plugins
 ~~~~~~~~~~~~~~~
 
-There are also a couple of great plugins for Firefox. Both *Live HTTP
-Headers* and *Firebug* can show you what headers are beeing sent and
-recieved. Try googling for them if you want to check them out. They
-are both recommended.
+There is also a plugin for Firefox. *Live HTTP Headers* can show you
+what headers are beeing sent and recieved. Live HTTP Headers can be
+found at https://addons.mozilla.org/en-US/firefox/addon/3829/ or by
+googling "Live HTTP Headers".
 
 
 The role of HTTP Headers
@@ -124,15 +125,19 @@ Quite simple. If, however, you need to do something more complicated,
 like removing one out of several cookies, things get
 difficult. Unfornunatly Varnish doesn't have good tools for
 manipulating the Cookies. We have to use regular expressions to do the
-work.
+work. If you are familiar with regular expressions you'll understand
+whats going on. If you don't I suggest you either pick up a book on
+the subject, read through the *pcrepattern* man page or read through
+one of many online guides.
 
 Let me show you what Varnish Software uses. We use some cookies for
 Google Analytics tracking and similar tools. The cookies are all set
 and used by Javascript. Varnish and Drupal doesn't need to see those
 cookies and since Varnish will cease caching of pages when the client
-sends cookies we will discard these unnecessary cookies in VCL.
+sends cookies we will discard these unnecessary cookies in VCL. 
 
-In the following VCL we discard all cookies that start with a underscore.::
+In the following VCL we discard all cookies that start with a
+underscore.::
 
   // Remove has_js and Google Analytics __* cookies.
   set req.http.Cookie = regsuball(req.http.Cookie, "(^|;\s*)(_[_a-z]+|has_js)=[^;]*", "");

doc/sphinx/tutorial/index.rst

@@ -30,6 +30,7 @@ it is installed with the default configuration.
         statistics.rst
         increasing_your_hitrate.rst
 	advanced_backend_servers.rst
+        handling_misbehaving_servers.rst
 	troubleshooting.rst
 
 .. todo::

doc/sphinx/tutorial/vcl.rst

@@ -56,3 +56,6 @@ from the backend. Normal tasks her are to alter the response headers,
 trigger ESI processing, try alternate backend servers in case the
 request failed.
 
+
+Example one
+~~~~~~~~~~~