r3214 - trunk/varnish-cache/man

[tfheen at projects.linpro.no]

Author: tfheen
Date: 2008-09-23 13:58:53 +0200 (Tue, 23 Sep 2008)
New Revision: 3214

Modified:
   trunk/varnish-cache/man/vcl.7so
Log:
Update man page a bit

* Directors
* Probing and backend health
* vcl_hash
* Updates for 2.0 (backend.host => .host; insert => deliver)


Modified: trunk/varnish-cache/man/vcl.7so
===================================================================
--- trunk/varnish-cache/man/vcl.7so	2008-09-22 13:36:34 UTC (rev 3213)
+++ trunk/varnish-cache/man/vcl.7so	2008-09-23 11:58:53 UTC (rev 3214)
@@ -92,6 +92,78 @@
     set req.backend = www;
 }
 .Ed
+.Ss Directors
+Directors choose from different backends based on health status and a
+per-director algorithm.
+There currently exists a round-robin and a random director.  
+
+Directors are defined using:
+.Bd -literal -offset 4n
+director b2 random {
+    .retries = 5;
+    {
+        /* We can refer to named backends */
+        .backend        = b1;
+        .weight         = 7;
+    }
+    {
+        /* Or define them inline */
+        .backend        = {
+            .host = "fs2";
+        }
+        .weight         = 3;
+    }
+}
+.Ed
+.Ss The random director
+The random director takes one per-director option
+.Fa .retries .
+This specifies how many tries it will use to find a working backend.
+The default is the same as the number of backends defined for the
+director.
+
+There is also a per-backend option: weight which defines the portion
+of traffic to send to the particular backend.
+.Ed
+.Ss The round-robin director
+The round-robin does not take any options.
+.Ed
+.Ss Backend probes
+Backends can be probed to see whether they should be considered
+healthy or not.  The return status can also be checked by using 
+.Fa req.backend.healthy
+.
+.Fa .window
+is how many of the latest polls we examine, while
+.Fa .threshold
+is how many of those must have succeeded for us to consider the
+backend healthy.
+.Bd -literal -offset 4n
+backend www {
+    .host = "www.example.com";
+    .port = "http";
+    .probe = {
+        .url = "/test.jpg";
+        .timeout = 0.3 s;
+	.window = 8;
+	.threshold = 3;
+    }
+}
+.Ed
+It is also possible to specify the raw HTTP request.
+.Bd -literal -offset 4n
+backend www {
+    .host = "www.example.com";
+    .port = "http";
+    .probe = {
+        # NB: \\r\\n automatically inserted after each string!
+        .request =
+            "GET / HTTP/1.1"
+            "Host: www.foo.bar"
+            "Connection: close";
+    }
+}
+.Ed
 .Ss ACLs
 An ACL declaration creates and initializes a named access control list
 which can later be used to match client addresses:
@@ -245,7 +317,9 @@
 .El
 .\" vcl_hash
 .It Cm vcl_hash
-Currently not used.
+Use
+.Cm req.hash += req.http.Set-Cookie
+or similar to include the Set-Cookie HTTP header in the hash string.
 The
 .Cm vcl_hash
 subroutine may terminate with one of the following keywords:
@@ -313,10 +387,12 @@
 Switch to pass mode.
 Control will eventually pass to
 .Cm vcl_pass .
-.It Cm insert
-Insert the object into the cache, then deliver it to the client.
+.It Cm deliver
+Possibly insert the object into the cache, then deliver it to the client.
 Control will eventually pass to
 .Cm vcl_deliver .
+.It Cm esi
+ESI-process the document which has just been fetched.
 .El
 .\" vcl_deliver
 .It Cm vcl_deliver
@@ -381,9 +457,9 @@
 .Pp
 The following variables are available in backend declarations:
 .Bl -tag -width 4n
-.It Va backend.host
+.It Va .host
 Host name or IP address of a backend.
-.It Va backend.port
+.It Va .port
 Service name or port number of a backend.
 .El
 .Pp
@@ -405,6 +481,8 @@
 The HTTP protocol version used by the client.
 .It Va req.backend
 The backend to use to service the request.
+.It Va req.backend.healthy
+Whether the backend is healthy or not.
 .It Va req.http. Ns Ar header
 The corresponding HTTP
 .Ar header .
@@ -502,8 +580,8 @@
 .\" Keep this in synch with bin/varnishd/mgt_vcc.c and etc/default.vcl
 .Bd -literal -offset 4n
 backend default {
-    set backend.host = "backend.example.com";
-    set backend.port = "http";
+    .host = "backend.example.com";
+    .port = "http";
 }
 
 .so default.vcl
@@ -514,13 +592,13 @@
 based on the request URL.
 .Bd -literal -offset 4n
 backend www {
-    set backend.host = "www.example.com";
-    set backend.port = "80";
+    .host = "www.example.com";
+    .port = "80";
 }
 
 backend images {
-    set backend.host = "images.example.com";
-    set backend.port = "80";
+    .host = "images.example.com";
+    .port = "80";
 }
 
 sub vcl_recv {