Building HAProxy - linux-on-ibm-z/docs GitHub Wiki

Building HAProxy

Below versions of HAProxy are available in respective distributions at the time of creation of these build instructions:

  • RHEL (8.8, 8.10) have 1.8.27
  • RHEL (9.2, 9.4, 9.5) have 2.4.22
  • SLES 15 SP6 has 2.8.11
  • Ubuntu 22.04 has 2.4.24
  • Ubuntu 24.04 has 2.8.5
  • Ubuntu 24.10 has 2.9.10

The instructions provided below specify the steps to build HAProxy version 3.1.7 on Linux on IBM Z for following distributions:

  • RHEL (8.8, 8.10, 9.2, 9.4, 9.5)
  • SLES 15 SP6
  • Ubuntu (22.04, 24.04, 24.10)

General Notes:

  • When following the steps below please use a standard permission user unless otherwise specified.
  • A directory /<source_root>/ will be referred to in these instructions, this is a temporary writable directory anywhere you'd like to place it.

1. Build and Install HAProxy

1.1. Build using script

If you want to build haproxy using manual steps, go to STEP 1.2

Use the following commands to build HAProxy using the build script. Please make sure you have wget installed.

wget -q https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/HAProxy/3.1.7/build_haproxy.sh

# Build HAProxy
bash build_haproxy.sh [Provide -t option for executing build with tests]

If the build completes successfully, go to STEP 2. In case of error, check logs for more details or go to STEP 1.2 to follow manual build steps.

1.2. Install the build dependencies

export SOURCE_ROOT=/<source_root>/

  • RHEL (8.8, 8.10)

    sudo yum install -y gcc gcc-c++ gzip make tar wget xz zlib-devel pcre2 pcre2-devel systemd-devel openssl-devel diffutils

  • RHEL (9.2, 9.4, 9.5)

    sudo yum install -y gcc gcc-c++ gzip make tar wget xz zlib-devel lua-devel pcre2 pcre2-devel systemd-devel compat-openssl11 openssl-devel diffutils perl

  • SLES 15 SP6

    sudo zypper install -y awk gcc gcc-c++ gzip make tar wget xz zlib-devel libopenssl-devel lua54-devel pcre2-devel systemd-devel

  • Ubuntu (22.04, 24.04, 24.10)

    sudo apt-get update
sudo apt-get install -y gcc g++ gzip make tar wget curl xz-utils zlib1g-dev liblua5.4-dev libpcre2-dev libsystemd-dev libssl-dev

1.3. Install additional dependencies

  • Lua 5.4.0 (RHEL 8.x)

    cd $SOURCE_ROOT
wget --no-check-certificate https://www.lua.org/ftp/lua-5.4.0.tar.gz
tar zxf lua-5.4.0.tar.gz
cd lua-5.4.0
sed -i '61 i \\t$(CC) -shared -ldl -Wl,-soname,liblua$R.so -o liblua$R.so $? -lm $(MYLDFLAGS)\n' src/Makefile
make clean
make linux "MYCFLAGS=-fPIC" "R=5.4"
sudo make install
sudo cp /usr/local/bin/lua* /usr/bin/
sudo cp src/liblua5.4.so /usr/lib64/ 
sudo rm -f /usr/lib64/liblua.so   
sudo ln -s /usr/lib64/liblua5.4.so /usr/lib64/liblua.so  

lua -v

  • OpenSSL 1.1.1w (RHEL 9.x)

    cd $SOURCE_ROOT
wget --no-check-certificate https://www.openssl.org/source/openssl-1.1.1w.tar.gz
tar -xzf openssl-1.1.1w.tar.gz
cd openssl-1.1.1w
./config --prefix=/usr --openssldir=/usr
make
sudo make install

1.4. Download HAProxy source package

cd $SOURCE_ROOT
wget https://www.haproxy.org/download/3.1/src/haproxy-3.1.7.tar.gz
tar xzvf haproxy-3.1.7.tar.gz
cd haproxy-3.1.7

1.5. Build and Install HAProxy

make all TARGET=linux-glibc USE_ZLIB=1 USE_PCRE2=1 USE_PCRE2_JIT=1 USE_LUA=1 USE_OPENSSL=1 USE_SYSTEMD=1
sudo make install
sudo ln -sf /usr/local/sbin/haproxy /usr/sbin/

Note: For more advanced build options, please visit the installation documention for HAProxy.

haproxy -v

You will get output similar to this:

