diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-07-17 18:40:09 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-07-17 18:40:09 +0300 |
commit | 9115ff0a790cb5bf6eb748cef6733562f18e9d75 (patch) | |
tree | e2489c1fa219437015f49a994444475ae8cf1b76 | |
parent | 351364f283f3223f29090068069a127aef572cbf (diff) | |
download | vmod-dbrw-9115ff0a790cb5bf6eb748cef6733562f18e9d75.tar.gz vmod-dbrw-9115ff0a790cb5bf6eb748cef6733562f18e9d75.tar.bz2 |
Add the documentation.
* Makefile.am (SUBDIRS): Add doc.
* configure.ac: Build doc/Makefile.
* doc/Makefile.am: New file.
* doc/vmod_dbrw.3: New file.
* src/vmod_dbrw.c (vmod_rewrite): Minor change.
-rw-r--r-- | Makefile.am | 2 | ||||
-rw-r--r-- | configure.ac | 1 | ||||
-rw-r--r-- | doc/Makefile.am | 1 | ||||
-rw-r--r-- | doc/vmod_dbrw.3 | 381 | ||||
-rw-r--r-- | src/vmod_dbrw.c | 4 |
5 files changed, 386 insertions, 3 deletions
diff --git a/Makefile.am b/Makefile.am index 2352cee..829c138 100644 --- a/Makefile.am +++ b/Makefile.am @@ -15,7 +15,7 @@ # along with libvmod_dbrw. If not, see <http://www.gnu.org/licenses/>. ACLOCAL_AMFLAGS = -I m4 -SUBDIRS = src #tests +SUBDIRS = src doc #tests EXTRA_DIST=git2chg.awk diff --git a/configure.ac b/configure.ac index 8a3bc59..d5a8767 100644 --- a/configure.ac +++ b/configure.ac @@ -183,6 +183,7 @@ dnl FIXME: tests/Makefile AC_CONFIG_FILES([ Makefile src/Makefile + doc/Makefile ]) AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..87c1767 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1 @@ +dist_man_MANS = vmod_dbrw.3 diff --git a/doc/vmod_dbrw.3 b/doc/vmod_dbrw.3 new file mode 100644 index 0000000..a086c59 --- /dev/null +++ b/doc/vmod_dbrw.3 @@ -0,0 +1,381 @@ +.\" This file is part of libvmod_basicauth -*- nroff -*- +.\" Copyright (C) 2013 Sergey Poznyakoff +.\" +.\" Libvmod_basicauth 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_basicauth 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_basicauth. If not, see <http://www.gnu.org/licenses/>. +.TH VMOD_DBRW 1 "July 17, 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 tuples consist of one column 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 \fBPosgres\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 +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. If 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; + if (req.http.X-VMOD-DBRW-Status) { + set obj.status = req.http.X-VMOD-DBRW-Status; + } else { + set obj.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 { + 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). +.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/src/vmod_dbrw.c b/src/vmod_dbrw.c index 2895ea5..56a4144 100644 --- a/src/vmod_dbrw.c +++ b/src/vmod_dbrw.c @@ -508,8 +508,8 @@ vmod_rewrite(struct sess *sp, struct vmod_priv *priv, const char *arg) char *res; debug(conf, 2, ("vmod_rewrite(%s) begin", arg)); - if (!conf) { - debug(conf, 2, ("vmod_rewrite: no conf; exiting")); + if (!conf || !conf->query) { + debug(conf, 2, ("vmod_rewrite: not configured; exiting")); return NULL; } cp = get_connection(conf); |