r5518 - trunk/varnish-cache/doc/sphinx/reference
perbu at varnish-cache.org
perbu at varnish-cache.org
Fri Nov 5 14:09:07 CET 2010
Author: perbu
Date: 2010-11-05 14:09:07 +0100 (Fri, 05 Nov 2010)
New Revision: 5518
Modified:
trunk/varnish-cache/doc/sphinx/reference/vcl.rst
Log:
documented return, restart, reordered some docs for readability and elaborated on saint and grace mode
Modified: trunk/varnish-cache/doc/sphinx/reference/vcl.rst
===================================================================
--- trunk/varnish-cache/doc/sphinx/reference/vcl.rst 2010-11-05 12:38:22 UTC (rev 5517)
+++ trunk/varnish-cache/doc/sphinx/reference/vcl.rst 2010-11-05 13:09:07 UTC (rev 5518)
@@ -56,6 +56,21 @@
remove headers with the *remove* or *unset* keywords, which are
synonym.
+The return(action) keyword terminates the subroutine. *action* can be,
+depending on context one of
+
+* deliver
+* error
+* fetch
+* hash
+* lookup
+* pass
+* pipe
+* restart
+
+Please see the list of subroutines to see what return actions are
+available where.
+
VCL has if tests, but no loops.
You may log arbitrary strings to the shared memory log with the
@@ -273,30 +288,15 @@
return (pipe);
}
-Grace
------
-
-If the backend takes a long time to generate an object there is a risk
-of a thread pile up. In order to prevent this you can enable grace.
-This allows varnish to serve an expired version of the object while a
-fresh object is being generated by the backend.
-
-The following vcl code will make Varnish serve expired objects. All
-object will be kept up to two minutes past their expiration time or a
-fresh object is generated.::
-
- sub vcl_recv {
- set req.grace = 2m;
- }
- sub vcl_fetch {
- set beresp.grace = 2m;
- }
-
Functions
---------
The following built-in functions are available:
+hash_data(str)
+ Adds a string to the hash input. In default.vcl hash_data() is
+ called on the host and URL of the *request*.
+
regsub(str, regex, sub)
Returns a copy of str with the first occurrence of the regular
expression regex replaced with sub. Within sub, \0 (which can
@@ -387,9 +387,13 @@
pass
Proceed with pass mode.
+ restart
+ Restart the transaction. Increases the restart counter. If the number
+ of restarts is higher than *max_restarts* varnish emits a guru meditation
+ error.
+
vcl_hash
- Use req.hash += req.http.Cookie or similar to include the Cookie HTTP
- header in the hash string.
+ You may call hash_data() on the data you would like to add to the hash.
The vcl_hash subroutine may terminate with calling return() with one of
the following keywords:
@@ -403,15 +407,20 @@
The vcl_hit subroutine may terminate with calling return() with one of
the following keywords:
+ deliver
+ Deliver the cached object to the client. Control will eventually
+ pass to vcl_deliver.
+
error code [reason]
Return the specified error code to the client and abandon the request.
pass
Switch to pass mode. Control will eventually pass to vcl_pass.
- deliver
- Deliver the cached object to the client. Control will eventually
- pass to vcl_deliver.
+ restart
+ Restart the transaction. Increases the restart counter. If the number
+ of restarts is higher than *max_restarts* varnish emits a guru meditation
+ error.
vcl_miss
Called after a cache lookup if the requested document was not found
@@ -437,31 +446,56 @@
The vcl_fetch subroutine may terminate with calling return() with
one of the following keywords:
+ deliver
+ Possibly insert the object into the cache, then deliver it to the
+ client. Control will eventually pass to vcl_deliver.
+
error code [reason]
Return the specified error code to the client and abandon the request.
+ esi
+ ESI-process the document which has just been fetched.
+
pass
Switch to pass mode. Control will eventually pass to vcl_pass.
- deliver
- Possibly insert the object into the cache, then deliver it to the
- client. Control will eventually pass to vcl_deliver.
+ restart
+ Restart the transaction. Increases the restart counter. If the number
+ of restarts is higher than *max_restarts* varnish emits a guru meditation
+ error.
- esi
- ESI-process the document which has just been fetched.
-
vcl_deliver
Called before a cached object is delivered to the client.
The vcl_deliver subroutine may terminate with one of the following
keywords:
+ deliver
+ Deliver the object to the client.
+
error code [reason]
Return the specified error code to the client and abandon the request.
+ restart
+ Restart the transaction. Increases the restart counter. If the number
+ of restarts is higher than *max_restarts* varnish emits a guru meditation
+ error.
+
+vcl_error
+ Called when we hit an error, either explicitly or implicitly due to
+ backend or internal errors.
+
+ The vcl_error subroutine may terminate by calling return with one of
+ the following keywords:
+
deliver
- Deliver the object to the client.
+ Deliver the error object to the client.
+ restart
+ Restart the transaction. Increases the restart counter. If the number
+ of restarts is higher than *max_restarts* varnish emits a guru meditation
+ error.
+
If one of these subroutines is left undefined or terminates without
reaching a handling decision, control will be handed over to the
builtin default. See the EXAMPLES section for a listing of the
@@ -550,16 +584,20 @@
The backend to use to service the request.
req.backend.healthy
- Whether the backend is healthy or not.
+ Whether the backend is healthy or not. Requires an active probe to be set
+ on the backend.
req.http.header
The corresponding HTTP header.
req.hash_always_miss
- Force a cache miss for this request.
+ Force a cache miss for this request. If set to true Varnish will disregard
+ any existing objects and always (re)fetch from the backend.
req.hash_ignore_busy
- Ignore any busy object during cache lookup.
+ Ignore any busy object during cache lookup. You would want to do
+ this if you have two server looking up content from each other to
+ avoid potential deadlocks.
The following variables are available while preparing a backend
request (either for a cache miss or for pass or pipe mode):
@@ -677,6 +715,36 @@
remove beresp.http.Set-Cookie;
}
+Grace and saint mode
+--------------------
+
+If the backend takes a long time to generate an object there is a risk
+of a thread pile up. In order to prevent this you can enable *grace*.
+This allows varnish to serve an expired version of the object while a
+fresh object is being generated by the backend.
+
+The following vcl code will make Varnish serve expired objects. All
+object will be kept up to two minutes past their expiration time or a
+fresh object is generated.::
+
+ sub vcl_recv {
+ set req.grace = 2m;
+ }
+ sub vcl_fetch {
+ set beresp.grace = 2m;
+ }
+
+Saint mode is similar to grace mode and relies on the same
+infrastructure but functions differently. You can add VCL code to
+vcl_fetch to see whether or not you *like* the response coming from
+the backend. If you find that the response is not appropriate you can
+set beresp.saintmode to a time limit and call *restart*. Varnish will
+then retry other backends to try to fetch the object again.
+
+If there are no more backends or if you hit *max_restarts* and we have
+an object that is younger than what you set beresp.saintmode to be
+Varnish will serve the object, even if it is stale.
+
EXAMPLES
========
More information about the varnish-commit
mailing list