rework tutorial according to new layout

doc/sphinx/tutorial/index.rst

@@ -13,13 +13,12 @@ following points:
 
 Then we hand things over to the user guide. 
 
-Let's start off by including some of the  stuff we chucked out of the
-previous tutorial - now "users guide"
+.. Let's start off by including some of the  stuff we chucked out of the
+.. previous tutorial - now "users guide"
 
 .. toctree:: :maxdepth: 1
 
    introduction
-   web_accelerator
    starting_varnish
    putting_varnish_on_port_80
    backend_servers

doc/sphinx/tutorial/introduction.rst

@@ -4,15 +4,38 @@ What is Varnish?
 ----------------
 
 Varnish Cache is a web application accelerator. It can also be called
-a HTTP reverse proxy. The next chapter :ref:`tutorial-web-accelerator`
-will go into detail on what Varnish is.
+a HTTP reverse proxy. It sits in front of a web server, accepts HTTP
+requests and tries to answer those by looking them up in it's
+cache. If it can't answer the request from cache it will hand the
+request over to a backend server.
+
+You can say that Varnish Cache is a specialized key-value store that
+stores HTTP responses. These are looked up with HTTP requests. If a
+match is found the content is delivered.
+
+Varnish Cache will typically look up a response by inspecting the HTTP
+Host header together with the URL.  Varnish Cache maintains an index,
+a hash, with all the host+url combinations that are kept in the cache.
+
+Some times Varnish will refuse to store the content in it's
+cache. This might be because the HTTP reponse has metadata that
+disables cacheing or that there might be a cookie involved. Varnish,
+in the default configuration, will refuse to cache content when there
+are cookies involved because it has no idea if the content is derived
+from the cookie or not.
+
+All this behaviour can be changed using VCL. See the Users Guide for
+more information on how to do that.
+
 
 Performance
 ~~~~~~~~~~~
 
 Varnish has a modern architecture and is written with performance in
 mind.  It is usually bound by the speed of the network, effectivly
-turning performance into a non-issue.
+turning performance into a non-issue. You get to focus on how your web
+application work and you can allow yourself, to some degree, to care
+less about performance and scalability.
 
 Flexibility
 ~~~~~~~~~~~
@@ -51,3 +74,5 @@ The are two mailing lists available. One for user questions and one
 for development discussions. See varnish-cache.org/mailinglist for
 information and signup.  There is also a web forum on the same site.
 
+Now that you have a vague idea on what Varnish Cache is, let see if we
+can get it up and running.

doc/sphinx/tutorial/peculiarities.rst

+
+Peculiarities
+-------------
+
+There are a couple of things that are different with Varnish Cache, as
+opposed to other programs. One thing you've already seen - VCL. I'll
+just give you a very quick tour of the other pecularities.
+
+
+varnishadm
+~~~~~~~~~~
+
+Varnish Cache has an admin console. You can connect it it through the
+"varnishadm" command. In order to connect the user needs to be able to
+read /etc/varnish/secret in order to authenticate.
+
+Once you've started the console you can do quite a few operations on
+Varnish, like stopping and starting the cache process, load VCL,
+adjust the built in load balancer and invalidate cached content.
+
+It has a built in command "help" which will give you some hints on
+what it does.
+
+varnishlog
+~~~~~~~~~~
+
+Varnish does not log to disk. Instead it logs to a bit of memory. It
+is like a stream of logs. At any time you'll be able to connect to the
+stream and see what is going on. Varnish logs quite a bit of
+information. You can have a look at the logstream with the command
+``varnishlog``.
+
+
+
+

doc/sphinx/tutorial/putting_varnish_on_port_80.rst

@@ -3,23 +3,46 @@ Put Varnish on port 80
 ----------------------
 
 Until now we've been running with Varnish on a high port, for testing
-purposes. You should test your application and if it works OK we can
-switch, so Varnish will be running on port 80 and your web server on a
-high port.
+purposes. You probably don't want to do this in the long term so let's
+put Varnish on port 80.
 
-First we kill off varnishd::
+First we stop varnish::
 
-     # pkill varnishd
+     # service varnish stop
 
-and stop your web server. Edit the configuration for your web server
-and make it bind to port 8080 instead of 80. Now open the Varnish
-default.vcl and change the port of the *default* backend to 8080.
+Now we need to edit the configuration file that starts Varnish. 
 
-Start up your web server and then start varnish::
 
-      # varnishd -f /usr/local/etc/varnish/default.vcl -s malloc,1G -T 127.0.0.1:2000
+Debian/Ubuntu
+~~~~~~~~~~~~~
 
