HTTP redirection

HTTP redirection is the technic which allows HAProxy to redirect a client to an other location.

It can be used for many reasons:

  • pages moved to a new domain name / URL
  • changing the URL scheme to a new protocol (HTTP => HTTPs)
  • short aliases for long URLs
  • persistent aliases for changing URLs
  • non exhaustive list

There are two directives to perform HTTP redirections:

  • http-request redirect
  • redirect (legacy)

The syntax of both directives is the same, that said, redirect is now considered as legacy and configurations should move to the http-request redirect form.

An other main difference, is that the http-request redirect uses the log variable format while the redirect statement relies only on static strings.

Note

When performing a redirection, HAProxy answer directly to the client, no traffic is forwarded to the server

Location redirection

Use the directives below to redirect the user to the exact location provided by <loc>:

  • 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, shouldn’t be cached by the client. This is the default value if no code is configured.
    303 like 302, but the browser must fetch the new location using a GET
    307 like 302, but the browser must re-use the same method the one from the original request
    308 like 301, but the browser must re-use the same method than 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 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. Purpose is to instruct the browser to delete the cookie.

    Note

    for 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

Prefix redirection

Use the directives below to redirect the user to a URL built by concateneting <pfx> and the complete original uri path:

  • 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 redirect 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, shouldn’t be cached by the client. This is the default value if no code is configured.
    303 like 302, but the browser must fetch the new location using a GET
    307 like 302, but the browser must re-use the same method the one from the original request
    308 like 301, but the browser must re-use the same method than the one from the original request
  • <option> (optional) : can be any or a combination of the statement below:

    • drop-query : Remove 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] : A Set-Cookie header is added to the redirection. The cookie is named NAME and can have an optional value 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. Purpose is to instruct the browser to delete the cookie.

    Note

    for 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

scheme redirection

Use the directives below to redirect the user to a new URL scheme:

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

The Location header is built by contatenating 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, shouldn’t be cached by the client. This is the default value if no code is configured.
    303 like 302, but the browser must fetch the new location using a GET
    307 like 302, but the browser must re-use the same method the one from the original request
    308 like 301, but the browser must re-use the same method than the one from the original request
  • <option> (optional) : can be any or a combination of the statement below:

    • drop-query : Remove 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] : A Set-Cookie header is added to the redirection. The cookie is named NAME and can have an optional value 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. Purpose is to instruct the browser to delete the cookie.

    Note

    for 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

Redirection Examples

  1. Append ‘www.’ prefix in front of all URLs not having 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 request 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