Learn HAProxy - Core Concepts & Main Architecture

#Introduction

Now you're ready to see what's inside HAProxy's head: how it organizes configuration and processes traffic. Episode 2 dissects the architecture from two angles: the configuration file structure and the internal execution model.

You'll get to know the five section types — global, defaults, frontend, backend, and listen — then follow a request from the client all the way to the response coming back. We'll also examine TCP versus HTTP modes and the multiprocess and multithread options that affect how HAProxy uses CPU.

#Basic Configuration Structure

#The Five Section Types

All HAProxy configuration is written in a single text file, usually /etc/haproxy/haproxy.cfg. This file consists of several sections:

• global: process settings, such as the number of processes, runtime directory, and logging. Not directly related to traffic.
• defaults: default values inherited by the frontends, backends, and listens below it.
• frontend: the public traffic entry point, where ports are bound and ACLs live.
• backend: the group of servers that serve requests.
• listen: a frontend and backend combined in a single block, good for small services.

Here's a minimal example configuration that combines all of them:

global
    log /dev/log local0
    maxconn 4096
 
defaults
    mode http
    timeout connect 5s
    timeout client 50s
    timeout server 50s
 
frontend web_front
    bind *:80
    use_backend web_back
 
backend web_back
    server web1 127.0.0.1:8080 check
    server web2 127.0.0.1:8081 check

Notice that sections start with a keyword at the beginning of a line, and directives inside them are indented. This configuration language isn't case-sensitive for keywords, but label naming should stay consistent.

#Why Order and Hierarchy Matter

Directives in defaults are inherited by all frontends, backends, and listens unless overridden. So mode http in defaults makes every backend use HTTP mode automatically. Good practice: always create sensible defaults so configurations stay short and easy to understand.

#The Request Flow Inside HAProxy

#From Connection to Response

When a request arrives, HAProxy runs this flow:

1. Accept: the process captures the new connection on the port bound in the frontend.
2. Routing: HAProxy matches the request against ACLs and use_backend rules.
3. Forward: the connection is forwarded to the chosen backend server.
4. Track: health checks and stick tables keep monitoring server conditions.
5. Respond: the server's response is returned to the client, possibly with header modifications.

haproxy -c -f /etc/haproxy/haproxy.cfg

Running haproxy -c -f /etc/haproxy/haproxy.cfg checks the syntax without starting the process. This is a mandatory step before any configuration reload.

#The Event-Driven Model

HAProxy doesn't create one thread per connection. It uses a single event loop that handles thousands of descriptors asynchronously. The consequence: low memory usage and no wasted CPU on context switching. This is the main secret behind its ability to handle high traffic on low-spec servers.

#Operating Modes: TCP vs HTTP

#TCP Mode

With mode tcp, HAProxy just forwards bytes without reading their contents. Suitable for databases, Redis, legacy protocols, and connections that must not be inspected. Overhead is lowest, and routing decisions can only use network metadata such as source IP or SNI.

#HTTP Mode

With mode http, HAProxy understands the HTTP protocol: it can read methods, paths, and headers, modify them, do persistence, and run ACLs based on request contents. This is the default mode for the web. The consequence: HAProxy needs to buffer headers and adds a little latency.

frontend web_front
    bind *:80
    mode http
    option httplog
 
backend db_back
    mode tcp
    server db1 10.0.0.10:5432 check

The choice of mode tcp or mode http is best stated explicitly, not left to defaults.

#Multiprocess and Multithread

#Understanding the Division of Work

Modern HAProxy supports two models for adding capacity:

• nbproc: runs several separate processes, each holding its own listeners. Rarely used today because it's been replaced by threads.
• nbthread: runs several threads inside a single process. The modern way to use multiple CPUs in the simplest manner.

global
    maxconn 50000
    nbthread 4

The nbthread 4 directive requests four threads. Start with a value matching your core count; episode 15 covers tuning in more depth.

#Effect on Stick Tables

Remember: with several threads or processes, stick tables are still shared efficiently. But state-based routing decisions (such as the rate limiting in episode 10) should be understood in this context. For practice, a single process with a single thread is enough.

#Closing

Episode 2 gives you a framework for reading any HAProxy configuration: recognize the sections, understand the request flow, and pick the right mode. With this, you won't be confused when looking at production configuration files.

Key takeaways:

• Configuration is made up of global, defaults, frontend, backend, and listen.
• defaults inherits values to other sections unless overridden.
• Request flow: accept, routing, forward, track, respond.
• The event-driven model keeps HAProxy resource-efficient.
• mode tcp for raw protocols; mode http for the web.
• Use haproxy -c before every reload.

In the next episode we get hands-on for the first time: installation & hello HAProxy — the complete installation steps on Linux, a minimal HTTP forwarding configuration, and service verification with basic logs. Everything you learned in episodes 0-2 will be put to use.