diff options
-rw-r--r-- | Makefile.am | 8 | ||||
-rw-r--r-- | configure.ac | 10 | ||||
-rw-r--r-- | doc/.gitignore | 30 | ||||
-rw-r--r-- | doc/Makefile.am | 22 | ||||
-rw-r--r-- | doc/vmod-dbrw.3 | 402 | ||||
-rw-r--r-- | doc/vmod-dbrw.texi (renamed from doc/vmod_dbrw.texi) | 32 | ||||
-rw-r--r-- | doc/vmod_dbrw.3 | 403 | ||||
-rw-r--r-- | src/Makefile.am | 8 | ||||
-rw-r--r-- | src/dbrw.h | 8 | ||||
-rw-r--r-- | src/mysql.c | 8 | ||||
-rw-r--r-- | src/pgsql.c | 8 | ||||
-rw-r--r-- | src/sql.c | 8 | ||||
-rw-r--r-- | src/vmod_dbrw.c | 8 |
13 files changed, 486 insertions, 469 deletions
diff --git a/Makefile.am b/Makefile.am index 829c138..fa15223 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,5 +1,5 @@ -# This file is part of libvmod_dbrw +# This file is part of vmod-dbrw # Copyright (C) 2013 Sergey Poznyakoff # -# Libvmod_dbrw is free software; you can redistribute it and/or modify +# Vmod-dbrw is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -8,3 +8,3 @@ # -# Libvmod_dbrw is distributed in the hope that it will be useful, +# Vmod-dbrw is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of @@ -14,3 +14,3 @@ # You should have received a copy of the GNU General Public License -# along with libvmod_dbrw. If not, see <http://www.gnu.org/licenses/>. +# along with vmod-dbrw. If not, see <http://www.gnu.org/licenses/>. ACLOCAL_AMFLAGS = -I m4 diff --git a/configure.ac b/configure.ac index d5a8767..a287eb3 100644 --- a/configure.ac +++ b/configure.ac @@ -1,5 +1,5 @@ -# This file is part of libvmod_dbrw -*- autoconf -*- +# This file is part of vmod-dbrw -*- autoconf -*- # Copyright (C) 2013 Sergey Poznyakoff # -# Libvmod_dbrw is free software; you can redistribute it and/or modify +# Vmod-dbrw is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -8,3 +8,3 @@ # -# Libvmod_dbrw is distributed in the hope that it will be useful, +# Vmod-dbrw is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of @@ -14,5 +14,5 @@ # You should have received a copy of the GNU General Public License -# along with libvmod_dbrw. If not, see <http://www.gnu.org/licenses/>. +# along with vmod-dbrw. If not, see <http://www.gnu.org/licenses/>. AC_PREREQ(2.69) -AC_INIT([libvmod-dbrw], 0.99, [gray@gnu.org]) +AC_INIT([vmod-dbrw], 0.99, [gray@gnu.org]) AC_CONFIG_AUX_DIR([build-aux]) diff --git a/doc/.gitignore b/doc/.gitignore index 4e23977..ddb72ba 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -3,17 +3,17 @@ stamp-vti version.texi -vmod_dbrw.info* -vmod_dbrw.aux -vmod_dbrw.cp -vmod_dbrw.cps -vmod_dbrw.fn -vmod_dbrw.kw -vmod_dbrw.ky -vmod_dbrw.log -vmod_dbrw.op -vmod_dbrw.pdf -vmod_dbrw.pg -vmod_dbrw.toc -vmod_dbrw.tp -vmod_dbrw.vr -vmod_dbrw.t2p +vmod-dbrw.info* +vmod-dbrw.aux +vmod-dbrw.cp +vmod-dbrw.cps +vmod-dbrw.fn +vmod-dbrw.kw +vmod-dbrw.ky +vmod-dbrw.log +vmod-dbrw.op +vmod-dbrw.pdf +vmod-dbrw.pg +vmod-dbrw.toc +vmod-dbrw.tp +vmod-dbrw.vr +vmod-dbrw.t2p manual diff --git a/doc/Makefile.am b/doc/Makefile.am index 9e03e8a..88cf24b 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,3 +1,19 @@ -dist_man_MANS = vmod_dbrw.3 -info_TEXINFOS=vmod_dbrw.texi +# This file is part of vmod-dbrw +# Copyright (C) 2013 Sergey Poznyakoff +# +# Vmod-dbrw is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3, or (at your option) +# any later version. +# +# Vmod-dbrw is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with vmod-dbrw. If not, see <http://www.gnu.org/licenses/>. + +dist_man_MANS = vmod-dbrw.3 vmod_dbrw.3 +info_TEXINFOS=vmod-dbrw.texi vmod_dbrw_TEXINFOS=fdl.texi @@ -21,3 +37,3 @@ manual: TEXI2HTML="texi2html $(AM_MAKEINFOFLAGS)" \ - $(GENDOCS) --texi2html vmod_dbrw 'Vmod_dbrw manual' + $(GENDOCS) --texi2html $(PACKAGE) '$(PACKAGE_NAME) manual' diff --git a/doc/vmod-dbrw.3 b/doc/vmod-dbrw.3 new file mode 100644 index 0000000..9c35772 --- /dev/null +++ b/doc/vmod-dbrw.3 @@ -0,0 +1,402 @@ +.\" This file is part of Vmod-dbrw -*- nroff -*- +.\" Copyright (C) 2013 Sergey Poznyakoff +.\" +.\" Vmod-dbrw is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 3, or (at your option) +.\" any later version. +.\" +.\" Vmod-dbrw is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" 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 "July 19, 2013" "VMOD_DBRW" "User Reference" +.SH NAME +vmod-dbrw \- Database-driven rewrite rules for Varnish Cache +.SH SYNOPSIS +.sp +.nf +import dbrw; + +sub vcl_init { + dbrw.config("\fIDBTYPE\fR", "\fIPARAMS\fR", "\fIQUERY\fR"); +} + +sub vcl_recv { + set req.http.\fIXHEADER\fR = dbrw.rewrite(\fIARGS\fR); + if (req.http.\fIXHEADER\fR) { + error(750, "Redirect"); + } +} + +sub vcl_error { + if (obj.status == 750) { + set obj.http.Location = req.http.\fIXHEADER\fR; + set obj.status = 301; + return (deliver); + } +} +.fi +.SH DESCRIPTION +.B Vmod-dbrw +is a Varnish Cache module implementing database-driven rewrite procedures. +Its intended use is for web sites that need an exceedingly big number +of redirect and/or rewrite rules. +.PP +Upon startup, the \fBconfig\fR function should be called. This call +configures the module and supplies it the information necessary for +accessing the database and interpreting the data obtained from it. +.PP +Two database types are supported: \fBMySQL\fR or \fBPostgreSQL\fR. +The first argument \fBconfig\fR instructs the module which type to +use. +.PP +.B Vmod-dbrw +does not impose any requirements on the structure of the database, +therefore the connection arguments and access credentials may vary +depending on the flavor of the database used. This information is +supplied in the \fIPARAMS\fR argument, which is a list of parameter +assignments separated with semicolons. +.PP +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 +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 +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 +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 +first tuple is used and the value of its first column is returned. +The second column (if present) is ignored. +.SS Regexp matches +Otherwise, if the returned set consists of three or four columns, the +columns are interpreted as follows: \fBresult\fR, \fBregexp\fR, +\fBvalue\fR and optional \fBflags\fR. For each returned tuple, the +\fBvalue\fR column undergoes variable expansion, using the same +algorithm as when preparing the query, and the resulting string is +matched with the \fBregexp\fR column, which is treated as an extended +\fBPOSIX\fR regular expression. If the match occurs, the \fBresult\fR +column is expanded by replacing \fBbackreferences\fR. Each occurrence +of \fB$\fIDIGIT\fR (where \fIDIGIT\fR stands for a decimal digit from +\fB0\fR through \fB9\fR) is replaced with the contents of the +\fIDIGIT\fR's parenthesized subexpression in \fBregexp\fR. For +compatibility with the traditional usage, the \fB\\\fIDIGIT\fR +notation is also allowed. The resulting value is returned. +.PP +Optional \fBflags\fR column is a comma-separated list of flags that +modify regular expression handling. The following flags are defined: +.TP +.BR NC " or " nocase +Treat \fBregexp\fR as case-insensitive. +.TP +.B case +Treat \fBregexp\fR as case-sensitive (default). +.TP +.BR QSA " or " qsappend +Treat the resulting value as URL; append any query string from the +original \fBvalue\fR to it. +.TP +.BR QSD " or " qsdiscard +Treat the resulting value as URL; discard any query string attached to +the original \fBvalue\fR. +.TP +\fBredirect=\fICODE\fR or \fBR=\fICODE\fR +On success, set the \fBX\-VMOD\-DBRW\-Status\fR header to \fICODE\fR, +which must be a valid HTTP status code. +.PP +If \fBregexp\fR or \fBvalue\fR is NULL, the tuple is handled as +described in +.BR "Strict matches" . +.PP +If \fBflags\fR is NULL, it is ignored. +.SH FUNCTIONS +.SS config +.TP +.B Prototype +config(STRING \fIDBTYPE\fR, STRING \fIPARAMS\fR, STRING \fIQUERY\fR) +.TP +.B Return value +VOID +.TP +.B Description +This function configures the module and supplies the data necessary to +connect and use the database. +.TP +.B Arguments +.RS 4 +.TP +.I DBTYPE +Type of the database. Valid values are \fBmysql\fR (for \fBMySQL\fR) +and \fBpgsql\fR (for \fBPostgreSQL\fR). +.TP +.I PARAMS +Database connection parameters. This is a list of +\fINAME\fB=\fIVALUE\fR assignments separated with semicolons. The +\fIVALUE\fR can be any sequence of characters, excepting white space +and semicolon. If any of these have to appear in it, they must either +be escaped by prepending them with a backslash, or entire \fIVALUE\fR +enclosed in a pair of (single or double) quotes. The following +\fBescape sequences\fR are allowed for use in \fIVALUE\fR: +.sp +.nf +.ta 8n 18n 42n +.ul + Sequence Expansion ASCII + \fB\\\\\fR \fB\\\fR 134 + \fB\\"\fR \fB"\fR 042 + \fB\\a\fR audible bell 007 + \fB\\b\fR backspace 010 + \fB\\f\fR form-feed 014 + \fB\\n\fR new line 012 + \fB\\r\fR charriage return 015 + \fB\\t\fR horizontal tabulation 011 + \fB\\v\fR vertical tabulation 013 +.fi +.sp +Any other character following a backslash is output verbatim. +.sp +The valid parameters are: +.RS 8 +.TP +\fBdebug\fR=\fIN\fR +Set debugging level. \fIN\fR is a decimal number. +.TP +\fBserver\fR=\fIHOST\fR +Name or IP address of the database server to connect to. If not +defined, localhost (\fB127.0.0.1\fR) is assumed. For \fBMySQL\fR +databases, if \fIHOST\fR begins with a slash (\fB/\fR), its value is +taken to be the full pathname of the local UNIX socket to connect to. +.TP +\fBport\fR=\fINUM\fR +Port number on the \fBserver\fR to connect to. Default is \fB3306\fR +for \fBMySQL\fR and \fB5432\fR for \fBPostgres\fR. +.TP +\fBdatabase=\fINAME\fR +The database name. +.TP +\fBconfig\fR=\fIFILE\fR +(\fBMySQL\fR-specific) Read credentials from the \fBMySQL\fR options +file \fIFILE\fR. +.TP +\fBgroup\fR=\fINAME\fR +(\fBMySQL\fR-specific) Read credentials from section \fINAME\fR of the +options file supplied with the \fBconfig\fR parameter. Default +section name is \fBclient\fR. +.TP +\fBcacert\fR=\fIFILE\fR +Use secure connection to the database server via SSL. The \fIFILE\fR +is a full pathname to the certificate authority file. +.TP +\fBoptions\fR=\fISTRING\fR +(\fBPostgres\fR-specific) Connection options. +.TP +\fBuser\fR=\fINAME\fR +Database user name. +.TP +\fBpassword\fR=\fISTRING\fR +Password to access the database. +.RE +.TP +.I QUERY +\fBSQL\fR query to use. It can contain variable references in the +form \fB$\fINAME\fR or \fB${\fINAME\fB|\fR, which will be replaced +prior to the execution with the actual value of the \fINAME\fR +argument to the function \fBrewrite\fR. +.RE +.SS rewrite +.TP +.B Prototype +rewrite(STRING \fIARGS\fR) +.TP +.B Return value +STRING +.TP +.B Description +Rewrites the argument according to the database. See the section +\fBDESCRIPTION\fR for a detailed discussion. +.SH EXAMPLES +The examples in this section assume \fBMySQL\fR databases. Any +details not related to \fBvmod-dbrw\fR are omitted. The \fBsub +vcl_error\fR is responsible for actual returning the 301 or 302 +error. If not shown it is the same as in section \fBSYNOPSIS\fR. +.SS Redirects +.PP +This example shows how to implement apache-style permanent redirects +in Varnish. +.PP +The following table is used to keep the redirection data: +.sp +.nf +.in +2 +CREATE TABLE redirects ( + host varchar(255) NOT NULL DEFAULT '', + url varchar(255) NOT NULL DEFAULT '', + dest varchar(255) DEFAULT NULL, + PRIMARY KEY (host,url) +); +.in +.fi +.PP +VCL code: +.sp +.nf +.in +2 +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 != "") { + error(750, "Redirect"); + } +} +.in +.fi +.PP +Notice the use of concatenation to build the argument to +\fBdbrw.rewrite\fR. +.SS Rewrites. +.PP +The database structure is as follows: +.sp +.nf +.in +2 +CREATE TABLE rewrite ( + host varchar(255) NOT NULL DEFAULT '', + url varchar(255) NOT NULL DEFAULT '', + dest varchar(255) DEFAULT NULL, + value varchar(255) DEFAULT NULL, + pattern varchar(255) DEFAULT NULL, + flags char(64) DEFAULT NULL, + KEY source (host,url) +) +.in +.fi +.PP +VCL code: +.sp +.nf +.in +2 +import std; # The std module is used by \fBvcl_error\fR below +import dbrw; + +sub vcl_init { + # It is supposed that the url column contains an SQL-style + # wildcard pattern. + dbrw.config("mysql", "database=varnish;user=varnish;debug=10", + {"SELECT dest,pattern,value,flags FROM rewrite + WHERE host='$host' and '$url' like 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 != "") { + error(750, "Redirect"); + } +} +.in +.fi +.PP +The \fBvcl_error\fR function uses the \fBX\-VMOD\-DBRW\-Status\fR +header, which may be set by \fBredirect=\fR flag in the +\fBflags\fR column. Its value is converted to integer using the +\fBinteger\fR function from the \fBstd\fR module. If the header is +not set, permanent redirect is assumed: +.sp +.nf +.in +2 +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); + } +} +.in +.fi +.SS Use of vmod-dbrw and vmod-redirect +.PP +Using the \fBvmod-redirect\fR module +.BR ( https://www.varnish-cache.org/vmod/redirect ) +you can get rid of the \fBvcl_error\fR subroutine. +.sp +.nf +.in +2 +import std; +import dbrw; +import redirect; + +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(redirect.location( + std.integer(req.http.X-VMOD-DBRW-Status, 301), + req.http.X-Redirect-To), "Redirection"); + } +} +.in +.fi +.SH "SEE ALSO" +.BR vcl (7), +.BR varnishd (1). +.PP +The full documentation for +.B vmod-dbrw +is maintained as a Texinfo +manual. If the +.B info +program and +.B vmod-dbrw +module are properly installed at your site, the command +.sp +.nf +.in +4 +.B info vmod-dbrw +.in +.fi +.PP +should give you access to the complete manual. +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to <gray@gnu.org>. +.SH COPYRIGHT +Copyright \(co 2013 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> +.br +.ad +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.\" Local variables: +.\" eval: (add-hook 'write-file-hooks 'time-stamp) +.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.-]* [0-9] \"" +.\" time-stamp-format: "%:B %:d, %:y" +.\" time-stamp-end: "\"" +.\" time-stamp-line-limit: 20 +.\" end: diff --git a/doc/vmod_dbrw.texi b/doc/vmod-dbrw.texi index 6ec2431..de83723 100644 --- a/doc/vmod_dbrw.texi +++ b/doc/vmod-dbrw.texi @@ -3,4 +3,4 @@ @c %**start of header -@setfilename vmod_dbrw.info -@settitle Vmod_dbrw User Manual +@setfilename vmod-dbrw.info +@settitle vmod-dbrw User Manual @c %**end of header @@ -23,3 +23,3 @@ @direntry -* vmod_dbrw: (vmod_dbrw). Database-driven rewrite rules. +* vmod-dbrw: (vmod-dbrw). Database-driven rewrite rules. @end direntry @@ -43,3 +43,3 @@ Documentation License''. @titlepage -@title Vmod_Dbrw User Manual +@title Vmod-Dbrw User Manual @subtitle version @value{VERSION}, @value{UPDATED} @@ -60,5 +60,5 @@ Documentation License''. @node Top -@top Vmod_dbrw -This edition of the @cite{Vmod_dbrw User Manual}, last updated @value{UPDATED}, -documents @command{vmod_dbrw} Version @value{VERSION}. +@top vmod-dbrw +This edition of the @cite{vmod-dbrw User Manual}, last updated @value{UPDATED}, +documents @command{vmod-dbrw} Version @value{VERSION}. @end ifnottex @@ -66,3 +66,3 @@ documents @command{vmod_dbrw} Version @value{VERSION}. @menu -* Intro:: What is Vmod_dbrw. +* Intro:: What is vmod-dbrw. * Overview:: How it works. @@ -87,6 +87,6 @@ Appendices @node Intro -@chapter Introduction to Vmod_dbrw +@chapter Introduction to vmod-dbrw @cindex Varnish @cindex rewrite rules -@command{Vmod_dbrw} is a module for +@command{Vmod-dbrw} is a module for @command{Varnish Cache}@footnote{@url{https://www.varnish-cache.org}} @@ -97,3 +97,3 @@ module in @command{Apache} or to @code{Redirect} directives of its @command{mod_alias} module. What distinguishes the -@command{vmod_dbrw} rules from these, is that they are handled by +@command{vmod-dbrw} rules from these, is that they are handled by @command{Varnish}, before the request reaches the httpd server, and @@ -111,3 +111,3 @@ of this module is to facilitate deploying and handling them. The rewrite rules are stored in a MySQL or PostgreSQL database. The -@command{vmod_dbrw} module does not impose any restrictions on its +@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 @@ -338,3 +338,3 @@ with the actual value of the @var{name} argument to the function -The example below configures @command{vmod_dbrw} to use MySQL database +The example below configures @command{vmod-dbrw} to use MySQL database @samp{rewrite}, with the user name @samp{varnish} and password @var{guessme}. @@ -364,3 +364,3 @@ and the query so that the database look up be as fast as possible. -Suppose that you plan to use @command{vmod_dbrw} to implement +Suppose that you plan to use @command{vmod-dbrw} to implement redirection rules based on strict matching (@pxref{strict matching}). @@ -412,3 +412,3 @@ Handling regular expression matches is a bit trickier. Your query should first return the rows that could match the request. Then the -@command{vmod_dbrw} engine will do the rest, by iterating over them +@command{vmod-dbrw} engine will do the rest, by iterating over them and finding the one that actually does. It will iterate over the rows @@ -628,3 +628,3 @@ information needed is: file along with your bug report. This file is created after running -@command{./configure} in @command{vmod_dbrw} source root directory. +@command{./configure} in @command{vmod-dbrw} source root directory. @end itemize diff --git a/doc/vmod_dbrw.3 b/doc/vmod_dbrw.3 index 777547e..7aa3d08 100644 --- a/doc/vmod_dbrw.3 +++ b/doc/vmod_dbrw.3 @@ -1,402 +1 @@ -.\" This file is part of libvmod_dbrw -*- nroff -*- -.\" Copyright (C) 2013 Sergey Poznyakoff -.\" -.\" Libvmod_dbrw is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License as published by -.\" the Free Software Foundation; either version 3, or (at your option) -.\" any later version. -.\" -.\" Libvmod_dbrw is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" along with libvmod_dbrw. If not, see <http://www.gnu.org/licenses/>. -.TH VMOD_DBRW 1 "July 19, 2013" "VMOD_DBRW" "User Reference" -.SH NAME -vmod_dbrw \- Database-driven rewrite rules for Varnish Cache -.SH SYNOPSIS -.sp -.nf -import dbrw; - -sub vcl_init { - dbrw.config("\fIDBTYPE\fR", "\fIPARAMS\fR", "\fIQUERY\fR"); -} - -sub vcl_recv { - set req.http.\fIXHEADER\fR = dbrw.rewrite(\fIARGS\fR); - if (req.http.\fIXHEADER\fR) { - error(750, "Redirect"); - } -} - -sub vcl_error { - if (obj.status == 750) { - set obj.http.Location = req.http.\fIXHEADER\fR; - set obj.status = 301; - return (deliver); - } -} -.fi -.SH DESCRIPTION -.B Vmod-dbrw -is a Varnish Cache module implementing database-driven rewrite procedures. -Its intended use is for web sites that need an exceedingly big number -of redirect and/or rewrite rules. -.PP -Upon startup, the \fBconfig\fR function should be called. This call -configures the module and supplies it the information necessary for -accessing the database and interpreting the data obtained from it. -.PP -Two database types are supported: \fBMySQL\fR or \fBPostgreSQL\fR. -The first argument \fBconfig\fR instructs the module which type to -use. -.PP -.B Vmod-dbrw -does not impose any requirements on the structure of the database, -therefore the connection arguments and access credentials may vary -depending on the flavor of the database used. This information is -supplied in the \fIPARAMS\fR argument, which is a list of parameter -assignments separated with semicolons. -.PP -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 -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 -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 -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 -first tuple is used and the value of its first column is returned. -The second column (if present) is ignored. -.SS Regexp matches -Otherwise, if the returned set consists of three or four columns, the -columns are interpreted as follows: \fBresult\fR, \fBregexp\fR, -\fBvalue\fR and optional \fBflags\fR. For each returned tuple, the -\fBvalue\fR column undergoes variable expansion, using the same -algorithm as when preparing the query, and the resulting string is -matched with the \fBregexp\fR column, which is treated as an extended -\fBPOSIX\fR regular expression. If the match occurs, the \fBresult\fR -column is expanded by replacing \fBbackreferences\fR. Each occurrence -of \fB$\fIDIGIT\fR (where \fIDIGIT\fR stands for a decimal digit from -\fB0\fR through \fB9\fR) is replaced with the contents of the -\fIDIGIT\fR's parenthesized subexpression in \fBregexp\fR. For -compatibility with the traditional usage, the \fB\\\fIDIGIT\fR -notation is also allowed. The resulting value is returned. -.PP -Optional \fBflags\fR column is a comma-separated list of flags that -modify regular expression handling. The following flags are defined: -.TP -.BR NC " or " nocase -Treat \fBregexp\fR as case-insensitive. -.TP -.B case -Treat \fBregexp\fR as case-sensitive (default). -.TP -.BR QSA " or " qsappend -Treat the resulting value as URL; append any query string from the -original \fBvalue\fR to it. -.TP -.BR QSD " or " qsdiscard -Treat the resulting value as URL; discard any query string attached to -the original \fBvalue\fR. -.TP -\fBredirect=\fICODE\fR or \fBR=\fICODE\fR -On success, set the \fBX\-VMOD\-DBRW\-Status\fR header to \fICODE\fR, -which must be a valid HTTP status code. -.PP -If \fBregexp\fR or \fBvalue\fR is NULL, the tuple is handled as -described in -.BR "Strict matches" . -.PP -If \fBflags\fR is NULL, it is ignored. -.SH FUNCTIONS -.SS config -.TP -.B Prototype -config(STRING \fIDBTYPE\fR, STRING \fIPARAMS\fR, STRING \fIQUERY\fR) -.TP -.B Return value -VOID -.TP -.B Description -This function configures the module and supplies the data necessary to -connect and use the database. -.TP -.B Arguments -.RS 4 -.TP -.I DBTYPE -Type of the database. Valid values are \fBmysql\fR (for \fBMySQL\fR) -and \fBpgsql\fR (for \fBPostgreSQL\fR). -.TP -.I PARAMS -Database connection parameters. This is a list of -\fINAME\fB=\fIVALUE\fR assignments separated with semicolons. The -\fIVALUE\fR can be any sequence of characters, excepting white space -and semicolon. If any of these have to appear in it, they must either -be escaped by prepending them with a backslash, or entire \fIVALUE\fR -enclosed in a pair of (single or double) quotes. The following -\fBescape sequences\fR are allowed for use in \fIVALUE\fR: -.sp -.nf -.ta 8n 18n 42n -.ul - Sequence Expansion ASCII - \fB\\\\\fR \fB\\\fR 134 - \fB\\"\fR \fB"\fR 042 - \fB\\a\fR audible bell 007 - \fB\\b\fR backspace 010 - \fB\\f\fR form-feed 014 - \fB\\n\fR new line 012 - \fB\\r\fR charriage return 015 - \fB\\t\fR horizontal tabulation 011 - \fB\\v\fR vertical tabulation 013 -.fi -.sp -Any other character following a backslash is output verbatim. -.sp -The valid parameters are: -.RS 8 -.TP -\fBdebug\fR=\fIN\fR -Set debugging level. \fIN\fR is a decimal number. -.TP -\fBserver\fR=\fIHOST\fR -Name or IP address of the database server to connect to. If not -defined, localhost (\fB127.0.0.1\fR) is assumed. For \fBMySQL\fR -databases, if \fIHOST\fR begins with a slash (\fB/\fR), its value is -taken to be the full pathname of the local UNIX socket to connect to. -.TP -\fBport\fR=\fINUM\fR -Port number on the \fBserver\fR to connect to. Default is \fB3306\fR -for \fBMySQL\fR and \fB5432\fR for \fBPostgres\fR. -.TP -\fBdatabase=\fINAME\fR -The database name. -.TP -\fBconfig\fR=\fIFILE\fR -(\fBMySQL\fR-specific) Read credentials from the \fBMySQL\fR options -file \fIFILE\fR. -.TP -\fBgroup\fR=\fINAME\fR -(\fBMySQL\fR-specific) Read credentials from section \fINAME\fR of the -options file supplied with the \fBconfig\fR parameter. Default -section name is \fBclient\fR. -.TP -\fBcacert\fR=\fIFILE\fR -Use secure connection to the database server via SSL. The \fIFILE\fR -is a full pathname to the certificate authority file. -.TP -\fBoptions\fR=\fISTRING\fR -(\fBPostgres\fR-specific) Connection options. -.TP -\fBuser\fR=\fINAME\fR -Database user name. -.TP -\fBpassword\fR=\fISTRING\fR -Password to access the database. -.RE -.TP -.I QUERY -\fBSQL\fR query to use. It can contain variable references in the -form \fB$\fINAME\fR or \fB${\fINAME\fB|\fR, which will be replaced -prior to the execution with the actual value of the \fINAME\fR -argument to the function \fBrewrite\fR. -.RE -.SS rewrite -.TP -.B Prototype -rewrite(STRING \fIARGS\fR) -.TP -.B Return value -STRING -.TP -.B Description -Rewrites the argument according to the database. See the section -\fBDESCRIPTION\fR for a detailed discussion. -.SH EXAMPLES -The examples in this section assume \fBMySQL\fR databases. Any -details not related to \fBvmod_dbrw\fR are omitted. The \fBsub -vcl_error\fR is responsible for actual returning the 301 or 302 -error. If not shown it is the same as in section \fBSYNOPSIS\fR. -.SS Redirects -.PP -This example shows how to implement apache-style permanent redirects -in Varnish. -.PP -The following table is used to keep the redirection data: -.sp -.nf -.in +2 -CREATE TABLE redirects ( - host varchar(255) NOT NULL DEFAULT '', - url varchar(255) NOT NULL DEFAULT '', - dest varchar(255) DEFAULT NULL, - PRIMARY KEY (host,url) -); -.in -.fi -.PP -VCL code: -.sp -.nf -.in +2 -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 != "") { - error(750, "Redirect"); - } -} -.in -.fi -.PP -Notice the use of concatenation to build the argument to -\fBdbrw.rewrite\fR. -.SS Rewrites. -.PP -The database structure is as follows: -.sp -.nf -.in +2 -CREATE TABLE rewrite ( - host varchar(255) NOT NULL DEFAULT '', - url varchar(255) NOT NULL DEFAULT '', - dest varchar(255) DEFAULT NULL, - value varchar(255) DEFAULT NULL, - pattern varchar(255) DEFAULT NULL, - flags char(64) DEFAULT NULL, - KEY source (host,url) -) -.in -.fi -.PP -VCL code: -.sp -.nf -.in +2 -import std; # The std module is used by \fBvcl_error\fR below -import dbrw; - -sub vcl_init { - # It is supposed that the url column contains an SQL-style - # wildcard pattern. - dbrw.config("mysql", "database=varnish;user=varnish;debug=10", - {"SELECT dest,pattern,value,flags FROM rewrite - WHERE host='$host' and '$url' like 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 != "") { - error(750, "Redirect"); - } -} -.in -.fi -.PP -The \fBvcl_error\fR function uses the \fBX\-VMOD\-DBRW\-Status\fR -header, which may be set by \fBredirect=\fR flag in the -\fBflags\fR column. Its value is converted to integer using the -\fBinteger\fR function from the \fBstd\fR module. If the header is -not set, permanent redirect is assumed: -.sp -.nf -.in +2 -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); - } -} -.in -.fi -.SS Use of vmod_dbrw and vmod_redirect -.PP -Using the \fBvmod_redirect\fR module -.BR ( https://www.varnish-cache.org/vmod/redirect ) -you can get rid of the \fBvcl_error\fR subroutine. -.sp -.nf -.in +2 -import std; -import dbrw; -import redirect; - -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(redirect.location( - std.integer(req.http.X-VMOD-DBRW-Status, 301), - req.http.X-Redirect-To), "Redirection"); - } -} -.in -.fi -.SH "SEE ALSO" -.BR vcl (7), -.BR varnishd (1). -.PP -The full documentation for -.B vmod_dbrw -is maintained as a Texinfo -manual. If the -.B info -program and -.B vmod_dbrw -module are properly installed at your site, the command -.sp -.nf -.in +4 -.B info vmod_dbrw -.in -.fi -.PP -should give you access to the complete manual. -.SH AUTHORS -Sergey Poznyakoff -.SH "BUG REPORTS" -Report bugs to <gray@gnu.org>. -.SH COPYRIGHT -Copyright \(co 2013 Sergey Poznyakoff -.br -.na -License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> -.br -.ad -This is free software: you |