HAProxy version 3.1.7-d929ca2 2025/03/20 - https://haproxy.org/
Known bugs: http://www.haproxy.org/bugs/bugs-3.1.7.html

Note: If you encounter bash: haproxy: command not found error, please make sure /usr/local/sbin is in the system's $PATH.

2. Testing - Regression Tests (optional)

2.1. Install distro packages needed for running the tests.

  • RHEL (8.8, 8.10)

    sudo yum install -y socat curl python2 python38

  • RHEL (9.2, 9.4, 9.5)

    sudo yum install -y --allowerasing socat curl python3

  • SLES 15 SP6

    sudo zypper install -y ninja socat python curl

  • Ubuntu 22.04

    sudo apt-get update
sudo apt-get install -y ninja-build socat curl python2 python3

  • Ubuntu (24.04, 24.10)

    sudo apt-get update
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y tzdata ninja-build socat curl python3

2.2. Run regression tests.

cd $SOURCE_ROOT
cd haproxy-3.1.7

scripts/build-vtest.sh

make -C addons/wurfl/dummy

make -j$(nproc) all \
      ERR=1 \
      TARGET=linux-glibc \
      CC=gcc \
      DEBUG="-DDEBUG_STRICT -DDEBUG_MEMORY_POOLS -DDEBUG_POOL_INTEGRITY" \
      USE_ZLIB=1 USE_PCRE2=1 USE_PCRE2_JIT=1 USE_LUA=1 USE_OPENSSL=1 USE_SYSTEMD=1 USE_WURFL=1 WURFL_INC=addons/wurfl/dummy WURFL_LIB=addons/wurfl/dummy USE_DEVICEATLAS=1 DEVICEATLAS_SRC=addons/deviceatlas/dummy USE_PROMEX=1 USE_51DEGREES=1 51DEGREES_SRC=addons/51degrees/dummy/pattern \
      ADDLIB="-Wl,-rpath,/usr/local/lib/ -Wl,-rpath,$HOME/opt/lib/"
      
sudo make install

ulimit -n 65536    
make reg-tests VTEST_PROGRAM=../vtest/vtest REGTESTS_TYPES=default,bug,devel

3. Testing - Simple Round-Robin Load Balancing Test (optional)

Adapted from Servers for Hackers.

3.1. Prepare a simple set of servers serving the same webpage

For example, this simple server.js script will serve a small text page, including the serving address and port, on the machine's ports 9000-9002:

var http = require('http');

function serve(ip, port){
    http.createServer(function (req, res){
        res.writeHead(200, {'Content-Type': 'text/plain'});
        res.write(JSON.stringify(req.headers));
        res.end("\nThere's no place like "+ip+":"+port+"\n");
    }).listen(port, ip);
    console.log('Server running at http://'+ip+':'+port+'/');
}

// Create three servers for
// the load balancer, listening on any
// network on the following three ports
serve('0.0.0.0', 9000);
serve('0.0.0.0', 9001);
serve('0.0.0.0', 9002);

Note: You can download the latest Node.js binaries from here. For RHEL 8.x, RHEL 9.x, SLES and Ubuntu, you may also install Node.js in their own respective repo.

3.2. Create a config file haproxy.cfg to serve as the configuration file for this test

This is a simple round-robin configuration using three servers:

global
    daemon
    maxconn 256

defaults
    mode http
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms

frontend http-in
    bind *:80
    default_backend nodes

backend nodes
    mode http
    balance roundrobin
    option forwardfor
    http-request set-header X-Forwarded-Port %[dst_port]
    option httpchk HEAD / HTTP/1.1
    http-check send meth HEAD ver HTTP/1.1 hdr Host localhost
    server s1 127.0.0.1:9000 maxconn 32
    server s2 127.0.0.1:9001 maxconn 32
    server s3 127.0.0.1:9002 maxconn 32

listen admin
    bind *:8080
    stats enable

Note: This assumes that server.js from Step 3.1 is being run on the same machine, serving three almost-identical webpages on ports 9000-9002. If this is not the case, replace the server declarations for s1-s3 accordingly.

3.3. Run HAProxy and the Node server

haproxy -f haproxy.cfg

Note: This will normally need to be done as root, or HAProxy will not have authority to access one or more ports, such as 80 and 8080.

node server.js

3.4. Navigate to the URL address of the server running HAProxy

The browser displays the webpage from the list of servers in haproxy.cfg. If the browser is refreshed, it should cycle through the provided servers server.js in a round-robin fashion.

References: