Installing HAProxy From Source on Debian Stretch

The Debian Stretch repositories provide HAProxy version 1.7. You may want or need features in newer versions. Fortunately, installing HAProxy 1.9.7 from source is relatively straightforward.

The steps to do so are:

Install required packages
Download the HAProxy source code
Compile and install HAProxy
Create an unprivileged service account
Create a SystemD unit file
Create a SystemD environment file
Create a test configuration file
Test your installation
Configure HAProxy for your environment
Enable HAProxy to start automatically on boot

All commands in this guide should be executed as the root user.

Install Required Packages

In order to compile HAProxy, you will need to ensure a few packages from the standard repositories are installed. Run the following command as root to do so:

root@debian:~# apt install make gcc libsystemd-dev libssl-dev lua5.3 liblua5.3-dev  libpcre3-dev zlib1g-dev

Download and Extract Source Code

Use the commands below to download HAProxy 1.9.7.

root@debian:~# wget http://www.haproxy.org/download/1.9/src/haproxy-1.9.7.tar.gz

Extract the source archive file:

root@debian:~# tar xf haproxy-1.9.7.tar.gz

Install HAProxy 1.9.7

Change your working directory to the directory created by tar when you extracted the archive:

root@debian:~# cd haproxy-1.9.7

Compile HAProxy:

root@debian:~/haproxy-1.9.7# make USE_NS=1 \
USE_TFO=1 \
USE_OPENSSL=1 \
USE_ZLIB=1 \
USE_LUA=1 \
USE_PCRE=1 \
USE_SYSTEMD=1 \
USE_LIBCRYPT=1 \
USE_THREAD=1 \
TARGET=linux2628

If you wish to see a full list of make arguments along with short descriptions, run the command:

root@debian:~/haproxy-1.9.7# make help

Install HAProxy to /opt/haproxy-1.9.7:

root@debian:~/haproxy-1.9.7# make PREFIX=/opt/haproxy-1.9.7 install

Create Unprivileged HAProxy User and Group

Create an unprivileged user and group for HAProxy to run as. We will make them identical to the ones created by the HAProxy package in the standard apt repositories.

root@debian:~/haproxy-1.9.7# groupadd -g 113 haproxy
root@debian:~/haproxy-1.9.7# useradd -g 113 -u 109 -d /var/lib/haproxy -s /bin/false haproxy

If these commands have the output shown below, HAProxy was or is installed from the repositories. This will not affect source installation. It is safe to ignore this and move to the next step.

root@debian:~/haproxy-1.9.7# groupadd -g 113 haproxy
groupadd: group 'haproxy' already exists
root@debian:~/haproxy-1.9.7# useradd -g 113 -u 109 -d /var/lib/haproxy -s /bin/false haproxy
useradd: user 'haproxy' already exists
root@debian:~/haproxy-1.9.7#

Create SystemD Unit File

Use your favorite text editor to create the SystemD unit file that controls how HAProxy will be started, reloaded, stopped, and monitored. If you are on a minimal system, it is likely vi is all that is available. If you aren’t familiar with vi, I wrote a short tutorial that should teach you enough for basic tasks such as this.

Create the file /etc/systemd/system/haproxy-1.9.7.service with the following contents:

[Unit]
Description=HAProxy 1.9.7
After=syslog.target network.target

[Service]
Type=notify
EnvironmentFile=/etc/default/haproxy-1.9.7
ExecStart=/opt/haproxy-1.9.7/sbin/haproxy -f $CONFIG_FILE -p $PID_FILE $CLI_OPTIONS
ExecReload=/bin/kill -USR2 $MAINPID
ExecStop=/bin/kill -USR1 $MAINPID

[Install]
WantedBy=multi-user.target

The USR2 signal instructs HAProxy to reload its configuration without bringing it down. USR1 brings down HAProxy, allowing processes to finish what they were doing before exiting.

Create the SystemD Environment File

Create the file /etc/default/haproxy-1.9.7 with the following contents:

# Additional command line options to pass to HAProxy at startup
# The default is:  
#CLI_OPTIONS="-Ws"
CLI_OPTIONS="-Ws"

# Specify an alternate configuration file. The default is:
#CONFIG_FILE=/etc/haproxy/haproxy-1.9.7.conf
CONFIG_FILE=/etc/haproxy/haproxy-1.9.7.conf

# File used to track process IDs. The default is:
#PID_FILE=/var/run/haproxy-1.9.7.pid
PID_FILE=/var/run/haproxy-1.9.7.pid

The -Ws option runs HAProxy in a mode where it is able to notify SystemD when it is done starting.

Load the configuration with the following command:

root@debian:~/haproxy-1.9.7# systemctl daemon-reload

Create an HAProxy Configuration File

First, create the directory that will store HAProxy’s configuration files:

root@debian:~/haproxy-1.9.7# mkdir /etc/haproxy

Create the file /etc/haproxy/haproxy-1.9.7.conf with the following contents:

global
    daemon
    maxconn 256
    user        haproxy
    group       haproxy
    chroot      /var/lib/haproxy

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

frontend http
    bind *:8000
    default_backend servers

backend servers
    server server 127.0.0.1:81

Start and Test HAProxy

Start HAProxy:

root@debian:~/haproxy-1.9.7# systemctl start haproxy-1.9.7.service

Check to see if it is running:

root@debian:~/haproxy-1.9.7# ps -ef | grep haproxy | cut -c 1-100
root      6708     1  0 Apr25 ?        00:00:02 /opt/haproxy-1.9.7/sbin/haproxy -Ws -Ds -f /etc/haproxy/haproxy-1.9.7.conf -p /var/run/haproxy-1.9.6.pid
haproxy   6709  6708  0 Apr25 ?        00:00:01 /opt/haproxy-1.9.7/sbin/haproxy -Ws -Ds -f /etc/haproxy/haproxy-1.9.7.conf -p /var/run/haproxy-1.9.6.pid

Configure HAProxy

The details of configuring HAProxy beyond a simple test are beyond the scope of this guide. Consult the official documentation for help. If you are new to HAProxy, the starter guide will help get you started.

Configure HAProxy to Start at Boot

root@debian:~/haproxy-1.9.7# systemctl enable haproxy-1.9.7
Created symlink from /etc/systemd/system/multi-user.target.wants/haproxy-1.9.7.service to /etc/systemd/system/haproxy-1.9.7.service.