-Note that we've removed the -a option. Now Varnish, as its default
-setting dictates, will bind to the http port (80). Now everyone
-accessing your site will be accessing through Varnish.
+On Debian/Ubuntu this is /etc/default/varnish. In the file you'll find some text that looks like this::
+
+  DAEMON_OPTS="-a :6081 \
+               -T localhost:6082 \
+               -f /etc/varnish/default.vcl \
+               -S /etc/varnish/secret \
+               -s malloc,256m"
+
+Change it to::
+
+  DAEMON_OPTS="-a :80 \
+               -T localhost:6082 \
+               -f /etc/varnish/default.vcl \
+               -S /etc/varnish/secret \
+               -s malloc,256m"
+
+Red Hat EL / Centos
+~~~~~~~~~~~~~~~~~~~
+
+On Red Hat EL / Centos
+On Red Hat/Centos it is
+
+
+Restarting Varnish
+------------------
+
+Once the change is done. Restart varnish: ``service varnish
+restart``. Now everyone accessing your site will be accessing through
+Varnish.
 

doc/sphinx/tutorial/starting_varnish.rst

 .. _tutorial-starting_varnish:
 
+
 Starting Varnish
 ----------------
 
-You might want to run ``pkill varnishd`` to make sure varnishd isn't
-already running. Become root and type:
-
-``# /usr/local/sbin/varnishd -f /usr/local/etc/varnish/default.vcl -s malloc,1G -a :80``
-
-I added a few options, lets go through them:
+This tutorial will assume that you are either running Ubuntu, Debian,
+Red Hat Enterprise Linux or Centos. Those of you running on other
+platforms might have to do some mental translation exercises in order
+to follow me. Since you're on a "weird" platform you're probably used
+to it. :-)
 
-``-f /usr/local/etc/varnish/default.vcl``
- The -f options specifies what configuration varnishd should use. If
- you are on a Linux system and have installed Varnish through packages
- the configuration files might reside in ``/etc/varnish``.
+I assume you have Varnish Cache installed.
 
-``-s malloc,1G``
- The -s options chooses the storage type Varnish should use for
- storing its content. I used the type *malloc*, which uses memory for
- storage. There are other backends as well, described in
- :ref:`user-guide-storage`. 1G specifies how much memory should be
- allocated - one gigabyte. 
+You start Varnish with ``service varnish start``.  This will start
+Varnish if it isn't already running.
 
 Now you have Varnish running. Let us make sure that it works
-properly. Use your browser to go to http://192.168.2.2/
+properly. Use your browser to go to http://127.0.0.1:6081/
 (obviously, you should replace the IP address with one on your own
-system) - you should now see your web application running there.
-
-There are many command line options available for Varnish. For a walk
-through the most important ones see :ref:`users-guide-command-line` or
-for a complete list see :ref:`ref-varnishd`. 
-
-Ignore that for the moment, we'll revisit that topic in the Users
-Guide :ref:`users-guide-increasing_your_hitrate`.
+system). 
+
+The default configuration will try to forward requests to a web
+service running on the same computer as Varnish was installed at,
+port 8080.
+
+If there is no web application being served up there Varnish will
+issue an error. Varnish Cache is very conservative about telling the
+world what is wrong so whenever something is amiss it will issue the
+same generic "Error 503 Service Unavilable".
+
+You might have a web application running on some other port or some
+other computer. Let's edit the configuration and make it point to
+something that actually works.
+
+Fire up your favorite editor and edit /etc/varnish/default.vcl. Most
+of it is commented out but there is some text that is not. It will
+probably look like this::
+
+  backend default {
+      .host = "127.0.0.1";
+      .port = "8080";
+  }
+
+We'll change it and make it point to something that works. Hopefully
+www.varnish-cache.org is up. Let's use that. Replace the text with::
+
+  backend default {
+      .host = "www.varnish-cache.org";
+      .port = "80";
+  }
+
+
+Now issue ``service varnish reload`` to make Varnish reload it's
+configuration. If that succeeded visit http://127.0.0.1:6081/ in your
+browser and you should see some directory listing. It works! The
+reason you're not seeing the Varnish official website is because your
+client isn't sending the appropriate Host: header in the request and
+it ends up showing a listing of the default webfolder on the machine
+usually serving up varnish-cache.org.

doc/sphinx/tutorial/web_accelerator.rst

-.. _tutorial-web_accelerator:
-
-What is a web accelerator
--------------------------
-
-Really.XXX.
-
-
-The problem
------------
-
-Application servers  er slow. They do lots of different things and
-they can sometimes take seconds to complete a web page.
-
-The solution
-------------
-
-Enter Varnish. It keeps a copy of the web pages that pass through
-it. If it finds that it can reuse these later so the server doesn't
-have to regenerate these it speeds things up.
-
-
-