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 thenodes
backend.backend nodes
: Defines the backend, which consists of three servers (web01
,web02
,web03
). Thebalance 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
, andhttp-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
- HAProxy Documentation: The official documentation is the most comprehensive resource for all HAProxy configuration options.
- Servers for Hackers - HAProxy: A practical guide to using HAProxy for various use cases.
- Percona Blog - HAProxy Logging on CentOS: A detailed guide to configuring HAProxy logging with rsyslog.