another bunch of man pages. Some have rendering issues that need I need to work out

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

doc/sphinx/installation/install.rst

 .. _install-doc:
 
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Installing Varnish on your computer
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Installing Varnish
+==================
 
 With open source software, you can choose to install binary packages
 or compile stuff from source-code. To install a package or compile
@@ -11,8 +10,8 @@ method too choose read the whole document and choose the method you
 are most confortable with.
 
 
-Installing Varnish from packages
-================================
+Source or packages?
+~~~~~~~~~~~~~~~~~~~
 
 Installing Varnish on most relevant operating systems can usually 
 be done with with the systems package manager, typical examples

doc/sphinx/reference/index.rst

@@ -5,14 +5,19 @@ The Varnish Reference Manual
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 .. toctree::
-	
-	varnishadm.rst
-	shmem.rst
+
 	vcl.rst
-	varnishstat.rst
-	varnishsizes.rst
-	varnishreplay.rst
+	varnishadm.rst
+	varnishd.rst
+	varnishhist.rst
 	varnishlog.rst
+	varnishncsa.rst
+	varnishreplay.rst
+	varnishsizes.rst
+	varnishstat.rst
+	varnishtest.rst
+	varnishtop.rst
+	shmem.rst
 
 .. todo::
         The programs:

doc/sphinx/reference/varnishhist.rst

+===========
+varnishhist
+===========
+
+-------------------------
+Varnish request histogram
+-------------------------
+
+SYNOPSIS
+========
+
+varnishhist [-b] [-C] [-c] [-d] [-I regex] [-i tag] [-n varnish_name] 
+[-r file] [-V] [-w delay] [-X regex] [-x tag]
+
+DESCRIPTION
+===========
+
+The varnishhist utility reads varnishd(1) shared memory logs and
+presents a continuously updated histogram show‐ ing the distribution
+of the last N requests by their processing.  The value of N and the
+vertical scale are dis‐ played in the top left corner.  The horizontal
+scale is logarithmic.  Hits are marked with a pipe character ("|"),
+and misses are marked with a hash character ("#").
+
+The following options are available:
+
+-b          Include log entries which result from communication with 
+	    a backend server.  If neither -b nor -c is
+	    specified, varnishhist acts as if they both were.
+
+-C          Ignore case when matching regular expressions.
+
+-c          Include log entries which result from communication with 
+	    a client.  If neither -b nor -c is specified, 
+	    varnishhist acts as if they both were.
+
+-d          Process old log entries on startup.  Normally, varnishhist 
+	    will only process entries which are written to the 
+	    log after it starts.
+
+-I regex    Include log entries which match the specified 
+   	    regular expression.  If neither -I nor -i is specified, 
+	    all log entries are included.
+
+-i tag      Include log entries with the specified tag.  If neither 
+   	    -I nor -i is specified, all log entries are included.
+
+-n          Specifies the name of the varnishd instance to get logs 
+	    from.  If -n is not specified, the host name is used.
+
+-r file     Read log entries from file instead of shared memory.
+
+-V          Display the version number and exit.
+
+-w delay    Wait at least delay seconds between each update.  The 
+   	    default is 1.  file instead of displaying them.  The file 
+	    will be overwritten unless the -a option was specified.
+
+-X regex    Exclude log entries which match the specified regular expression.
+
+-x tag      Exclude log entries with the specified tag.
+
+SEE ALSO
+========
+
+* varnishd(1)
+* varnishlog(1)
+* varnishncsa(1)
+* varnishstat(1) 
+* varnishtop(1)
+
+HISTORY
+=======
+The varnishhist utility was developed by Poul-Henning Kamp in cooperation with Verdens Gang
+AS and Linpro AS.  This manual page was written by Dag-Erling Smørgrav and Per Buer.
+
+COPYRIGHT
+=========
+
+This document is licensed under the same licence as Varnish
+itself. See LICENCE for details.
+
+* Copyright (c) 2006 Verdens Gang AS
+* Copyright (c) 2006-2008 Linpro AS
+* Copyright (c) 2008-2010 Redpill Linpro AS
+* Copyright (c) 2010 Varnish Software AS

