Improving the VCL examples

Thijs Feryn · Thijs Feryn · commit eab5adcac3fa · 2013-05-23T17:52:28.000+02:00
diff --git a/cookbook/cache/varnish.rst b/cookbook/cache/varnish.rst
@@ -35,6 +35,7 @@ application:
 .. code-block:: text
 
     sub vcl_recv {
+        // Add a Surrogate-Capability header to announce ESI support.
         set req.http.Surrogate-Capability = "abc=ESI/1.0";
     }
 
@@ -45,12 +46,16 @@ Symfony2 adds automatically:
 .. code-block:: text
 
     sub vcl_fetch {
+        /* 
+        Check for ESI acknowledgement 
+        and remove Surrogate-Control header
+        */
         if (beresp.http.Surrogate-Control ~ "ESI/1.0") {
             unset beresp.http.Surrogate-Control;
 
-            // for Varnish >= 3.0
+            // For Varnish >= 3.0
             set beresp.do_esi = true;
-            // for Varnish < 3.0
+            // For Varnish < 3.0
             // esi;
         }
     }
@@ -75,14 +80,43 @@ that will invalidate the cache for a given resource:
 
 .. code-block:: text
 
+    /* 
+     Connect to the backend server 
+     on the local machine on port 8080
+     */
+    backend default {
+        .host = "127.0.0.1";
+        .port = "8080";
+    }
+
+    sub vcl_recv {
+        /* 
+        Varnish default behaviour doesn't support PURGE.
+        Match the PURGE request and immediately do a cache lookup, 
+        otherwise Varnish will directly pipe the request to the backend
+        and bypass the cache        
+        */
+        if (req.request == "PURGE") {
+            return(lookup);
+        }
+    }
+
     sub vcl_hit {
+        // Match PURGE request
         if (req.request == "PURGE") {
+            // Force object expiration for Varnish < 3.0
             set obj.ttl = 0s;
+            // Do an actual purge for Varnish >= 3.0
+            // purge;
             error 200 "Purged";
         }
     }
 
     sub vcl_miss {
+        /*
+        Match the PURGE request and
+        indicate the request wasn't stored in cache.
+        */
         if (req.request == "PURGE") {
             error 404 "Not purged";
         }
@@ -91,7 +125,56 @@ that will invalidate the cache for a given resource:
 .. caution::
 
     You must protect the ``PURGE`` HTTP method somehow to avoid random people
-    purging your cached data.
+    purging your cached data. You can do this by setting up an access list: 
+
+.. code-block:: text
+    /* 
+     Connect to the backend server 
+     on the local machine on port 8080
+     */
+    backend default {
+        .host = "127.0.0.1";
+        .port = "8080";
+    }
+
+	// Acl's can contain IP's, subnets and hostnames
+    acl purge {
+        "localhost";
+        "192.168.55.0"/24;
+    }
+
+    sub vcl_recv {
+        // Match PURGE request to avoid cache bypassing
+        if (req.request == "PURGE") {
+            // Match client IP to the acl
+            if (!client.ip ~ purge) {
+                // Deny access
+                error 405 "Not allowed.";
+            }
+            // Perform a cache lookup
+            return(lookup);
+        }
+    }
+	
+    sub vcl_hit {
+        // Match PURGE request
+        if (req.request == "PURGE") {
+            // Force object expiration for Varnish < 3.0
+            set obj.ttl = 0s;
+            // Do an actual purge for Varnish >= 3.0
+            // purge;
+            error 200 "Purged";
+        }
+    }	
+
+    sub vcl_miss {
+        // Match PURGE request    
+        if (req.request == "PURGE") {
+            // Indicate that the object isn't stored in cache
+            error 404 "Not purged";
+        }
+    }	
+
 
 .. _`Edge Architecture`: http://www.w3.org/TR/edge-arch
 .. _`GZIP and Varnish`: https://www.varnish-cache.org/docs/3.0/phk/gzip.html
