Redirecting HTTP Traffic

HTTP redirection is a technique that allows HAProxy to redirect a client to a different location.

You can use it for a variety of reasons, including:

  • pages were moved to a new domain name or URL
  • change in the URL scheme to a new protocol (e.g. HTTP => HTTPs)
  • short aliases for long URLs
  • persistent aliases for changing URLs

There are two directives for redirecting HTTP traffic:

  • http-request redirect
  • redirect (legacy)

The syntax of both directives is the same. However redirect is now considered to be legacy and configurations should use the http-request redirect form.

Also, the http-request redirect uses the log variable format while the redirect statement relies only on static strings.

When performing a redirection, HAProxy responds directly to the client. No traffic is forwarded to the server.

Redirect traffic to a location

HAProxy can redirect the user to the exact location provided by <loc>using the directives below:

http-request redirect location <loc> [code <code>] [<option>] [<condition>]redirect location <loc> [code <code>] [<option>] [<condition>]

These directives expect the following parameters:

<loc> A log format variable (or a simple string for redirect statement) describing the new location.
code <code> (optional)

Status code of the HTTP redirection to perform. Values accepted are:

Code Meaning
301 Permanent move
302 Temporary move; should not be cached by the client. This is the default value if no code is configured.
303 Similar to 302, but the browser must fetch the new location using a GET
307 Similar to 302, but the browser must reuse the same method as the one from the original request
308 Similar to 301, but the browser must reuse the same method as the one from the original request
<option> (optional) Can be any or a combination of the statement below:
 
set-cookie NAME[=value] A Set-Cookie header is added to the redirection. The cookie is named NAME and can have an optional value.
clear-cookie NAME[=] A special Set-Cookie header is added to the redirection. The cookie is named NAME and the Max-Age cookie parameter is set to 0. Its purpose is to instruct the browser to delete the cookie.
  Note: To a browser, these are two different cookies: NAME and NAME=. You must adapt the two statements above based on your traffic pattern.
<condition> (optional) A condition to apply this rule.

Redirect traffic using a prefix

HAProxy can redirect the user to a URL made up by concatenating <pfx> with the complete original URI path using the directives below:

http-request redirect prefix <pfx> [code <code>] [<option>] [<condition>]
redirect prefix <pfx> [code <code>] [<option>] [<condition>]

These directives expect the following parameters:

<pfx>

A log format variable (or a simple string for redirect statement) describing the new location prefix.

Note: if <pfx> is “/”, then the redirection is performed to the same URL. This can be used to insert a cookie.

code <code> (optional)

Status code of the HTTP redirection to perform. Values accepted are:

Code Meaning
301 Permanent move
302 Temporary move; should not be cached by the client. This is the default value if no code is configured.
303 Similar to 302, but the browser must fetch the new location using a GET
307 Similar to 302, but the browser must reuse the same method as the one from the original request
308 Similar to 301, but the browser must reuse the same method as the one from the original request
<option> (optional)

Can be any or a combination of the statement below:

drop-query Removes the query string from the original URL when performing the concatenation.
append-slash Used in conjunction with drop-query to add a “/” character at the end of the URL
set-cookie NAME[=value] Adds a Set-Cookie header to the redirection. The cookie is named NAME and can have an optional value.
clear-cookie NAME[=] A special Set-Cookie header is added to the redirection. The cookie is named NAME and the Max-Age cookie parameter is set to 0. Its purpose is to instruct the browser to delete the cookie.
Note: To a browser, these are two different cookies: NAME and NAME=. You must adapt the two statements above based on your traffic pattern.
<condition> (optional) A condition to apply this rule.

Redirect the scheme

HAProxy can redirect the user to a new URL scheme using the directives below:

http-request redirect scheme <schloc> [code <code>] [<option>] [<condition>]
redirect scheme <sch> [code <code>] [<option>] [<condition>]

The Location header is built by concatenating the following elements in this order:

  • <sch> provided by the directive
  • ://
  • first occurence of the Host header
  • URL

These directives expect the following parameters:

<sch> a log format variable (or a simple string for redirect statement) describing the new location
code <code> (optional)

Status code of the HTTP redirection to perform. Values accepted are:

Code Meaning
301 Permanent move
302 Temporary move; should not be cached by the client. This is the default value if no code is configured.
303 Similar to 302, but the browser must fetch the new location using a GET
307 Similar to 302, but the browser must reuse the same method as the one from the original request
308 Similar to 301, but the browser must reuse the same method as the one from the original request
<option> (optional)

Can be any or a combination of the statement below:

drop-query Removes the query string from the original URL when performing the concatenation.
append-slash Used in conjunction with drop-query to add a “/” character at the end of the URL
set-cookie NAME[=value] Adds a Set-Cookie header to the redirection. The cookie is named NAME and can have an optional value.
clear-cookie NAME[=] A special Set-Cookie header is added to the redirection. The cookie is named NAME and the Max-Age cookie parameter is set to 0. Its purpose is to instruct the browser to delete the cookie.
Note: To a browser, these are two different cookies: NAME and NAME=. You must adapt the two statements above based on your traffic pattern.
<condition> (optional) A condition to apply this rule.

Examples of traffic redirection

1. Append a ‘www.’ prefix in front of all URLs that do not have it:

acl has_www hdr_beg(host) -i www
http-request redirect code 301 location www.%[hdr(host)]%[req.uri] unless has_www

2. Redirect all HTTP traffic to HTTPS when SSL is handled by haproxy:

acl http      ssl_fc,not
http-request redirect scheme https if http

3. Send redirects for requests for articles without a ‘/’:

acl missing_slash path_reg ^/article/[^/]*$
http-request redirect code 301 prefix / drop-query append-slash if missing_slash

4. Move the login URL only to HTTPS:

acl http       ssl_fc,not
acl https      ssl_fc
acl u_login    path_beg   /login
acl u_logout   path_beg   /logout
acl up_userid  urlp_len(userid) gt 0
acl cookie_set hdr_sub(cookie) SEEN=1

http-request redirect scheme https if http  u_login
http-request redirect prefix https://%[req.hdr(Host)] set-cookie SEEN=1 if !cookie_set
http-request redirect prefix https://%[req.hdr(Host)] drop-query if u_login !up_userid
http-request redirect scheme http if https !u_login
http-request redirect location / clear-cookie USERID=       if u_logout