[master] c17a6d2 Spelling, formatting and various other fixes
Federico G. Schwindt
fgsch at lodoss.net
Fri Mar 28 09:46:50 CET 2014
commit c17a6d23c0255d0ae11c5612be5e313078273db8
Author: Federico G. Schwindt <fgsch at lodoss.net>
Date: Fri Mar 28 08:44:29 2014 +0000
Spelling, formatting and various other fixes
diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index 580caff..033e04b 100644
--- a/doc/sphinx/reference/vmod.rst
+++ b/doc/sphinx/reference/vmod.rst
@@ -158,7 +158,7 @@ STRING_LIST
A multi-component text-string. We try very hard to avoid
doing text-processing in Varnish, and this is one way we
- to avoid that, by not editing separate pieces of a sting
+ to avoid that, by not editing separate pieces of a string
together to one string, unless we have to.
Consider this contrived example::
diff --git a/doc/sphinx/users-guide/increasing-your-hitrate.rst b/doc/sphinx/users-guide/increasing-your-hitrate.rst
index 9d8e0af..a413b71 100644
--- a/doc/sphinx/users-guide/increasing-your-hitrate.rst
+++ b/doc/sphinx/users-guide/increasing-your-hitrate.rst
@@ -3,29 +3,30 @@
Achieving a high hitrate
------------------------
-Now that Varnish is up and running, and you can access your web
-application through Varnish. Unless your application is specifically
-written to work behind a web accelerator you'll probably need to do
-some changes to either the configuration or the application in order
-to get a high hitrate in Varnish.
+Now that Varnish is up and running you can access your web application
+through Varnish. Unless your application is specifically written to
+work behind a web accelerator you'll probably need to do some
+changes to either the configuration or the application in order to
+get a high hitrate in Varnish.
Varnish will not cache your data unless it's absolutely sure it is
safe to do so. So, for you to understand how Varnish decides if and
-how to cache a page, We'll guide you through a couple of tools that you
-should find useful to understand what is happening in your Varnish setup.
+how to cache a page, we'll guide you through a couple of tools that
+you should find useful to understand what is happening in your
+Varnish setup.
-Note that you need a tool to see the HTTP headers that fly between Varnish and
-the backend. On the Varnish server, the easiest way to do this is to use
-`varnishlog` and `varnishtop` but sometimes a client-side tool makes
-sense. Here are the ones we commonly use.
+Note that you need a tool to see the HTTP headers that fly between
+Varnish and the backend. On the Varnish server, the easiest way to
+do this is to use `varnishlog` and `varnishtop` but sometimes a
+client-side tool makes sense. Here are the ones we commonly use.
Tool: varnishtop
~~~~~~~~~~~~~~~~
You can use varnishtop to identify what URLs are hitting the backend
-the most. ``varnishtop -i txurl`` is an essential command, showing you
-the top `txurl` requests Varnish is sending to the backend. You can
-see some other examples of `varnishtop` usage in
+the most. ``varnishtop -i txurl`` is an essential command, showing
+you the top `txurl` requests Varnish is sending to the backend. You
+can see some other examples of `varnishtop` usage in
:ref:`users-guide-statistics`.
@@ -47,9 +48,10 @@ http://www.varnish-cache.org/trac/wiki/VCLExampleHitMissHeader
Tool: lwp-request
~~~~~~~~~~~~~~~~~
-`lwp-request` is tool that is a part of The World-Wide Web library for Perl. It's a
-couple of really basic programs that can execute an HTTP request and
-show you the result. We mostly use the two programs, ``GET`` and ``HEAD``.
+`lwp-request` is tool that is a part of The World-Wide Web library
+for Perl. It's a couple of really basic programs that can execute
+an HTTP request and show you the result. We mostly use the two
+programs, ``GET`` and ``HEAD``.
vg.no was the first site to use Varnish and the people running Varnish
there are quite clueful. So it's interesting to look at their HTTP
@@ -59,7 +61,7 @@ Headers. Let's send a GET request for their home page::
GET http://vg.no/
Host: www.vg.no
User-Agent: lwp-request/5.834 libwww-perl/5.834
-
+
200 OK
Cache-Control: must-revalidate
Refresh: 600
@@ -81,7 +83,7 @@ really care about the content, only the headers.
As you can see, VG adds quite a bit of information in their
headers. Some of the headers, like the 'X-Rick-Would-Never' are specific
to vg.no and their somewhat odd sense of humour. Others, like the
-'X-VG-Webcache' are for debugging purposes.
+'X-VG-Webcache' are for debugging purposes.
So, to check whether a site sets cookies for a specific URL, just do::
@@ -92,10 +94,11 @@ So, to check whether a site sets cookies for a specific URL, just do::
Tool: Live HTTP Headers
~~~~~~~~~~~~~~~~~~~~~~~
-There is also a plugin for Firefox called `Live HTTP Headers`. This plugin can show you
-what headers are being sent and recieved. `Live HTTP Headers` can be
-found at https://addons.mozilla.org/en-US/firefox/addon/3829/ or by
-googling "Live HTTP Headers".
+There is also a plugin for Firefox called `Live HTTP Headers`. This
+plugin can show you what headers are being sent and received.
+`Live HTTP Headers` can be found at
+https://addons.mozilla.org/en-US/firefox/addon/3829/ or by googling
+"Live HTTP Headers".
The role of HTTP Headers
@@ -108,7 +111,7 @@ the content cached.
Please note that when Varnish considers these headers Varnish actually
considers itself *part of* the actual webserver. The rationale being
-that both are under your control.
+that both are under your control.
The term *surrogate origin cache* is not really well defined by the
IETF or RFC 2616 so the various ways Varnish works might differ from
@@ -129,7 +132,7 @@ the backend.
This can be overly conservative. A lot of sites use Google Analytics
(GA) to analyze their traffic. GA sets a cookie to track you. This
cookie is used by the client side javascript and is therefore of no
-interest to the server.
+interest to the server.
Cookies from the client
~~~~~~~~~~~~~~~~~~~~~~~
@@ -139,9 +142,9 @@ cookies unless you are accessing a special part of the web site. This
VCL snippet in `vcl_recv` will disregard cookies unless you are
accessing `/admin/`::
- if ( !( req.url ~ ^/admin/) ) {
- unset req.http.Cookie;
- }
+ if (!(req.url ~ "^/admin/")) {
+ unset req.http.Cookie;
+ }
Quite simple. If, however, you need to do something more complicated,
like removing one out of several cookies, things get
@@ -152,36 +155,39 @@ whats going on. If you aren't we recommend that you either pick up a book on
the subject, read through the *pcrepattern* man page, or read through
one of many online guides.
-Lets use the Varnish Software (VS) web as an example here. Very simplified the setup VS uses can be described as a Drupal-based backend with a Varnish cache infront. VS uses some cookies for
-Google Analytics tracking and similar tools. The cookies are all set
-and used by Javascript. Varnish and Drupal doesn't need to see those
-cookies and since Varnish will cease caching of pages when the client
-sends cookies Varnish will discard these unnecessary cookies in VCL.
+Lets use the Varnish Software (VS) web as an example here. Very
+simplified the setup VS uses can be described as a Drupal-based
+backend with a Varnish cache in front. VS uses some cookies for
+Google Analytics tracking and similar tools. The cookies are all
+set and used by Javascript. Varnish and Drupal doesn't need to see
+those cookies and since Varnish will cease caching of pages when
+the client sends cookies Varnish will discard these unnecessary
+cookies in VCL.
-In the following VCL we discard all cookies that start with a
+In the following VCL we discard all cookies that start with an
underscore::
- // Remove has_js and Google Analytics __* cookies.
- set req.http.Cookie = regsuball(req.http.Cookie, "(^|;\s*)(_[_a-z]+|has_js)=[^;]*", "");
- // Remove a ";" prefix, if present.
- set req.http.Cookie = regsub(req.http.Cookie, "^;\s*", "");
+ # Remove has_js and Google Analytics __* cookies.
+ set req.http.Cookie = regsuball(req.http.Cookie, "(^|;\s*)(_[_a-z]+|has_js)=[^;]*", "");
+ # Remove a ";" prefix, if present.
+ set req.http.Cookie = regsub(req.http.Cookie, "^;\s*", "");
Lets look at an example where we remove everything except the
cookies named "COOKIE1" and "COOKIE2" and you can marvel at the "beauty" of it::
- sub vcl_recv {
- if (req.http.Cookie) {
- set req.http.Cookie = ";" + req.http.Cookie;
- set req.http.Cookie = regsuball(req.http.Cookie, "; +", ";");
- set req.http.Cookie = regsuball(req.http.Cookie, ";(COOKIE1|COOKIE2)=", "; \1=");
- set req.http.Cookie = regsuball(req.http.Cookie, ";[^ ][^;]*", "");
- set req.http.Cookie = regsuball(req.http.Cookie, "^[; ]+|[; ]+$", "");
-
- if (req.http.Cookie == "") {
- remove req.http.Cookie;
- }
+ sub vcl_recv {
+ if (req.http.Cookie) {
+ set req.http.Cookie = ";" + req.http.Cookie;
+ set req.http.Cookie = regsuball(req.http.Cookie, "; +", ";");
+ set req.http.Cookie = regsuball(req.http.Cookie, ";(COOKIE1|COOKIE2)=", "; \1=");
+ set req.http.Cookie = regsuball(req.http.Cookie, ";[^ ][^;]*", "");
+ set req.http.Cookie = regsuball(req.http.Cookie, "^[; ]+|[; ]+$", "");
+
+ if (req.http.Cookie == "") {
+ unset req.http.Cookie;
+ }
+ }
}
- }
A somewhat simpler example that can accomplish almost the same functionality can be
found below. Instead of filtering out "other" cookies it instead picks out
@@ -190,16 +196,16 @@ copies it back to the request, deleting the original cookie header.
.. XXX:Verify correctness of request above! benc
::
- sub vcl_recv {
- # save the original cookie header so we can mangle it
+ sub vcl_recv {
+ # save the original cookie header so we can mangle it
set req.http.X-Varnish-PHP_SID = req.http.Cookie;
- # using a capturing sub pattern, extract the continuous string of
+ # using a capturing sub pattern, extract the continuous string of
# alphanumerics that immediately follows "PHPSESSID="
- set req.http.X-Varnish-PHP_SID =
+ set req.http.X-Varnish-PHP_SID =
regsuball(req.http.X-Varnish-PHP_SID, ";? ?PHPSESSID=([a-zA-Z0-9]+)( |;| ;).*","\1");
set req.http.Cookie = req.X-Varnish-PHP_SID;
- remove req.X-Varnish-PHP_SID;
- }
+ unset req.X-Varnish-PHP_SID;
+ }
There are other scary examples of what can be done in VCL in the
Varnish Cache Wiki.
@@ -211,10 +217,10 @@ Cookies coming from the backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If your backend server sets a cookie using the 'Set-Cookie' header
-Varnish will not cache the page when using the default configuration. A
-`hit-for-pass` object (see :ref:`user-guide-vcl_actions`) is created.
-So, if the backend server acts silly and sets unwanted cookies just unset
-the 'Set-Cookie' header and all should be fine.
+Varnish will not cache the page when using the default configuration.
+A `hit-for-pass` object (see :ref:`user-guide-vcl_actions`) is
+created. So, if the backend server acts silly and sets unwanted
+cookies just unset the 'Set-Cookie' header and all should be fine.
Cache-Control
@@ -247,7 +253,7 @@ In `vcl_backend_response`::
if (beresp.http.Pragma ~ "nocache") {
set beresp.uncacheable = true;
- set beresp.ttl = 120s; // how long not to cache this url.
+ set beresp.ttl = 120s; # how long not to cache this url.
}
Authorization
@@ -266,11 +272,11 @@ somewhat cumbersome backend.
You need VCL to identify the objects you want and then you set the
'beresp.ttl' to whatever you want::
- sub vcl_backend_response {
- if (req.url ~ "^/legacy_broken_cms/") {
- set beresp.ttl = 5d;
- }
- }
+ sub vcl_backend_response {
+ if (req.url ~ "^/legacy_broken_cms/") {
+ set beresp.ttl = 5d;
+ }
+ }
This example will set the TTL to 5 days for the old legacy stuff on
your site.
@@ -288,18 +294,18 @@ the cache but it isn't really recommended.
Normalizing your namespace
~~~~~~~~~~~~~~~~~~~~~~~~~~
-Some sites are accessed via lots of
-hostnames. http://www.varnish-software.com/,
-http://varnish-software.com/ and http://varnishsoftware.com/ all point
-at the same site. Since Varnish doesn't know they are the same,
+Some sites are accessed via lots of hostnames.
+http://www.varnish-software.com/, http://varnish-software.com/ and
+http://varnishsoftware.com/ all point at the same site. Since Varnish
+doesn't know they are the same,
.. XXX: heavy meaning change above. benc
Varnish will cache different versions of every page for every
-hostname. You can mitigate this in your web server configuration by
-setting up redirects or by using the following VCL::
+hostname. You can mitigate this in your web server configuration
+by setting up redirects or by using the following VCL::
- if (req.http.host ~ "(?i)^(www.)?varnish-?software.com") {
- set req.http.host = "varnish-software.com";
- }
+ if (req.http.host ~ "(?i)^(www.)?varnish-?software.com") {
+ set req.http.host = "varnish-software.com";
+ }
.. _users-guide-vary:
@@ -307,38 +313,38 @@ setting up redirects or by using the following VCL::
HTTP Vary
---------
-*HTTP Vary is not a trivial concept. It is by far the most
-misunderstood HTTP header.*
+*HTTP Vary is not a trivial concept. It is by far the most misunderstood
+HTTP header.*
-A lot of the response headers tell the client something about the HTTP
-object being delivered. Clients can request different variants of a
-HTTP object, based on their preference. Their preferences might cover
-stuff like encoding or language. When a client prefers UK English this
-is indicated through ``Accept-Language: en-uk``. Caches need to keep
-these different variants apart and this is done through the HTTP
-response header 'Vary'.
+A lot of the response headers tell the client something about the
+HTTP object being delivered. Clients can request different variants
+of a HTTP object, based on their preference. Their preferences might
+cover stuff like encoding or language. When a client prefers UK
+English this is indicated through ``Accept-Language: en-uk``. Caches
+need to keep these different variants apart and this is done through
+the HTTP response header 'Vary'.
When a backend server issues a ``Vary: Accept-Language`` it tells
Varnish that its needs to cache a separate version for every different
Accept-Language that is coming from the clients.
-If two clients say they accept the languages "en-us, en-uk" and "da,
-de" respectively, Varnish will cache and serve two different versions
-of the page if the backend indicated that Varnish needs to vary on the
-'Accept-Language' header.
+If two clients say they accept the languages "en-us, en-uk" and
+"da, de" respectively, Varnish will cache and serve two different
+versions of the page if the backend indicated that Varnish needs
+to vary on the 'Accept-Language' header.
Please note that the headers that 'Vary' refer to need to match
-*exactly* for there to be a match. So Varnish will keep two copies of
-a page if one of them was created for "en-us, en-uk" and the other for
-"en-us,en-uk". Just the lack of a whitespace will force Varnish to cache
-another version.
+*exactly* for there to be a match. So Varnish will keep two copies
+of a page if one of them was created for "en-us, en-uk" and the
+other for "en-us,en-uk". Just the lack of a whitespace will force
+Varnish to cache another version.
-To achieve a high hitrate whilst using Vary is there therefore crucial
-to normalize the headers the backends varies on. Remember, just a
-difference in casing can force different cache entries.
+To achieve a high hitrate whilst using Vary is there therefore
+crucial to normalize the headers the backends varies on. Remember,
+just a difference in casing can force different cache entries.
-The following VCL code will normalize the 'Accept-Language' headers, to
-one of either "en","de" or "fr"::
+The following VCL code will normalize the 'Accept-Language' headers,
+to one of either "en", "de" or "fr"::
if (req.http.Accept-Language) {
if (req.http.Accept-Language ~ "en") {
@@ -348,9 +354,9 @@ one of either "en","de" or "fr"::
} elsif (req.http.Accept-Language ~ "fr") {
set req.http.Accept-Language = "fr";
} else {
- # unknown language. Remove the accept-language header and
- # use the backend default.
- remove req.http.Accept-Language
+ # unknown language. Remove the accept-language header and
+ # use the backend default.
+ unset req.http.Accept-Language
}
}
@@ -360,22 +366,22 @@ gzip, deflate with a preference for gzip.
Vary parse errors
~~~~~~~~~~~~~~~~~
-Varnish will return a "503 internal server error" page when it fails to
-parse the 'Vary' header, or if any of the client headers listed
+Varnish will return a "503 internal server error" page when it fails
+to parse the 'Vary' header, or if any of the client headers listed
in the Vary header exceeds the limit of 65k characters. An 'SLT_Error'
log entry is added in these cases.
Pitfall - Vary: User-Agent
~~~~~~~~~~~~~~~~~~~~~~~~~~
-Some applications or application servers send ``Vary: User-Agent`` along
-with their content. This instructs Varnish to cache a separate copy
-for every variation of 'User-Agent' there is and there are plenty. Even a
-single patchlevel of the same browser will generate at least 10
-different 'User-Agent' headers based just on what operating system they
-are running.
+Some applications or application servers send ``Vary: User-Agent``
+along with their content. This instructs Varnish to cache a separate
+copy for every variation of 'User-Agent' there is and there are
+plenty. Even a single patchlevel of the same browser will generate
+at least 10 different 'User-Agent' headers based just on what
+operating system they are running.
So if you *really* need to vary based on 'User-Agent' be sure to
-normalize the header or your hit rate will suffer badly. Use the above
-code as a template.
+normalize the header or your hit rate will suffer badly. Use the
+above code as a template.
diff --git a/doc/sphinx/whats-new/upgrading.rst b/doc/sphinx/whats-new/upgrading.rst
index 3634a33..d64772d 100644
--- a/doc/sphinx/whats-new/upgrading.rst
+++ b/doc/sphinx/whats-new/upgrading.rst
@@ -7,13 +7,17 @@ Upgrading to Varnish 4
Changes to VCL
==============
-Much of the VCL syntax has changed in Varnish 4. We've tried to compile a list of changes needed to upgrade here.
+Much of the VCL syntax has changed in Varnish 4. We've tried to
+compile a list of changes needed to upgrade here.
Version statement
~~~~~~~~~~~~~~~~~
-To make sure that people have upgraded their VCL to the current version, Varnish now requires the first line of VCL to indicate the VCL version number::
- vcl 4.0;
+To make sure that people have upgraded their VCL to the current
+version, Varnish now requires the first line of VCL to indicate the
+VCL version number::
+
+ vcl 4.0;
vcl_fetch is now vcl_backend_response
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -21,8 +25,8 @@ vcl_fetch is now vcl_backend_response
Directors have been moved to the vmod_directors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To make directors (backend selection logic) easier to extend, the directors
-are now defined in loadable VMODs.
+To make directors (backend selection logic) easier to extend, the
+directors are now defined in loadable VMODs.
Setting a backend for future fetches in `vcl_recv` is now done as follows::
@@ -31,6 +35,7 @@ Setting a backend for future fetches in `vcl_recv` is now done as follows::
cluster1.add_backend(b1, 1.0);
cluster1.add_backend(b2, 1.0);
}
+
sub vcl_recv {
set req.backend_hint = cluster1.backend();
}
@@ -47,21 +52,22 @@ has been removed, and you should use the hash director directly::
h.add_backend(b1, 1);
h.add_backend(b2, 1);
}
+
sub vcl_recv {
set req.backend_hint = h.backend(client.ip);
}
-error() is now a return value
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You must explicitly return an error::
+error() is now synth()
+~~~~~~~~~~~~~~~~~~~~~~
- return(error(999, "Response));
+And you must explicitly return it::
+ return (synth(999, "Response"));
-Synthetic responses in vcl_error
+Synthetic responses in vcl_synth
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Setting headers on synthetic response bodies made in vcl_error are now done on
+Setting headers on synthetic response bodies made in vcl_synth are now done on
resp.http instead of obj.http.
The synthetic keyword is now a function::
@@ -73,31 +79,33 @@ The synthetic keyword is now a function::
return (deliver);
}
-
-
hit_for_pass objects are created using beresp.uncacheable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
Example::
- sub vcl_backend_response {
- if(beresp.http.X-No-Cache) {
- set beresp.uncacheable = true;
- set beresp.ttl = 120s;
- return(deliver);
- }
- }
+ sub vcl_backend_response {
+ if (beresp.http.X-No-Cache) {
+ set beresp.uncacheable = true;
+ set beresp.ttl = 120s;
+ return (deliver);
+ }
+ }
vcl_recv should return(hash) instead of lookup now
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
req.* not available in vcl_backend_response
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-req.* used to be available in `vcl_fetch`, but after the split of functionality, you only have 'bereq.*' in `vcl_backend_response`.
+
+req.* used to be available in `vcl_fetch`, but after the split of
+functionality, you only have 'bereq.*' in `vcl_backend_response`.
vcl_* reserved
~~~~~~~~~~~~~~
-Any custom-made subs cannot be named 'vcl_*' anymore. This namespace is
-reserved for builtin subs.
+
+Any custom-made subs cannot be named 'vcl_*' anymore. This namespace
+is reserved for builtin subs.
req.backend.healthy replaced by std.healthy(req.backend)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -112,15 +120,15 @@ objecthead, not per object. `obj.last_use` has been retired.
default/builtin VCL changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The VCL code that is appended to user-configured VCL automatically is now
-called the builtin VCL. (previously default.vcl)
+The VCL code that is appended to user-configured VCL automatically
+is now called the builtin VCL. (previously default.vcl)
-The builtin VCL now honors Cache-Control: no-cache (and friends) to indicate
-uncacheable content from the backend.
+The builtin VCL now honors Cache-Control: no-cache (and friends)
+to indicate uncacheable content from the backend.
The `remove` keyword is gone
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Replaced by `unset`.
More information about the varnish-commit
mailing list