aboutsummaryrefslogtreecommitdiff
path: root/README
blob: 2ddf2b71de4d380d5782468fc1fb4de1e1a90a3b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
Vmod-dbrw README
Copyright (C) 2013-2014 Sergey Poznyakoff
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 compiles for
both Varnish 3.x and 4.x.

* 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)
  );

VCL 3.x code:

  import dbrw;

  sub vcl_init {
          dbrw.config("mysql", "database=dbname;user=varnish;debug=1",
              "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");
          }
  }

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

VCL 4.0 code:

  import dbrw;

  sub vcl_init {
           dbrw.config("mysql", "database=dbname;user=varnish;debug=1",
              "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 != "") {
                  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)
  )

VCL code differs only in definition of the vcl_init:

  sub vcl_init {
          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 Varnish source tree.
Both Varnish 3.x and 4.x are supported.  Supposing that the Varnish
source tree is available under /usr/src/varnish-3.0.1, run:

  ./configure --with-varnish-source=/usr/src/varnish-3.0.1

Once configured, do
  
  make

This will build the module.  Finally, do 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 the database
and SQL user, or just an SQL user and give him rights for creating it.
For example:

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

Once done, supply the SQL credentials and the database name with
extra arguments to configure, as shown in the example below:

  ./configure --with-varnish-source=/usr/src/varnish-3.0.1\
              DBRW_TEST_DATABASE=dbrw_test\
	      DBRW_TEST_USER=dbrw_test

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).

After running make, do

  make check

to run the tests.  Ideally, they should succeed.  The tests will be skipped
if the supplied credentials are insufficient to access the SQL server.
If they fail, the file testsuite.log will contain detailed logs.
Additional information can then be found in the directory testsuite.dir.

* Bug reporting

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


* Copyright information:

Copyright (C) 2013-2014 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:

Return to:

Send suggestions and report system problems to the System administrator.