diff options
Diffstat (limited to 'doc/vmod-dbrw.3')
-rw-r--r-- | doc/vmod-dbrw.3 | 402 |
1 files changed, 402 insertions, 0 deletions
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: |