Install HAProxy 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:
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

$ sudo find /usr/local -name "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

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

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
    maxconn 10000
    log local0
    user www
    group www

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

frontend lb-http
    bind *:80

    redirect scheme https code 301 if !{ ssl_fc }

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

    acl example-com hdr(host) -i
    use_backend example-com-web-server if example-com

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

backend example-com-web-server
    balance roundrobin
    server s1
    server s2

backend example-net-web-server
    balance roundrobin
    server s1
    server s2

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 or, 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 and locally, make a host entry by mapping the localhost IP address ( ) to the domain names and in the system hosts config file.

Terminal ~ 1.2-2
$ sudo nano -w -c /etc/hosts

## LOCALHOST localhost
::1 localhost


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 website locally, point Lighttpd web server hostnames s1 ( ) and s2 ( ) to localhost IP address ( ) in the /etc/hosts configuration file.

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

Terminal ~ 1.2-3
$ sudo nano -w -c /etc/hosts
# backend example-com-web-server

# backend example-net-web-server

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">
    <meta charset="utf-8" />
    <title>Server Maintenance - Done Booting</title>
<body id="gw_baseContainer">
        <h1 style="color:red;">SERVER IS UNDER MAINTENANCE !!!</h1>
        <h3>Sorry for the inconvenience.</h3>
        <h3>Service will be restored soon.</h3>

# 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
frontend lb-http

frontend lb-https
    acl server-maintenance hdr_reg(host) -i ^.+$
    use_backend maintenance-web-server if 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
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/

# 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.