aboutsummaryrefslogtreecommitdiff
path: root/README
blob: 87da0e6d9c2502a7c3a08dd0e6795b1f937f3cd7 (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
* HAProxy bulk redirects

Lua library for handling big amounts of redirect rules in HAProxy.

* Introduction

The traditional way of implementing redirects in HAProxy configuration
file is by using the 'http-request redirect' statement.  It is quite
OK for a couple of redirect rules.  Sometimes, however, you need to
install thousands of redirects.  This may be necessary, for instance,
when switching to a new version of a site, in order to preserve old
references.  Keeping such a big number of redirect statements in the
configuration file is impractical, and maintaining such a
configuration is tedious and error-prone task.

The haproxy-bulkredirect library is designed for such cases.  It
reads redirection rules from a plain text file, which is easy to
maintain.  Internally, the rules are stored in an associative array,
which provides for fast lookups.

* Dependencies

HAProxy version 2.3.6 or newer, compiled with Lua support.

* Installation

Copy the file 'bulkredirect.lua' to a directory on the server where
the haproxy server is run.  Load it in the 'global' section of your
configuration file:

  global
     lua-load /<path>/bulkredirect.lua

(replace <path> with the actual location on the filesystem).

In your 'frontend' section, add the following statement:

  http-request lua.bulkredirect

Write down your redirection rules to the file
'/etc/haproxy/bulkredirect.rt' (see below for detailed instructions).
If you prefer another file name, make it known to the library using
the HAPROXY_BULKREDIRECT environment variable.  When done, restart
haproxy.

* Redirection table

By default, the library reads redirection table from the file
'/etc/haproxy/bulkredirect.rt'.  Another file name can be supplied via
the HAPROXY_BULKREDIRECT environment variable.  Unless it ends with a
'.lua' suffix, it will be parsed as a plain text redirection table.

Each line in a redirection table file is either a comment or a
statement.  A comment begins with a '#' character as first
non-whitespace character in the line and extends to the end of the
line.  Comments serve as human-readable annotations and are otherwise
ignored.  Empty lines are ignored as well.

There are three kinds of statements: option definition, domain
declaration, and redirection rule.

** Domain declaration

This statement declares a domain for which the redirection rules below
apply.  Syntactically, it is:

  [DOMAIN]

where DOMAIN is the domain name.  No whitespace is allowed between the
name and square brackets.

Each domain declaration remains in effect until another domain
declaration is encountered in the redirection table.

Special name "*" means "any domain name".

A redirection table file must declare at least one domain.

** Option definition

Option definition begins with the word 'option' followed by one or
more option names, delimited with commas.  An option name is:

*** www

Declares that rules for each domain name declared below apply also for
that domain name, prefixed with "www."

Similarly, if a domain name already begins with "www.", all rules
defined for it apply also for a domain name with the "www." prefix
removed.

*** exact

By default, all redirects imply prefix search.  That is, if you
declare redirect rule from "/foo" to "/bar", it would also apply to
"/foo/bay", which would be redirected to "/bar/bay", etc.

If the 'exact' option is set, no path prefix search is done: the
redirection is triggered only when the pathname part of the URL
matches exactly the left-hand side of a redirection rule.

*** strippath

When set, removes from the final URL the pathname components
stripped off during prefix search.  For example, given a redirect rule
from "/foo" to "/bar", the URL "/foo/bay/qux" will be redirected to
"/bar" as well.

*** stripquery

Discard any query string attached to the incoming URI.

*** temporary

Creates a temporary redirect (HTTP response code 302).  By default,
permanent redirects (301) are created.

*** urlencode

Encode special characters in path parts of both source and destination
URLs as specified in RFC 3986 ("percent encoding").  By default,
bulkencode assumes all URLs are already properly encoded.

Each of these option names can be prefixed with 'no' to revert its
meaning.

By default all options are unset.

Here is an example of the 'option' statement:

  option www,stripquery

The 'option' statement that appears before the first domain
declaration sets the default options for each domain declared in the
file.  These defaults can be changed for each domain individually,
by placing an 'option' statement after declaring that domain.  Options
set by such statement remain in effect for each redirect that appears
after it, until overridden by another 'option' statement.

** Redirection rule

A redirection rule consists of two parts separated with arbitrary
amount of whitespace.  The left-hand side of the rule supplies the URI
in the current domain and the right-hand side gives the URL to
redirect it to.  Examples

  /about  	            /info
  /pager?q=10&confirm=true  https://example.com/pages

Left-hand side may contain query part, as shown in the last example.
Notice, that the query part is matched verbatim, which means that, e.g.
"/pager?confirm=true&q=10" won't be redirected.

If the query part is present in the right-hand side, it will replace
the actual query (i.e. the stripquery option is enabled
automatically).  It will also enable the strippath option for this
redirect.

A question mark without query part in the destination silently enables
both stripquery and strippath options for this redirect.

To override options for a single redirect, supply them after the
destination using the same syntax as in 'option' statement.  For
example:

  /about	/info  exact,www

* Test suite

A test suite is included in the distribution.  The following utilities
are needed for testing: curl, egrep, and nc.  To run the test, change
to the directory t/ and run:

  ./testsuite

By default this will start a copy of haproxy listening on localhost
port 8080, if this port is available.  If not, you will need to select
an unused TCP port and supply its number with the -p option, e.g.:

  ./testsuite -p 8081

Upon termination the testsuite prints total number of tests run and
number of failed tests.  In case of failure, the information about
each failed test is preserved in the directory 'testsuite.dir/N',
where N is the test number.  If you encounter any failures, please
create a tar archive of the testsuite.dir directory and send it to
the author.

* Bug reports

Please, send bug reports and suggestions to:

   Sergey Poznyakoff <gray@gnu.org>

* Copyright

Copyright (C) 2021 Sergey Poznyakoff

This program 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.

This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.

Return to:

Send suggestions and report system problems to the System administrator.