HAProxy Essentials

Production Reference and Architecture Guide

Introduction

1. How This Book Is Organized
2. Prerequisites
3. Version Conventions
4. A Note on HAProxy Enterprise
5. How to Use This Book

Part I: Foundations

Chapter 1: What Is HAProxy and Why Does It Exist

1. The Proxy Problem Space
2. HAProxy’s Origins and Design Philosophy
3. HAProxy Among Alternatives
4. When to Use HAProxy and When Not To
5. Community Edition vs Enterprise: What Differs

Chapter 2: Architecture and Internals from First Principles

1. The HAProxy Process Model
2. Master and Worker Processes
3. Threads and Task Scheduling
4. The Event Loop and Epoll/Kqueue/Devpoll
5. Buffers, Queues and Data Flow
6. Connection vs Session vs Stream vs Transaction
7. The Lifecycle of a Single Request
8. Runtime Memory Layout and File Descriptors

Chapter 3: Installation, Versioning and Build Considerations

1. HAProxy Versioning and Release Cadence
2. Package Managers vs Building from Source
3. Critical Build Options and Their Impact
4. OpenSSL and TLS Build Choices
5. Container Images and Runtime Environments
6. Verifying Your Installation

Part II: Configuration Fundamentals

Chapter 4: Configuration Language, Parsers and Processing Order

1. The Five Sections: global, defaults, frontend, listen, backend
2. Configuration Parsing Rules and Syntax
3. Directive Precedence and Inheritance
4. The Order Matters: Processing Flow Overview
5. Validation, Dry-Run and Testing Configuration
6. Common Configuration Mistakes and How to Avoid Them

Chapter 5: Global Configuration

1. Master-Worker Mode and Process Control
2. Logging Configuration
3. SSL/TLS Global Settings
4. Tuning Directives
5. Runtime and Statistics Sockets
6. Security and Hardening in Global

Chapter 6: Defaults Section

1. Setting Global Timeouts
2. Default Mode and Options
3. Connection Reuse and Keep-Alive Defaults
4. Log Format Defaults
5. Retries and Error Handling Defaults
6. When to Use Defaults vs Inline Configuration

Part III: Core Proxying

Chapter 7: Frontends, Backends and Server Configuration

1. Frontends: Binding and Accepting Connections
2. Backends: Server Pools and Selection
3. Servers: Defining Upstream Endpoints
4. Listen Sections: The Combined Approach
5. Complete Working Configuration Examples
6. Line-by-Line Explanation of a Production Baseline

Chapter 8: Load-Balancing Algorithms and Server Selection

1. Round Robin and Static Round Robin
2. Least Connections
3. Source IP Hashing and URI Hashing
4. Consistent Hashing (where applicable)
5. Random Selection and Weighted Selection
6. Choosing an Algorithm for Your Use Case

Chapter 9: Server States, Health Checks and Resilience

1. Server States: DOWN, UP, MAINT, DRAINING
2. Active Health Checks: Types and Configuration
3. Passive Health Checks and Error Tracking
4. Agent-Based Health Checks
5. Slow Start and Gradual Traffic Ramp
6. Backup Servers and Maintenance Modes
7. Failover Behavior and Failback Patterns

Chapter 10: Connection Management and Timeouts

1. The Timeout Family: client, server, connect, queue and others
2. Setting Timeouts Correctly
3. Keep-Alive and Connection Reuse
4. Connection Draining and Graceful Shutdown
5. Idle Connection Behavior
6. Timeout-Related Production Failures

Chapter 11: TCP Proxying: Layer 4 Load Balancing

1. TCP Mode vs HTTP Mode
2. Binding and Server Configuration in TCP
3. TLS Passthrough in TCP Mode
4. Health Checks in TCP Mode
5. Use Cases: Databases, Redis, SSH, Custom Protocols
6. Limitations and Considerations of TCP Proxying

Part IV: HTTP and Routing

Chapter 12: HTTP Processing and the Request/Response Cycle

1. HTTP Parsing in HAProxy
2. Request and Response Processing Order
3. HTTP Version Handling
4. Header Management Fundamentals
5. Status Codes and Error Pages
6. WebSockets and Upgrade Requests

Chapter 13: ACLs, Fetch Methods and Conditionals

1. ACL Syntax and Evaluation
2. Common ACL Types: host, path, header, method and others
3. Fetch Methods and Samples
4. Sample Fetchers vs Converters vs ACLs
5. Using Maps for Complex Lookups
6. Performance Implications of ACL Evaluation

Chapter 14: Routing: Content Switching and Traffic Distribution

1. Host-Based Routing (Virtual Hosts)
2. Path-Based Routing
3. Header and Cookie-Based Routing
4. Method and Content-Type Routing
5. Multi-Tenant and Geolocation Routing
6. Complete Working Routing Examples

Chapter 15: HTTP Headers, Redirects and Traffic Manipulation

1. Adding, Removing and Setting Headers
2. Redirect Rules and Permanent Redirects
3. URL Rewriting with Use-Backend and Rewrite
4. Forwarded and X-Forwarded-* Headers
5. CORS and Trust-Proxy Considerations

Part V: Sessions, Stickiness and State

Chapter 16: Stickiness and Session Persistence

1. Why Stickiness Matters
2. Cookie-Based Persistence (insert, rewrite, prefix)
3. Source IP Stickiness
4. Custom Cookie and Header-Based Stickiness
5. Stick Tables: Architecture and Use
6. Stick Tables and Peer Synchronization

Chapter 17: Stick Tables, Rate Limiting and Abuse Prevention

1. Stick-Table Configuration
2. Tracking Clients and Servers
3. Rate Limiting Requests and Connections
4. Connection Limiting per Client
5. Abuse Detection Patterns
6. Circuit-Breaking with Stick Tables

Part VI: TLS and Security

Chapter 18: TLS Termination, Passthrough and Re-Encryption

1. TLS Termination at HAProxy
2. TLS Passthrough (Layer 4)
3. Re-Encryption Patterns
4. SNI and Virtual Host Selection
5. ALPN and Protocol Negotiation
6. Complete TLS Configuration Examples

Chapter 19: TLS Certificates, Configuration and Management

1. Certificate Formats and Loading
2. Certificate Chains and Intermediate Certificates
3. Multiple Certificates and SNI Mapping
4. Protocol Versions and Security Hardening
5. Cipher Suites and Security Recommendations
6. Certificate Rotation and Zero-Downtime Renewal

Chapter 20: Mutual TLS, Authentication and Security Hardening

1. Mutual TLS (mTLS) Configuration
2. Client Certificate Validation
3. OCSP and Certificate Revocation
4. HSTS and Security Headers
5. SSL/TLS Security Scanning and Grading
6. Hardening Checklist for Production

Part VII: Performance, Scalability and Tuning

Chapter 21: HAProxy Performance Characteristics

1. CPU Usage and Thread Affinity
2. NUMA and Multi-Socket Considerations
3. Memory Behavior and Limits
4. File Descriptors and Connection Limits
5. Kernel Networking Tuning
6. Benchmarking Methodology and Interpretation

Chapter 22: Advanced Tuning and Optimization

1. Tuning maxconn and Connection Limits
2. Buffer and Queue Tuning
3. TLS Acceleration and Performance
4. Compression (gzip, brotli)
5. Logging Overhead and Optimization
6. Connection Reuse and Capacity Planning
7. Real-World Tuning Examples at Scale

Part VIII: High Availability and Deployment Architecture

Chapter 23: High Availability Architectures

1. Active-Standby with VRRP and Keepalived
2. Floating IPs and Failover Mechanics
3. DNS-Based Failover and Its Limitations
4. Active-Active Topologies
5. Multi-Region and Multi-AZ Architectures
6. State Synchronization and Consistency

Chapter 24: Deployment Models and Integration

1. Bare-Metal and VM Deployments
2. HAProxy in Containers (Docker, Podman)
3. HAProxy in Kubernetes: Ingress, Sidecar, Gateway
4. HAProxy and Service Discovery
5. Cloud Load Balancers and HAProxy Together
6. Edge and Hybrid Deployments

Chapter 25: Configuration Management, Automation and CI/CD

1. Configuration as Code and Version Control
2. Template Engines and Dynamic Config
3. Validation Pipelines and CI Integration
4. Rolling Updates and Zero-Downtime Reloads
5. The Data Plane API and Automation
6. Rollback Strategies and Emergency Procedures

Part IX: Operations and Observability

Chapter 26: Logging, Monitoring and Observability

1. Log Formats and Structure
2. Syslog and Centralized Logging Integration
3. The Stats Page and Its Data
4. Prometheus Metrics and Exporters
5. Runtime API and Socket Commands
6. Building Alerting and Dashboards

Chapter 27: Troubleshooting, Debugging and Incident Response

1. Debugging Methodology and Checklist
2. Runtime Diagnostics
3. Log-Based Troubleshooting
4. Packet-Level Debugging with tcpdump
5. Configuration Issues and Validation Errors
6. Performance Degradation Investigation
7. Real Incident Scenarios and Postmortems

Part X: Advanced Architectures and Patterns

Chapter 28: Production Architectures and Design Patterns

1. Public-Facing Web Application Architecture
2. API Gateway and Backend-for-Frontend Patterns
3. Blue/Green and Canary Deployments with HAProxy
4. Multi-Tenant Platform Design
5. Database Adjacent Proxying (MySQL, Redis)
6. Geographically Distributed Architecture

Chapter 29: Upgrade, Migration and Change Management

1. HAProxy Version Upgrade Strategies
2. Backward Compatibility and Breaking Changes
3. Migration from Nginx or Other Proxies
4. Testing and Validation of Upgrades
5. Blue/Green HAProxy Deployments
6. Rollback and Recovery Procedures

Part XI: Reference

Chapter 30: Configuration Reference and Quick Lookups

1. Essential Directives Quick Reference
2. Common ACL Types and Syntax
3. Key Fetch Methods and Converters
4. Map File Syntax and Patterns
5. Timeout Defaults and Recommendations
6. Useful Runtime API Commands

Chapter 31: Troubleshooting Reference and Decision Trees

1. Connection and Timeout Issues
2. TLS and Certificate Problems
3. Routing and ACL Troubleshooting
4. Performance and Capacity Issues
5. Health Check and Failover Problems

Conclusion: Operating HAProxy as a Platform

1. The HAProxy Ecosystem Today
2. Emerging Trends and Future Directions
3. Building an HAProxy Competence Organization
4. Final Checklist for Production Readiness

Back Matter

Glossary of Terms

Production Deployment Checklist

Bibliography and References