Skip to content

V
varnish-cache
Commit b39db7f6 authored by Kristian Lyngstøl's avatar Kristian Lyngstøl
Browse files
Options

generate vcl.7 from rst, include default.vcl in vcl.rst 

git-svn-id: http://www.varnish-cache.org/svn/trunk/varnish-cache@5009 d4fa192b-c00b-0410-8231-f00ffab90ce4
parent 1cb7b206
Hide whitespace changes
Inline Side-by-side
Showing with 14 additions and 854 deletions
doc/sphinx/reference/vcl.rst
View file @ b39db7f6
......@@ -583,105 +583,8 @@ specified:::
.port = "http";
}
sub vcl_recv {
if (req.http.x-forwarded-for) {
set req.http.X-Forwarded-For = req.http.X-Forwarded-For ", " client.ip;
} else {
set req.http.X-Forwarded-For = client.ip;
}
if (req.request != "GET" &&
req.request != "HEAD" &&
req.request != "PUT" &&
req.request != "POST" &&
req.request != "TRACE" &&
req.request != "OPTIONS" &&
req.request != "DELETE") {
// Non-RFC2616 or CONNECT which is weird.
return (pipe);
}
if (req.request != "GET" && req.request != "HEAD") {
// We only deal with GET and HEAD by default
return (pass);
}
if (req.http.Authorization || req.http.Cookie) {
// Not cacheable by default
return (pass);
}
return (lookup);
}
sub vcl_pipe {
# Note that only the first request to the backend will have
# X-Forwarded-For set. If you use X-Forwarded-For and want to
# have it set for all requests, make sure to have:
# set req.http.connection = "close";
# here. It is not set by default as it might break some broken web
# applications, like IIS with NTLM authentication.
return (pipe);
}
sub vcl_pass {
return (pass);
}
sub vcl_hash {
set req.hash += req.url;
if (req.http.host) {
set req.hash += req.http.host;
} else {
set req.hash += server.ip;
}
return (hash);
}
sub vcl_hit {
if (!obj.cacheable) {
return (pass);
}
return (deliver);
}
sub vcl_miss {
return (fetch);
}
sub vcl_fetch {
if (!beresp.cacheable) {
return (pass);
}
if (beresp.http.Set-Cookie) {
return (pass);
}
return (deliver);
}
sub vcl_deliver {
return (deliver);
}
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>
<hr>
Varnish cache server
</body>
</html>
"};
return (deliver);
}
.. include:: ../../../man/default.vcl
:literal:
The following example shows how to support multiple sites running on
separate backends in the same Varnish instance, by selecting backends
......
man/Makefile.am
View file @ b39db7f6
# $Id$
EXTRA_DIST = vcl.7so
DISTCLEANFILES = vcl.7 default.vcl
if HAVE_RST2MAN
dist_man_MANS = vcl.7
endif
vcl.7: vcl.7so default.vcl Makefile
soelim $(srcdir)/vcl.7so > $@
default.vcl: $(top_srcdir)/bin/varnishd/default.vcl Makefile
sed -n '/vcl_recv/,$$p' $(top_srcdir)/bin/varnishd/default.vcl > $@
vcl.7: ../doc/sphinx/reference/vcl.rst default.vcl
if HAVE_RST2MAN
${RST2MAN} $< >$@
else
@echo "========================================"
@echo "You need rst2man installed to make dist"
@echo "========================================"
@false
endif
man/vcl.7so deleted 100644 → 0
View file @ 1cb7b206
.\"-
.\" Copyright (c) 2006 Verdens Gang AS
.\" Copyright (c) 2006-2009 Linpro AS
.\" All rights reserved.
.\"
.\" Author: Dag-Erling Smørgrav <des@des.no>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Id$
.\"
.Dd August 10, 2007
.Dt VCL 7
.Os
.Sh NAME
.Nm VCL
.Nd Varnish Configuration Language
.Sh DESCRIPTION
The
.Nm
language is a small domain-specific language designed to be used to
define request handling and document caching policies for the Varnish
HTTP accelerator.
.Pp
When a new configuration is loaded, the
.Nm varnishd
management process translates the VCL code to C and compiles it to a
shared object which is then dynamically linked into the server
process.
.Ss Syntax
The VCL syntax is very simple, and deliberately similar to C and Perl.
Blocks are delimited by curly braces, statements end with semicolons,
and comments may be written as in C, C++ or Perl according to your own
preferences.
.Pp
In addition to the C-like assignment (=), comparison (==) and boolean
(!, && and ||) operators, VCL supports regular expression and ACL
matching using the ~ operator.
.Pp
Unlike C and Perl, the backslash (\e) character has no special meaning
in strings in VCL, which use the (%xx) escape mechanism just like URLs,
so it can be freely used in regular expressions without doubling.
.Pp
Strings are concatenated by just putting them one after each other
without any operator in between.
.Pp
Assignments are introduced with the
.Cm set
keyword.
There are no user-defined variables; values can only be assigned to
variables attached to backend, request or document objects.
Most of these are typed, and the values assigned to them must have a
compatible unit suffix.
.Pp
VCL has
.Cm if
tests, but no loops.
.Pp
The contents of another VCL file may be inserted at any point in the
code by using the
.Cm include
keyword followed by the name of the other file as a quoted string.
.Ss Backend declarations
A backend declaration creates and initializes a named backend object:
.Bd -literal -offset 4n
backend www {
.host = "www.example.com";
.port = "http";
}
.Ed
.Pp
The backend object can later be used to select a backend at request
time:
.Bd -literal -offset 4n
if (req.http.host ~ "^(www\.)?example.com$") {
set req.backend = www;
}
.Ed
.Pp
To avoid overloading backend servers,
.Fa .max_connections
can be set to limit the maximum number of concurrent backend connections.
.Pp
The timeout parameters can be overridden in the backend declaration.
The timeout parameters are
.Fa .connect_timeout
for the time to wait for a backend connection,
.Fa .first_byte_timeout
for the time to wait for the first byte from the backend and
.Fa .between_bytes_timeout
for time to wait between each received byte.
.Pp
These can be set in the declaration like this:
.Bd -literal -offset 4n
backend www {
.host = "www.example.com";
.port = "http";
.connect_timeout = 1s;
.first_byte_timeout = 5s;
.between_bytes_timeout = 2s;
}
.Ed
.Pp
To mark a backend as unhealthy after number of items have been added to
it's saintmode list
.Fa .saintmode_threshold
can be set to the maximum list size. Setting a value of 0 disables
saintmode checking entirely for that backend. The value in the backend
declaration overrides the parameter.
.Ss Directors
Directors choose from different backends based on health status and a
per-director algorithm.
There currently exists a round-robin and a random director.
.Pp
Directors are defined using:
.Bd -literal -offset 4n
director b2 random {
.retries = 5;
{
/* We can refer to named backends */
.backend = b1;
.weight = 7;
}
{
/* Or define them inline */
.backend = {
.host = "fs2";
}
.weight = 3;
}
}
.Ed
.Ss The random director
The random director takes one per-director option
.Fa .retries .
This specifies how many tries it will use to find a working backend.
The default is the same as the number of backends defined for the
director.
.Pp
There is also a per-backend option: weight which defines the portion
of traffic to send to the particular backend.
.Ss The round-robin director
The round-robin does not take any options.
.Ss Backend probes
Backends can be probed to see whether they should be considered
healthy or not. The return status can also be checked by using
.Fa req.backend.healthy
.
.Fa .window
is how many of the latest polls we examine, while
.Fa .threshold
is how many of those must have succeeded for us to consider the
backend healthy.
.Fa .initial
is how many of the probes are considered good when Varnish starts -
defaults to the same amount as the threshold.
.Bd -literal -offset 4n
backend www {
.host = "www.example.com";
.port = "http";
.probe = {
.url = "/test.jpg";
.timeout = 0.3 s;
.window = 8;
.threshold = 3;
.initial = 3;
}
}
.Ed
It is also possible to specify the raw HTTP request.
.Bd -literal -offset 4n
backend www {
.host = "www.example.com";
.port = "http";
.probe = {
# NB: \er\en automatically inserted after each string!
.request =
"GET / HTTP/1.1"
"Host: www.foo.bar"
"Connection: close";
}
}
.Ed
.Ss ACLs
An ACL declaration creates and initializes a named access control list
which can later be used to match client addresses:
.Bd -literal -offset 4n
acl local {
"localhost"; /* myself */
"192.0.2.0"/24; /* and everyone on the local network */
! "192.0.2.23"; /* except for the dialin router */
}
.Ed
.Pp
If an ACL entry specifies a host name which Varnish is unable to
resolve, it will match any address it is compared to.
Consequently, if it is preceded by a negation mark, it will reject any
address it is compared to, which may not be what you intended.
If the entry is enclosed in parentheses, however, it will simply be
ignored.
.Pp
To match an IP address against an ACL, simply use the match operator:
.Bd -literal -offset 4n
if (client.ip ~ local) {
pipe;
}
.Ed
.Ss 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.
.Pp
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.
.Bd -literal -offset 4n
sub vcl_recv {
set req.grace = 2m;
}
sub vcl_fetch {
set obj.grace = 2m;
}
.Ed
.Ss Functions
The following built-in functions are available:
.Bl -tag -width indent
.It Fn regsub "str" "regex" "sub"
Returns a copy of
.Fa str
with the first occurrence of the regular expression
.Fa regex
replaced with
.Fa sub .
Within
.Fa sub ,
.Va \e0
(which can also be spelled
.Va & )
is replaced with the entire matched string, and
.Va \en
is replaced with the contents of subgroup
.Ar n
in the matched string.
.It Fn regsuball "str" "regex" "sub"
As
.Fn regsuball
but this replaces all occurrences.
.It Fn purge_url "regex"
Purge all objects in cache whose URLs match
.Fa regex .
.El
.Ss Subroutines
A subroutine is used to group code for legibility or reusability:
.Bd -literal -offset 4n
sub pipe_if_local {
if (client.ip ~ local) {
pipe;
}
}
.Ed
.Pp
Subroutines in VCL do not take arguments, nor do they return values.
.Pp
To call a subroutine, use the
.Cm call
keyword followed by the subroutine's name:
.Bd -literal -offset 4n
call pipe_if_local;
.Ed
.Pp
There are a number of special subroutines which hook into the Varnish
workflow.
These subroutines may inspect and manipulate HTTP headers and various
other aspects of each request, and to a certain extent decide how the
request should be handled.
Each subroutine terminates by calling one of a small number of
keywords which indicates the desired outcome.
.Bl -tag -width indent
.\" vcl_recv
.It Cm vcl_recv
Called at the beginning of a request, after the complete request has
been received and parsed.
Its purpose is to decide whether or not to serve the request, how to
do it, and, if applicable, which backend to use.
.Pp
The
.Cm vcl_recv
subroutine may terminate with one of the following keywords:
.Bl -tag -width indent
.It Cm error Ar code Op Ar reason
Return the specified error code to the client and abandon the
request.
.It Cm pass
Switch to pass mode.
Control will eventually pass to
.Cm vcl_pass .
.It Cm pipe
Switch to pipe mode.
Control will eventually pass to
.Cm vcl_pipe .
.It Cm lookup
Look up the requested object in the cache.
Control will eventually pass to
.Cm vcl_hit
or
.Cm vcl_miss ,
depending on whether the object is in the cache.
.El
.\" vcl_pipe
.It Cm vcl_pipe
Called upon entering pipe mode.
In this mode, the request is passed on to the backend, and any further
data from either client or backend is passed on unaltered until either
end closes the connection.
.Pp
The
.Cm vcl_pipe
subroutine may terminate with one of the following keywords:
.Bl -tag -width indent
.It Cm error Ar code Op Ar reason
Return the specified error code to the client and abandon the
request.
.It Cm pipe
Proceed with pipe mode.
.El
.\" vcl_pass
.It Cm vcl_pass
Called upon entering pass mode.
In this mode, the request is passed on to the backend, and the
backend's response is passed on to the client, but is not entered into
the cache.
Subsequent requests submitted over the same client connection are
handled normally.
.Pp
The
.Cm vcl_pass
subroutine may terminate with one of the following keywords:
.Bl -tag -width indent
.It Cm error Ar code Op Ar reason
Return the specified error code to the client and abandon the
request.
.It Cm pass
Proceed with pass mode.
.El
.\" vcl_hash
.It Cm vcl_hash
Use
.Cm req.hash += req.http.Cookie
or similar to include the Cookie HTTP header in the hash string.
The
.Cm vcl_hash
subroutine may terminate with one of the following keywords:
.Bl -tag -width indent
.It Cm hash
Proceed.
.El
.\" vcl_hit
.It Cm vcl_hit
Called after a cache lookup if the requested document was found in the
cache.
.Pp
The
.Cm vcl_hit
subroutine may terminate with one of the following keywords:
.Bl -tag -width indent
.It Cm error Ar code Op Ar reason
Return the specified error code to the client and abandon the
request.
.It Cm pass
Switch to pass mode.
Control will eventually pass to
.Cm vcl_pass .
.It Cm deliver
Deliver the cached object to the client.
Control will eventually pass to
.Cm vcl_deliver .
.El
.\" vcl_miss
.It Cm vcl_miss
Called after a cache lookup if the requested document was not found in
the cache.
Its purpose is to decide whether or not to attempt to retrieve the
document from the backend, and which backend to use.
.Pp
The
.Cm vcl_miss
subroutine may terminate with one of the following keywords:
.Bl -tag -width indent
.It Cm error Ar code Op Ar reason
Return the specified error code to the client and abandon the
request.
.It Cm pass
Switch to pass mode.
Control will eventually pass to
.Cm vcl_pass .
.It Cm fetch
Retrieve the requested object from the backend.
Control will eventually pass to
.Cm vcl_fetch .
.El
.\" vcl_fetch
.It Cm vcl_fetch
Called after a document has been successfully retrieved from the
backend.
.Pp
The
.Cm vcl_fetch
subroutine may terminate with one of the following keywords:
.Bl -tag -width indent
.It Cm error Ar code Op Ar reason
Return the specified error code to the client and abandon the
request.
.It Cm pass
Switch to pass mode.
Control will eventually pass to
.Cm vcl_pass .
.It Cm deliver
Possibly insert the object into the cache, then deliver it to the client.
Control will eventually pass to
.Cm vcl_deliver .
.It Cm esi
ESI-process the document which has just been fetched.
.El
.\" vcl_deliver
.It Cm vcl_deliver
Called before a cached object is delivered to the client.
.Pp
The
.Cm vcl_deliver
subroutine may terminate with one of the following keywords:
.Bl -tag -width indent
.It Cm error Ar code Op Ar reason
Return the specified error code to the client and abandon the
request.
.It Cm deliver
Deliver the object to the client.
.El
.El
.Pp
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
.Sx EXAMPLES
section for a listing of the default code.
.Ss Multiple subroutines
If multiple subroutines with the same name are defined, they are
concatenated in the order in which the appear in the source.
.Pp
Example:
.Bd -literal -offset 4n
# in file "main.vcl"
include "backends.vcl";
include "purge.vcl";
# in file "backends.vcl"
sub vcl_recv {
if (req.http.host ~ "example.com") {
set req.backend = foo;
} elsif (req.http.host ~ "example.org") {
set req.backend = bar;
}
}
# in file "purge.vcl"
sub vcl_recv {
if (client.ip ~ admin_network) {
if (req.http.Cache-Control ~ "no-cache") {
purge_url(req.url);
}
}
}
.Ed
.Pp
The builtin default subroutines are implicitly appended in this way.
.Ss Variables
Although subroutines take no arguments, the necessary information is
made available to the handler subroutines through global variables.
.Pp
The following variables are always available:
.Bl -tag -width 4n
.It Va now
The current time, in seconds since the epoch.
.El
.Pp
The following variables are available in backend declarations:
.Bl -tag -width 4n
.It Va .host
Host name or IP address of a backend.
.It Va .port
Service name or port number of a backend.
.El
.Pp
The following variables are available while processing a request:
.Bl -tag -width 4n
.It Va client.ip
The client's IP address.
.It Va server.hostname
The host name of the server.
.It Va server.identity
The identity of the server, as set by the
.Fl i
parameter.
If the
.Fl i
parameter is not passed to
.Nm varnishd ,
.Va server.identity
will be set to the name of the instance, as specified by the
.Fl n
parameter.
.It Va server.ip
The IP address of the socket on which the client connection was
received.
.It Va server.port
The port number of the socket on which the client connection was
received.
.It Va req.request
The request type (e.g. "GET", "HEAD").
.It Va req.url
The requested URL.
.It Va req.proto
The HTTP protocol version used by the client.
.It Va req.backend
The backend to use to service the request.
.It Va req.backend.healthy
Whether the backend is healthy or not.
.It Va req.http. Ns Ar header
The corresponding HTTP
.Ar header .
.El
.Pp
The following variables are available while preparing a backend
request (either for a cache miss or for pass or pipe mode):
.Bl -tag -width 4n
.It Va bereq.request
The request type (e.g. "GET", "HEAD").
.It Va bereq.url
The requested URL.
.It Va bereq.proto
The HTTP protocol version used to talk to the server.
.It Va bereq.http. Ns Ar header
The corresponding HTTP
.Ar header .
.It Va bereq.connect_timeout
The time in seconds to wait for a backend connection.
.It Va bereq.first_byte_timeout
The time in seconds to wait for the first byte from the backend.
Not available in pipe mode.
.It Va bereq.between_bytes_timeout
The time in seconds to wait between each received byte from the backend.
Not available in pipe mode.
.El
.Pp
The following variables are available after the requested object has
been retrieved from cache or from the backend:
.Bl -tag -width 4n
.It Va obj.proto
The HTTP protocol version used when the object was retrieved.
.It Va obj.status
The HTTP status code returned by the server.
.It Va obj.response
The HTTP status message returned by the server.
.It Va obj.cacheable
True if the request resulted in a cacheable response.
.\" see cache_center.c and rfc2616.c for details
A response is considered cacheable if it is valid (see above), and the
HTTP status code is 200, 203, 300, 301, 302, 404 or 410.
.It Va obj.ttl
The object's remaining time to live, in seconds.
.It Va obj.lastuse
The approximate time elapsed since the object was last requests, in
seconds.
.It Va obj.hits
The approximate number of times the object has been delivered. A value of 0
indicates a cache miss.
.El
.Pp
The following variables are available while determining the hash key
of an object:
.Bl -tag -width 4n
.It Va req.hash
The hash key used to refer to an object in the cache. Used when both
reading from and writing to the cache.
.El
.Pp
The following variables are available while preparing a response to
the client:
.Bl -tag -width 4n
.It Va resp.proto
The HTTP protocol version to use for the response.
.It Va resp.status
The HTTP status code that will be returned.
.It Va resp.response
The HTTP status message that will be returned.
.It Va resp.http. Ns Ar header
The corresponding HTTP
.Ar header .
.El
.Pp
Values may be assigned to variables using the
.Cm set
keyword:
.Bd -literal -offset 4n
sub vcl_recv {
# Normalize the Host: header
if (req.http.host ~ "^(www\.)?example\.com$") {
set req.http.host = "www.example.com";
}
}
.Ed
.Pp
HTTP headers can be removed entirely using the
.Cm remove
keyword:
.Bd -literal -offset 4n
sub vcl_fetch {
# Don't cache cookies
remove obj.http.Set-Cookie;
}
.Ed
.Sh EXAMPLES
The following code is the equivalent of the default configuration with
the backend address set to "backend.example.com" and no backend port
specified.
.\" Keep this in synch with bin/varnishd/mgt_vcc.c and etc/default.vcl
.Bd -literal -offset 4n
backend default {
.host = "backend.example.com";
.port = "http";
}
.so default.vcl
.Ed
.Pp
The following example shows how to support multiple sites running on
separate backends in the same Varnish instance, by selecting backends
based on the request URL.
.Bd -literal -offset 4n
backend www {
.host = "www.example.com";
.port = "80";
}
backend images {
.host = "images.example.com";
.port = "80";
}
sub vcl_recv {
if (req.http.host ~ "^(www\.)?example\.com$") {
set req.http.host = "www.example.com";
set req.backend = www;
} elsif (req.http.host ~ "^images\.example\.com$") {
set req.backend = images;
} else {
error 404 "Unknown virtual host";
}
}
.Ed
.Pp
The following snippet demonstrates how to force a minimum TTL for all
documents.
Note that this is not the same as setting the
.Va default_ttl
run-time parameter, as that only affects document for which the
backend did not specify a TTL.
.Bd -literal -offset 4n
sub vcl_fetch {
if (obj.ttl < 120s) {
set obj.ttl = 120s;
}
}
.Ed
.Pp
The following snippet demonstrates how to force Varnish to cache
documents even when cookies are present.
.Bd -literal -offset 4n
sub vcl_recv {
if (req.request == "GET" && req.http.cookie) {
lookup;
}
}
sub vcl_fetch {
if (obj.http.Set-Cookie) {
deliver;
}
}
.Ed
.Pp
The following code implements the HTTP PURGE method as used by Squid
for object invalidation:
.Bd -literal -offset 4n
acl purge {
"localhost";
"192.0.2.1"/24;
}
sub vcl_recv {
if (req.request == "PURGE") {
if (!client.ip ~ purge) {
error 405 "Not allowed.";
}
lookup;
}
}
sub vcl_hit {
if (req.request == "PURGE") {
set obj.ttl = 0s;
error 200 "Purged.";
}
}
sub vcl_miss {
if (req.request == "PURGE") {
error 404 "Not in cache.";
}
}
.Ed
.Sh SEE ALSO
.Xr varnishd 1
.Sh HISTORY
The
.Nm
language was developed by
.An Poul-Henning Kamp Aq phk@phk.freebsd.dk
in cooperation with Verdens Gang AS and Linpro AS.
This manual page was written by
.An Dag-Erling Sm\(/orgrav Aq des@des.no .
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment