summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2014-11-12 10:28:47 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2014-11-12 10:30:46 (GMT)
commit1cb6d5974b17364d651636ec088066fef210ad2b (patch) (side-by-side diff)
tree3affe01a800c9d8c94c070e5650e35e33973b516
parentbcce955697d68e0daf93e8a64ec2e6a5bb107d1d (diff)
downloadvmod-dbrw-1cb6d5974b17364d651636ec088066fef210ad2b.tar.gz
vmod-dbrw-1cb6d5974b17364d651636ec088066fef210ad2b.tar.bz2
Update the docs for VCL 4.0
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--doc/vmod-dbrw.369
-rw-r--r--doc/vmod-dbrw.texi56
2 files changed, 102 insertions, 23 deletions
diff --git a/doc/vmod-dbrw.3 b/doc/vmod-dbrw.3
index 89b56d6..f2ee5fe 100644
--- a/doc/vmod-dbrw.3
+++ b/doc/vmod-dbrw.3
@@ -13,7 +13,7 @@
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with vmod-dbrw. If not, see <http://www.gnu.org/licenses/>.
-.TH VMOD-DBRW 1 "November 1, 2014" "VMOD-DBRW" "User Reference"
+.TH VMOD-DBRW 1 "November 12, 2014" "VMOD-DBRW" "User Reference"
.SH NAME
vmod-dbrw \- Database-driven rewrite rules for Varnish Cache
.SH SYNOPSIS
@@ -111,17 +111,17 @@ Once configured, the \fBrewrite\fR function can be called in the
appropriate place of the Varnish configuration file. Its argument
\fIargs\fR is a list of variable assignments separated with
semicolons, similarly to the \fIparams\fR argument described above.
-Each assignment has the form \fINAME\fB=\fIVALUE\fR. When called
-the function expands the \fBSQL\fR query, supplied with the \fIquery\fR
+Each assignment has the form \fINAME\fB=\fIVALUE\fR. When called,
+the function expands the \fBSQL\fR query supplied with the \fIquery\fR
argument to the \fBconfig\fR call, by replacing each \fB$\fINAME\fR
construct (a \fBvariable reference\fR) with the corresponding
\fIVALUE\fR from its argument. Similarly to the shell syntax, the
-variable reference can be written as \fB${\fINAME\fB}\fR. This latter
+variable reference can be written as \fB${\fINAME\fB}\fR. This
form can be used in contexts where the variable name is immediately
followed by another letter, to prevent it from being counted as a part
of the name.
.PP
-The expanded query is then sent to the database server. The handling
+The expanded query is then sent to the database server. Handling
of the return value depends on the number of fields it contains.
.SS Strict matches
If the returned set consists of one or two columns, only the
@@ -187,7 +187,7 @@ CREATE TABLE redirects (
);
.EE
.PP
-VCL code:
+VCL 3.0 code:
.PP
.EX
sub vcl_init {
@@ -218,6 +218,34 @@ sub vcl_error {
.PP
Notice the use of concatenation to build the argument to
\fBdbrw.rewrite\fR.
+.PP
+The following is the same code for VCL 4.0:
+.PP
+.EX
+sub vcl_init {
+ dbrw.config("mysql", "database=dbname;user=varnish",
+ {"SELECT dest
+ FROM redirects
+ WHERE host='$host'
+ AND url='$url'"});
+}
+
+sub vcl_recv {
+ set req.http.X-Redirect-To =
+ dbrw.rewrite("host=" + req.http.Host + ";" +
+ "url=" + req.url);
+ if (req.http.X-Redirect-To != "") {
+ return(synth(301, "Redirect"));
+ }
+}
+
+sub vcl_synth {
+ if (resp.status == 301) {
+ set resp.http.Location = req.http.X-Redirect-To;
+ return (deliver);
+ }
+}
+.EE
.SS Rewrites
.PP
The database structure is as follows:
@@ -234,7 +262,7 @@ CREATE TABLE rewrite (
)
.EE
.PP
-VCL code:
+VCL 3.0 code:
.PP
.EX
import std;
@@ -273,17 +301,38 @@ sub vcl_error {
}
}
.EE
+.PP
+For VCL 4.0, \fBvcl_synth\fR is used instead of \fBvcl_error\fR:
+.PP
+.EX
+sub vcl_recv {
+ set req.http.X-Redirect-To =
+ dbrw.rewrite("host=" + req.http.Host + ";" +
+ "url=" + req.url);
+ if (req.http.X-Redirect-To != "") {
+ return(synth(750, "Redirect"));
+ }
+}
+
+sub vcl_synth {
+ if (resp.status == 750) {
+ set obj.status = std.integer(req.http.X-VMOD-DBRW-Status, 301);
+ set resp.http.Location = req.http.X-Redirect-To;
+ return (deliver);
+ }
+}
+.EE
.SS Use of vmod-dbrw and vmod-redirect
.PP
.ie "\*[.T]"html" \{\
-Using the
+For VCL 3.0 you can use the
.URL https://www.varnish-cache.org/vmod/redirect \fBvmod-redirect\fR " module"
\}
.el \{\
-Using the \fBvmod-redirect\fR module
+For VCL 3.0 you can use the \fBvmod-redirect\fR module
.BR ( https://www.varnish-cache.org/vmod/redirect )
\}
-you can get rid of the \fBvcl_error\fR subroutine:
+and get rid of the \fBvcl_error\fR subroutine:
.PP
.EX
import std;
diff --git a/doc/vmod-dbrw.texi b/doc/vmod-dbrw.texi
index e399a84..344b940 100644
--- a/doc/vmod-dbrw.texi
+++ b/doc/vmod-dbrw.texi
@@ -103,12 +103,14 @@ manageable.
Some web sites implement thousands of rewrite rules. The purpose
of this module is to facilitate deploying and handling them.
+The module can be compiled for VCL 3.0 or 4.0.
+
@node Overview
@chapter Overview
@cindex rewrite rules
@cindex database engines
@cindex supported databases
-The rewrite rules are stored in a MySQL or PostgreSQL database. The
+Rewrite rules are stored in a MySQL or PostgreSQL database. The
@command{vmod-dbrw} module does not impose any restrictions on its
schema. It only needs to know the SQL query which is to be used to
retrieve data. This query is supplied to the module, along with the
@@ -116,7 +118,7 @@ credentials for accessing the database, by calling the @code{config}
function in the @code{vcl_init} subroutine of the Varnish
configuration file.
-Once the module configured, the @code{rewrite} function can be called
+Once the module is configured, the @code{rewrite} function can be called
in the appropriate place of the Varnish configuration file. Its argument
is a list of variable assignments separated with semicolons, each
assignment having the form @code{@var{name}=@var{value}}. When called,
@@ -261,7 +263,7 @@ The following @dfn{escape sequences} are allowed for use in
If a backslash is followed by a symbol other than listed above, it
is removed and the symbol following it is reproduced verbatim.
-The valid parameters are:
+Valid parameters are:
@table @samp
@kindex debug
@@ -545,7 +547,7 @@ caller.
@cindex vcl_recv
Assuming the database structure similar to the one discussed in the
previous chapter, the following example illustrates how to use
-@code{rewrite} to redirect the incoming request:
+@code{rewrite} to redirect the incoming request. It assumes VCL 4.0:
@example
@group
@@ -554,22 +556,54 @@ sub vcl_recv @{
dbrw.rewrite("host=" + req.http.Host + ";" +
"url=" + req.url);
if (req.http.X-Redirect-To != "") @{
- error(750, "Redirect");
+ return(synth(301, "Redirect"));
@}
@}
@end group
@end example
-Further handling of the 750 error should be performed in a traditional
+Further handling of the 301 response should be performed in a traditional
way, e.g.:
@vindex X-VMOD-DBRW-Status
-@cindex vcl_error
+@cindex vcl_synth
@cindex vmod_std
@example
@group
import std;
+sub vcl_synth @{
+ if (resp.status == 301) @{
+ set resp.http.Location = req.http.X-Redirect-To;
+ if (req.http.X-VMOD-DBRW-Status != "") @{
+ set resp.status =
+ std.integer(req.http.X-VMOD-DBRW-Status, 301);
+ @}
+ return (deliver);
+ @}
+@}
+@end group
+@end example
+
+The @code{X-VMOD-DBRW-Status} header, if set, contains the status code to be
+returned to the client (@pxref{X-VMOD-DBRW-Status}). Notice the use
+of the @command{vmod_std} module to cast it to integer.
+
+The example below shows the same code for VCL 3.0:
+
+@example
+@group
+import std;
+
+sub vcl_recv @{
+ set req.http.X-Redirect-To =
+ dbrw.rewrite("host=" + req.http.Host + ";" +
+ "url=" + req.url);
+ if (req.http.X-Redirect-To != "") @{
+ error(750, "Redirect");
+ @}
+@}
+
sub vcl_error @{
if (obj.status == 750) @{
set obj.http.Location = req.http.X-Redirect-To;
@@ -581,13 +615,9 @@ sub vcl_error @{
@end group
@end example
-The @code{X-VMOD-DBRW-Status} header, if set, contains the status code to be
-returned to the client (@pxref{X-VMOD-DBRW-Status}). Notice the use
-of the @command{vmod_std} module to cast it to integer.
-
@cindex vmod_redirect
-Using the @command{vmod_redirect}, the redirection can be further
-simplified:
+For VCL 3.0, you can use @command{libvmod_redirect} to simplify the
+code:
@example
@group

Return to:

Send suggestions and report system problems to the System administrator.