diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2014-11-12 12:28:47 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2014-11-12 12:30:46 +0200 |
commit | 1cb6d5974b17364d651636ec088066fef210ad2b (patch) | |
tree | 3affe01a800c9d8c94c070e5650e35e33973b516 | |
parent | bcce955697d68e0daf93e8a64ec2e6a5bb107d1d (diff) | |
download | vmod-dbrw-1cb6d5974b17364d651636ec088066fef210ad2b.tar.gz vmod-dbrw-1cb6d5974b17364d651636ec088066fef210ad2b.tar.bz2 |
Update the docs for VCL 4.0
-rw-r--r-- | doc/vmod-dbrw.3 | 69 | ||||
-rw-r--r-- | doc/vmod-dbrw.texi | 56 |
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,27 +556,29 @@ 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_error @{ - if (obj.status == 750) @{ - set obj.http.Location = req.http.X-Redirect-To; - set obj.status = +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); @} @} @@ -585,9 +589,35 @@ 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; + set obj.status = + std.integer(req.http.X-VMOD-DBRW-Status, 301); + return (deliver); + @} +@} +@end group +@end example + @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 |