------

HALoad

------

HAProxy's dummy HTTP

client for benchmarks

1. Background

-------------

HALoad is a lightweight, multi-threaded traffic generator designed to benchmark

HTTP infrastructures under heavy loads. Built directly onto HAProxy's highly

scalable core architecture, it shares its parent engine's efficient handling of

connections. This framework allows the tool to generate high-volume traffic

across all standard application layers, including HTTP/1, HTTP/2, and HTTP/3

(QUIC), over either cleartext or secured TLS connections.

The primary design goal is to provide a modernized alternative to legacy tools

like h1load, extending benchmarking capabilities to newer protocols. Notably,

HALoad introduces the concept of users (-u), a feature completely absent

from h1load. Here, a "user" strictly represents an independent, concurrent

HTTP client task. Under this architecture, each simulated client will

instantiate as many backend server connections as there are target URLs

specified on the command line.

HALoad does not require any configuration file. Instead, the configuration is

dynamically derived from basic command line inputs. This ensures immediate

usability for test operators while retaining the ability to test complex,

multi-protocol setups.

2. Compilation

--------------

The compilation process mirrors standard HAProxy builds, specifying "haload"

as the compilation target via the command line:

$ make -j $(nproc) TARGET=linux-glibc haload

To enable encrypted communication layers (TLS/SSL):

$ make TARGET=linux-glibc USE_OPENSSL=1 haload

For advanced HTTP/3 over QUIC load testing:

$ make -j $(nproc) TARGET=linux-glibc USE_OPENSSL=1 USE_QUIC=1 haload

Because HALoad shares the code of the main HAProxy binary, it natively

inherits all standard HAProxy compiler flags, optimizations, and build

targets.

3. Execution

------------

HALoad displays its usage when run without argument or wrong arguments:

Usage : haload [opts] [URL]

where <opts> may be any combination of:

-d <time> test duration in seconds (0)

-e stop upon first connection error

-ee on first error, reset counters and probe at 1 conn/req

per sec per URL, doubling the rate every second while

requests keep succeeding, until 100 per URL succeed;

then resume the load asked for on the command line

-h(0|1|2|2c|3) use h0 (hq-interop for QUIC), h1, h2, h2c or h3

(QUIC/TCP) protocols (*)

-(0|1|2|2c|3) same as above (*)

-fcgi use FastCGI protocol (*)

-get use GET method (default) (*)

-head use HEAD method instead of GET (*)

-post <size> use POST method, sending <size> bytes of body (*)

-hs show HTTP status codes distribution

-hsv show HTTP status codes distribution ((global + per HTTP version)

-l enable long output format; double for raw values

-m <streams> maximum concurrent streams (1)

-n <reqs> maximum total requests (-1)

-r <reqs> number of requests per connection (-1)

-s <time> soft start: time in sec to reach 100% load

-t <threads> number of threads (1)

-u <users> number of users (1)

-w <time> I/O timeout in milliseconds (10000)

-C dump the configuration and exit

-H "foo:bar" add this header name and value

-P report ttfb/ttlb percentiles at the end

-R <rate> limit to this many request attempts per second (0)

-T <time> think time in ms after a response (0) (*)

-v shows version

--defaults <str> add a string to default section

--global <str> add a string to global section

--server <opts> set server <opt> options as defined for "server"

haproxy keyword

--fcgi-app <str> add a string to the generated "fcgi-app haload"

section (docroot, index...). Note: "set-param" and

"pass-header" rules have no effect, since HALoad

does not use HAProxy streams to run them; use "-H"

to set FCGI params directly (e.g. -H ":fcgi-script_filename:...")

--traces enable the traces for all the protocols

SSL options:

--tls-ciphers <ciphers> for TLS1.2 and below (*)

--tls-ciphersuites <ciphers> for TLS1.3 and above (*)

--tls-curves <curves> (*)

URL format:

(http://|https://|quic://)<addr>:<port>/<path>

Note: Options marked with an asterisk (*) are positional and MUST be placed

BEFORE the URLs they are intended to affect.

At startup, HALoad dynamically generates an HAProxy configuration in memory.

Options like --global and --defaults allow raw configuration lines to be added

directly to the "global" and "defaults" sections, while --server appends

options to the backend server. These parameters support standard escaped

notation (e.g., '\n' or '\t') to insert multi-line statements in a single

argument en ligne de commande.

Examples:

# 30-second test using 4 threads simulating 10 distinct users

$ ./haload -t 4 -u 10 -d 30 http://127.0.0.1:8888/

# HTTP/3 test limiting concurrent streams to 3 per connection (-m3)

$ ./haload -m3 quic://127.0.0.1:8889/

# POST 500 bytes to /a, then GET /b, on the same server: each path keeps

# its own method and body size even though they share the same address

$ ./haload -post 500 http://127.0.0.1:8888/a -get http://127.0.0.1:8888/b -u 10 -d 30

# Dump the generated memory configuration and exit (-C)

$ ./haload https://127.0.0.1:4443 -C

global

tune.memory.hot-size 3145728

ssl-server-verify none

tune.h2.be.max-concurrent-streams 1

tune.quic.be.stream.max-concurrent 1

# Dump the configuration and exit (-C) to check -m3 effect

$ ./haload https://127.0.0.1:4443 -m3 -C

global

tune.memory.hot-size 3145728

ssl-server-verify none

tune.h2.be.max-concurrent-streams 3

tune.quic.be.stream.max-concurrent 3

# Add a custom directive into defaults, dump the configuration and exit (-C)

$ ./haload https://127.0.0.1:4443 --defaults "timeout connect 5s" -C

global

tune.memory.hot-size 3145728

ssl-server-verify none

tune.h2.be.max-concurrent-streams 1

tune.quic.be.stream.max-concurrent 1

defaults

timeout connect 5s

# FastCGI target, with a docroot for the generated "fcgi-app" section

$ ./haload --fcgi-app "docroot /var/www" -fcgi -u 10 -d 30 http://127.0.0.1:9000/index.php

4. Limitations

--------------

When using HTTP/3 (QUIC or QMUX) protocols with the maximum concurrent streams

option (-m) enabled, HAProxy's connection layer currently does not enforce or

respect the strict limit on the number of open connections usually dictated by

the concurrent users option (-u).

For example, when targeting a single URL, specifying "-u 10 -m 5" might lead

to opening more than 10 concurrent connections to the target server under

heavy load, instead of strictly capping the total connections to the requested

number of users.

FastCGI (-fcgi) requires a "docroot" set via --fcgi-app, and only supports a

single "fcgi-app" configuration for the whole run: HAProxy allows only one

per backend, and HALoad uses a single internal backend for every URL. Also,

"set-param" and "pass-header" rules in that section have no effect, since

they are only evaluated through an HAProxy stream filter and HALoad drives

its connections without ever creating a stream; use "-H :fcgi-<param>:<val>"

instead to override an FCGI parameter.