r4754 - in trunk/varnish-cache/doc/sphinx/tutorial: . vtc_files
phk at varnish-cache.org
phk at varnish-cache.org
Mon May 3 11:50:15 CEST 2010
Author: phk
Date: 2010-05-03 11:50:13 +0200 (Mon, 03 May 2010)
New Revision: 4754
Added:
trunk/varnish-cache/doc/sphinx/tutorial/intro.rst
trunk/varnish-cache/doc/sphinx/tutorial/tut001.rst
trunk/varnish-cache/doc/sphinx/tutorial/vtc_files/
trunk/varnish-cache/doc/sphinx/tutorial/vtc_files/C001.vtc
trunk/varnish-cache/doc/sphinx/tutorial/vtc_files/S001.vtc
Modified:
trunk/varnish-cache/doc/sphinx/tutorial/index.rst
Log:
Add the first tutorial example, based on the new -L flag to varnishtest.
Modified: trunk/varnish-cache/doc/sphinx/tutorial/index.rst
===================================================================
--- trunk/varnish-cache/doc/sphinx/tutorial/index.rst 2010-05-03 09:49:32 UTC (rev 4753)
+++ trunk/varnish-cache/doc/sphinx/tutorial/index.rst 2010-05-03 09:50:13 UTC (rev 4754)
@@ -7,33 +7,11 @@
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::
+.. toctree::
- Jogging: A Handbook
- Author: S. Noopy
- Chapter 1: Left foot
- It was a dark and stormy night...
+ intro.rst
+ tut001.rst
-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)
-
-
.. todo::
starting varnish with -d, seeing a transaction go through
explain varnishlog output for a miss and a hit
Added: trunk/varnish-cache/doc/sphinx/tutorial/intro.rst
===================================================================
--- trunk/varnish-cache/doc/sphinx/tutorial/intro.rst (rev 0)
+++ trunk/varnish-cache/doc/sphinx/tutorial/intro.rst 2010-05-03 09:50:13 UTC (rev 4754)
@@ -0,0 +1,51 @@
+%%%%%%%%%%%%
+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.
Added: trunk/varnish-cache/doc/sphinx/tutorial/tut001.rst
===================================================================
--- trunk/varnish-cache/doc/sphinx/tutorial/tut001.rst (rev 0)
+++ trunk/varnish-cache/doc/sphinx/tutorial/tut001.rst 2010-05-03 09:50:13 UTC (rev 4754)
@@ -0,0 +1,78 @@
+.. _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
Added: trunk/varnish-cache/doc/sphinx/tutorial/vtc_files/C001.vtc
===================================================================
--- trunk/varnish-cache/doc/sphinx/tutorial/vtc_files/C001.vtc (rev 0)
+++ trunk/varnish-cache/doc/sphinx/tutorial/vtc_files/C001.vtc 2010-05-03 09:50:13 UTC (rev 4754)
@@ -0,0 +1,6 @@
+# $Id$
+
+client c1 -connect 12 {
+ txreq
+ rxresp
+} -run
Added: trunk/varnish-cache/doc/sphinx/tutorial/vtc_files/S001.vtc
===================================================================
--- trunk/varnish-cache/doc/sphinx/tutorial/vtc_files/S001.vtc (rev 0)
+++ trunk/varnish-cache/doc/sphinx/tutorial/vtc_files/S001.vtc 2010-05-03 09:50:13 UTC (rev 4754)
@@ -0,0 +1,6 @@
+# $Id$
+
+server s1 -listen 2 {
+ rxreq
+ txresp -hdr "Foo: bar" -body "Hello World!"
+} -start -wait
More information about the varnish-commit
mailing list