More clean-up.

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

doc/sphinx/faq/configuration.rst

@@ -2,6 +2,8 @@
 Configuration
 %%%%%%%%%%%%%%%
 
+.. _faq-vcl:
+
 VCL
 ===
 
@@ -23,3 +25,28 @@ Please also see ``man 7 vcl``.
 * do a "vcl.load <configname> <filename>" in managment interface. <configname> is whatever you would like to call your new configuration.
 * do a "vcl.use <configname>" to start using your new config.
 
+**Should I use ''pipe'' or ''pass'' in my VCL code? What is the difference?**
+
+When varnish does a ``pass`` it acts like a normal HTTP proxy. It
+reads the request and pushes it onto the backend. The next HTTP
+request can then be handled like any other.
+
+``pipe`` is only used when Varnish for some reason can't handle the
+``pass``. ``pipe`` reads the request, pushes in onty the backend
+_only_ pushes bytes back and forth, with no other actions taken.
+
+Since most HTTP clients do pipeline several requests into one
+connection this might give you an undesirable result - as every
+subsequent request will reuse the existing ``pipe``.
+
+Varnish versions prior to 2.0 does not support handling a request body
+with ``pass`` mode, so in those releases ``pipe`` is required for
+correct handling.
+
+In 2.0 and later, ``pass`` will handle the request body correctly.
+
+If you get 503 errors when making a request which is ``pass`` ed, make sure
+that you're specifying the backend before returning from vcl_recv with ``pass``.
+
+
+

doc/sphinx/faq/general.rst

@@ -49,6 +49,52 @@ You can not.  Varnish operates in Virtual Memory and it is up to the
 kernel to decide which process gets to use how much RAM to map the
 virtual address-space of the process.
 
+**How do I instruct varnish to ignore the query parameters and only cache one instance of an object?**
+
+This can be achieved by removing the query parameters using a regexp::
+
+        sub vcl_recv {
+            set req.url = regsub(req.url, "\?.*", "");
+        }
+
+**How can I force a refresh on a object cached by varnish?**
+
+Refreshing is often called `purging <http://dictionary.reference.com/browse/PURGE>`_ a document.  You can purge at least 2 different ways in Varnish:
+
+1. Command line
+
+        From the command line you can write::
+
+                url.purge ^/$
+
+        to purge your / document.  As you might see url.purge takes an `regular expression <http://en.wikipedia.org/wiki/Regular_expression>`_
+        as its argument. Hence the ``^`` and ``$`` at the front and end.  If the ``^`` is ommited, all the documents ending in a ``/`` in the cache would be deleted.
+
+        So to delete all the documents in the cache, write::
+
+                url.purge .*
+
+        at the command line.
+
+2. HTTP PURGE
+
+        VCL code to allow HTTP PURGE is to be found `here <http://www.varnish-cache.org/wiki/VCLExamplePurging>`_. Note that this method does not support wildcard purging.
+
+**How can I debug the requests of a single client?**
+
+The "varnishlog" utility may produce a horrendous amount of output.  To be able debug our own traffic can be useful.
+
+The ReqStart token will include the client IP address.  To see log entries matching this, type::
+
+        $ varnishlog -c -o ReqStart 192.0.2.123
+
+To see the backend requests generated by a client IP address, we can match on the TxHeader token, since the IP address of the client is included in the X-Forwarded-For header in the request sent to the backend.
+
+At the shell command line, type::
+
+        $ varnishlog -b -o TxHeader 192.0.2.123
+
+
 
 Where...
 ========
@@ -162,6 +208,14 @@ To make a PCRE regex case insensitive, put ``(?i)`` at the start::
 
 See the `PCRE man pages <http://www.pcre.org/pcre.txt>`_ for more information.
 
+**Are regular expressions case sensitive or not? Can I change it?**
+
+In 2.1 and newer, regular expressions are case sensitive by default.  In earlier versions, they were case insensitive.
+
+To change this for a single regex in 2.1, use ``(?i)`` at the start.
+
+See the `PCRE man pages <http://www.pcre.org/pcre.txt>`_ for more information.
+
 
 **Why does the ``Via:`` header say 1.1 in Varnish 2.1.x?**
 
@@ -184,15 +238,10 @@ r.v. var·nished, var·nish·ing, var·nish·es
 The three point describes happens to your backend system when you
 put Varnish in front of it.
 
