Add a varnishtest man page

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

bin/varnishtest/Makefile.am

@@ -9,6 +9,8 @@ INCLUDES = -I$(top_srcdir)/include
 
 bin_PROGRAMS =	varnishtest
 
+dist_man_MANS = varnishtest.1
+
 varnishtest_SOURCES = \
 		vtc.c \
 		vtc.h \

bin/varnishtest/varnishtest.1

+.\"-
+.\" Copyright (c) 2006-2008 Linpro AS
+.\" All rights reserved.
+.\"
+.\" Author: Stig Sandbeck Mathisen <ssm@linpro.no>
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $Id$
+.\"
+.Dd October 29, 2008
+.Dt VARNISHTEST 1
+.Os
+.Sh NAME
+.Nm varnishtest
+.Nd Test program for Varnish
+.Sh SYNOPSIS
+.Nm
+.Op Fl n Ar iter
+.Op Fl q
+.Op Fl v
+.Ar file
+.Op Ar file ...
+.Sh DESCRIPTION
+The
+.Nm
+program is a script driven program used to test the varnish HTTP
+accelerator.
+.Pp
+The
+.Nm
+program, when started and given one or more script files, can create a
+number of threads representing backends, some threads representing
+clients, and a varnishd process.
+.Pp
+The following options are available:
+.Bl -tag -width Fl
+.It Fl n Ar iter
+Run 
+.Ar iter
+number of iterations.
+.It Fl q
+Be quiet.
+.It Fl v
+Be verbose.
+.It Ar file
+File to use as a script
+.El
+.Sh SCRIPTS
+.Ss Example script
+.Bd -literal -offset 4n
+# Start a varnish instance called "v1"
+varnish v1 -arg "-b localhost:9080" -start
+
+# Create a server thread called "s1"
+server s1 {
+    # Receive a request
+    rxreq 
+    # Send a standard response
+    txresp -hdr "Connection: close" -body "012345\\n"
+}
+
+# Start the server thread
+server s1 -start 
+
+# Create a client thread called "c1"
+client c1 {
+   # Send a request
+   txreq -url "/"
+   # Wait for a response
+   rxresp
+   # Insist that it be a success
+   expect resp.status == 200
+}
+
+# Run the client
+client c1 -run
+
+# Wait for the server to die
+server s1 -wait
+
+# (Forcefully) Stop the varnish instance.
+varnish v1 -stop
+.Ed
+
+.Ss Example script output
+The output, running this script looks as follows.
+.Pp
+The "bargraph" at the beginning of the line is an indication of the
+level of detail in the line.
+.Pp
+The second field where the message comes from
+.Pp
+The rest of the line is anyones guess :-)
+.Bd -literal -offset 4n
+#    TEST tests/b00000.vtc starting
+###  v1   CMD: cd ../varnishd && ./varnishd -d -d -n v1 -a :9081 -T :9001 -b localhost:9080
+###  v1   opening CLI connection
+#### v1   debug| NB: Storage size limited to 2GB on 32 bit architecture,\\n
+#### v1   debug| NB: otherwise we could run out of address space.\\n
+#### v1   debug| storage_file: filename: ./varnish.Shkoq5 (unlinked) size 2047 MB.\\n
+###  v1   CLI connection fd = 3
+#### v1   CLI TX| start
+#### v1   debug| Using old SHMFILE\\n
+#### v1   debug| Notice: locking SHMFILE in core failed: Operation not permitted\\n
+#### v1   debug| bind(): Address already in use\\n
+#### v1   debug| rolling(1)...
+#### v1   debug| \\n
+#### v1   debug| rolling(2)...\\n
+#### v1   debug| Debugging mode, enter "start" to start child\\n
+###  v1   CLI 200 <start>
+##   s1   Starting server
+###  s1   listen on :9080 (fd 6)
+##   c1   Starting client
+##   c1   Waiting for client
+##   s1   started on :9080
+##   c1   started
+###  c1   connect to :9081
+###  c1   connected to :9081 fd is 8
+#### c1   | GET / HTTP/1.1\\r\\n
+#### c1   | \\r\\n
+###  c1   rxresp
+#### s1   Accepted socket 7
+###  s1   rxreq
+#### s1   | GET / HTTP/1.1\\r\\n
+#### s1   | X-Varnish: 422080121\\r\\n
+#### s1   | X-Forwarded-For: 127.0.0.1\\r\\n
+#### s1   | Host: localhost\\r\\n
+#### s1   | \\r\\n
+#### s1   http[ 0] | GET
+#### s1   http[ 1] | /
+#### s1   http[ 2] | HTTP/1.1
+#### s1   http[ 3] | X-Varnish: 422080121
+#### s1   http[ 4] | X-Forwarded-For: 127.0.0.1
+#### s1   http[ 5] | Host: localhost
+#### s1   | HTTP/1.1 200 Ok\\r\\n
+#### s1   | Connection: close\\r\\n
+#### s1   | \\r\\n
+#### s1   | 012345\\n
+#### s1   | \\r\\n
+##   s1   ending
+#### c1   | HTTP/1.1 200 Ok\\r\\n
+#### c1   | Content-Length: 9\\r\\n
+#### c1   | Date: Mon, 16 Jun 2008 22:16:55 GMT\\r\\n
+#### c1   | X-Varnish: 422080121\\r\\n
+#### c1   | Age: 0\\r\\n
+#### c1   | Via: 1.1 varnish\\r\\n
+#### c1   | Connection: keep-alive\\r\\n
+#### c1   | \\r\\n
+#### c1   http[ 0] | HTTP/1.1
+#### c1   http[ 1] | 200
+#### c1   http[ 2] | Ok
+#### c1   http[ 3] | Content-Length: 9
+#### c1   http[ 4] | Date: Mon, 16 Jun 2008 22:16:55 GMT
+#### c1   http[ 5] | X-Varnish: 422080121
+#### c1   http[ 6] | Age: 0
+#### c1   http[ 7] | Via: 1.1 varnish
+#### c1   http[ 8] | Connection: keep-alive
+#### c1   EXPECT resp.status (200) == 200 (200) match
+##   c1   ending
+##   s1   Waiting for server
+#### v1   CLI TX| stop
+###  v1   CLI 200 <stop>
+#    TEST tests/b00000.vtc completed
+.Ed
+.Pp
+If instead of 200 we had expected 201 with the line:
+.Bd -literal -offset 4n
+expect resp.status == 201
+.Ed
+.Pp
+The output would have ended with:
+.Bd -literal -offset 4n
+#### c1   http[ 0] | HTTP/1.1
+#### c1   http[ 1] | 200
+#### c1   http[ 2] | Ok
+#### c1   http[ 3] | Content-Length: 9
+#### c1   http[ 4] | Date: Mon, 16 Jun 2008 22:26:35 GMT
+#### c1   http[ 5] | X-Varnish: 648043653 648043652
+#### c1   http[ 6] | Age: 6
+#### c1   http[ 7] | Via: 1.1 varnish
+#### c1   http[ 8] | Connection: keep-alive
+---- c1   EXPECT resp.status (200) == 201 (201) failed
+.Ed
+.Sh SEE ALSO
+.Xr varnishlog 1 ,
+.Xr varnishhist 1 ,
+.Xr varnishncsa 1 ,
+.Xr varnishstat 1 ,
+.Xr varnishtop 1 ,
+.Xr vcl 7
+.Sh HISTORY
+The
+.Nm
+program was developed by
+.An Poul-Henning Kamp Aq phk@phk.freebsd.dk
+in cooperation with Verdens Gang AS and Linpro AS.  This manual page
+was written by
+.An Stig Sandbeck Mathisen Aq ssm@linpro.no
+using examples by
+.An Poul-Henning Kamp Aq phk@phk.freebsd.dk