Configuration basics
Frontends
A frontend section defines the IP addresses and ports that clients can connect to. You may add as many frontend sections as needed to expose various websites or applications to the internet.
Frontend configuration example Jump to heading
The following configuration sample defines a frontend with the label myfrontend:
haproxyfrontend myfrontend# Set the proxy mode to http (layer 7) or tcp (layer 4)mode http# Receive HTTP traffic on all IP addresses assigned to the server at port 80bind :80# Choose the default pool of backend serversdefault_backend web_servers
haproxyfrontend myfrontend# Set the proxy mode to http (layer 7) or tcp (layer 4)mode http# Receive HTTP traffic on all IP addresses assigned to the server at port 80bind :80# Choose the default pool of backend serversdefault_backend web_servers
The label myfrontend is mostly for readability, but it does come into play when defining stick tables and categorizing traffic metrics. It should consist of only upper or lowercase letters, digits, dashes, underscores, dots, and colons.
In this example:
- The
modesets the proxy mode tohttp, which enables deeper inspection and routing of HTTP messages. - The
bindsets the IP address and ports that clients can connect to. - The
default_backendsets whichbackendto send requests to.
Listen on multiple IP addresses and ports Jump to heading
A frontend may listen on multiple addresses and/or ports. In the following configuration sample, myfrontend listens on two IP addresses at port 80:
haproxyfrontend myfrontendmode httpbind 192.168.1.5:80bind 192.168.1.6:80default_backend web_servers
haproxyfrontend myfrontendmode httpbind 192.168.1.5:80bind 192.168.1.6:80default_backend web_servers
In the following configuration sample, myfrontend listens on all IP addresses at port 80:
haproxyfrontend myfrontendmode httpbind :80default_backend web_servers
haproxyfrontend myfrontendmode httpbind :80default_backend web_servers
In the next sample, the frontend listens on both ports 80 and 443. The http-request redirect directive redirects all clients from HTTP (port 80) to HTTPS (port 443).
haproxyfrontend myfrontendmode httpbind :80bind :443 ssl crt /site.pem# Redirect HTTP to HTTPShttp-request redirect scheme https unless { ssl_fc }default_backend web_servers
haproxyfrontend myfrontendmode httpbind :80bind :443 ssl crt /site.pem# Redirect HTTP to HTTPShttp-request redirect scheme https unless { ssl_fc }default_backend web_servers
You can also specify a range of ports. In the following example, the load balancer listens on any port between 8080 and 8090, inclusive:
haproxyfrontend myfrontendbind 192.168.1.5:8080-8090default_backend web_servers
haproxyfrontend myfrontendbind 192.168.1.5:8080-8090default_backend web_servers
To listen on all IPv4 and IPv6 addresses, use [::] as the address and specify the v4v6 argument:
haproxyfrontend myfrontendbind [::]:80 v4v6default_backend web_servers
haproxyfrontend myfrontendbind [::]:80 v4v6default_backend web_servers
Use multiple frontends for different traffic types Jump to heading
In the next configuration sample, frontend foo.com has been configured to receive HTTP traffic. It specifies a mode of http in order to enable Layer 7 processing of HTTP messages.
Frontend db.foo.com has been configured to receive TCP traffic, in this case MySQL traffic at port 3306, and cannot make use of Layer 7 inspection and routing. Therefore, mode is set to tcp, which enables a simpler Layer 4 proxying.
haproxyfrontend foo.commode httpbind 192.168.1.5:80default_backend foo_serversfrontend db.foo.commode tcpbind 192.168.1.15:3306default_backend db_servers
haproxyfrontend foo.commode httpbind 192.168.1.5:80default_backend foo_serversfrontend db.foo.commode tcpbind 192.168.1.15:3306default_backend db_servers
Matching mode
A frontend section’s mode should match the mode of the backend section it sends traffic to. A mismatch will cause the configuration to not work.
Use one frontend for multiple traffic types Jump to heading
A frontend in mode tcp can still send some of its traffic to a mode http backend. With the switch-mode action on a tcp-request content directive, the load balancer inspects the first bytes from the client and, when they look like an HTTP request rather than a TLS handshake, upgrades the connection to HTTP mode. This lets one address and port accept both TLS that is passed through untouched and plaintext HTTP that you want to redirect.
In the next configuration example, myfrontend listens for both kinds of traffic on port 443. TLS connections are passed through to tls_servers unchanged, while plaintext HTTP requests are sent to redirect_backend, which redirects them to HTTPS.
haproxyfrontend myfrontend# Pass TLS through and accept plaintext HTTP on the same portmode tcpbind :443# Wait for the client's first bytes to identify the protocoltcp-request inspect-delay 5stcp-request content switch-mode http if HTTPuse_backend redirect_backend if HTTPdefault_backend tls_serversbackend redirect_backendmode http# Redirect HTTP to HTTPShttp-request redirect scheme httpsbackend tls_serversmode tcpserver web1 192.168.1.10:8443
haproxyfrontend myfrontend# Pass TLS through and accept plaintext HTTP on the same portmode tcpbind :443# Wait for the client's first bytes to identify the protocoltcp-request inspect-delay 5stcp-request content switch-mode http if HTTPuse_backend redirect_backend if HTTPdefault_backend tls_serversbackend redirect_backendmode http# Redirect HTTP to HTTPShttp-request redirect scheme httpsbackend tls_serversmode tcpserver web1 192.168.1.10:8443
In this example:
tcp-request inspect-delaygives the load balancer five seconds to collect data from the client before deciding.tcp-request content switch-mode http if HTTPswitches the connection to HTTP mode when the data is a plaintext HTTP request.HTTPis a predefined ACL that matches HTTP/1 and HTTP/2 requests. The upgrade happens immediately, so anytcp-request contentdirectives listed after this line aren’t evaluated for that connection.use_backend redirect_backend if HTTPsends the upgraded connection to themode https backend that returns the redirect. TLS connections don’t match the HTTP ACL, so they stay in mode tcp and go todefault_backend.- The redirect lives in its own backend because an upgraded connection must be routed to an HTTP backend; you can’t route an upgraded connection to a
mode tcpserver. Thehttp-request redirectline has nounless { ssl_fc }condition, unlike the redirect example above, because only plaintext requests are ever upgraded to HTTP. The redirect backend needs noserverlines, since every request it receives is redirected.
Once the connection is upgraded, HTTP directives can also be placed directly in the frontend. They are evaluated only for connections that were upgraded.
Use conditionals to forward traffic to different backends Jump to heading
You configure a frontend to send traffic to a backend by using the default_backend directive. However, you can choose a different backend with the use_backend directive followed by a conditional statement. These conditionals are called ACLs.
In the next configuration sample, frontend foo_and_bar listens for HTTP traffic and uses use_backend to send traffic to backend foo_servers when the host HTTP header matches foo.com. Otherwise, traffic goes to the backend named bar_servers.
haproxyfrontend foo_and_barmode httpbind :80use_backend foo_servers if { req.hdr(host) -i foo.com }default_backend bar_servers
haproxyfrontend foo_and_barmode httpbind :80use_backend foo_servers if { req.hdr(host) -i foo.com }default_backend bar_servers
The if statement checks whether the string returned by the req.hdr(host) fetch matches the string foo.com. The -i flag ignores case during string matching. There’s also an unless statement available, which checks whether a condition is false.
See also Jump to heading
- To specify the type of traffic being processed, see mode.
- To specify the IP address, port, and other attributes of incoming traffic, see bind.
- To specify the default backend for a frontend, see default_backend.
- To specify a backend for selected traffic, see use_backend.
- To redirect an HTTP request, see http-request redirect.
- To upgrade a TCP connection to HTTP when the client speaks HTTP, see switch-mode http.