diff options
Diffstat (limited to 'README')
-rw-r--r-- | README | 202 |
1 files changed, 202 insertions, 0 deletions
@@ -0,0 +1,202 @@ +* 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. + +** 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. + +Each of these option names can be prefixed with 'no' to revert its +meaning. + +By default all options are unset. + +The options defined in this statement remain in effect until changed +by another 'option' statement below. They also can be overridden for +each redirect individually. See the discussion of redirection rules +below. + +Here is an example of the 'option' statement: + + option www,stripquery + +** 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". + +** 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/>. + |