HTTP redirects tell a client to go to another URL to find the requested content.

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.

Note

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:

# Used in the a frontend, listen, or backend section
    http-request redirect location <loc> [code <code>] [<option>] [<condition>]

These directives expect the following parameters:

Parameter

Description

<loc>

A string and/or log format variable describing the new location (see examples at the end of this page)

code <code> (optional, defaults to a 302 if not specified)

Status code of the HTTP redirection to perform.

Accepted values 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 statements below:

set-cookie NAME[=value] (optional)

A Set-Cookie header is added to the redirection. The cookie is named NAME and can have an optional value.

clear-cookie NAME[=] (optional)

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:

# Used in the a frontend, listen, or backend section
    http-request redirect prefix <pfx> [code <code>] [<option>] [<condition>]

These directives expect the following parameters:

Parameter

Description

<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. Accepted values 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 statements 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:

# Used in the a frontend, listen, or backend section
    http-request redirect scheme <schloc> [code <code>] [<option>] [<condition>]

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

  1. <sch> provided by the directive

  2. ://

  3. first occurence of the Host header

  4. URL

These directives expect the following parameters:

Parameter

Description

<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 statements 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

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

# Used in the a frontend, listen, or backend section
    acl has_www hdr_beg(host) -i www
    http-request redirect code 301 location http://www.%[hdr(host)]%[req.uri] unless has_www

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

# Used in the a frontend, listen, or backend section
    acl http      ssl_fc,not
    http-request redirect scheme https if http

Send redirects for requests for articles without a '/':

# Used in the a frontend, listen, or backend section
    acl missing_slash path_reg ^/article/[^/]*$
    http-request redirect code 301 prefix / drop-query append-slash if missing_slash

Move the login URL only to HTTPS:

# Used in the a frontend, listen, or backend section
    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