-How...
-======
-
-**How do I instruct varnish to ignore the query parameters and only cache one instance of an object?**
-
-This can be achieved by removing the query parameters using a regexp::
+**Why does Varnish require the system to have a C compiler?**
 
-        sub vcl_recv {
-            set req.url = regsub(req.url, "\?.*", "");
-        }
+The :ref:`VCL <faq-vcl>` compiler generates C source as output (your config file), and uses the systems C-compiler to compile that into a shared library.  If there is no C compiler, Varnish will not work.
 
+**Isn't that security problem?**
 
+The days when you could prevent people from running non-approved programs by removing the C compiler from your system ended roughly with the VAX 11/780 computer.

doc/sphinx/faq/old-faq.rst

@@ -6,89 +6,8 @@ The old Trac FAQ, still to be reformattet:
 
 
 
-        === Does Varnish require the system to have a C compiler? ===
-
-        Yes.  The VCL compiler generates C source as output, and uses the systems C-compiler to compile that into a shared library.  If there is no C compiler, Varnish will not work.
-
-        === ... Isn't that security problem? ===
-
-        The days when you could prevent people from running non-approved programs by removing the C compiler from your system ended roughly with the VAX 11/780 computer.
-
-        === Should I use ''pipe'' or ''pass'' in my VCL code? What is the difference? ===
-
-        When varnish does a ''pass'' it acts like a normal HTTP proxy. It
-        reads the request and pushes it onto the backend. The next HTTP
-        request can then be handled like any other.
-
-        ''pipe'' is only used when Varnish for some reason can't handle the
-        ''pass''. ''pipe'' reads the request, pushes in onty the backend
-        _only_ pushes bytes back and forth, with no other actions taken.
-
-        Since most HTTP clients do pipeline several requests into one
-        connection this might give you an undesirable result - as every
-        subsequent request will reuse the existing ''pipe''.
-
-        Varnish versions prior to 2.0 does not support handling a request body
-        with ''pass'' mode, so in those releases ''pipe'' is required for
-        correct handling.
-
-        In 2.0 and later, ''pass'' will handle the request body correctly.
-
-        If you get 503 errors when making a request which is ''pass''ed, make sure
-        that you're specifying the backend before returning from vcl_recv with ''pass''.
-
-
-        === Are regular expressions case sensitive or not? Can I change it? ===
-
-        In 2.1 and newer, regular expressions are case sensitive by default.  In earlier versions, they were case insensitive.
-
-        To change this for a single regex in 2.1, use "(?i)" at the start.  See the [http://www.pcre.org/pcre.txt PCRE man pages] for more information.
-
         == How do I... ==
 
-        === How can I force a refresh on a object cached by varnish? ===
-
-        Refreshing is often called [http://dictionary.reference.com/browse/PURGE purging] a document.  You can purge at least 2 different ways in Varnish:
-
-        1. From the command line you can write:
-
-        {{{
-        url.purge ^/$
-        }}}
-
-        to purge your '''/''' document.  As you might see url.purge takes an
-        [http://en.wikipedia.org/wiki/Regular_expression regular expression]
-        as its argument. Hence the !^ and $ at the front and end.  If the !^ is ommited, all the documents ending in a / in the cache would be deleted.
-
-        So to delete all the documents in the cache, write:
-
-        {{{
-        url.purge .*
-        }}}
-
-        at the command line.
-
-        2. HTTP PURGE
-
-        VCL code to allow HTTP PURGE [wiki:VCLExamples is to be found here]. Note that this method does not support wildcard purging.
-
-        === How can I debug the requests of a single client? ===
-
-        The "varnishlog" utility may produce a horrendous amount of output.  To be able debug our own traffic can be useful.
-
-        The ReqStart token will include the client IP address.  To see log entries matching this, type:
-
-        {{{
-        $ varnishlog -c -o ReqStart 192.0.2.123
-        }}}
-
-        To see the backend requests generated by a client IP address, we can match on the TxHeader token, since the IP address of the client is included in the X-Forwarded-For header in the request sent to the backend.
-
-        At the shell command line, type:
-        {{{
-        $ varnishlog -b -o TxHeader 192.0.2.123
-        }}}
-
         === How can I rewrite URLS before they are sent to the backend? ===
 
         You can use the "regsub()" function to do this.  Here's an example for zope, to rewrite URL's for the virtualhostmonster: