Leanpub Header

Skip to main content
Go to Leanpub.com

HAProxy Essentials

Production Reference and Architecture Guide

HAProxy Essentials
This book is 100% completeLast updated on 2026-10-01
Steve Publications

HAProxy Essentials is a practical guide to building, running and troubleshooting HAProxy in production. From core concepts to advanced architecture, it explains how the pieces fit together and what can go wrong. Based on HAProxy 3.4 LTS, with clear notes on 2.8 and Enterprise-specific features.

Minimum price

$25.00

$35.00

You pay

Author earns

$

Also available for 1 book credit with a Reader Membership

PDF
EPUB
WEB
APP
240
Pages
About

About

About the Book

This book is a comprehensive guide to designing, deploying, and operating HAProxy in production environments. It moves from first principles through advanced engineering topics, explaining not just how to configure HAProxy but why each feature exists, how it interacts with other components, what can go wrong, and how to build reliable systems around it. Every configuration example is complete, valid, and designed for real-world use.

The primary reference version for this book is HAProxy 3.4 LTS. Where behavior differs from earlier stable versions, especially 2.8 LTS, this is explicitly noted. HAProxy Enterprise-specific capabilities are distinguished from the open-source Community Edition wherever the difference matters for architecture or configuration.

Share this book

Categories

NetworkingSystems AdministrationLinuxSystems EngineeringSoftware ArchitectureProxy Server

Feedback

Email the Author

Bundle

Bundles that include this book

Author

About the Author

Steve Publications

Steve is a technology professional with more than 20 years of experience in software development, server infrastructure, cybersecurity, vulnerability research and reverse engineering. Throughout his career, he has designed, secured, analyzed and tested complex software and infrastructure, with a particular focus on understanding how systems fail and how they can be made more secure.

Outside of work, Steve enjoys sharing knowledge with the technology community. He collaborates with researchers, industry experts and technology professionals to write practical books covering software development, cybersecurity, cloud computing, networking, DevOps, artificial intelligence and enterprise technologies. His books focus on practical learning through clear explanations, real-world examples and hands-on exercises. With more than two decades of industry experience, his goal is to help IT professionals, students and technology enthusiasts build useful skills and stay current in a rapidly changing industry.

We believe readers deserve to know how our books are created. Most of our authors are not native English speakers, so we use AI to help translate, proofread manuscripts, fix grammar, improve sentence structure and make technical explanations easier to read. AI is used as an editing tool only. It does not replace the research, technical knowledge or hands-on experience behind our books. Some of our authors also prefer to remain anonymous for privacy or professional reasons. In those cases, we publish their work under a different name. The author's name may be different, but the quality of the content and our review process remain the same.

Every book is written, reviewed and maintained by experienced technology professionals, with contributions from our private technical community of more than 420 engineers and researchers. We spend far more time validating technical accuracy and keeping our content up to date than generating text. We are always interested in working with experienced professionals who have deep expertise in a particular technology or domain. If you would like to publish a book with us or help review an existing manuscript, we'd love to hear from you. Send us a message describing your area of expertise. We are especially interested in niche technologies, specialized skills and emerging topics that are underrepresented in existing technical literature.

If you look through the contents of our books, you'll see practical examples, detailed explanations and material that is regularly updated. Our goal is to publish books that professionals can actually rely on, not low-effort AI-generated content. If you ever feel that one of our books does not meet that standard, Leanpub offers a 60-day money-back guarantee. Feel free to request a refund if you are not satisfied with your purchase.

Contents

Table of Contents

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

Get the free sample chapters

Click the buttons to get the free sample in PDF or EPUB, or read the sample online here

Download Sample PDFDownload Sample EPUB

The Leanpub 60 Day 100% Happiness Guarantee

Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.

See full terms...

Earn $8 on a $10 Purchase, and $16 on a $20 Purchase

We pay 80% royalties on purchases of $7.99 or more, and 80% royalties minus a 50 cent flat fee on purchases between $0.99 and $7.98. You earn $8 on a $10 sale, and $16 on a $20 sale. So, if we sell 5000 non-refunded copies of your book for $20, you'll earn $80,000.

(Yes, some authors have already earned much more than that on Leanpub.)

In fact, authors have earned over $15 million writing, publishing and selling on Leanpub.

Learn more about writing on Leanpub

Free Updates. DRM Free.

If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).

Most Leanpub books are available in PDF (for computers) and EPUB (for phones, tablets and Kindle). The formats that a book includes are shown at the top right corner of this page.

Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.

Learn more about Leanpub's ebook formats and where to read them

Write and Publish on Leanpub

You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!

Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.

Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.

Learn more about writing on Leanpub