Protocol support

HTTP

On this page

Although HAProxy can load balance HTTP requests in TCP mode, in which the connections are opaque and the HTTP messages aren’t inspected or altered, it can also operate in HTTP mode. In HTTP mode, the load balancer can inspect and modify the messages to perform protocol-specific actions. To enable HTTP mode, set the directive mode http in your frontend and backend section.

Below, we describe features related to distinct versions of the HTTP protocol.

HTTP/3 Jump to heading

HAProxy can send and receive HTTP/3 messages over the QUIC protocol.

While earlier HTTP implementations were transported over TCP, HTTP/3 uses QUIC, a UDP-based, connectionless protocol. To support QUIC, the load balancer must bundle a compatible SSL/TLS library. Ordinarily, the stock OpenSSL library on a Linux system will do, but in this case, we provide a specialized version of OpenSSL. For HAProxy ALOHA 15.5 / HAProxy Enterprise 2.8r1 and newer, bind lines that use the QUIC protocol will get a default ALPN value of h3 for HTTP/3. Versions prior to that must set the alpn argument to h3.

Install for HAProxy Enterprise 3.0r1 and newer Jump to heading

The QUIC protocol is supported by default on HAProxy Enterprise 3.0r1 and newer.

To enable HTTP/3 over QUIC:

  1. Uninstall any installed instance of HAProxy Enterprise prior to 3.0r1.

  2. Install HAProxy Enterprise 3.2r1, replacing <HAProxy Enterprise key> with your HAProxy Enterprise license key:

    nix
    wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
    sudo bash ./install_haproxy_enterprise.sh \
      --version 3.2r1 \
      --key <HAProxy Enterprise key>
    nix
    wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
    sudo bash ./install_haproxy_enterprise.sh \
      --version 3.2r1 \
      --key <HAProxy Enterprise key>

  3. Update your configuration file so that your frontend includes required directives:

    haproxy
    frontend example
      bind :80
      
      # Enable HTTPS
      bind :443  ssl crt ssl.pem
      
      # enables HTTP/3 over QUIC
      bind quic4@:443 ssl crt ssl.pem alpn h3
       
      # Redirects to HTTPS
      http-request redirect scheme https unless { ssl_fc }
      
      # 'Alt-Svc' header invites client to switch to the QUIC protocol
      # Max age (ma) is set to 15 minutes (900 seconds), but
      # can be increased once verified working as expected
      http-response set-header alt-svc "h3=\":443\";ma=900;"
       
      default_backend webservers
    haproxy
    frontend example
      bind :80
      
      # Enable HTTPS
      bind :443  ssl crt ssl.pem
      
      # enables HTTP/3 over QUIC
      bind quic4@:443 ssl crt ssl.pem alpn h3
       
      # Redirects to HTTPS
      http-request redirect scheme https unless { ssl_fc }
      
      # 'Alt-Svc' header invites client to switch to the QUIC protocol
      # Max age (ma) is set to 15 minutes (900 seconds), but
      # can be increased once verified working as expected
      http-response set-header alt-svc "h3=\":443\";ma=900;"
       
      default_backend webservers

  4. Enable and start the service:

    nix
    sudo systemctl enable hapee-3.2-lb
    sudo systemctl start hapee-3.2-lb
    nix
    sudo systemctl enable hapee-3.2-lb
    sudo systemctl start hapee-3.2-lb

To confirm what specialized version of OpenSSL is installed on your HAProxy Enterprise instance, run:

nix
sudo /opt/hapee-3.2/sbin/hapee-lb -vv
nix
sudo /opt/hapee-3.2/sbin/hapee-lb -vv
output
text
 ...
 Built with OpenSSL version : OpenSSL 1.1.1za+quic  3 Sep 2024
 Running on OpenSSL version : OpenSSL 1.1.1za+quic  3 Sep 2024
 OpenSSL library supports TLS extensions : yes
 OpenSSL library supports SNI : yes
 OpenSSL library supports : SSLv3 TLSv1.0 TLSv1.1 TLSv1.2 TLSv1.3
 ...
output
text
 ...
 Built with OpenSSL version : OpenSSL 1.1.1za+quic  3 Sep 2024
 Running on OpenSSL version : OpenSSL 1.1.1za+quic  3 Sep 2024
 OpenSSL library supports TLS extensions : yes
 OpenSSL library supports SNI : yes
 OpenSSL library supports : SSLv3 TLSv1.0 TLSv1.1 TLSv1.2 TLSv1.3
 ...

Install for HAProxy Enterprise 2.7r1 to 2.9r1 Jump to heading

To enable HTTP/3 over QUIC, you must uninstall any prior installed instance of HAProxy Enterprise and install the QUIC-compatible package.

This package is available for the following operating system versions:

  • AlmaLinux 9
  • Debian 11
  • Red Hat Enterprise Linux 9
  • Rocky Linux 9
  • Ubuntu 22.04

To install HAProxy Enterprise with QUIC support:

  1. Uninstall any prior installed instance of HAProxy Enterprise.

  2. Install the QUIC-compatible HAProxy Enterprise package, replacing <HAProxy Enterprise key> with your HAProxy Enterprise license key:

    nix
    wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
    sudo bash ./install_haproxy_enterprise.sh \
      --version 2.9r1 \
      --key <HAProxy Enterprise key> \
      --quictls
    nix
    wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
    sudo bash ./install_haproxy_enterprise.sh \
      --version 2.9r1 \
      --key <HAProxy Enterprise key> \
      --quictls

  3. Update your configuration file so that your frontend includes required directives:

    haproxy
    frontend example
      bind :80
      
      # Enable HTTPS
      bind :443  ssl crt ssl.pem
      
      # enables HTTP/3 over QUIC
      bind quic4@:443 ssl crt ssl.pem alpn h3
       
      # Redirects to HTTPS
      http-request redirect scheme https unless { ssl_fc }
      
      # 'Alt-Svc' header invites client to switch to the QUIC protocol
      # Max age (ma) is set to 15 minutes (900 seconds), but
      # can be increased once verified working as expected
      http-response set-header alt-svc "h3=\":443\";ma=900;"
       
      default_backend webservers
    haproxy
    frontend example
      bind :80
      
      # Enable HTTPS
      bind :443  ssl crt ssl.pem
      
      # enables HTTP/3 over QUIC
      bind quic4@:443 ssl crt ssl.pem alpn h3
       
      # Redirects to HTTPS
      http-request redirect scheme https unless { ssl_fc }
      
      # 'Alt-Svc' header invites client to switch to the QUIC protocol
      # Max age (ma) is set to 15 minutes (900 seconds), but
      # can be increased once verified working as expected
      http-response set-header alt-svc "h3=\":443\";ma=900;"
       
      default_backend webservers

  4. Enable and start the service:

    nix
    sudo systemctl enable hapee-3.2-lb
    sudo systemctl start hapee-3.2-lb
    nix
    sudo systemctl enable hapee-3.2-lb
    sudo systemctl start hapee-3.2-lb

Troubleshoot HTTP/3 over QUIC Jump to heading

Browsers can be strict when it comes to QUIC and when they encounter an issue will silently fall back to using HTTP/2. For instance, they often don’t allow self-signed TLS certificates, and getting verbose error logs from a browser can be difficult. Instead, try running QUIC-compatible curl to test QUIC connections so that you can see the verbose output of the request and response. You can run it as a Docker container.

Here, we run curl as a container to test HTTP/3 over QUIC for example.com:

nix
docker run -ti --rm alpine/curl-http3 curl -v --http3 -sI https://example.com
nix
docker run -ti --rm alpine/curl-http3 curl -v --http3 -sI https://example.com

HTTP/2 Jump to heading

You can load balance HTTP/2 over:

  • encrypted HTTPS when OpenSSL 1.0.2 or newer is available on the server
  • unencrypted HTTP (known as h2c)

Most browsers support HTTP/2 over HTTPS only, but you may find it useful to enable h2c between backend services (for example, gRPC services).

HTTP/2 over HTTPS to the client Jump to heading

Available since

  • HAProxy 1.8
  • HAProxy Enterprise 1.8r1
  • HAProxy ALOHA 10.0

HTTP/2 is enabled by default between clients and load balancer in HAProxy ALOHA 15.5 / HAProxy Enterprise 2.8r1 and up. You don’t need to specify the alpn extension, because it has a default value of h2,http/1.1 for HTTPS bind lines. Note that ALPN works only for HTTPS bind lines, so HTTP/2 requires HTTPS. Clients that lack support for HTTP/2 will be automatically reverted to HTTP/1.1. The load balancer server must have OpenSSL 1.0.2 or newer.

haproxy
frontend www
  mode http
  bind :443 ssl crt /path/to/cert.crt
  default_backend servers
