Proxying essentials
HTTP rewrites
Use the http-request and http-response configuration directives to rewrite HTTP requests and responses. You can place them into a frontend or backend section.
Rewrite requests Jump to heading
Use the http-request configuration directives to rewrite HTTP requests sent from clients before the load balancer forwards them to a backend server. The server will see something different than what the client sent.
Change the HTTP request method Jump to heading
Use http-request set-method to change the method (for example, GET, POST, and PUT) on a request before relaying it to a backend server. In the example below, we change GET requests made to the /login URL path to be POST requests:
haproxy
haproxy
As another example, turn a GET into a POST if there is data in the body of the request by checking the Content-Length header:
haproxy
haproxy
Add a header Jump to heading
Use http-request add-header to add a new HTTP header to a request before relaying it to a backend server. In the example below, we add an X-Forwarded-For header containing the client IP address:
haproxy
haproxy
Going further, you can add a condition that first checks whether the X-Forwarded-For header exists and only add it if it doesn’t:
haproxy
haproxy
Set a header Jump to heading
Use http-request set-header to add a new header or overwrite it if it already exists. In the example below, we overwrite any existing X-Forwarded-For header with one containing the client’s IP address by referencing the src fetch method:
haproxy
haproxy
In the next example, we change the Host header when traffic is sent to the maintenance backend:
haproxy
haproxy
Delete a header Jump to heading
Use http-request del-header to remove an HTTP header from a request before relaying it to a backend server. In the example below, we delete any existing X-Forwarded-For header:
haproxy
haproxy
In the next example, we delete all Cookie headers before sending the request to the backend servers, which in this case is a pool of cache (Varnish) servers:
haproxy
haproxy
Replace a header by using a regular expression Jump to heading
Use http-request replace-header to capture the entire value of a header by using a regular expression and then replace that value with a new one. You can use this technique to add data to a header, as in the example below, where we add a new IP address to the X-Forwarded-For header before relaying it to a backend server:
haproxy
haproxy
We use a regular expression capture group to capture the whole, existing value. Then, we add the new IP address to the beginning. We get the IP address with the src fetch method. This updates the string below…
text
text
…to become this one (considering the client’s IP is 172.16.0.2):
text
text
Replace part of a header by using a regular expression Jump to heading
Use http-request replace-value to capture part of a header’s value by using a regular expression and then replace that part with a new one. In the example below, we capture the Host header’s value up to the first colon. We then strip off the colon and port, if any:
haproxy
haproxy
This updates the string below…
text
text
…into the following one:
text
text
In cases where a header has multiple values, they are expected to be separated by a comma. The load balancer looks for commas and applies the replacement to each value it finds.
Set the URL path Jump to heading
Use http-request set-path to change the requested URL path before relaying it to a backend server. Below, we change the URL path for JPG images so that it begins with /images/, but only if not already set:
haproxy
haproxy
This changes the requests below…
text
text
…into the following ones, respectively:
text
text
Set the query string Jump to heading
Use http-request set-query to change the requested URL’s query string. You can use the query fetch method to get the current query string value. Then, use the regsub function to replace the first occurrence of a given substring. In the example below, we replace the string %3D with = in the query string. The third parameter is set to g, which applies the replacement to all occurrences within the string:
haproxy
haproxy
You can also use the urlp fetch method to get one of the query string’s parameters. Below, we reorder the parameters in the query string to ensure that the user parameter comes before the group parameter:
haproxy
haproxy
This changes the request below…
text
text
…into the following one:
text
text
Set the URI Jump to heading
Use http-request set-uri to rewrite the entire URI string of an HTTP request, including its HTTP scheme, authority, path, and query string. In the example below, we create one URL for HTTP and another for HTTPS when forwarding traffic to a proxy server:
haproxy
haproxy
This changes the request below…
text
text
…into this one if the user connected over HTTP:
text
text
…or into this one if the user connected over HTTPS:
text
text
Rewrite responses Jump to heading
Use the http-response configuration directives to rewrite HTTP responses before they are sent back to clients. You can place them into a frontend or backend section. The client will see something different than what the server sees.
Add a header Jump to heading
Use http-response add-header to add a header to the response before relaying it back to the client. In the example below, we add an X-Via header containing the hostname of the current load balancer server processing the traffic:
haproxy
haproxy
Set a header Jump to heading
Use http-response set-header to change the current value of a header. In the example below, we give the Server header the value webserver, which can be useful for hiding the true name of the server:
haproxy
haproxy
Delete a header Jump to heading
Use http-response del-header to remove a header. Below, we delete several headers that are set by Varnish:
haproxy
haproxy
Replace a header by using a regular expression Jump to heading
Use http-response replace-header to change a header by using a regular expression. Below, we update the Cookie header named JSESSIONID, which was set by the server, with the Secure flag if the client-side connection is ciphered:
haproxy
haproxy
We use a regular expression capture group to capture the whole, existing value. Then, we add the new flag to the end, after a semi-colon. This assumes that the server sets up a single cookie. HTTP RFC specifies that the comma , character is a header field delimiter.
Replace part of a header by using a regular expression Jump to heading
Use http-response replace-value to capture part of a header’s value by using a regular expression and then replace that part with a new one. In the example below, we insert a Secure flag on each cookie set up by the server:
haproxy
haproxy
In cases where a header has multiple values, they are expected to be separated by a comma. The load balancer looks for commas and applies the replacement to each value it finds.
See also Jump to heading
For complete information on actions used in HTTP rewrites, see these topics in the HAProxy Configuration Manual:
- To add a header field to the request, see http-request add-header.
- To remove a header field to the request, see http-request del-header.
- To replace one or more matching header fields in the request, see http-request replace-header.
- To replace one or more matching header field values in the request, see http-request replace-value.
- To add a header field, replacing it if already present in the request, see http-request set-header.
- To rewrite a request method, see http-request set-method.
- To rewrite a request path, see http-request set-path.
- To rewrite a request query, see http-request set-query.
- To rewrite a request URI, see http-request set-uri.
- To add a header field to the response, see http-response add-header.
- To remove a header field to the response, see http-response del-header.
- To replace one or more matching header fields in the response, see http-response replace-header.
- To replace one or more matching header field values in the response, see http-response replace-value.
- To add a header field, replacing it if already present in the response, see http-response set-header.
Do you have any suggestions on how we can improve the content of this page?