HAProxy Reverse Proxy

HAProxy can be used for centralized access to the LogScale self-hosted cluster. It provides front-end SSL termination, and back-end load balancing for event ingest, API access, and UI sessions.

Note

Before deploying HAProxy, secure a valid signed SSL certificate with associated public and private keys. A self-signed certificate may be used for initial build and testing if a signed SSL certificate is not available.

Refer to the official HAProxy documentation for the latest HAProxy releases, documentation, and installation instructions.

Prerequisites

  • Ubuntu 26.04 LTS or later.

  • A valid signed SSL certificate and associated public/private keys.

  • HAProxy 3.0 (LTS) or greater. It is recommended you install HAProxy from the official HAProxy PPA to ensure access to current releases, as default Ubuntu repositories may not carry the latest LTS version.

Install HAProxy

Add the official HAProxy PPA and install the current LTS release:

shell
apt-get install --no-install-recommends software-properties-common
add-apt-repository ppa:vbernat/haproxy-3.0
apt-get install haproxy=3.0.\*

Verify the installation:

shell
haproxy -v

Configure HAProxy

Edit the HAProxy configuration file at /etc/haproxy/haproxy.cfg:

haproxy
global
        log /dev/log local0
        log /dev/log local1 notice
        maxconn 50000
        user haproxy
        group haproxy
        daemon

        # TLS hardening
        ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
        ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
        ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets

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

frontend logscale_frontend
        mode http
        bind :443 ssl crt /etc/haproxy/cacert_combo.pem ssl-min-ver TLSv1.2
        default_backend logscale_servers

backend logscale_servers
        mode http
        balance roundrobin
        server s1 <logscale-server1>:8080 check
        server s2 <logscale-server2>:8080 check
        server s3 <logscale-server3>:8080 check

# Stats are exposed on a dedicated port, separate from the main frontend,
# to avoid exposing metrics on the public-facing interface.
listen stats
        bind :8404
        stats enable
        stats hide-version
        stats refresh 30s
        stats show-node
        stats auth <stats_user>:<password>
        stats uri /haproxy?stats

Important

Security Note - Backend SSL Verification: If your LogScale backend nodes are configured to serve HTTPS, add ssl verify required ca-file /etc/haproxy/ca.pem to each server line in the backend block to enable certificate verification. Disabling backend SSL verification (ssl verify none) is not recommended in production environments as it exposes the backend connection to potential interception.

Security Note - Stats Endpoint: The stats endpoint is bound to port 8404 on a dedicated listen block. Ensure this port is firewalled and not publicly accessible. Consider replacing the stats endpoint with the HAProxy Prometheus exporter for production monitoring environments.

Disabling HAProxy Retries for Ingest

When using HAProxy for ingest, it is best practice to enable the log shipper to perform retries on sending the data if the connection fails, rather than allowing HAProxy to retry. If both HAProxy and the log shipper resend data, duplication may occur during ingest.

To disable retries in HAProxy, add retries 0 to the defaults section:

haproxy
defaults
        log     global
        mode    http
        option  httplog
        option  dontlognull
        timeout connect 5000
        timeout client  65000
        timeout server  65000
        errorfile 400 /var/log/haproxy/400.http
        errorfile 403 /var/log/haproxy/403.http
        errorfile 408 /var/log/haproxy/408.http
        errorfile 500 /var/log/haproxy/500.http
        errorfile 502 /var/log/haproxy/502.http
        errorfile 503 /var/log/haproxy/503.http
        errorfile 504 /var/log/haproxy/504.http
        retries 0
...

Retry configuration varies by log shipper. Refer to the relevant documentation for your shipper:

Log Shipper Retry Configuration Reference
Filebeat Filebeat output configuration
Fluentd Fluentd retry configuration
Vector Vector sink retry options
Logstash Logstash persistent queues

Configuring HAProxy as a Service

To ensure HAProxy starts automatically on boot and is managed by systemd, create and enable a systemd service unit file.

Create the Systemd Service Unit File

Create the file /lib/systemd/system/haproxy.service with the following contents:

ini
[Unit]
Description=HAProxy Load Balancer
Documentation=man:haproxy(1)
Documentation=file:/usr/share/doc/haproxy/configuration.txt.gz
After=network-online.target rsyslog.service
Wants=network-online.target

[Service]
EnvironmentFile=-/etc/default/haproxy
EnvironmentFile=-/etc/sysconfig/haproxy
BindReadOnlyPaths=/dev/log:/var/lib/haproxy/dev/log
Environment="CONFIG=/etc/haproxy/haproxy.cfg" "PIDFILE=/run/haproxy.pid" "EXTRAOPTS=-S /run/haproxy-master.sock"
ExecStart=/usr/sbin/haproxy -Ws -f $CONFIG -p $PIDFILE $EXTRAOPTS
ExecReload=/usr/sbin/haproxy -Ws -f $CONFIG -c -q $EXTRAOPTS
ExecReload=/bin/kill -USR2 $MAINPID
KillMode=mixed
Restart=always
SuccessExitStatus=143
Type=notify

[Install]
WantedBy=multi-user.target

If HAProxy was installed via the official HAProxy PPA, this service file may already be present. Verify before creating a new one:

shell
systemctl cat haproxy

If the file already exists and is correct, you can skip the creation step and proceed to reloading the daemon.

Enable and Start the HAProxy Service

Once the service file is in place, reload the systemd daemon to register the new unit, then enable and start the service:

shell
# Reload systemd to pick up the new service file
systemctl daemon-reload

# Enable HAProxy to start automatically on boot
systemctl enable haproxy

# Start the HAProxy service
systemctl start haproxy

Note

The legacy service haproxy start command is still functional on most systems but is a compatibility wrapper around systemctl. It is recommended to use systemctl directly on Ubuntu 26.04 LTS or later for consistency and access to full service management features.

Verify the HAProxy Service

Confirm the service is active and running:

shell
systemctl status haproxy

Expected output should show the service as active (running). For example:

shell
● haproxy.service - HAProxy Load Balancer
     Loaded: loaded (/lib/systemd/system/haproxy.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-08-06 10:00:00 UTC; 5s ago

If the service fails to start, review the logs for errors:

shell
journalctl -u haproxy --no-pager -n 50

Validate the HAProxy Configuration

Before restarting or reloading HAProxy after any configuration changes, validate the configuration file to catch errors:

shell
haproxy -c -f /etc/haproxy/haproxy.cfg

A successful validation will return: 

Configuration file is valid

To apply configuration changes without a full restart (zero downtime reload):

shell
systemctl reload haproxy

Verify LogScale Connectivity

Once HAProxy is confirmed as running, verify end-to-end connectivity by accessing the LogScale UI via the PUBLIC_URL configured in your LogScale settings. For example: https://<your-logscale-public-url>.

You are presented with the LogScale login page, confirming that:

  • HAProxy is correctly terminating SSL

  • Traffic is being load balanced across the configured backend LogScale nodes

  • The LogScale cluster is reachable and healthy

You can also verify backend node health by checking the HAProxy stats page at https://<haproxy-host>:8404/haproxy?stats using the credentials configured in haproxy.cfg. Ensure all backend servers show a green (UP) status before directing production traffic through the proxy.