# This file is part of vmod-dbrw
# Copyright (C) 2013-2020 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/>.

$Module dbrw 3 "Database-driven rewrite rules for Varnish Cache"

COLOPHON
========
This document provides a short description of the **vmod-dbrw** module.
For a detailed documentation, please see the vmod-dbrw texinfo document
or vmod-dbrw(3) manual page.  If **vmod-dbrw** is properly installed on
your system, running **info vmod-dbrw** will bring you complete
documentation.

You will find documentation sources in **vmod-dbrw** source tree,
subdirectory **doc**.

DESCRIPTION
===========

This module for Varnish Cache implements database-driven rewrite rules.
These rules may be similar to *RewriteRule* directives implemented by
**mod_rewrite** module in Apache or to *Redirect* directives of its
**mod_alias** module.  What distinguishes the **vmod-dbrw** rules from
these, is that they are handled by Varnish, before the request reaches the
httpd server, and that they are stored in an SQL database, which makes
them easily manageable.

$Event dbrw_event
$Function VOID config(PRIV_TASK, STRING, STRING, STRING)

Description
    Configures the module and provides it with the data
    necessary to connect and use the database.  It is normally called
    from the **vcl_recv** subroutine.

Example
    ::
	
      dbrw.config("mysql",
                  "database=rewrite;user=varnish;password=guessme",
                  {"SELECT dest
                      FROM redirects
                     WHERE host='$host'
                       AND url='$url'"});


$Function STRING rewrite(PRIV_TASK, STRING)

Description
     Rewrites its argument using the database configured in the previous
     call to **config** and returns the obtained value.

Example
     ::
     
       set req.http.X-Redirect-To =
             dbrw.rewrite("host=" + req.http.Host + ";" +
                          "url=" + req.url);

SEE ALSO
========

* vcl(7)
* varnishd(1)