HAProxy is a robust, high-performance TCP/HTTP load balancer, perfectly suited for ensuring high availability and efficient traffic distribution across your servers. This guide provides a comprehensive walkthrough of installing and configuring HAProxy on CentOS. We’ll cover everything from initial installation to advanced logging configuration.

Installation on CentOS

This section details the steps required to install HAProxy from source on CentOS. While package managers often offer HAProxy, installing from source allows for greater control over the version and compilation options.

Prerequisites

Ensure you have the necessary development tools and libraries installed:

sudo yum install make gcc wget

make and gcc are essential for compiling the source code. wget is used to download the HAProxy source archive.

Downloading and Extracting the Source

Download the desired HAProxy version (in this example, 1.5.11) from the official HAProxy website or a trusted mirror. It is recommended to check for the latest stable release.

wget http://www.haproxy.org/download/1.5/src/haproxy-1.5.11.tar.gz
tar -zxvf haproxy-1.5.11.tar.gz -C /opt
cd /opt/haproxy-1.5.11

This downloads the tarball, extracts it to the /opt directory, and then navigates into the extracted directory.

Compiling and Installing HAProxy

Compile the HAProxy source code with specific target and CPU architecture flags. The TARGET and CPU options are crucial for optimal performance. Adjust TARGET according to your kernel version (use uname -r to find out). For most modern systems, linux26 and x86_64 are appropriate.

sudo make TARGET=linux26 CPU=x86_64
sudo make install

The make install command copies the compiled binary to /usr/local/sbin.

Creating an Init Script

To manage HAProxy as a service, create an init script. This allows you to start, stop, and restart HAProxy using the service command.

sudo ln -sf /usr/local/sbin/haproxy /usr/sbin/haproxy
sudo cp /opt/haproxy-1.5.11/examples/haproxy.init /etc/init.d/haproxy
sudo chmod 755 /etc/init.d/haproxy

The first command creates a symbolic link to make HAProxy accessible in the system’s PATH. The second command copies the example init script from the source directory to /etc/init.d. Finally, the script is made executable.

Configuring HAProxy

The HAProxy configuration file defines how it handles incoming traffic, load balances requests, and monitors the health of backend servers.

sudo mkdir /etc/haproxy
sudo cp /opt/haproxy-1.5.11/examples/examples.cfg /etc/haproxy/haproxy.cfg
sudo mkdir /var/lib/haproxy
sudo touch /var/lib/haproxy/stats
sudo useradd haproxy

These commands create the necessary directory for the configuration file, copy the example configuration, create a directory for runtime data, create a stats file, and create a dedicated user for HAProxy.

Starting and Enabling HAProxy

Finally, start the HAProxy service and configure it to start automatically at boot time.

sudo service haproxy check
sudo service haproxy start
sudo chkconfig haproxy on

The service haproxy check command verifies the configuration file for syntax errors before starting the service. chkconfig haproxy on ensures that HAProxy starts automatically on system boot.

Configuration Sample: haproxy.cfg

Here’s a sample haproxy.cfg file demonstrating a basic HTTP load balancing setup:

global
    log /dev/log    local0
    log /dev/log    local1 notice
    log 127.0.0.1   local2
    # chroot /var/lib/haproxy
    # stats socket /run/haproxy/admin.sock mode 660 level admin
    stats timeout 30s
    user haproxy
    group haproxy
    daemon

    # Default SSL material locations
    # ca-base /etc/ssl/certs
    # crt-base /etc/ssl/private

    # Default ciphers to use on SSL-enabled listening sockets.
    # For more information, see ciphers(1SSL).
    # ssl-default-bind-ciphers
    #         kEECDH+aRSA+AES:kRSA+AES:+AES256:RC4-SHA:!kEDH:!LOW:!EXP:!MD5:!aNULL:!eNULL

defaults
    log     global
    mode    http
    option  httplog
    option  dontlognull
    timeout connect 5000
    timeout client  50000
    timeout server  50000
    # errorfile 400 /etc/haproxy/errors/400.http
    # errorfile 403 /etc/haproxy/errors/403.http
    # errorfile 408 /etc/haproxy/errors/408.http
    # errorfile 500 /etc/haproxy/errors/500.http
    # errorfile 502 /etc/haproxy/errors/502.http
    # errorfile 503 /etc/haproxy/errors/503.http
    # errorfile 504 /etc/haproxy/errors/504.http

frontend localnodes
    bind *:9002
    mode http
    default_backend nodes

backend nodes
    mode http
    balance roundrobin
    option forwardfor
    http-request set-header X-Forwarded-Port %[dst_port]
    http-request add-header X-Forwarded-Proto https if { ssl_fc }
    option httpchk HEAD / HTTP/1.1\r\nHost:localhost
    server web01 127.0.0.1:9090 check
    server web02 127.0.0.1:9091 check
    server web03 127.0.0.1:9092 check

listen stats *:9001
    stats enable
    stats uri /
    stats hide-version
    stats auth someuser:password

Explanation:

  • global: Defines global settings such as logging, user, and group.
  • defaults: Sets default options for the frontend and backend sections.
  • frontend localnodes: Defines the frontend, which listens on port 9002 and directs traffic to the nodes backend.
  • backend nodes: Defines the backend, which consists of three servers (web01, web02, web03). The balance roundrobin directive specifies that HAProxy should distribute traffic to these servers in a round-robin fashion.
  • listen stats: Configures a statistics page accessible on port 9001, secured with basic authentication.

Important Considerations:

  • Security: Change the default username and password (someuser:password) for the stats page. Consider using a more secure authentication method.
  • Health Checks: The option httpchk directive enables health checks. HAProxy will periodically send HTTP HEAD requests to the specified path (/) on each backend server. If a server doesn’t respond with a 200 OK status, it will be temporarily removed from the load balancing rotation.
  • Forwarding Headers: The option forwardfor, http-request set-header, and http-request add-header directives are used to forward client information (IP address, port, and protocol) to the backend servers. This is crucial for applications that need to know the original client’s information.
  • SSL/TLS: The commented-out SSL/TLS options in the global section demonstrate how to configure HAProxy to handle secure connections. You will need to uncomment these lines and configure the appropriate certificates and ciphers.

Configuring Logging

Proper logging is crucial for monitoring HAProxy’s performance and troubleshooting issues.

Configure rsyslog to receive HAProxy logs:

Edit /etc/rsyslog.conf and uncomment or add the following lines to enable UDP reception:

$ModLoad imudp
$UDPServerRun 514

# Optionally, limit to 127.0.0.1
# $UDPServerAddress 127.0.0.1

Create a dedicated HAProxy log configuration file:

Create /etc/rsyslog.d/haproxy.conf with the following content:

local2.*    /var/log/haproxy.log

This directs all logs from facility local2 to the /var/log/haproxy.log file.

(Optional) Separate log files based on severity:

For more granular logging, you can create separate files based on the log level:

local2.=info     /var/log/haproxy/haproxy-info.log
local2.notice    /var/log/haproxy/haproxy-allbutinfo.log

Restart rsyslog:

sudo service rsyslog restart

Verify that the log files are created and that HAProxy is writing to them.

ls -l /var/log/haproxy

More Details