Vmod-dbrw README
See the end of file for copying conditions.

* Introduction

This file contains brief information about configuring, testing
and running vmod-dbrw.  It is *not* intended as a replacement
for the documentation and is provided as a brief reference only.

The complete documentation for vmod-dbrw is available in
doc/ subdirectory. To read it without installing the package
run `info -f doc/vmod-dbrw.info'. After the package is installed
the documentation can be accessed running `info vmod-dbrw'.

A shorter version of the documentation is provided in manpage
format, in file doc/vmod-dbrw.3.  After installation, it will
become available by running `man vmod-dbrw'.

An online copy of the documentation in various formats is
available at http://www.gnu.org.ua/software/vmod-dbrw/manual.html

* Overview

Vmod-dbrw is a Varnish Cache module implementing database-driven
rewrite rules. Its intended use is for web sites that need an
exceedingly big number of redirect and/or rewrite rules. Vmod-dbrw
allows you to keep all rules in an SQL database of arbitrary
structure, considerably speeding up their handling. Another advantage
of this approach is that rewrite rules stored in a database are easier
to maintain. 

This version supports MySQL and PostgreSQL databases and is known to
work for Varnish versions 6.0.6 through 6.4.0.

* Example

** Simplest case

The redirection database has the following structure

  CREATE TABLE redirects (
    host varchar(255) NOT NULL DEFAULT '',
    url varchar(255) NOT NULL DEFAULT '',
    dest varchar(255) DEFAULT NULL,
    PRIMARY KEY (host,url)
  );

The VCL code:

  import dbrw;

  sub vcl_recv {
         dbrw.config("mysql", "database=dbname;user=varnish;debug=1",
              "SELECT dest FROM redirects WHERE host='$host' AND url='$url'");
         set req.http.X-Redirect-To =
                  dbrw.rewrite("host=" + req.http.Host + ";" +
                               "url=" + req.url);
         if (req.http.X-Redirect-To != "") {
                  return(synth(301, "Redirect"));
         }
  }

  sub vcl_synth {
        if (resp.status == 301) {
                set resp.http.Location = req.http.X-Redirect-To;
                return (deliver);
        }
  }

** More complex case: rewrites

Table structure:

  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,
    KEY source (host,url)
  )

The VCL code differs only in the call to dbrw.config in vcl_recv:

  sub vcl_recv {
          dbrw.config("mysql", "database=varnish;user=varnish;debug=10",
                      {"SELECT dest,pattern,value FROM rewrite
                        WHERE host='$host' and '$url' like url"});
  }

* Installation

In order to compile the package you need to have installed
varnishd and varnishapi package.

Supposing that condition is met, run:

  ./configure

It should be able to automatically find the necessary components. In case 
it doesn't, tweak the configuration variables as necessary. The most 
important one is PKG_CONFIG_PATH, which contains a path (in the UNIX sense)
where the .pc files are located. It should contain a directory where the
'varnishapi.pc' file lives. Example usage:

  ./configure PKG_CONFIG_PATH=/usr/local/varnish/lib/pkgconfig:$PKG_CONFIG_PATH

Please read the file INSTALL for a detailed discussion of available variables
and command line options.

Once configured, do

  make

This will build the module.  After this step you can optionally run
'make test' to test the package.

Finally, run the following command as root:

  make install

* Testing

Testing the module requires access to an SQL database which will be
populated with the test data.  You can either create that database
yourself, or let the testsuite create it.  The easiest way is to
create a user (role), which is able to create the database.  For
example, in MySQL:

   GRANT ALL PRIVILEGES on dbrw_test.* to dbrw_test@localhost;

Or, in PostgreSQL:

   CREATE ROLE dbrw_test WITH LOGIN CREATEDB
   
Once done, supply the SQL credentials and the database name with
extra arguments to `make check', as shown in the example below:

  make DBRW_TEST_DBTYPE=mysql\
       DBRW_TEST_DATABASE=dbrw_test\
       DBRW_TEST_USER=dbrw_test check

You can use the following variables:

** DBRW_TEST_DATABASE

Name of the test database.  This one must be supplied in order to
enable the tests.

** DBRW_TEST_DEBUG

Debugging level to use during the test.  If greater than 0, debugging
info will be logged via syslog channel daemon.debug.

** DBRW_TEST_DBTYPE

Type of the database to use.  Either mysql or pgsql.  By default,
mysql is used, if enabled.

** DBRW_TEST_PARAMS

Any additional parameters.  These must be in the format understood
by dbrw.config function (see vmod_dbrw(3)).

** DBRW_TEST_SERVER

Name or IP address of SQL server.  Defaults to localhost.

** DBRW_TEST_USER

Database user.

** DBRW_TEST_PASS

Password to connect to the server (if necessary).

Ideally, the tests should succeed.  If they don't, that does not
necessarily indicates a problem in the module:

The tests will be skipped if the supplied credentials are insufficient
to access the SQL server. 

If the first test fails, and all subsequent ones are marked as
"expected failure", that means that the testsuite wasn't able to
create or populate the test database.  You will find more info in the
file named FAILURE located in the tests directory.  Fix the problem,
run `make -C tests clean' (see below) and re-run `make check'.

If all tests are marked as "expected failure", then the testsuite
uses the cached data from the previous run, which wasn't able to
create or populate the test database.  In this case, act as described
above.

Finally, if some or all of the tests were marked as failed, that
indicates a bug either in the module itself, or in the test suite.  In
this case, the file testsuite.log will contain detailed logs.  Additional
information can then be found in the directory testsuite.dir.  Please
send these data to the developer.

Notice, that the testsuite tries to create the database only once.
Subsequent invocations of `make check' will use the existing database.
Similarly, if it failed to create the database, the failure will be
memorized and all subsequent runs will just skip all checks.  To clear
the state, run `make clean' in the directory tests, e.g.:

  make -C tests clean
  make check

You can also supply the database credentials to invocation of
configure:
  
  ./configure --with-varnish-source=/usr/src/varnish-3.0.1\
              DBRW_TEST_DATABASE=dbrw_test\
	      DBRW_TEST_USER=dbrw_test

This way you won't need to supply them to `make check'.
	      
* Bug reporting

Send bug reports and suggestions to <gray@gnu.org>


* Copyright information:

Copyright (C) 2013-2020 Sergey Poznyakoff

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and this permission notice are preserved,
   thus giving the recipient permission to redistribute in turn.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.

Local Variables:
mode: outline
paragraph-separate: "[  ]*$"
version-control: never
End: