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:

haproxy
frontend 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 80
bind :80
# Choose the default pool of backend servers
default_backend web_servers
haproxy
frontend 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 80
bind :80
# Choose the default pool of backend servers
default_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 mode sets the proxy mode to http, which enables deeper inspection and routing of HTTP messages.
  • The bind sets the IP address and ports that clients can connect to.
  • The default_backend sets which backend to 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:

haproxy
frontend myfrontend
mode http
bind 192.168.1.5:80
bind 192.168.1.6:80
default_backend web_servers
haproxy
frontend myfrontend
mode http
bind 192.168.1.5:80
bind 192.168.1.6:80
default_backend web_servers

In the following configuration sample, myfrontend listens on all IP addresses at port 80:

haproxy
frontend myfrontend
mode http
bind :80
default_backend web_servers
haproxy
frontend myfrontend
mode http
bind :80
default_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).

haproxy
frontend myfrontend
mode http
bind :80
bind :443 ssl crt /site.pem
# Redirect HTTP to HTTPS
http-request redirect scheme https unless { ssl_fc }
default_backend web_servers
haproxy
frontend myfrontend
mode http
bind :80
bind :443 ssl crt /site.pem
# Redirect HTTP to HTTPS
http-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:

haproxy
frontend myfrontend
bind 192.168.1.5:8080-8090
default_backend web_servers
haproxy
frontend myfrontend
bind 192.168.1.5:8080-8090
default_backend web_servers

To listen on all IPv4 and IPv6 addresses, use [::] as the address and specify the v4v6 argument:

haproxy
frontend myfrontend
bind [::]:80 v4v6
default_backend web_servers
haproxy
frontend myfrontend
bind [::]:80 v4v6
default_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.

haproxy
frontend foo.com
mode http
bind 192.168.1.5:80
default_backend foo_servers
frontend db.foo.com
mode tcp
bind 192.168.1.15:3306
default_backend db_servers
haproxy
frontend foo.com
mode http
bind 192.168.1.5:80
default_backend foo_servers
frontend db.foo.com
mode tcp
bind 192.168.1.15:3306
default_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.

haproxy
frontend myfrontend
# Pass TLS through and accept plaintext HTTP on the same port
mode tcp
bind :443
# Wait for the client's first bytes to identify the protocol
tcp-request inspect-delay 5s
tcp-request content switch-mode http if HTTP
use_backend redirect_backend if HTTP
default_backend tls_servers
backend redirect_backend
mode http
# Redirect HTTP to HTTPS
http-request redirect scheme https
backend tls_servers
mode tcp
server web1 192.168.1.10:8443
haproxy
frontend myfrontend
# Pass TLS through and accept plaintext HTTP on the same port
mode tcp
bind :443
# Wait for the client's first bytes to identify the protocol
tcp-request inspect-delay 5s
tcp-request content switch-mode http if HTTP
use_backend redirect_backend if HTTP
default_backend tls_servers
backend redirect_backend
mode http
# Redirect HTTP to HTTPS
http-request redirect scheme https
backend tls_servers
mode tcp
server web1 192.168.1.10:8443

In this example:

  • tcp-request inspect-delay gives the load balancer five seconds to collect data from the client before deciding.
  • tcp-request content switch-mode http if HTTP switches the connection to HTTP mode when the data is a plaintext HTTP request. HTTP is a predefined ACL that matches HTTP/1 and HTTP/2 requests. The upgrade happens immediately, so any tcp-request content directives listed after this line aren’t evaluated for that connection.
  • use_backend redirect_backend if HTTP sends the upgraded connection to the mode https backend that returns the redirect. TLS connections don’t match the HTTP ACL, so they stay in mode tcp and go to default_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 tcp server. The http-request redirect line has no unless { ssl_fc } condition, unlike the redirect example above, because only plaintext requests are ever upgraded to HTTP. The redirect backend needs no server lines, 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.

haproxy
frontend foo_and_bar
mode http
bind :80
use_backend foo_servers if { req.hdr(host) -i foo.com }
default_backend bar_servers
haproxy
frontend foo_and_bar
mode http
bind :80
use_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.

Do you have any suggestions on how we can improve the content of this page? Please leave feedback!