Introduction
HAProxy, which stands for High Availability Proxy, is a popular open source software TCP/HTTP Load Balancer and proxying solution which can be run on Linux, Solaris, and FreeBSD. Its most common use is to improve the performance and reliability of a server environment by distributing the workload across multiple servers (e.g. web, application, database). It is used in many high-profile environments, including: GitHub, Imgur, Instagram, and Twitter.
In this tutorial, we will go over how to use HAProxy for SSL termination, for traffic encryption, and for load balancing your web servers. We will also show you how to use HAProxy to redirect HTTP traffic to HTTPS.
Native SSL support was implemented in HAProxy 1.5.x, which was released as a stable version in June 2014.
Prerequisites
To complete this tutorial, you must have or obtain the following:
At least one web server, with private networking, listening on HTTP (port 80)
Root access to an additional VPS on which we will install HAProxy. Instructions to set up root access can be found here (steps 3 and 4): Initial Server Setup with Ubuntu 14.04.
An SSL certificate and private key pair with a “common name” that matches your domain name or IP address
If you do not already have an SSL certificate and private key pair, please obtain one before continuing. Here are a few tutorials that contain steps that cover creating SSL certificates:
Create an StartSSL Certificate (private.key and ssl.crt)
Create a Self-Signed SSL Certificate on Ubuntu 14.04 (Step 2–apache.key and apache.crt)
Creating a Combined PEM SSL Certificate/Key File
To implement SSL termination with HAProxy, we must ensure that your SSL certificate and key pair is in the proper format, PEM. In most cases, you can simply combine your SSL certificate (.crt or .cer file provided by a certificate authority) and its respective private key (.key file, generated by you). Assuming your certificate file is called example.com.crt, and your private key file is called example.com.key, here is an example of how to combine the files:
cat example.com.crt example.com.key > example.com.pem
sudo cp example.com.pem /etc/ssl/private/
This creates the combined PEM file, called example.com.pem and copies it to /etc/ssl/private. As always, be sure to secure any copies of your private key file, including the PEM file (which contains the private key).
In some cases, you may need to copy your CA root certificate and CA intermediate certificates into your PEM file.
Our Starting Environment
Here is the environment that we are starting with:
If your environment differs from the example, like if you are already using SSL on the web server or you have a separate database server, you should be able to adapt this tutorial to work with your environment.
If you are unfamiliar with basic load-balancing concepts or terminology, like layer 7 load balancing or backends or ACLs, here is an article that explains the basics: An Introduction to HAProxy and Load Balancing Concepts.
Our Goal
By the end of this tutorial, we want to have an environment that looks like this:
That is, your users will access your website by connecting to your HAProxy server via HTTPS, which will decrypt the SSL session and forward the unencrypted requests to your web servers (i.e. the servers in www-backend) via their private network interfaces on port 80. Your web servers will then send their responses to your HAProxy server, which will encrypt the responses and send them back to the user that made the original request.
You can set up your www-backend with as many web servers as you want, as long as they serve identical content. In other words, you can set this up with a single server then scale it out later by adding as many servers as you want. Remember, as your traffic increases, your HAProxy server may become a performance bottleneck if it does not have enough system resources to handle your user traffic.
Note: This tutorial does not cover how to ensure that your web/application servers serve the same content because that is often application or web server dependent.
Install HAProxy 1.6.x
Create a new VPS with private networking. For this tutorial, we will call it haproxy-www, but you may call it whatever you want.
In our haproxy-www VPS, add the dedicated PPA to apt-get:
sudo add-apt-repository ppa:vbernat/haproxy-1.6
Then update your apt cache:
sudo apt-get update
Then install HAProxy 1.6 with apt-get with the following command:
sudo apt-get install haproxy
Now that HAProxy 1.6 is installed, let’s configure it!
HAProxy Configuration
HAProxy’s configuration file is located at /etc/haproxy/haproxy.cfg and is divided into two major sections:
Global: sets process-wide parameters
Proxies: consists of defaults, listen, frontend, and backend sections
Again, if you are unfamiliar with HAProxy or basic load-balancing concepts and terminology, please refer to this link: An Introduction to HAProxy and Load Balancing Concepts.
HAProxy Configuration: Global
All of the HAProxy configuration should be done on your HAProxy VPS, haproxy-www.
Open haproxy.cfg in an editor:
sudo vi /etc/haproxy/haproxy.cfg
You will see that there are two sections already defined: global and defaults.
The first thing you will want to do is set maxconn to a reasonable number. This setting affects how many concurrent connections HAProxy will allow, which can affect QoS and prevent your web servers from crashing from trying to serve too many requests. You will need to play around with it to find what works for your environment. Add the following line (with a value you think is reasonable) to the global section of the configuration
maxconn 2048
Add this line, to configure the maximum size of temporary DHE keys that are generated:
tune.ssl.default-dh-param 2048
Next, in the defaults section, add the following lines under the line that says mode http:
option forwardfor
option http-server-close
The forwardfor option sets HAProxy to add X-Forwarded-For headers to each request, and the http-server-close option reduces latency between HAProxy and your users by closing connections but maintaining keep-alives.
HAProxy Configuration: Stats
Using HAProxy stats can be useful in determining how HAProxy is handling incoming traffic. If you would like to enable the HAProxy stats page, add the following lines in the defaults section (substitute user and password with secure values):
stats enable
stats uri /stats
stats realm Haproxy Statistics
stats auth user:password
This will allow you to look at the HAProxy stats page by going to your domain on /stats (e.g. https://example.com/stats).
Do not close the config file yet! We will add the proxy configuration next.
HAProxy Configuration: Proxies
Frontend Configuration
The first thing we want to add is a frontend to handle incoming HTTP connections. At the end of the file, let’s add a frontend called www-http. Be sure to replace haproxy_www_public_IP with the public IP of your haproxy-www VPS:
frontend www-http
bind haproxy_www_public_IP:80
reqadd X-Forwarded-Proto: http
default_backend www-backend
Here is an explanation of what each line in the frontend config snippet above means:
frontend www-http: specifies a frontend named “www-http”
bind haproxy_www_public_IP:80: replace haproxy_www_public_IP with haproxy-www’s public IP address. This tells HAProxy that this frontend will handle the incoming network traffic on this IP address and port 80 (HTTP)
reqadd X-Forwarded-Proto: http: Adds http header to end of end of the HTTP request
default_backend www-backend: this specifies that any traffic that this frontend receives will be forwarded to www-backend, which we will define in a following step
Next, we will add a frontend to handle incoming HTTPS connections. At the end of the file, let’s add a frontend called www-https. Be sure to replace haproxy_www_public_IP with the public IP of your haproxy-www VPS:
frontend www-https
bind haproxy_www_public_IP:443 ssl crt /etc/ssl/private/example.com.pem
reqadd X-Forwarded-Proto: https
default_backend www-backend
frontend www-https: specifies a frontend named “www-https”
bind haproxy_www_public_IP:443 ssl crt …: replace haproxy_www_public_IP with haproxy-www’s public IP address, and example.com.pem with your SSL certificate and key pair in combined pem format. This tells HAProxy that this frontend will handle the incoming network traffic on this IP address and port 443 (HTTPS).
reqadd X-Forwarded-Proto: https: Adds https header to end of end of the HTTPS request
default_backend www-backend: this specifies that any traffic that this frontend receives will be forwarded to www-backend, which we will define in a following step
Backend Configuration
After you are finished configuring the frontends, continue adding your backend by adding the following lines. Be sure to replace the highlighted words with the respective private IP addresses of your web servers:
backend www-backend
redirect scheme https if !{ ssl_fc }
server www-1 www_1_private_IP:80 check
server www-2 www_2_private_IP:80 check
Here is an explanation of what each line in the backend config snippet above means:
backend www-backend: specifies a backend named www-backend
redirect scheme https if !{ ssl_fc }: this line redirects HTTP requests to HTTPS, which makes your site HTTPS-only. If you want to allow both HTTP and HTTPS, remove this line
server www-1 …: specifies a backend server named www-1, the private IP (which you must substitute) and port that it is listening on, 80. The check option makes the load balancer periodically perform a health check on this server
server www-2 …: similar to the previous line. Add additional lines like this, with appropriate names and IP addresses to add more servers to the load balancer
Now save and exit haproxy.cfg. HAProxy is now ready to be started, but let’s enable logging first.
Enable HAProxy Logging
Enabling logging in HAProxy is very simple. First edit the rsyslog.conf file:
sudo vi /etc/rsyslog.conf
Then find the following two lines, and uncomment them to enable UDP syslog reception. It should look like the following when you are done:
$ModLoad imudp
$UDPServerRun 514
$UDPServerAddress 127.0.0.1
Now restart rsyslog to enable the new configuration:
sudo service rsyslog restart
HAProxy logging is is now enabled! The log file will be created at /var/log/haproxy.log once HAProxy is started.
Start HAProxy
On haproxy-www, start HAProxy to put your configuration changes into effect:
sudo service haproxy restart
HAProxy is now performing SSL termination and load balancing your web servers! Your load balanced server is now accessible to your user via the public IP address or domain name of your load balancer, haproxy-www! There are a few things that you will want to check, to make sure everything is set up correctly.
Things to Check
If you haven’t already, update your nameservers to point your domain to your haproxy-www server’s public IP address
If you want your servers to use only HTTPS, you will want to make sure that your web servers (e.g. www-1, www-2, etc.) are only listening on their private IP addresses on port 80. Otherwise, users will be able to access your web servers via HTTP (unencrypted) on their public IP addresses.
Visit haproxy-www via HTTPS and ensure that it works
Visit haproxy-www via HTTP and ensure that it redirects to HTTPS (unless you configured it to allow both HTTP and HTTPS)
Note: If you’re using an application that needs to know its own URL, like WordPress, you need to change your URL setting from “http” to https”. To follow the WordPress example, you would go to your WordPress General Settings, then change the WordPress Address (URL) and the Site Address (URL) from “http” to “https”.
Conclusion
Now you have a load balancer solution that handles your SSL connections and can be used to horizontally scale out your server environment. Feel free to combine what you have learned in this guide with other HAProxy guides to improve your environment even further!
