[master] f8dd5cc Documentation updates
Tollef Fog Heen
tfheen at varnish-cache.org
Thu May 5 14:39:32 CEST 2011
commit f8dd5cccebe2101dc2114e5d1b8d4be5e0ecfe31
Author: Tollef Fog Heen <tfheen at varnish-software.com>
Date: Thu May 5 14:38:45 2011 +0200
Documentation updates
Update docs for purge → ban rename plus various typos and grammatical
errors.
diff --git a/doc/sphinx/faq/general.rst b/doc/sphinx/faq/general.rst
index 26b86fa..12617f5 100644
--- a/doc/sphinx/faq/general.rst
+++ b/doc/sphinx/faq/general.rst
@@ -33,11 +33,11 @@ How...
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 a SSD disk.
+RAM configuration, something like 1-16GB, and an SSD.
Unless you positively know that you will need it, there is
-little point in spendng a fortune on a hand-sewn motherboard
-that can fit several TB in special RAM blocks, rivetet together
+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
@@ -65,14 +65,14 @@ Refreshing is often called `purging <http://dictionary.reference.com/browse/PURG
From the command line you can write::
- url.purge ^/$
+ ban.url ^/$
- 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.
+ 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::
- url.purge .*
+ ban.url .
at the command line.
@@ -96,15 +96,15 @@ At the shell command line, type::
**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::
+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 hostnames, how do I keep them from multiplying the cache?**
+**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 hostnames. Here's a VCL example::
+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";
@@ -120,7 +120,7 @@ You can use the ``bereq`` object for altering requests going to the backend, but
**How do I force the backend to send Vary headers?**
-We have anectdotal evidence of non-RFC2616 compliant backends, which support content negotiation, but which do not emit a Vary header, unless the request contains Accept headers.
+We have anecdotal evidence of non-RFC2616 compliant backends, which support content negotiation, but which do not emit a Vary header, unless the request contains Accept headers.
It may be appropriate to send no-op Accept headers to trick the backend into sending us the Vary header.
@@ -177,8 +177,8 @@ Where...
**Can I find varnish for my operating system?**
We know that Varnish has been packaged for Debian, Ubuntu, RHEL,
-Centos, (Open)SuSE, Gentoo and FreeBSD, possibly more. Check whatever
-packagemanager you use. Or read :ref:`Installing Varnish on your computer <install-doc>`.
+CentOS, (Open)SUSE, Gentoo and FreeBSD, possibly more. Check whatever
+package manager you use. Or read :ref:`Installing Varnish on your computer <install-doc>`.
Can I...
========
@@ -211,7 +211,7 @@ Yes, as long as you give them different TCP ports and different ``-n``
arguments, you will be fine.
-**Can I cache multiple vhosts with one Varnish?**
+**Can I cache multiple virtual hosts with one Varnish?**
Yes, that works right out of the box.
@@ -228,7 +228,7 @@ Besides, the output is a lot less useful than you might think.
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 ngnix or pound.
+HTTPS proxy such as nginx or pound.
**Can Varnish load balance between multiple backends?**
@@ -259,10 +259,10 @@ There are 2 common reasons for this:
**Why are regular expressions case-sensitive?**
-Some HTTP headers, such as ``Host:`` and ``Location:``
-contain FQDN's which by definition is not case-sensitive. Other
-HTTP headers are case-sensitive, most notably the URLs. Therefore
-a "one size fits all" solution is not possible.
+Some HTTP headers, such as ``Host:`` and ``Location:`` contain fully
+qualified domain names, which by definition is not case-sensitive.
+Other HTTP headers are case-sensitive, most notably the URLs.
+Therefore a "one size fits all" solution is not possible.
In previous releases, we used the POSIX regular expressions
supplied with the operating system, and decided, because the
@@ -272,12 +272,12 @@ they should not be case-sensitive.
From version 2.1.0 and forward, we use PCRE regular expressions,
where it *is* possible to control case-sensitivity in the
individual regular expressions, so we decided that it would
-probably confuse people if we made the default case-insentive.
+probably confuse people if we made the default case-insensitive.
(We promise not to change our minds about this again.)
To make a PCRE regex case insensitive, put ``(?i)`` at the start::
- if (req.http.host ~ "?iexample.com$") {
+ if (req.http.host ~ "(?i)example.com$") {
...
}
@@ -295,7 +295,7 @@ 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?**
The number in the ``Via:`` header is the HTTP protocol version
-supported/applied, not the softwares version number.
+supported/applied, not the software's version number.
**Why did you call it *Varnish*?**
@@ -336,14 +336,14 @@ Varnish has a feature called **hit for pass**, which is used when Varnish gets a
* 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 it's 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 **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. You can lower the ttl for such an object if you are sure this is needed, 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;
- pass;
+ return(hit_for_pass);
}
}
diff --git a/doc/sphinx/reference/varnish-cli.rst b/doc/sphinx/reference/varnish-cli.rst
index 145f960..36e4c16 100644
--- a/doc/sphinx/reference/varnish-cli.rst
+++ b/doc/sphinx/reference/varnish-cli.rst
@@ -120,7 +120,7 @@ ban.url regexp
Immediately invalidate all documents whose URL matches the
specified regular expression. Please note that the Host part of
the URL is ignored, so if you have several virtual hosts all of
- them will be purged. Use *ban* to specify a complete ban if you
+ them will be banned. Use *ban* to specify a complete ban if you
need to narrow it down.
quit
@@ -280,16 +280,16 @@ EXAMPLES
========
Simple example: All requests where req.url exactly matches the string
-/news are purged from the cache:::
+/news are banned from the cache:::
req.url == "/news"
-Example: Purge all documents where the name does not end with ".ogg",
+Example: Ban all documents where the name does not end with ".ogg",
and where the size of the object is greater than 10 megabytes:::
req.url !~ "\.ogg$" && obj.size > 10MB
-Example: Purge all documents where the serving host is "example.com"
+Example: Ban all documents where the serving host is "example.com"
or "www.example.com", and where the Set-Cookie header received from
the backend contains "USERID=1663":::
diff --git a/doc/sphinx/reference/vcl.rst b/doc/sphinx/reference/vcl.rst
index 85553f4..cfb1c38 100644
--- a/doc/sphinx/reference/vcl.rst
+++ b/doc/sphinx/reference/vcl.rst
@@ -323,8 +323,8 @@ regsub(str, regex, sub)
regsuball(str, regex, sub)
As regsuball() but this replaces all occurrences.
-purge_url(regex)
- Purge all objects in cache whose URLs match regex.
+ban_url(regex)
+ Ban all objects in cache whose URLs match regex.
Subroutines
~~~~~~~~~~~
@@ -523,7 +523,7 @@ Example:::
# in file "main.vcl"
include "backends.vcl";
- include "purge.vcl";
+ include "ban.vcl";
# in file "backends.vcl"
sub vcl_recv {
@@ -534,11 +534,11 @@ Example:::
}
}
- # in file "purge.vcl"
+ # in file "ban.vcl"
sub vcl_recv {
if (client.ip ~ admin_network) {
if (req.http.Cache-Control ~ "no-cache") {
- purge_url(req.url);
+ ban_url(req.url);
}
}
}
@@ -858,14 +858,15 @@ for object invalidation:::
sub vcl_hit {
if (req.request == "PURGE") {
- set obj.ttl = 0s;
+ purge;
error 200 "Purged.";
}
}
sub vcl_miss {
if (req.request == "PURGE") {
- error 404 "Not in cache.";
+ purge;
+ error 200 "Purged.";
}
}
diff --git a/doc/sphinx/tutorial/purging.rst b/doc/sphinx/tutorial/purging.rst
index 61e1e69..bd00e49 100644
--- a/doc/sphinx/tutorial/purging.rst
+++ b/doc/sphinx/tutorial/purging.rst
@@ -1,7 +1,8 @@
.. _tutorial-purging:
-Purging and banning
--------------------
+=====================
+ Purging and banning
+=====================
One of the most effective way of increasing your hit ratio is to
increase the time-to-live (ttl) of your objects. But, as you're aware
@@ -14,7 +15,7 @@ bans. First, let me explain the HTTP purges.
HTTP Purges
-~~~~~~~~~~~
+===========
An HTTP purge is similar to an HTTP GET request, except that the
*method* is PURGE. Actually you can call the method whatever you'd
@@ -40,17 +41,15 @@ following VCL in place::
sub vcl_hit {
if (req.request == "PURGE") {
- # Note that setting ttl to 0 is magical.
- # the object is zapped from cache.
- set obj.ttl = 0s;
+ purge;
error 200 "Purged.";
}
}
sub vcl_miss {
if (req.request == "PURGE") {
-
- error 404 "Not in cache.";
+ purge;
+ error 200 "Purged.";
}
}
@@ -60,23 +59,17 @@ its cache. It will either hit an object or miss it and so the
corresponding subroutine is called. In vcl_hit the object that is
stored in cache is available and we can set the TTL.
-So for vg.no to invalidate their front page they would call out to
-Varnish like this::
+So for example.com to invalidate their front page they would call out
+to Varnish like this::
PURGE / HTTP/1.0
- Host: vg.no
+ Host: example.com
-And Varnish would then discard the front page. If there are several
-variants of the same URL in the cache however, only the matching
-variant will be purged. To purge a gzip variant of the same page the
-request would have to look like this::
-
- PURGE / HTTP/1.0
- Host: vg.no
- Accept-Encoding: gzip
+And Varnish would then discard the front page. This will remove all
+variants as defined by Vary.
Bans
-~~~~
+====
There is another way to invalidate content. Bans. You can think of
bans as a sort of a filter. You *ban* certain content from being
@@ -84,10 +77,10 @@ served from your cache. You can ban content based on any metadata we
have.
Support for bans is built into Varnish and available in the CLI
-interface. For VG to ban every png object belonging on vg.no they could
-issue::
+interface. For VG to ban every png object belonging on example.com
+they could issue::
- purge req.http.host == "vg.no" && req.http.url ~ "\.png$"
+ ban req.http.host == "example.com" && req.http.url ~ "\.png$"
Quite powerful, really.
@@ -104,7 +97,7 @@ You can also add bans to Varnish via HTTP. Doing so requires a bit of VCL::
if (!client.ip ~ purge) {
error 405 "Not allowed.";
}
- purge("req.http.host == " req.http.host
+ ban("req.http.host == " req.http.host
"&& req.url == " req.url);
# Throw a synthetic page so the
More information about the varnish-commit
mailing list