VCL Basics

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

doc/sphinx/tutorial/vcl.rst

@@ -31,7 +31,12 @@ subroutines of the configuration at the relevant times.
 
 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 @@ the request, how to do it, and, if applicable, which backend to use.
 In vcl_recv you can also alter the request, dropping cookies, rewrite
 headers.
 
-
 vcl_fetch
 ~~~~~~~~~
 
@@ -56,6 +60,69 @@ from the backend. Normal tasks her are to alter the response headers,
 trigger ESI processing, try alternate backend servers in case the
 request failed.
 
+actions
+~~~~~~~
+
+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 one
-~~~~~~~~~~~
+Example 3 - ACLs
+~~~~~~~~~~~~~~~~