HAProxy

haproxy(1) is a TCP load balancer and reverse proxy.

Installation

Most Linux and BSD distributions offer a haproxy package.

Docker

haproxy(1) is a popular method for proxying traffic between several Docker containers.

There is a temptation to run a containerized instance of haproxy(1) on the host network to give it visibility to all other containers.

The official HAProxy image runs as a non-root user (haproxy), so it cannot bind to a privileged port. There are workarounds, but the upstream recommendation is to properly configure bridge networks and DNS and then to configure haproxy(1) to resolve names at runtime.

Configuration

BSD distributions will look for configuration files in /usr/local/etc.

Basic Configuration

A minimal configuration file looks like:

global
  user haproxy
  group haproxy
  daemon

backend www_backend
  server www1 127.0.0.1:80

frontend http_in
  bind *:80
  mode http
  default_backend www_backend

A backend instructs haproxy(1) where traffic for a particular service should be routed to. Multiple servers can be defined in a backend and an algorithm for load balancing (i.e. roundrobin, leastconn, etc.) can be specified.

A frontend instructs haproxy(1) to listen on an address and/or port. In the above, http_in binds to any name on port 80 and handles HTTP traffic. A frontend also provides logic for routing traffic to the correct backend.

SSL Termination

haproxy(1) uses PEM-formatted certificates, which are fundamentally just the certificate and private key concatenated.

To terminate the encryption, the bind instruction requires some additional parameters. It is also important to set a minimum version of TLS as a configuration option.

global
  ssl-default-bind-options ssl-min-ver TLSv1.2

frontend https_frontend
  bind *:443 ssl crt /path/to/the/pem/certificate alpn h2, http1.1

Using with Let's Encrypt Certificates

Let's Encrypt doesn't automatically generate a PEM-formatted certificate. The following script could be deployed as either a cron(8) job or a certbot(1) post-installation hook.

domain="example.com"
dir="/etc/letsencrypt/live/${domain}"

cat "${dir}/fullchain.pem" "${dir}/privkey.pem" > "${dir}/${domain}.pem"

SSL Passthrough

If SSL/TLS certificates will not be handled by haproxy(1), then configuration is much the same as with unencrypted traffic. The exception is that mode must be set to tcp, as HTTP headers will not be available for inspection.

SSL Redirect

For security, if a server is already configured for HTTPS, unencrypted traffic should be redirected to the HTTPS protocol.

http-request redirect scheme https unless { ssl_fc }
# ...or...
http-request redirect scheme https code 301 unless { ssl_fc }

The latter will cause the redirect to be cached on clients.

These directives can be placed in a frontend or a backend. The pros and cons of using one location or the other mostly relate to the specific use case. Do you have any non-HTTP backends, such as websockets?

Web Sockets

When a connection is upgraded to the websocket protocol, haproxy(1) implicitly drops to tunnel mode. Generally no other configuration is necessary.

If you are redirecting HTTP traffic to HTTPS in the frontend, you will need to make that redirect further conditional on not being a websocket connection.

acl is_websocket hdr(Upgrade) -i WebSocket
http-request redirect scheme https if !{ ssl_fc } !is_websocket

Thorough Configuration

HTTP headers can be inspected to logically route traffic. Consider the below frontend:

frontend http_frontend
  bind *:80
  bind *:443 ssl crt /path/to/the/pem/certificate alpn h2, http1.1
  mode http

  default_backend www_backend

  #route ACME challenge from Let's Encrypt to the certbot temporary server
  acl acme path_beg /.well-known/acme-challenge
  use_backend letsencrypt_backend if acme

  #route API requests
  acl api hdr(host) -i api.example.com

  #for webgit, split CGI requests from file requests
  acl webgit hdr(host) -i git.example.com
  acl cdn path_beg /js
  acl cdn path_beg /css
  use_backend www_backend if webgit ! cdn
  use_backend cdn_backend if cdn

This demonstrates:

• ACLs are defined and calculated based on HTTP headers, including host names and URI paths
• Re-using an ACL name is equivalent to a logical OR
• ACL names can be chained, acting as a logical AND

• ACLs can be negated by prefixing with an exclamation mark (!)

Name Resolution

haproxy(1) can be configured to resolve server addresses at runtime.

First, configure a resolvers:

resolvers docker_dns
  nameserver docker1 127.0.0.11:53

Second, configure servers to defer name resolution and provide instructions on how to resolve names.

backend www_backend
  server www1 nginx:80 check resolvers docker_dns

CategoryRicottone