doc/sphinx/reference/varnishncsa.rst

+===========
+varnishncsa
+===========
+
+---------------------------------------------------------
+Display Varnish logs in Apache / NCSA combined log format
+---------------------------------------------------------
+
+SYNOPSIS
+========
+
+varnishncsa [-a] [-b] [-C] [-c] [-D] [-d] [-f] [-I regex] 
+[-i tag] [-n varnish_name] [-P file] [-r file] [-V] 
+[-w file] [-X regex] [-x tag]
+
+DESCRIPTION
+===========
+
+The varnishncsa utility reads varnishd(1) shared memory logs and
+presents them in the Apache / NCSA "combined" log format.
+
+The following options are available:
+
+-a          When writing to a file, append to it rather than overwrite it.
+
+-b          Include log entries which result from communication with a 
+	    backend server.  If neither -b nor -c is
+	    specified, varnishncsa acts as if they both were.
+
+-C          Ignore case when matching regular expressions.
+
+-c          Include log entries which result from communication 
+	    with a client.  If neither -b nor -c is specified, 
+	    varnishncsa acts as if they both were.
+
+-D          Daemonize.
+
+-d          Process old log entries on startup.  Normally, varnishncsa 
+	    will only process entries which are written to the log 
+	    after it starts.
+
+-f          Prefer the X-Forwarded-For HTTP header over client.ip in 
+	    the log output.
+
+-I regex    Include log entries which match the specified regular 
+   	    expression.  If neither -I nor -i is specified, 
+	    all log entries are included.
+
+-i tag      Include log entries with the specified tag.  If neither -I nor 
+   	    -i is specified, all log entries are included.
+
+-n          Specifies the name of the varnishd instance to get logs 
+	    from.  If -n is not specified, the host name is used.
+
+-P file     Write the process's PID to the specified file.
+
+-r file     Read log entries from file instead of shared memory.
+
+-V          Display the version number and exit.
+
+-w file     Write log entries to file instead of displaying them.  
+   	    The file will be overwritten unless the -a
+	    option was specified.
+	    
+	    If varnishncsa receives a SIGHUP while writing to a file, 
+	    it will reopen the file, allowing the old one to be 
+	    rotated away.
+
+-X regex    Exclude log entries which match the specified 
+   	    regular expression.
+
+-x tag      Exclude log entries with the specified tag.
+
+SEE ALSO
+========
+
+* varnishd(1)
+* varnishhist(1)
+* varnishlog(1)
+* varnishstat(1)
+* varnishtop(1)
+
+HISTORY
+=======
+
+The varnishncsa utility was developed by Poul-Henning Kamp in
+cooperation with Verdens Gang AS and Linpro AS.  This manual page was
+written by Dag-Erling Smørgrav ⟨des@des.no⟩.

doc/sphinx/reference/varnishtest.rst

