Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
HAProxy pfSense package, howto
Purpose of this little wiki is to show how to configure some of the most requested HAProxy configuration options within the pfSense HAProxy package.
HAProxy is a small but powerful reverse proxy, and allows for loadbalancing between multiple (web)servers, but also acl (Access Control Lists) allow for selecting a specific backend or action depending on flexible criteria. And though many features are available through the created webgui, lots more are only available as 'advanced settings' which can be added into several places into the webgui. For all possible options please look at the official HAProxy documentation.
How to configure HAProxy package on pfSense
- Single frontend serving multiple different domains using http.
- Serving multiple domains over http/https using SNI and offloading on pfSense 2.3.
- How to let the webserver know what IP the client connected from.
Chapters in this page:
- Configuring the general settings.
- Scenario that will be used in below examples.
- HTTPS for multiple domains using SNI from 1 frontend
- HTTPS for multiple backend using offloading from 1 frontend
- Configuration file.
I strongly recommend that the webgui of pfSense will be configured on a different port that those that HAProxy will listen on. As you will likely want to have HAProxy listen on 80 and or 443 those ports will need to be opened in the firewall. If for some case HAProxy does not run, connections could get served by the pfSense webgui. Which is in my opinion not supposed to be accessible directly from the internet. (Disabling the webgui-redirect on port 80 in pfSense advanced settings also helps avoid confusion.)
Configuring the general settings.
It is required to enable the package, and configure the total number of connections that HAProxy will accept in a single process. I advise to configure a local stats port, this allows to use the integrated HAProxy stats directly from the pfSense webgui.
Scenario that will be used in below examples.
In each of the scenarios below i will assume that you have a domain name yourdomain.tld and serveral sub-domains pointing to the pfSense wan-ip or perhaps a secondary ipalias or carpip. The examples will assume that the follow sub-domains will be used for separate webapplications running on separate webservers:
For each of these domains 1 or more servers will be used to serve each website. The exception is the ssh.yourdomain.tld where only a ssh server is listening on port 22.
HTTPS for multiple domains using SNI from 1 frontend
Haproxy can use SNI to read the requested destination domain from a ssl-handshake, this allows haproxy to direct traffic for different domains to correct backend.
- Create a backend for each domain you want to be handled by a seperate group of servers.
- Configure the servers for each of the backends.
- Create a Frontend new frontend and give it a name (mainsites).
- Select the interface and port it should listen on wan:ip and 443, leave the SSL checkbox empty here.
- Select the mode: "SSL/HTTPS (TCP)"
- Select the default backend (www.yourdomain.tld) to use when the user acls and actions dont select a different backend or operation to use. For the example lets direct users that type http://ssh.yourdomain.tld in their browser they will be directed to the www backend. Instead of getting no valid reply.
- Add a acl with the name 'forum-acl' for the forum.yourdomain.tld by adding a acl and selecting the 'SNI matches' option for the value fill in the domain
- Add a action 'use backend' and select the forum backend, also fill in the forum-acl. Repeat above steps for the other domains change the acl name and value accordingly.
- Save the frontend configuration
- Apply the configuration.
- Check on the stats page all servers are shown as 'up'.
- Create a firewall rules to allow access to the frontends that haproxy should serve. In this case we should configure on the firewall/rules/wan page the access from any source and any source-port should be allowed to wan:ip 443.
- Ready to test connections from the outside
HTTPS for multiple backend using offloading from 1 frontend
Haproxy can offload / decrypt https traffic on the frontend. For this it is required to load the certificates including the psk and intermediate certifcate into pfSense.
- Load server certificate and its private key (decrypted) into the pfSense certificate manager.
- Load intermediate certificate into certificate manager CA tab. (if applicable)
- Load CA certificate into certificate manager CA tab. (required for OCSP-stapling to work)
- Configure backend 'www' with server address: 192.168.0.101: port 443 and ssl checkbox checked
- Configure backend 'forum' with server address: 192.168.0.102: port 443 and ssl checkbox checked
- Configure frontend 'websites' as following:
- Listen address: wan-adress port: 443 ssloffloading: yes
- Type: http/https(offloading)
- Configure a default backend: www
- Use acl's with host-matches fill in the domain forum.yourdomain.tld
- Configure action 'Use backend' configure the backend 'forum'
- In the SSLoffloading section choose the 'Certificate' previously imported into the certificate manager.
For troubleshooting the stats page is a good first location to check if all backend servers are shown as 'up'. If not done so before configure the 'Internal stats port' on the settings tab to enable the stats pages. Check that servers are all shown in 'green' colors.
If the servers are shown in the color gray then no healthcheck is defined. If possible i always configure a healthcheck for all servers so that haproxy will be aware and can send email alerts when a server go's down.
If the servers are shown in red there are a few things to check.
- Does the server work properly when accessed directly by a browser?
- What is error shown in the LastChk column, this might indicate a unreachable server. (L4 connection failure) or a problem with the ssl-layer (L6 error) in which case certificate settings should be checked.
- If there is a L7 problem it could be that the healthcheck needs to be changed to include a host header, or use HEAD or GET instead of OPTIONS to perform the check.
After applying the configuration changes the contents of the config file can be found at the bottom of the config tab, there are one or two links for the haproxy configuration files depending if there where errors validating the configuration.
Below some useful links from the official HAProxy project:
http://cbonte.github.io/haproxy-dconv/ HTML configuration documentation
http://discourse.haproxy.org/ Example configurations
Lua scripting api: