diff options
Diffstat (limited to 'doc')
| -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 |
5 files changed, 453 insertions, 436 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index 4e23977..ddb72ba 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,19 +1,19 @@ genfile.texi 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,5 +1,21 @@ -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 EXTRA_DIST = gendocs_template @@ -19,7 +35,7 @@ manual: MAKEINFO="$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS)" \ TEXI2DVI="$(TEXI2DVI) -t @finalout" \ TEXI2HTML="texi2html $(AM_MAKEINFOFLAGS)" \ - $(GENDOCS) --texi2html vmod_dbrw 'Vmod_dbrw manual' + $(GENDOCS) --texi2html $(PACKAGE) '$(PACKAGE_NAME) manual' manual.tar.bz2: 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 @@ -1,8 +1,8 @@ \input texinfo @c -*-texinfo-*- @smallbook @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 @setchapternewpage odd @@ -21,7 +21,7 @@ @ifinfo @dircategory Varnish Cache Modules @direntry -* vmod_dbrw: (vmod_dbrw). Database-driven rewrite rules. +* vmod-dbrw: (vmod-dbrw). Database-driven rewrite rules. @end direntry @end ifinfo @@ -41,7 +41,7 @@ Documentation License''. @end copying @titlepage -@title Vmod_Dbrw User Manual +@title Vmod-Dbrw User Manual @subtitle version @value{VERSION}, @value{UPDATED} @author Sergey Poznyakoff. @page @@ -58,13 +58,13 @@ Documentation License''. @ifnottex @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 @menu -* Intro:: What is Vmod_dbrw. +* Intro:: What is vmod-dbrw. * Overview:: How it works. * Configuration:: * Query:: How to Write a Query. @@ -85,17 +85,17 @@ Appendices @end menu @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}} which implements database-driven rewrite rules. These rules may be similar to @code{RewriteRule} directives implemented by @command{mod_rewrite}@footnote{@url{http://httpd.apache.org/docs/current/rewrite/}} 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 that they are stored in an SQL database, which makes them easily manageable. @@ -109,7 +109,7 @@ of this module is to facilitate deploying and handling them. @cindex database engines @cindex supported databases 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 retrieve data. This query is supplied to the module, along with the credentials for accessing the database, by calling the @code{config} @@ -336,7 +336,7 @@ with the actual value of the @var{name} argument to the function @end table @end deftypefn -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}. @example @@ -362,7 +362,7 @@ database schema and on the kind of matching required. To ensure the best performance of the module it is important to design the database 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}). The simplest database structure for this purpose (assuming MySQL) will be: @@ -410,7 +410,7 @@ actual host and URL parts of the incoming request. 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 in the order they were returned by the database server, so it might be necessary to sort them by some criterion beforehand. @@ -626,7 +626,7 @@ information needed is: @item Conditions under which the bug appears. @item It is often helpful to send the contents of @file{config.log} 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 @node Copying This Manual 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 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: +.so man3/vmod-dbrw.3 |