Install HAProxy Load Balancer on FreeBSD

HAProxy load balancer

Install, configure, and maintain the high-availability HAProxy load balancer on FreeBSD. A step-by-step article shows how to configure the HAProxy front-end to connect to an HTTP Lighttpd backend web server.

Topics covered:

1.1Install HAProxy
- 1.1.1Locate HAProxy
- 1.1.2Auto-start HAProxy
- 1.1.3HAProxy SSL
1.2HAProxy configuration
- 1.2.1Global config
- 1.2.2Frontend ACL
- 1.2.3Backend server
- 1.2.4Start HAProxy
1.3HAProxy maintenance
- 1.3.1Maintenance redirects
1.4Troubleshoot HAProxy
- 1.4.1Check HAProxy config
- 1.4.2HAProxy process
- 1.4.3HAProxy port
- 1.4.4HAProxy unresponsive

Buy this service

The service includes the installation and setup of a HAProxy load balancer on a single FreeBSD server. The customer must provide remote SSH access to the FreeBSD VPS or cloud server.

Product name:

Install HAProxy on FreeBSD

Product ID:

GWINC-SE-D2C6I4

Price*:

US $69.95 — Buy Now

*GST extra, please add 18% GST to the above price. GST is not applicable for orders outside India. International payments are accepted only through PayPal.

Affiliate links

Setting up a custom HAProxy load balancer requires a VPS or a cloud server with root access. Use our affiliate links to purchase a VPS or cloud server from third-party vendors. The affiliate commissions we earn facilitate, Free website access for everyone.

The affiliate links are listed in alphabetical order without any favor. Users are encouraged to refer to the Global Webdynamics LLP Terms of Service governing the Third-party vendors.

1.1Install HAProxy

Install HAProxy using the FreeBSD package manager. For custom installation configurations, install the HAProxy load balancer from the source. The documentation covers the HAProxy installation from the FreeBSD package manager only.

Terminal ~ 1.1-1

$ sudo pkg install haproxy

1.1.1Locate HAProxy

Find where HAProxy binaries, configurations, and documentation files are installed system-wide.

Terminal ~ 1.1-2

$ which haproxy
/usr/local/sbin/haproxy

$ sudo find /usr/local -name "haproxy*"
/usr/local/sbin/haproxy
/usr/local/share/licenses/haproxy-2.7.6
/usr/local/share/doc/haproxy
/usr/local/share/doc/haproxy/haproxy.1
/usr/local/share/examples/haproxy
/usr/local/share/examples/haproxy/haproxy.init
/usr/local/etc/ssl/haproxy
/usr/local/etc/rc.d/haproxy
/usr/local/etc/haproxy.conf
/usr/local/man/man1/haproxy.1.gz
/usr/local/haproxy

1.1.2Auto-start HAProxy

To auto-start HAProxy on system boot, add the following line to the end of the system run-commands configuration file /etc/rc.conf.

Terminal ~ 1.1-3

$ sudo nano -w -c /etc/rc.conf
...
haproxy_enable="YES"

1.1.3HAProxy SSL

By default, to handle all the incoming HTTP requests, generate a generic SSL/TLS certificate for HAProxy. The SSL/TLS certificate file www.pem contains the private and public keys. The www.pem certificate is for development use only. On the production HAProxy server, install a browser-recognized SSL/TLS certificate.

Terminal ~ 1.1-4

$ sudo mkdir -p /usr/local/etc/ssl/haproxy
$ cd /usr/local/etc/ssl/haproxy
$ sudo openssl req -x509 -nodes -days 7300 -newkey rsa:2048 -keyout www.pem -out www.pem

# Set permissions
$ sudo chmod 400 www.pem
$ sudo chown -R www:www /usr/local/etc/ssl/haproxy

1.1.3-1Install SSL

To install SSL/TLS certificate on HAProxy, add the www.pem SSL/TLS certificate file path to the HAProxy certificate list ( crt-list.txt ) file.

Terminal ~ 1.1-5

$ sudo nano -w -c /usr/local/etc/ssl/haproxy/crt-list.txt
/usr/local/etc/ssl/haproxy/www.pem

1.2HAProxy configuration

The basic HAProxy configuration file consists of the following configuration sections: Global, Frontend ACL, and Backend server.

Terminal ~ 1.2-1

$ sudo nano -w -c /usr/local/etc/haproxy.conf
## GLOBAL
global
    maxconn 10000
    log 127.0.0.1 local0
    user www
    group www
    daemon

defaults
    mode http
    log global
    option httplog
    option dontlognull
    option forwardfor
    timeout connect 5s
    timeout client 30s
    timeout server 30s

## FRONTEND ACL
frontend lb-http
    bind *:80

    ## FORCE REDIRECT TO HTTPS
    redirect scheme https code 301 if !{ ssl_fc }

frontend lb-https
    bind *:443 ssl crt-list /usr/local/etc/ssl/haproxy/crt-list.txt

    ## WEB DOMAIN
    ## example.com
    acl example-com hdr(host) -i example.com
    use_backend example-com-web-server if example-com

    ## example.net
    acl example-net hdr(host) -i example.net
    use_backend example-net-web-server if example-net

## BACKEND SERVER
## example.com
backend example-com-web-server
    balance roundrobin
    server s1 web1.example.com:8001
    server s2 web2.example.com:8001

## example.net
backend example-net-web-server
    balance roundrobin
    server s1 web1.example.net:8001
    server s2 web2.example.net:8001

1.2.1Global config

The global configuration section consists of global and defaults HAProxy configurations. The settings of maxconn and timeout attributes can be tuned according to the load balancer requirement. Refer to Terminal ~ 1.2-1.

1.2.2Frontend ACL

The frontend Access Control Logic (ACL) configuration section mainly handles the HTTP and backend server redirects. The frontend section lists the following HAProxy configuration rules:

Bind all HTTP requests to port 80 and all HTTPS requests to port 443.
Force redirect non-SSL/TLS requests to HTTPS requests.
The acl condition redirects the incoming HTTP requests to the backend web server example-com-web-server or example-net-web-server by comparing hostname example.com or example.net, respectively, using the header ( hdr ) function.

1.2.2-1Website host entry

The server's Domain Name System (DNS) client first looks up the host configuration file /etc/hosts to resolve the hostname before querying the remote DNS servers. For the HAProxy load balancer to serve the websites example.com and example.net locally, make a host entry by mapping the localhost IP address ( 127.0.0.1 ) to the domain names example.com and example.net in the system hosts config file.

Terminal ~ 1.2-2

$ sudo nano -w -c /etc/hosts
# HOST ENTRY

## LOCALHOST
127.0.0.1 localhost
::1 localhost

## WEBSITE
127.0.0.1 www.example.com example.com
127.0.0.1 www.example.net example.net
...

1.2.3Backend server

The backend section configures the web server pools or cluster groupings s1 and s2. The backend servers are load-balanced using a round-robin algorithm.

The HAProxy and web servers can use port 80 if the HAProxy load balancer and web servers run on separate machines (virtual or bare-metal). If running on the same server, use port 80 for the HAProxy and port 8001 for the web server.

1.2.3-1Web server host entry

For the HAProxy load balancer to serve the example.com website locally, point Lighttpd web server hostnames s1 ( web1.example.com ) and s2 ( web2.example.com ) to localhost IP address ( 127.0.0.1 ) in the /etc/hosts configuration file.

Likewise, for HAProxy to serve the website example.net locally, add Lighttpd web server hostnames s1 ( web1.example.net ) and s2 ( web1.example.net ) to hosts config file.

Terminal ~ 1.2-3

$ sudo nano -w -c /etc/hosts
# HOST ENTRY
...
## WEB SERVER
# backend example-com-web-server
127.0.0.1 web1.example.com
127.0.0.1 web2.example.com

# backend example-net-web-server
127.0.0.1 web1.example.net
127.0.0.1 web2.example.net
...

1.2.4Start HAProxy

Finally, start the HAProxy load balancer.

Terminal ~ 1.2-4

$ sudo service haproxy start

1.3HAProxy maintenance

The HAProxy load balancer software can be upgraded to a new version using the FreeBSD package manager. Keeping the FreeBSD system up to date ensures that HAProxy has the latest security updates and new features.

1.3.1Maintenance redirects

The backend server maintenance redirects can be handled at the HAProxy load balancer using Access Control Logic (ACL).

1.3.1-1Web server maintenance page

To handle the web server maintenance message and HTTP redirect at the HAProxy load balancer level, create an HTTP 503 error file ( 503-maintenance.http ) and add the following HTML code with the web server maintenance message.

Terminal ~ 1.3-1

$ sudo mkdir -p /usr/local/haproxy/data/error
$ sudo nano -w -c /usr/local/haproxy/data/error/503-maintenance.http
HTTP/1.1 503 Service Unavailable
Content-Type: text/html; charset=utf-8
Retry-After: 3600
Cache-Control: no-cache
Connection: close

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <title>Server Maintenance - Done Booting</title>
</head>
<body id="gw_baseContainer">
    <div>
        <h1 style="color:red;">SERVER IS UNDER MAINTENANCE !!!</h1>
        <h3>Sorry for the inconvenience.</h3>
        <h3>Service will be restored soon.</h3>
    </div>
</body>
</html>

# Set permissions
$ sudo chown -R www:www /usr/local/haproxy

1.3.1-2Edit HAProxy config

Edit the HAProxy configuration file and add acl condition to handle the web server maintenance page redirects.

Terminal ~ 1.3-2

$ sudo nano -w -c /usr/local/etc/haproxy.conf
## GLOBAL
...
## FRONTEND ACL
frontend lb-http
    ...

frontend lb-https
    ...
    ## SERVER MAINTENANCE
    acl server-maintenance hdr_reg(host) -i ^.+$
    use_backend maintenance-web-server if server-maintenance
    ...

## BACKEND SERVER
...

## SERVER MAINTENANCE
backend maintenance-web-server
    errorfile 503 /usr/local/haproxy/data/error/503-maintenance.http
...

1.3.1-3Restart HAProxy

After making changes to the HAProxy configuration file, reload (or restart) the HAProxy load balancer. Use the reload option for minimal service disruption.

Terminal ~ 1.3-3

$ sudo service haproxy reload

1.4Troubleshoot HAProxy

If the HAProxy load balancer is not working as expected after the installation and setup, the following are some HAProxy troubleshooting options.

1.4.1Check HAProxy config

Check whether the HAProxy configuration file has any errors. If HAProxy is correctly configured, the below command will exit without errors.

Terminal ~ 1.4-1

$ sudo haproxy -f /usr/local/etc/haproxy.conf -c

1.4.2HAProxy process

Find about the HAProxy process information using the top command with the process owner username www as the input. The PID and RES mention the process ID and RAM used by the HAProxy, respectively.

Terminal ~ 1.4-2

$ top -U www
...
 PID USERNAME    THR PRI NICE   SIZE    RES STATE   C   TIME    WCPU COMMAND
1252 www           1  20    0 24648K  5420K kqread  3   0:00   0.00% haproxy
...

1.4.3HAProxy port

HAProxy is configured to use ports 80 and 443. Find HAProxy is running on which port using the sockstat (list open sockets) command.

Terminal ~ 1.4-3

$ sockstat -4 -l | egrep ":80|:443"
...
www      haproxy    1252  5  tcp4   *:80                  *:*
www      haproxy    1252  6  tcp4   *:443                 *:*
...

1.4.4HAProxy unresponsive

Find the HAProxy process ID using the ps (process status) command. The first column displays the process owner username: www and the second column contains the HAProxy process ID: 1252. Use the kill command with HAProxy process ID to end the current HAProxy process. Finally, start the new HAProxy process.

Terminal ~ 1.4-4

$ ps -aux | grep haproxy | grep -v grep
www    1252  0.0  0.6 24708 5840  -  Ss    2:28PM   0:00.01 /usr/local/sbin/haproxy -q -f /usr/local/etc/haproxy.conf -p /var/run/haproxy.pid

# Use the above process ID
$ kill -9 1252
$ sudo service haproxy start
Starting haproxy.

Affiliate links

Setting up a custom HAProxy load balancer requires a VPS or a cloud server with root access. Use our affiliate links to purchase a VPS or cloud server from third-party vendors. The affiliate commissions we earn facilitate, Free website access for everyone.

The affiliate links are listed in alphabetical order without any favor. Users are encouraged to refer to the Global Webdynamics LLP Terms of Service governing the Third-party vendors.