haproxy
frontend www
  mode http
  bind :443 ssl crt /path/to/cert.crt
  default_backend servers

For HAProxy ALOHA 15.0 / HAProxy Enterprise 2.7r1 and older, you will need to specify both the extension and protocols:

haproxy
frontend www
  mode http
  bind :443 ssl crt /path/to/cert.crt alpn h2,http/1.1
  default_backend servers
haproxy
frontend www
  mode http
  bind :443 ssl crt /path/to/cert.crt alpn h2,http/1.1
  default_backend servers

HTTP/2 over HTTPS to the server Jump to heading

Available since

  • HAProxy 1.9
  • HAProxy Enterprise 1.9r1
  • HAProxy ALOHA 11.0

To enable HTTP/2 between the load balancer and your backend servers, add the alpn argument to your server or default-server lines:

haproxy
backend servers
   mode http
   server s1 192.168.0.10:443 ssl alpn h2,http/1.1
   server s2 192.168.0.11:443 ssl alpn h2,http/1.1
haproxy
backend servers
   mode http
   server s1 192.168.0.10:443 ssl alpn h2,http/1.1
   server s2 192.168.0.11:443 ssl alpn h2,http/1.1

This announces to the servers that the load balancer, acting as a client, supports HTTP/2. The servers must also support it.

HTTP/2 over HTTP (h2c) to the client Jump to heading

Available since

  • HAProxy 1.9
  • HAProxy Enterprise 1.9r1
  • HAProxy ALOHA 11.0

To enable HTTP/2 between clients and the load balancer without using TLS, use the proto argument to announce support for it. This method doesn’t allow you to support multiple versions of HTTP simultaneously.

haproxy
frontend www
  mode http
  bind :80 proto h2
  default_backend servers
haproxy
frontend www
  mode http
  bind :80 proto h2
  default_backend servers

HTTP/2 over HTTP (h2c) to the server Jump to heading

Available since

  • HAProxy 1.9
  • HAProxy Enterprise 1.9r1
  • HAProxy ALOHA 11.0

To enable HTTP/2 between the load balancer and your backend servers, add the proto argument to your server or default-server lines:

haproxy
backend servers
  mode http
  server s1 192.168.0.10:80 proto h2
  server s2 192.168.0.11:80 proto h2
haproxy
backend servers
  mode http
  server s1 192.168.0.10:80 proto h2
  server s2 192.168.0.11:80 proto h2

Adjust the HTTP/2 initial window size Jump to heading

When you expect large file uploads over a network with moderately high latency, you may experience slow upload speeds. You can increase the HTTP/2 Flow Control window size to allow the load balancer to buffer more data. Set tune.h2.initial-window-size in the global section to the number of bytes the client can upload before waiting for an acknowledgement from the load balancer. For example, you could set a high value like 1048576.

Enable an idleness ping Jump to heading

Available since

  • HAProxy 3.2
  • HAProxy Enterprise 3.2r1

To more efficiently close any idle HTTP/2 connections, you can add an idle connection check.

  • For HTTP/2 to the client, add idle-ping to the bind line. It sets an interval, such as 10 seconds in this example:

    haproxy
    frontend www
      mode http
      bind :443 ssl crt /path/to/cert.crt idle-ping 10s
      default_backend servers
    haproxy
    frontend www
      mode http
      bind :443 ssl crt /path/to/cert.crt idle-ping 10s
      default_backend servers

  • For HTTP/2 to the server, add idle-ping to the server line. It sets an interval, such as 10 seconds in this example:

    haproxy
    backend servers
      mode http
      server s1 192.168.0.10:443 ssl alpn h2,http/1.1 idle-ping 10s
      server s2 192.168.0.11:443 ssl alpn h2,http/1.1 idle-ping 10s
    haproxy
    backend servers
      mode http
      server s1 192.168.0.10:443 ssl alpn h2,http/1.1 idle-ping 10s
      server s2 192.168.0.11:443 ssl alpn h2,http/1.1 idle-ping 10s

See also Jump to heading

  • To enable the TLS ALPN extension and a protocol list for the bind directive, see bind - alpn.
  • To force a protocol for the bind directive, see bind - proto.
  • To enable the TLS ALPN extension and a protocol list for the server directive, see server - alpn.
  • To force a protocol for the server directive, see server - proto.
  • To set the default value for the HTTP/2 initial window size, see tune.h2.initial-window-size.

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

Previous page gRPC Next page Passive FTP
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences