Net-proxy/haproxy

From Gentoo Wiki
Jump to: navigation, search
This article is a stub. You can help by expanding it.

Haproxy (Originally High Availability Proxy) provides an industrial grade proxy to the Gentoo administrator routing traffic between ones frontend (web-facing) and backend (web-servers/web-services/databases). It reports connectivity statistics, performs health checks upon backend services and supports load balancing.

Interestingly, if one has multiple frontend machines HAProxy will redirect clients from one machine to another as they are taken offline ensuring a consistent service (One stands under correction on this point).

It handles both TCP (Level 4 in the OSI model) and the HTTP (Level 7 in the OSI model) routing (Routing further protocols seems possible too e.g. mail).

SSL termination may be done at Haproxy or passed through to be termination at the backend (SNI).

Installation

USE flags

USE flags for net-proxy/haproxy A TCP/HTTP reverse proxy for high availability environments

51degrees Device Detection using 51 Degrees local
device-atlas Use dev-libs/device-atlas-api-c library local
net_ns Enable network namespace support (CONFIG_NET_NS) local
pcre-jit Use JIT support for PCRE local
pcre2 Enable PCRE2 RegEx support local
pcre2-jit Use JIT support for PCRE2 local
slz Use dev-libs/libslz compression library local
tools Install additional tools (halog, iprange) local
wurfl Device Detection using WURFL local

Emerge

root #emerge --ask net-proxy/haproxy

Additional software

The following software supports, compliments or integrates with Haproxy :

HATop
An interactive ncurses client and real-time monitoring, statistics displaying tool for the Haproxy TCP/HTTP load balancer
Herald
A load feedback and check agent for Haproxy
Haproxystats
A statistics collector which processes various statistics and pushes them to a graphing system (Graphite)

HAProxy serves the usual web-servers (Apache/Lighthttpd/NginX/Traefik) and databases (PostgreSQL/Redis/MySQL/CouchDB) and supports encryption (OpenSSL/LetsEncrypt). It will handle backend connections via unix and web sockets. These packages are used with haproxy and do not interact with it directly, hence are not listed here.

Configuration

The global section, within Haproxy's configuration file, specifies the services permissions and behaviour upon ones system. This file is read sequentially and one may define One or more default block(s) may be set to define the common behaviour of the subsequent frontend/backend blocks; with later default blocks overriding the earlier ones.

In the example that follow one provide the minimal configuration necessary to enable some feature provided by Haproxy. By combining these examples one should be able to configure Haproxy for their own setup.

Files

The following files and folders are used to configure Haproxy

* /etc/haproxy/haproxy.cfg - The main configuration file
* /etc/haproxy/certs - The SSL certificates folder
* /etc/openssl/private - An alternate, possibly better, location for SSL certificates

Global

The haproxy user and group are configured by emerge during installation.

{{ global

       user        haproxy
       group       haproxy
       pidfile     /var/run/haproxy.pid
       daemon

}}

SSL

This terminates the secure connection and passes the decrypted traffic on to the backend. This assumes the backend is run on a secured internal network.

Haproxy uses a single certificate for authentication purposes, that is an ordered and combined key, thing and thing. If ones certificates are supplied by letsencrypts' certbot then they may use the following line to generate a combined certiifcate for haproxy. The combined certificates should be stored under either the Haproxy folder, /etc/haproxy/certs, or the OpenSSL one, /etc/openssl/private (The author is not sure which of these paths is the canonical one).

SNI

SNI is performed within the TCP layer (Level 4 in the OSI model) allowing frontend connections over HTTPS to be directed to the appropriate backend. Only very old browsers do not support this e.g. I.E. on WinXP.

Environment variables

  • VAR1
  • VAR2

Service

(Provide instructions on starting/stopping and enabling/disabling the software's service. This is only really necessary if it if the software includes a daemon for certain tasks.)

OpenRC

runit

systemd

Usage

(Explain how to use the package/software/tool/utility in this section.)

Invocation

(Remove this section if not applicable.)

Troubleshooting

(Troubleshoot issues in this section. Separate issues by best describing the error with a new section name. Remove if no issues are known.)

Issue 1

When X happens, Y is how you fix it.

Removal

(Explain how to properly remove the software. If this section needs more than an 'emerge -C' command each step should be explained in detail so that no trace of the software remains on the system.)

Unmerge

root #emerge --ask --depclean net-proxy/haproxy

See also

  • [[Article_name]] - (Link to related Gentoo Wiki articles using bullet points for each link in this section; each link should be local to the Wiki. Use a dash to separate the link from a reason why the link was decided upon.)

External resources

References

(Optional section. Remove this section if references are not used. This section is used to cite factual information. This information is found outside the Gentoo Wiki and used to back up truth claims. The actual references themselves still be littered throughout the main article.)