[3.0] 26c1421 Remove the FAQ from sphinx. It was never properly maintained.

Tollef Fog Heen tfheen at varnish-cache.org
Mon Apr 22 13:27:00 CEST 2013


commit 26c142159a41879a742b095a29d3b6157a35c361
Author: Per Buer <perbu at varnish-software.com>
Date:   Tue Aug 21 10:28:52 2012 +0200

    Remove the FAQ
    from sphinx. It was never properly maintained.

diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am
index dc20abd..ed0930f 100644
--- a/doc/sphinx/Makefile.am
+++ b/doc/sphinx/Makefile.am
@@ -91,11 +91,6 @@ doctest:
 EXTRA_DIST = \
 	conf.py \
 	index.rst \
-	faq/configuration.rst \
-	faq/general.rst \
-	faq/http.rst \
-	faq/index.rst \
-	faq/logging.rst \
 	glossary/index.rst \
 	installation/bugs.rst \
 	installation/help.rst \
diff --git a/doc/sphinx/faq/configuration.rst b/doc/sphinx/faq/configuration.rst
deleted file mode 100644
index df06b07..0000000
--- a/doc/sphinx/faq/configuration.rst
+++ /dev/null
@@ -1,53 +0,0 @@
-%%%%%%%%%%%%%%%
-Configuration
-%%%%%%%%%%%%%%%
-
-.. _faq-vcl:
-
-VCL
-===
-
-**What is VCL?**
-
-VCL is an acronym for Varnish Configuration Language.  In a VCL file, you configure how Varnish should behave.  Sample VCL files will be included in this Wiki at a later stage.
-
-**Where is the documentation on VCL?**
-
-Please see ``man 7 vcl``.  There are also some real-world examples on
-the `wiki <http://varnish-cache.org/wiki/VCLExamples>`_
-
-
-**How do I load VCL file while Varnish is running?**
-
-* Place the VCL file on the server
-* Telnet into the managment port.
-* 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``.  Please see `this
-article <http://www.varnish-cache.org/trac/wiki/VCLExamplePipe>` for
-more details and a workaround.
-
-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``.
-
-
-
diff --git a/doc/sphinx/faq/general.rst b/doc/sphinx/faq/general.rst
deleted file mode 100644
index b0c7e13..0000000
--- a/doc/sphinx/faq/general.rst
+++ /dev/null
@@ -1,238 +0,0 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-General questions
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-What is Varnish?
-================
-
-Please see ref:`tutorial-intro`.
-
-How...
-======
-
-**How much RAM/Disk do I need for Varnish?**
-
-That depends on pretty much everything.
-
-I think our best current guidance is that you go for a cost-effective
-RAM configuration, something like 1-16GB, and an SSD.
-
-Unless you positively know that you will need it, there is
-little point in spending a fortune on a hand-sewn motherboard
-that can fit several TB in special RAM blocks, riveted together
-by leftover watch-makers in Switzerland.
-
-On the other hand, if you plot your traffic in Gb/s, you probably
-need all the RAM you can afford/get.
-
-**How can I limit Varnish to use less RAM?**
-
-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::
-
-                ban.url ^/$
-
-        to ban your / document.  As you might see ban.url 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 omitted, all the documents ending in a ``/`` in the cache would be deleted.
-
-        So to delete all the documents in the cache, write::
-
-                ban.url .
-
-        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 -m 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 -m 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 URLs for the virtualhostmonster::
-
-        if (req.http.host ~ "^(www.)?example.com") {
-          set req.url = regsub(req.url, "^", "/VirtualHostBase/http/example.com:80/Sites/example.com/VirtualHostRoot");
-        }
-
-**I have a site with many host names, how do I keep them from multiplying the cache?**
-
-You can do this by normalizing the ``Host`` header for all your host names.  Here's a VCL example::
-
-        if (req.http.host ~ "^(www.)?example.com") {
-          set req.http.host = "example.com";
-        }
-
-**How do I do to alter the request going to the backend?**
-You can use the ``bereq`` object for altering requests going to the backend, but you can only 'set' values to it. Therefore use req.url to build the request::
-
-        sub vcl_miss {
-                set bereq.url = regsub(req.url,"stream/","/");
-                return(fetch);
-        }
-
-**How can I customize the error messages that Varnish returns?**
-
-A custom error page can be generated by adding a ``vcl_error`` to your configuration file. The default error page looks like this::
-
-        sub vcl_error {
-            set obj.http.Content-Type = "text/html; charset=utf-8";
-
-            synthetic {"
-            <?xml version="1.0" encoding="utf-8"?>
-            <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-             "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-            <html>
-              <head>
-                <title>"} + obj.status + " " + obj.response + {"</title>
-              </head>
-              <body>
-              <h1>Error "} + obj.status + " " + obj.response + {"</h1>
-              <p>"} + obj.response + {"</p>
-                <h3>Guru Meditation:</h3>
-                <p>XID: "} + req.xid + {"</p>
-                <address><a href="http://www.varnish-cache.org/">Varnish</a></address>
-              </body>
-             </html>
-             "};
-            return(deliver);
-        }
-
-**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, "\?.*", "");
-        }
-
-
-Can I...
-========
-
-**Can I run Varnish on the same system as Apache?**
-
-Yes, and many people do that with good success.
-
-There will be competition for resources, but Apache is not particular
-good at using RAM effectively and Varnish is, so this synergy usually
-more than compensates for the competition.
-
-**Can I run multiple Varnish on the same system?**
-
-Yes, as long as you give them different TCP ports and different ``-n``
-arguments, you will be fine.
-
-
-**Can I cache multiple virtual hosts with one Varnish?**
-
-Yes, that works right out of the box.
-
-**Can I see what is cached in Varnish?**
-
-That is not possible for several reasons.  A command to list
-all the contents of a Varnish cache with millions of objects would
-bring your Varnish to a standstill while it traverses the index.
-
-Besides, the output is a lot less useful than you might think.
-
-**Can I use Varnish to do HTTPS?**
-
-Not at present, and while we keep an eye on this, there are no
-current plans to add HTTPS support, until we can find a way where
-it adds significant value, relative to running a stand-alone
-HTTPS proxy such as nginx or pound.
-
-**Can Varnish load balance between multiple backends?**
-
-Yes, you need VCL code like this::
-
-	director foobar round-robin {
-	    { .backend = { .host = "www1.example.com"; .port = "http"; } }
-	    { .backend = { .host = "www2.example.com"; .port = "http"; } }
-	}
-
-	sub vcl_recv {
-		set req.backend = foobar;
-	}
-
-Please see :ref:`tutorial-advanced_backend_servers-directors`.
-
-
-Why ...
-=======
-
-**Why does it look like Varnish sends all requests to the backend? I thought it was a cache?**
-
-
-Please see :ref:`tutorial-increasing_your_hitrate`.
-
-**Why does Varnish require the system to have a C compiler?**
-
-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.
-
-Troubleshooting
-===============
-
-**Why am I getting a cache hit, but a request is still going to my backend?**
-
-Varnish has a feature called **hit for pass**, which is used when Varnish gets a response from the backend and finds out it cannot be cached. In such cases, Varnish will create a cache object that records that fact, so that the next request goes directly to "pass".
-
-        Since Varnish bundles multiple requests for the same URL to the backend, a common case where a client will get a **hit for pass** is:
-          * Client 1 requests url /foo
-          * Client 2..N request url /foo
-          * Varnish tasks a worker to fetch /foo for Client 1
-          * Client 2..N are now queued pending response from the worker
-          * Worker returns object to varnish which turns out to be non-cacheable.
-          * Client 2..N are now given the **hit for pass** object instructing them to go to the backend
-
-The **hit for pass** object will stay cached for the duration of its ttl. This means that subsequent clients requesting /foo will be sent straight to the backend as long as the **hit for pass** object exists.
-The :command:`varnishstat` can tell you how many **hit for pass** objects varnish has served. The default vcl will set ttl for a hit_for_pass object to 120s. But you can override this, using the following logic::
-
-        sub vcl_fetch {
-          if (!obj.cacheable) {
-            # Limit the lifetime of all 'hit for pass' objects to 10 seconds
-            obj.ttl = 10s;
-            return(hit_for_pass);
-          }
-        }
-
diff --git a/doc/sphinx/faq/http.rst b/doc/sphinx/faq/http.rst
deleted file mode 100644
index 1e276ba..0000000
--- a/doc/sphinx/faq/http.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-%%%%%%%%%%%
-HTTP
-%%%%%%%%%%%
-
-**What is the purpose of the X-Varnish HTTP header?** 
-
-The X-Varnish HTTP header allows you to find the correct log-entries for the transaction. For a cache hit, X-Varnish will contain both the ID of the current request and the ID of the request that populated the cache. It makes debugging Varnish a lot easier.
-
-**Does Varnish support compression?**
-
-This is a simple question with a complicated answer; see `WIKI <http://varnish-cache.org/wiki/FAQ/Compression>`_.
-
-**How do I add a HTTP header?**
-
-To add a HTTP header, unless you want to add something about the client/request, it is best done in vcl_fetch as this means it will only be processed every time the object is fetched::
-
-        sub vcl_fetch {
-          # Add a unique header containing the cache servers IP address:
-          remove beresp.http.X-Varnish-IP;
-          set    beresp.http.X-Varnish-IP = server.ip;
-          # Another header:
-          set    beresp.http.Foo = "bar";
-        }
-
-**How can I log the client IP address on the backend?**
-
-All I see is the IP address of the varnish server.  How can I log the client IP address?
-
-We will need to add the IP address to a header used for the backend request, and configure the backend to log the content of this header instead of the address of the connecting client (which is the varnish server).
-
-Varnish configuration::
-
-        sub vcl_recv {
-          # Add a unique header containing the client address
-          remove req.http.X-Forwarded-For;
-          set    req.http.X-Forwarded-For = client.ip;
-          # [...]
-        }
-
-For the apache configuration, we copy the "combined" log format to a new one we call "varnishcombined", for instance, and change the client IP field to use the content of the variable we set in the varnish configuration::
-
-        LogFormat "%{X-Forwarded-For}i %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" varnishcombined
-
-And so, in our virtualhost, you need to specify this format instead of "combined" (or "common", or whatever else you use)::
-        
-	<VirtualHost *:80>
-          ServerName www.example.com
-          # [...]
-          CustomLog /var/log/apache2/www.example.com/access.log varnishcombined
-          # [...]
-        </VirtualHost>
-
-The [http://www.openinfo.co.uk/apache/index.html mod_extract_forwarded Apache module] might also be useful.
-
-
diff --git a/doc/sphinx/faq/index.rst b/doc/sphinx/faq/index.rst
deleted file mode 100644
index a8136a8..0000000
--- a/doc/sphinx/faq/index.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-.. _faq:
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%
-Frequently asked questions
-%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-The most frequently asked questions about Varnish in different contexts.
-
-
-.. toctree::
-
-	general.rst
-	http.rst
-	configuration.rst
-	logging.rst
-
-.. todo::
-        [V] - Now that the FAQ has been all reStructureized, we need to qualitycheck the content, update old info, and delete unrelevant info.
-
-
diff --git a/doc/sphinx/faq/logging.rst b/doc/sphinx/faq/logging.rst
deleted file mode 100644
index 89fdbde..0000000
--- a/doc/sphinx/faq/logging.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-%%%%%%%%%%%%%%%%%%%
-Logging
-%%%%%%%%%%%%%%%%%%%
-
-**Where can I find the log files?**
-
-Varnish does not log to a file, but to shared memory log. Use the varnishlog utility to print the shared memory log or varnishncsa to present it in the Apache / NCSA "combined" log format.
-
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index 2dbd605..c7c7fe8 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -21,7 +21,6 @@ Contents:
    installation/index.rst
    tutorial/index.rst
    reference/index.rst
-   faq/index.rst
    phk/index.rst
    glossary/index.rst
 



More information about the varnish-commit mailing list