HAProxy in pfSense - Reverse Proxy and Load Balancing

HAProxy (High Availability Proxy) is a high-performance solution for proxying and load balancing TCP and HTTP traffic. In pfSense, HAProxy is installed as a package and provides reverse proxy functionality, load balancing across multiple servers, SSL termination to offload encryption from backend servers, and HTTP request routing based on ACL rules. HAProxy is widely used for publishing web applications through a single external IP address, ensuring server pool failover, and distributing client requests across multiple application instances.

Within the pfSense context, HAProxy operates alongside the firewall, enabling routing, filtering, and proxying functions on a single device. This simplifies network architecture and reduces points of failure.

Installing HAProxy

Installation is performed through the package manager:

1. Navigate to System > Package Manager > Available Packages
2. Search for haproxy (two versions are available: haproxy and haproxy-devel)
3. Click Install and confirm the installation
4. Wait for the installation to complete

After installation, configuration is accessible at Services > HAProxy.

Version Selection

HAProxy Architecture

HAProxy operates with two primary entities:

Client --> Frontend (listener) --> ACL (routing) --> Backend (server pool)
                                                       |-- Server 1
                                                       |-- Server 2
                                                       |-- Server 3

pfSense Implementation Details

The pfSense web interface differs from standard HAProxy configuration. Instead of separate frontend/backend sections in the configuration file, the pfSense package generates listen sections that combine frontend and backend. This simplifies basic setup but limits capabilities for advanced multi-backend scenarios.

Backend Configuration

A backend defines the group of servers to which HAProxy directs client requests. Configuration is performed through Services > HAProxy > Backend.

Creating a Backend

1. Navigate to Services > HAProxy > Backend
2. Click Add
3. Complete the parameters
4. Click Save and Apply Changes

Core Backend Parameters

Backend Servers

For each server in the pool, specify:

Load Balancing Algorithms

For most web applications, Round Robin or Least Connections is recommended. The Source algorithm suits applications that do not support distributed sessions.

Frontend Configuration

A frontend defines the entry point for client connections - the IP address, port, and protocol on which HAProxy accepts connections. Configuration is performed through Services > HAProxy > Frontend.

Creating a Frontend

1. Navigate to Services > HAProxy > Frontend
2. Click Add
3. Complete the parameters
4. Click Save and Apply Changes

Core Frontend Parameters

HTTPS Frontend Configuration

To accept HTTPS connections:

1. Set Type to HTTP / HTTPS (offloading)
2. In the SSL Offloading section, select the certificate
3. Set External Port to 443
4. Configure the Default Backend

To redirect HTTP to HTTPS, create an additional Frontend on port 80 with an http-request redirect action or use an ACL.

Binding to Virtual IP

To accept connections on a specific IP address different from the primary WAN address, use a Virtual IP:

1. Create an IP Alias or CARP VIP through Firewall > Virtual IPs
2. In the Frontend settings, select the created VIP in the External Address field

This enables serving multiple domains on different IP addresses through a single HAProxy instance.

ACL - Routing Rules

ACLs (Access Control Lists) define conditions by which HAProxy routes requests to different backends. ACLs analyze incoming request parameters and apply the corresponding action.

Creating ACLs

ACLs are configured within the Frontend section:

1. On the Frontend editing page, navigate to the Access Control Lists section
2. Click Add ACL (down arrow)
3. Complete the condition and action
4. Repeat for each routing rule

ACL Condition Types

ACL Actions

Domain-Based Routing Example

Publishing multiple web applications through a single external IP address:

Path-Based Routing Example

SSL Termination

SSL termination (SSL offloading) allows HAProxy to accept HTTPS connections from clients, decrypt the traffic, and forward it to backend servers over HTTP. This removes the encryption burden from backend servers and simplifies certificate management.

Importing a Certificate

Before configuring SSL, import the certificate into pfSense:

1. Navigate to System > Certificates > Certificates
2. Click Add/Sign
3. Select method: Import an existing Certificate
4. Paste the certificate and private key
5. Click Save

For Let’s Encrypt certificates, the ACME package is recommended for automatic issuance and renewal.

Configuring SSL Offloading in Frontend

1. In the Frontend settings, set Type to HTTP / HTTPS (offloading)
2. In the SSL Offloading section, select the certificate
3. Optionally add extra certificates through Additional Certificates (for multiple domains)
4. Configure the minimum TLS version (TLS 1.2 recommended)

SSL Parameters

SSL Pass-Through

When SSL termination must occur on the backend server (e.g., client certificates), use the SSL/HTTPS (TCP mode) type. HAProxy passes encrypted traffic without decryption, routing by SNI.

Health Checks

Health checks enable HAProxy to determine backend server availability and automatically remove unresponsive servers from the balancing pool.

Check Types

Configuring HTTP Checks

For web applications, HTTP checks are recommended:

1. In the Backend settings, navigate to Health Checking
2. Set Health Check Method to HTTP
3. Specify Check Frequency (check interval, e.g., 5 seconds)
4. Specify Health Check URI (check path, e.g., /health)
5. Specify HTTP Check Method (GET)
6. Specify the expected response code (default 200-399)

Check Parameters

Session Persistence

Session persistence (sticky sessions) ensures all requests from a single client are directed to the same backend server. This is necessary for applications that store session state locally on the server.

Persistence Methods

Configuring Cookie-Based Persistence

1. In the Backend settings under Cookie Persistence:
   • Cookie Name - cookie name (e.g., SERVERID)
   • Cookie Mode - mode: Insert (HAProxy inserts cookie), Prefix, Rewrite
   • Cookie Options - additional parameters (Indirect, NoCache, PostOnly)
2. For each server in the backend, specify a unique value in the Cookie field

Statistics Page

HAProxy provides a built-in statistics page with information about the state of frontends, backends, and individual servers.

Enabling Statistics

Configuration is performed through Services > HAProxy > Settings under the Stats section:

Statistics Page Information

The statistics page displays:

• State of each frontend (UP/DOWN, current connections)
• State of each backend and its servers (UP/DOWN, active/inactive)
• Request counts, bytes, and errors for current and previous sessions
• Server response times (avg, max)
• Queue status (request queue during server overload)
• Server weights and distribution ratios

With Stats Admin enabled, the following actions are available: disabling/enabling servers, draining connections, setting weights.

Warning:

The statistics page contains sensitive infrastructure information. Always configure authentication and restrict access by IP address through firewall rules or ACLs.

Common Use Cases

Reverse Proxy for Web Servers

Publishing multiple web applications through a single external IP address with domain-based routing:

1. Create a Backend for each web application (backend_site1, backend_site2)
2. Create a Frontend on port 443 with SSL termination
3. Configure ACL routing rules by Host
4. Create a Frontend on port 80 with HTTPS redirect
5. Configure firewall rules to allow traffic on ports 80 and 443

Web Application Load Balancing

Distributing requests across multiple application instances:

1. Create a Backend with multiple servers
2. Select the balancing algorithm (Round Robin or Least Connections)
3. Configure HTTP health check on the /health endpoint
4. Configure Cookie-based session persistence if required
5. Create a Frontend bound to a VIP or WAN address

API Publishing

Routing API requests with version separation:

1. Create a Backend for each API version
2. Create a Frontend with path-based ACLs: /v1/ - backend_v1, /v2/ - backend_v2
3. Configure health checks for each backend
4. Add rate limiting through ACLs if needed

Global Settings

General HAProxy parameters are configured through Services > HAProxy > Settings.

Logging

HAProxy writes events to the pfSense system log (Status > System Logs > HAProxy).

Log Levels

HTTP Log Format

Each HTTP request log line contains:

• Client IP and port
• Connection acceptance time
• Frontend and backend names
• HTTP response code
• Processing duration (Tq/Tw/Tc/Tr/Tt)
• Transferred data volume
• Request headers (when capture is enabled)

Troubleshooting

HAProxy Fails to Start

1. Check configuration: Services > HAProxy > Settings > Configuration Validity
2. Review system logs: Status > System Logs > HAProxy
3. Verify frontend ports are not occupied by other services
4. Confirm SSL certificates are valid and not expired

Backend Server Marked as DOWN

1. Verify server reachability from pfSense: Diagnostics > Ping
2. Confirm the backend server port accepts connections: Diagnostics > Test Port
3. Review health check settings - URI, method, expected response code
4. Examine HAProxy logs to determine the failure cause
5. Temporarily disable the health check for diagnostics

502 Bad Gateway

1. The backend server is not responding or returning an error
2. Check the backend connection timeout (Connection Timeout)
3. Verify the backend server can handle the request (not overloaded)
4. When using SSL to the backend, verify certificate correctness

503 Service Unavailable

1. All servers in the backend are marked as DOWN
2. Review health checks for each server
3. Verify the maximum connection count is not exceeded
4. Check the request queue on the statistics page

SSL Errors

1. Check certificate expiration: System > Certificates
2. Verify the certificate chain is complete (including intermediate CAs)
3. Confirm the domain name in the certificate matches the requested domain
4. When using multiple certificates, verify SNI is configured correctly
5. Check the minimum TLS version - older clients may not support TLS 1.2+

Session Not Persisting Between Requests

1. Review Cookie Persistence settings in the backend
2. Verify each server has a unique Cookie value
3. When using the Source algorithm, confirm clients connect from a consistent IP
4. Check whether a transparent proxy or CDN is modifying the client IP

Related Sections

• Package Management - installing and updating pfSense packages
• pfSense Certificates - managing SSL certificates for HAProxy
• Firewall Rules - configuring rules to allow traffic to HAProxy
• pfSense NAT - alternative method for publishing services through port forwarding