advanced topics pointed out + some minor fixes

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

advanced topics pointed out + some minor fixes
git-svn-id: http://www.varnish-cache.org/svn/trunk/varnish-cache@4949 d4fa192b-c00b-0410-8231-f00ffab90ce4
590f8295 · Per Andreas Buer · 803db3c6 · 590f8295 · 590f8295 · 590f8295
Commit 590f8295 authored Jun 12, 2010 by Per Andreas Buer
5 changed files
--- a/doc/sphinx/reference/vcl.rst
+++ b/doc/sphinx/reference/vcl.rst
+.. _reference-vcl:
+
 ===
 VCL
 ===

--- a/doc/sphinx/tutorial/advanced_topics.rst
+++ b/doc/sphinx/tutorial/advanced_topics.rst
+.. _tutorial-advanced_topics:
+
+Advanced topics
+---------------
+
+This tutorial has covered the basics in Varnish. If you read through
+it all you should now have the skills to run Varnish.
+
+Here is a short overview of topics that we haven't covered in the tutorial. 
+
+More VCL
+~~~~~~~~
+
+VCL is a bit more complex then what we've covered so far. There are a
+few more subroutines available and there a few actions that we haven't
+discussed. For a complete(ish) guide to VCL have a look at the VCL man
+page - `ref`:reference-vcl.
+
+Using Inline C to extend Varnish
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use *inline C* to extend Varnish. Please note that you can
+seriously mess up Varnish this way. The C code runs within the Varnish
+Cache process so if your code generates a segfault the cache will crash.
+
+One of the first uses I saw of Inline C was logging to syslog.::
+
+	# The include statements must be outside the subroutines.
+	C{
+		#include <syslog.h>
+        }C
+	
+        sub vcl_something {
+                C{
+		        syslog(LOG_INFO, "Something happened at VCL line XX.");
+	        }C
+        }
+
+
+Edge Side Includes
+~~~~~~~~~~~~~~~~~~
+
+Varnish can cache create web pages by putting different pages
+together. These *fragments* can have individual cache policies. If you
+have a web site with a list showing the 5 most popular articles on
+your site this list can probably be cached as a fragment and included
+in all the other pages. Used properly it can dramatically increase
+your hitrate and reduce the load on your servers. ESI looks like this::
+
+  <HTML>
+  <BODY>
+  The time is: <esi:include src="/cgi-bin/date.cgi"/>
+  at this very moment.
+  </BODY>
+  </HTML>
+
+ESI is processed in vcl_fetch by using the *esi* keyword.::
+
+  sub vcl_fetch {
+      if (req.url == "/test.html") {
+	  esi;  /* Do ESI processing */
+      }
+  }
--- a/doc/sphinx/tutorial/increasing_your_hitrate.rst
+++ b/doc/sphinx/tutorial/increasing_your_hitrate.rst
@@ -116,6 +116,22 @@ kept inside Varnish. You can grep out Age from varnishlog like this::

  varnishlog -i TxHeader -I ^Age

+Overriding the time-to-live (ttl)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes your backend will misbehave. It might, depending on your
+setup, be easier to override the ttl in Varnish then to fix your
+somewhat cumbersome backend. 
+
+You need VCL to identify the objects you want and then you set the
+beresp.ttl to whatever you want.::
+
+  sub vcl_fetch {
+      if (req.url ~ "^/legacy_broken_cms/") {
+          set beresp.ttl = 5d;
+      }
+  }
+
 Cookies
 ~~~~~~~

@@ -304,7 +320,7 @@ following VCL in place:::
 		  if (!client.ip ~ purge) {
 			  error 405 "Not allowed.";
 		  }
-		  lookup;
+		  return (lookup);
 	  }
  }
  
@@ -324,6 +340,11 @@ following VCL in place:::
 	  }
  }

+As you can see we have used to new VCL subroutines, vcl_hit and
+vcl_miss. When we call lookup Varnish will try to lookup the object in
+its cache. It will either hit an object or miss it and so the
+corresponding subroutine is called. In vcl_hit the object that is
+stored in cache is available and we can set the TTL.

 So for vg.no to invalidate their front page they would call out to
 varnish like this:::

--- a/doc/sphinx/tutorial/index.rst
+++ b/doc/sphinx/tutorial/index.rst
@@ -15,7 +15,7 @@ is done.
 We assume you have a web server and a web application up and running
 and that you want to accelerate this application with Varnish.

-Furthermore we assume you have read the :ref:`Installation` and that
+Furthermore we assume you have read the :ref:`install-index` and that
 it is installed with the default configuration.


@@ -31,6 +31,7 @@ it is installed with the default configuration.
        increasing_your_hitrate.rst
 	advanced_backend_servers.rst
        handling_misbehaving_servers.rst
+        advanced_topics.rst
 	troubleshooting.rst

 .. todo::

--- a/doc/sphinx/tutorial/vcl.rst
+++ b/doc/sphinx/tutorial/vcl.rst
@@ -32,8 +32,10 @@ the beginning of a request, after the complete request has been
 received and parsed.  Its purpose is to decide whether or not to serve
 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.
+In vcl_recv you can also alter the request. Typically you can alter
+the cookies and add and remove request headers.
+
+Note that in vcl_recv only the request object, req is availble.

 vcl_fetch
 ~~~~~~~~~
@@ -43,6 +45,11 @@ from the backend. Normal tasks her are to alter the response headers,
 trigger ESI processing, try alternate backend servers in case the
 request failed.

+In vcl_fetch you still have the request object, req, available. There
+is also a *backend response*, beresp. beresp will contain the HTTP
+headers from the backend.
+
+
 actions
 ~~~~~~~