+===========
+varnishtest
+===========
+
+------------------------
+Test program for Varnish
+------------------------
+
+:Author: Stig Sandbeck Mathisen
+:Date:   2010-05-31
+:Version: 1.0
+:Manual section: 1
+
+
+SYNOPSIS
+========
+     varnishtest [-n iter] [-q] [-v] file [file ...]
+
+DESCRIPTION
+===========
+
+The varnishtest program is a script driven program used to test the
+varnish HTTP accelerator.
+
+The varnishtest program, when started and given one or more script
+files, can create a number of threads repre senting backends, some
+threads representing clients, and a varnishd process.
+
+The following options are available:
+
+-n iter     Run iter number of iterations.
+
+-q          Be quiet.
+
+-v          Be verbose.
+
+-L port     Listen on *port*. 
+
+-t          Dunno.
+
+file        File to use as a script
+
+
+SCRIPTS
+=======
+
+Example script
+~~~~~~~~~~~~~~
+::
+
+    # 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
+
+Example script output
+~~~~~~~~~~~~~~~~~~~~~
+
+The output, running this script looks as follows. The "bargraph" at
+the beginning of the line is an indication of the level of detail in
+the line. The second field where the message comes from. The rest of
+the line is anyones guess :-)
+::
+
+    #  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
+
+If instead of 200 we had expected 201 with the line:::
+
+  expect resp.status == 201
+
+The output would have ended with:::
+
+  #### 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
+
+SEE ALSO
+========
+
+* varnishhist(1)
+* varnishlog(1)
+* varnishncsa(1)
+* varnishstat(1)
+* varnishtop(1)
+* vcl(7)
+
+HISTORY
+=======
+
+The varnishtest program was developed by Poul-Henning Kamp
+⟨phk@phk.freebsd.dk⟩ in cooperation with Linpro AS. This manual page
+was written by Stig Sandbeck Mathisen ⟨ssm@linpro.no⟩ using examples
+by Poul-Henning Kamp ⟨phk@phk.freebsd.dk⟩.
+
+COPYRIGHT
+=========
+
+This document is licensed under the same licence as Varnish
+itself. See LICENCE for details.
+
+* Copyright (c) 2007-2008 Linpro AS
+* Copyright (c) 2010 Varnish Software AS

doc/sphinx/reference/varnishtop.rst

+============
+varnishtop
+============
+
+-------------------------
+Varnish log entry ranking
+-------------------------
+
+SYNOPSIS
+========
+
+varnishtop [-1] [-b] [-C] [-c] [-d] [-f] [-I regex] 
+[-i tag] [-n varnish_name] [-r file] [-V] [-X regex]
+[-x tag]
+
+DESCRIPTION
+===========
+
+The varnishtop utility reads varnishd(1) shared memory logs and
+presents a continuously updated list of the most commonly occurring
+log entries.  With suitable filtering using the -I, -i, -X and -x
+options, it can be used to display a ranking of requested documents,
+clients, user agents, or any other information which is recorded in
+the log.
+
+The following options are available:
+
+-1          Instead of presenting of a continuously updated display, 
+	    print the statistics once and exit. Implies -d.
+
+-b          Include log entries which result from communication 
+	    with a backend server.  If neither -b nor -c is
+	    specified, varnishtop acts as if they both were.
+
+-C          Ignore case when matching regular expressions.
+
+-c          Include log entries which result from communication 
+	    with a client.  If neither -b nor -c is specified, 
+	    varnishtop acts as if they both were.
+
+-d          Process old log entries on startup.  Normally, varnishtop 
+	    will only process entries which are written to the log 
+	    after it starts.
+
+-f          Sort and group only on the first field of each log entry.  
+	    This is useful when displaying e.g. stataddr entries, 
+	    where the first field is the client IP address.
+
+-I regex    Include log entries which match the specified regular 
+   	    expression.  If neither -I nor -i is specified, all log 
+	    entries are included.
+
+-i tag      Include log entries with the specified tag.  If neither -I 
+   	    nor -i is specified, all log entries are included.
+
+-n          Specifies the name of the varnishd instance to get logs from.  
+	    If -n is not specified, the host name is used.
+
+-r file     Read log entries from file instead of shared memory.
+
+-V          Display the version number and exit.
+
+-X regex    Exclude log entries which match the specified regular expression.
+
+-x tag      Exclude log entries with the specified tag.
+
+EXAMPLES
+========
+
+The following example displays a continuously updated list of the most
+frequently requested URLs:::
+
+  varnishtop -i RxURL
+
+The following example displays a continuously updated list of the most
+commonly used user agents:::
+
+  varnishtop -i RxHeader -C -I ^User-Agent
+
+SEE ALSO
+========
+
+* varnishd(1)
+* varnishhist(1)
+* varnishlog(1)
+* varnishncsa(1)
+* varnishstat(1)
+
+HISTORY
+=======
+
+The varnishtop utility was originally developed by Poul-Henning Kamp
+in cooperation with Verdens Gang AS and Linpro AS, and later
+substantially rewritten by Dag-Erling Smørgrav.  This manual page was
+written by Dag-Erling Smørgrav.