summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2013-07-27 03:43:44 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2013-07-27 03:43:44 (GMT)
commit4912a0408aa773dc80e84e19d0d437795acfa043 (patch) (side-by-side diff)
tree7ce4221787afc9e31b5ef80e6da371d30cd34a32
parent9045c4dca5a4ca866dc5563a9aa7d6dd6c5350b7 (diff)
downloadvmod-dbrw-4912a0408aa773dc80e84e19d0d437795acfa043.tar.gz
vmod-dbrw-4912a0408aa773dc80e84e19d0d437795acfa043.tar.bz2
Improve manpage.
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--doc/vmod-dbrw.3227
1 files changed, 90 insertions, 137 deletions
diff --git a/doc/vmod-dbrw.3 b/doc/vmod-dbrw.3
index 9b6d9f5..9496270 100644
--- a/doc/vmod-dbrw.3
+++ b/doc/vmod-dbrw.3
@@ -13,138 +13,37 @@
.\"
.\" 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 26, 2013" "VMOD_DBRW" "User Reference"
+.TH VMOD_DBRW 1 "July 27, 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
+.B import dbrw;
+.br
+.BI "VOID dbrw.config(STRING " dbtype ", STRING " params ", STRING " query ");"
+.br
+.BI "STRING dbrw.rewrite(STRING " args ");"
.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.
+The \fBconfig\fR function should be called upon startup, in \fBsub
+vcl_init\fR. It 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.
+The \fIdbtype\fR argument specifies the database type to use.
+Valid values are \fBmysql\fR (for \fBMySQL\fR) and \fBpgsql\fR (for
+\fBPostgreSQL\fR).
.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
+supplied in the \fIparams\fR argument, which 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
@@ -169,7 +68,6 @@ enclosed in a pair of (single or double) quotes. The following
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.
@@ -208,30 +106,71 @@ Database user name.
.TP
\fBpassword\fR=\fISTRING\fR
Password to access the database.
-.RE
+.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
-.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
+.BR NC " or " nocase
+Treat \fBregexp\fR as case-insensitive.
.TP
-.B Prototype
-rewrite(STRING \fIARGS\fR)
+.B case
+Treat \fBregexp\fR as case-sensitive (default).
.TP
-.B Return value
-STRING
+.BR QSA " or " qsappend
+Treat the resulting value as URL; append any query string from the
+original \fBvalue\fR to it.
.TP
-.B Description
-Rewrites the argument according to the database. See the section
-\fBDESCRIPTION\fR for a detailed discussion.
+.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 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.
+details not related to \fBvmod-dbrw\fR are omitted.
.SS Redirects
.PP
This example shows how to implement apache-style permanent redirects
@@ -270,6 +209,14 @@ sub vcl_recv {
error(750, "Redirect");
}
}
+
+sub vcl_error {
+ if (obj.status == 750) {
+ set obj.http.Location = req.http.X-Redirect-To;
+ set obj.status = 301;
+ return (deliver);
+ }
+}
.in
.fi
.PP
@@ -338,9 +285,15 @@ sub vcl_error {
.fi
.SS Use of vmod-dbrw and vmod-redirect
.PP
+.ie "\*[.T]"html" \{\
+Using the
+.URL https://www.varnish-cache.org/vmod/redirect \fBvmod-redirect\fR " module"
+\}
+.el \{\
Using the \fBvmod-redirect\fR module
.BR ( https://www.varnish-cache.org/vmod/redirect )
-you can get rid of the \fBvcl_error\fR subroutine.
+\}
+you can get rid of the \fBvcl_error\fR subroutine:
.sp
.nf
.in +2

Return to:

Send suggestions and report system problems to the System administrator.