HAProxy is a free, very fast and reliable reverse-proxy offering high availability, load balancing, and proxying for TCP and HTTP-based applications.

The official OpenWrt packages feed provides a native HAProxy package to install directly on any OpenWrt router. This can be convenient for a router serving as the main gateway. Using the native firewall, you can easily route external traffic into your LAN for multiple services via HAProxy.

You may want to use HAProxy if you have multiple servers such as web, mail, or other services and don't wish to expose each of them to the wider WAN. Virtual hosts in software like Apache or NGINX often solve the multiple websites problem, but if you have multiple servers that you need to route traffic to, HAProxy can help simplify this requirement.

Note: There is currently no official HAProxy LuCI package available for management or configuration.

OpenWrt 25.12 or newer:

apk add haproxy

OpenWrt 24.10 or older:

opkg install haproxy

The configuration file is stored at /etc/haproxy.cfg. There is no LuCI interface to modify the config, all configuration changes would need to be made by editing this file. You can find further details of all the available HAProxy configuration options on the HAProxy documentation page.

The HAProxy OpenWrt package provides a proc.d service at /etc/init.d/haproxy, you can control the service via the various commands:

You can use the service haproxy or /etc/init.d/haproxy syntax to run the following proc.d commands:

start           Start the service
stop            Stop the service
restart         Restart the service
reload          Reload configuration files (or restart if service does not implement reload)
enable          Enable service autostart
disable         Disable service autostart
enabled         Check if service is started on boot
force_reload    Forcibly reload configuration files
check           Check haproxy config
running         Check if service is running
status          Service status
trace           Start with syscall trace
info            Dump procd service info

The startup order of HAproxy is included at the very end of the sequence (99) due to being reliant on various other services being available before starting.

When making changes to the HAProxy config file, you can use the HAProxy test config option before starting, reloading, or restarting the service. The proc.d script adds a helper command of service haproxy check, this is the same as running: haproxy -c -q -V -f /etc/haproxy.cfg.

By default, HAproxy runs as root. If you have HAProxy externally exposed on the WAN, you should consider creating a HAProxy user/group for the process to run under after doing privileged actions like binding to ports to protect against any CVE/RCE that could lead to gaining root access if the HAProxy process is compromised.

Add the tools required to create additional users and groups:

# OpenWrt 25.12 or newer
apk add shadow-useradd shadow-groupadd
# OpenWrt 24.10 or older
opkg install shadow-useradd shadow-groupadd

Create the haproxy user and group:

groupadd -g 100 haproxy
useradd -u 100 -g haproxy -s /bin/false -d /var/run/haproxy haproxy

If you have an existing HAProxy configuration that specifies uid 0 or gid 0 in your config, you should comment them out or remove them.

Add the following to the global section of the /etc/haproxy.cfg:

user haproxy
group haproxy

When running this setup, you should see two processes:

# ps -w | grep [h]aproxy
13239 root     16452 S    /usr/sbin/haproxy -q -W -db -f /etc/haproxy.cfg
13267 haproxy  21048 S    /usr/sbin/haproxy -q -W -db -f /etc/haproxy.cfg

The root process is still needed for binding to network interfaces, but you should have a second process that will run under the less privileged haproxy user/group created with more limited permissions and access to your router.

Using the OpenWrt native firewall, you can easily expose any HAProxy frontends as required.

One consideration is that if you are using HAProxy for web-based traffic i.e. HTTP/TCP 80 or HTTPS/TCP 443, you may wish to bind another separate IP address to your OpenWrt router in addition to the default, to add an exclusive bind to ports 80 and 443 for HAProxy usage.

By default OpenWrt binds various services to all available IPs by default. For services like uhttpd, you will need to amend the bind settings for uhttpd to use specific IP addresses before running HAProxy on these ports, or change the port bindings used for such services.

For example, your OpenWrt router IP might be 192.168.1.1. You could add another IP 192.168.1.2, to use separate bindings for HAProxy for this purpose.

Adding another IP address to your OpenWrt router can be done through the Network > Interfaces area, selecting the LAN interface and then adding additional IP addresses under the IPv4 and IPv6 address list fields as required.

Running HAProxy directly on a router may not suitable in all cases, depending on the hardware and RAM available.

Using HAProxy in a purely TCP-based mode e.g. passthrough is generally more lightweight and less resource-intensive. Doing TLS termination on your router itself may require more resources and may not be suitable for low-RAM routers.

If you experience crashes or routing performance issues, this may be a sign of hardware/resource limitations.