r4856 - trunk/varnish-cache/doc/sphinx/tutorial

[perbu at varnish-cache.org]

Author: perbu
Date: 2010-05-25 08:59:10 +0200 (Tue, 25 May 2010)
New Revision: 4856

Modified:
   trunk/varnish-cache/doc/sphinx/tutorial/vcl.rst
Log:
VCL Basics

Modified: trunk/varnish-cache/doc/sphinx/tutorial/vcl.rst
===================================================================
--- trunk/varnish-cache/doc/sphinx/tutorial/vcl.rst	2010-05-21 12:01:16 UTC (rev 4855)
+++ trunk/varnish-cache/doc/sphinx/tutorial/vcl.rst	2010-05-25 06:59:10 UTC (rev 4856)
@@ -31,8 +31,13 @@
 
 Varnish will execute these subroutines of code at different stages of
 its work. Since its code it's execute line by line and precedence
-isn't a problem.
+isn't a problem. At some point you call an action in this subroutine
+and then the execution of the subroutine stops. 
 
+If you don't call an action in your subroutine and it reaches the end
+Varnish will execute some built in code as well. We discuss this in
+XXX: Appendix A - the builtin VCL.
+
 99% of all the changes you'll need to do will be done in two of these
 subroutines.
 
@@ -47,7 +52,6 @@
 In vcl_recv you can also alter the request, dropping cookies, rewrite
 headers.
 
-
 vcl_fetch
 ~~~~~~~~~
 
@@ -56,6 +60,69 @@
 trigger ESI processing, try alternate backend servers in case the
 request failed.
 
+actions
+~~~~~~~
 
-Example one
-~~~~~~~~~~~
+The most common actions to call are these:
+
+*pass*
+ When you call pass the request and subsequent response will be passed
+ to and from the backend server. It won't be cached. pass can be called 
+ in both vcl_recv and vcl_fetch.
+
+*lookup*
+  When you call lookup from vcl_recv you tell Varnish to deliver content 
+  from cache even if the request othervise indicates that the request 
+  should be passed. You can't call lookup from vcl_fetch.
+
+*pipe*
+ 
+
+*deliver*
+
+*esi*
+ ESI-process the fetched document.
+
+Example 1 - manipulating headers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Lets say we want to remove the cookie for all objects in the /static
+directory of our web server:::
+
+  sub vcl_recv {
+    if (req.url ~ "^/images") {
+      unset req.http.cookie;
+    }
+  }
+
+Now, when the request is handled to the backend server there will be
+no cookie header. The interesting line is the one with the
+if-statement. It probably needs a bit of explaining. Varnish has a few
+objects that are available throughout the VCL. The important ones are:
+
+*req*
+ The request object. Each HTTP transaction contains a request and a 
+ response. When Varnish has recieved the request the req object is 
+ created and populated. Most of the work you do in vcl_fetch you 
+ do on or with the req object.
+
+*beresp*
+ The backend respons object. It contains the headers of the object 
+ comming from the backend. Most of the work you do in vcl_fetch you 
+ do on the beresp object.
+
+Example 2 - manipulating beresp
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here we override the TTL of a object comming from the backend if it
+matches certain criteria:::
+
+  sub vcl_fetch {
+     if (beresp.url ~ "\.(png|gif|jpg)$") {
+       unset beresp.http.set-cookie;
+       beresp.ttl = 3600;
+    }
+  }
+
+Example 3 - ACLs
+~~~~~~~~~~~~~~~~