Use vmod-dbrw (with a dash) as the canonical project name.

1 files changed, 1 insertions, 402 deletions

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