aboutsummaryrefslogtreecommitdiff
path: root/README
blob: 93f6f7effcbcde9b485d1a8f3abccaaf040efc81 (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
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
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 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-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.