aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Makefile.am8
-rw-r--r--configure.ac10
-rw-r--r--doc/.gitignore30
-rw-r--r--doc/Makefile.am22
-rw-r--r--doc/vmod-dbrw.3402
-rw-r--r--doc/vmod-dbrw.texi (renamed from doc/vmod_dbrw.texi)32
-rw-r--r--doc/vmod_dbrw.3403
-rw-r--r--src/Makefile.am8
-rw-r--r--src/dbrw.h8
-rw-r--r--src/mysql.c8
-rw-r--r--src/pgsql.c8
-rw-r--r--src/sql.c8
-rw-r--r--src/vmod_dbrw.c8
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