Add the first tutorial example, based on the new -L flag to varnishtest.

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

doc/sphinx/tutorial/index.rst

@@ -7,32 +7,10 @@ Varnish Tutorial
 Welcome to the Varnish Tutorial, we hope this will help you get to 
 know and understand Varnish.
 
-Most tutorials are written in "subject-order", as the old Peanuts
-strip goes::
-
-	Jogging: A Handbook
-	Author:  S. Noopy
-	    Chapter 1: Left foot
-		It was a dark and stormy night...
-
-This is great when the reader has no choice, or nothing better to do, but
-read the entire document before starting.
-
-We have taken the other approach: "breadth-first", because experience
-has shown us that Varnish users wants to get things running, and then
-polish up things later on.
-
-With that in mind, we have written the tutorial so you can break off,
-as Calvin tells Ms. Wormwood, "when my brain is full for today", and
-come back later and learn more.
-
-That also means that right from the start, we will have several
-things going on in parallel and you will need at least four, sometimes
-more, terminal windows at the same time, to run the examples.
-
-
-//todo// First simple example (pending varnishtest support)
+.. toctree::
 
+	intro.rst
+	tut001.rst
 
 .. todo::
         starting varnish with -d, seeing a transaction go through

doc/sphinx/tutorial/intro.rst

+%%%%%%%%%%%%
+Introduction
+%%%%%%%%%%%%
+
+Most tutorials are written in "subject-order", as the old Peanuts
+strip goes::
+
+	Jogging: A Handbook
+	Author:  S. Noopy
+	    Chapter 1: Left foot
+		It was a dark and stormy night...
+
+This is great when the reader has no choice, and nothing better to
+do, but read the entire document before starting.
+
+We have taken the other approach: "breadth-first", because experience
+has shown us that Varnish users wants to get things running, and then
+polish up things later on.
+
+With that in mind, we have written the tutorial so you can break off,
+as Calvin tells Ms. Wormwood, "when my brain is full for today", and
+come back later and learn more.
+
+That also means that right from the start, we will have several
+things going on in parallel and you will need at least four, sometimes
+more, terminal windows at the same time, to run the examples.
+
+A word about TCP ports
+----------------------
+
+We have subverted our custom built regression test tool, a program
+called ```varnishtest``` to help you get through these examples,
+without having to waste too much time setting up webservers as 
+backends or browsers as clients, to drive the examples.
+
+But there is one complication we can not escape:  TCP port numbers.
+
+Each of the backends we simulate and the varnishd instances we run
+needs a TCP port number to listen to and it is your job to find them,
+because we have no idea what servers are running on your computer
+nor what TCP ports they use.
+
+To make this as easy as possible, we have implemented a ```-L
+number``` argument to all the varnish programs, which puts them in
+"Learner" mode, and in all the examples we have used 20000 as
+the number, because on most systems the middle of the range
+(1000...65000) is usually not used.
+
+If these ports are in use on your system (is your colleague also running
+the Varnish tutorial ?) simply pick another number and use that
+instead of 20000.

doc/sphinx/tutorial/tut001.rst

+.. _TUT001:
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+TUT001: Let's see if varnishtest is working
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+In the first window, start this command::
+
+	varnishtest -L20000 S001.vtc
+
+Then in the second window, run this one::
+
+	varnishtest -L20000 C001.vtc
+
+If things work as they should, both programs spit out 5 lines, looking
+like this in the first window::
+
+	*    top  TEST S001.vtc starting
+	**   s1   Started on 127.0.0.1:20012
+	**   s1   Ending
+	*    top  RESETTING after S001.vtc
+	*    top  TEST S001.vtc completed
+
+and like this in the second window::
+
+	*    top  TEST C001.vtc starting
+	**   c1   Starting client
+	**   c1   Ending
+	*    top  RESETTING after C001.vtc
+	*    top  TEST C001.vtc completed
+
+If that did not work, please consult the XXX: troubleshooting section.
+
+Now, try again, but this time run the client with a couple of ``-v``
+arguments::
+
+	varnishtest -vv -L20000 C001.vtc
+
+Now the output contains a lot mode detail::
+
+	*    top  TEST C001.vtc starting
+	***  top  client
+	**   c1   Starting client
+	***  c1   Connect to 127.0.0.1:20012
+	***  c1   connected fd 3
+	***  c1   txreq
+	**** c1   txreq| GET / HTTP/1.1\r\n
+	**** c1   txreq| \r\n
+	***  c1   rxresp
+	**** c1   rxhdr| HTTP/1.1 200 Ok\r\n
+	**** c1   rxhdr| Foo: bar\r\n
+	**** c1   rxhdr| Content-Length: 12\r\n
+	**** c1   rxhdr| \r\n
+	**** c1   http[ 0] | HTTP/1.1
+	**** c1   http[ 1] | 200
+	**** c1   http[ 2] | Ok
+	**** c1   http[ 3] | Foo: bar
+	**** c1   http[ 4] | Content-Length: 12
+	**** c1   body| Hello World!
+	**** c1   bodylen = 12
+	***  c1   closing fd 3
+	**   c1   Ending
+	*    top  RESETTING after C001.vtc
+	*    top  TEST C001.vtc completed
+
+First the client does a ``txreq`` -- "transmit request", and you can
+see the HTTP request it sends to the server, a plain boring "GET".
+
+Then it does a ``rxresp`` -- "receive response", and we can see the
+HTTP response we get back, including the HTTP object body.
+
+Now try again, this time running the server in the first window with
+``-vv``. 
+
+If things do not work the way you expect, adding those ``-v`` options
+is a good place to start debugging.
+
+Next we put a Varnish cache between the server and the client: _TUT002

doc/sphinx/tutorial/vtc_files/C001.vtc

+# $Id$
+
+client c1 -connect 12 {
+	txreq
+	rxresp
+} -run

doc/sphinx/tutorial/vtc_files/S001.vtc

+# $Id$
+
+server s1 -listen 2 {
+	rxreq
+	txresp -hdr "Foo: bar" -body "Hello World!"
+} -start -wait