About this article: AI-assisted writing, reviewed against the cited sources. This is source research, not a lab validation of the procedures. Check the stated versions and your own recovery requirements before making changes.
A load balancer's configuration file is not a copy of the traffic it was handling. In the HAProxy 3.0 configuration manual of 14 October 2026, a frontend binds an address and names a backend, and a backend names servers by address and port. Those statements define listeners and backend targets; they do not by themselves assign or fail over a virtual IP on the host network. A stick table is runtime state that can hold affinity, counters and rate information; it is not the set of live TCP connections. Peers push updates of that store between processes. The file you restored does not contain the entries.
The manual's header says it covers the configuration language and does not provide hints, examples or advice. It does in fact contain a short illustrative configuration. This article uses the specified statements, not that illustration as something to install. Nothing was loaded, and no process was reloaded.
Why it matters
After a lost configuration, the usual restore puts the file back and starts the process. Three different things can still be wrong.
The bind address is not present on the host, so the frontend has nowhere to listen. The manual defines the bind as the listening address. It does not, in the passages used here, spell out the error when the address is missing. Our recommendation: do not expect the process to accept traffic on an address the recovered host does not have. Verify the intended host/network address, routing and listener ownership as separate recovery dependencies. Wildcard or explicitly supported non-local binds can change binding behaviour; process startup alone does not establish reachability.
The server lines name the pool as it was when the file was saved. Servers added later are absent. Servers removed later are still named. The manual says a server line declares a server in a backend or a listen section, with an internal name and an IPv4 or IPv6 address, and an optional port. Parameters follow. A restored list is that declaration, not a discovery of what is alive.
The stick table is missing or, worse, out of step with peers. The peers section propagates stick-table entries between HAProxy instances over TCP, multi-master. Each instance pushes its local updates and insertions. Pushed values overwrite remote ones. They are not merged. A restored process that starts empty and then learns from peers is a different event from a process that pushes its own entries over the top of everyone else's. The manual describes the overwrite. It does not say that an empty table emits deletions. Do not assume a cold start wipes the other nodes. Peers can propagate updates and recover interrupted exchanges independently of the special old-to-new process handoff. Do not assume a cold node has all required entries until its configured peer synchronization has been verified.
What the file actually contains
Configuration is sections. The manual's structure uses global, defaults, frontend, backend and listen. A frontend has a bind and a default backend in the short configuration the file itself shows, a frontend bound to port 80 and a backend with one server. A listen section can hold a bind and servers together. The objects that matter for recovery are the bind, which is the address clients use, and the server lines, which are the pool.
The server's name is the internal name that appears in logs and alerts. The address is where HAProxy connects. If a recovery renames servers, or reorders them so that an implicit identity changes, logs from before the restore no longer match the pool, and peers may not agree on which server is which. The peers section is explicit about identity: server IDs identify servers remotely, so configurations should look similar, or the same IDs must be forced on each server on every participant. A restore that loads a cleaned-up file in which the servers were rewritten without those IDs does not rejoin the same pool the other instances know. Stickiness and any peer data keyed by server ID then point at the wrong server, or at none.
That is a configuration-identity problem, not a traffic problem you can see from "the process started". The check, before the process is in the path, is that every server line you depend on has the same ID on every instance that shares the peers section, and that the address is the address that server still has. The manual states the requirement. It does not provide a reconciliation tool. Comparing the files is the check this article can justify.
Defaults sections apply to what follows them. A restore that changes which proxy section inherits which defaults, or that drops the defaults section because it looked like boilerplate, changes timeouts and modes the servers were inheriting. The manual is a language definition. Inheritance is why the whole file is the unit of restore, not the frontend you think of as the virtual address.
What a reload does with the table
The peers section says interrupted exchanges are detected and recovered from the last known point. During a soft restart, the old process connects to the new one and pushes all its entries before the new process tries to connect to other peers. The manual says this makes replication during a reload very fast, typically a fraction of a second even for large tables.
That path exists when the old process is still there to connect. A restore onto a new machine, or a start after the old process has exited, does not have an old process to push the table. The manual does not describe a file format for stick-table entries inside the configuration. Plan for a cold start to begin without those entries. Before usable persistence entries arrive from an approved peer or other configured mechanism, clients may be assigned to a different backend. For some applications that is harmless. For an application that stored session state on one server and not the others, it is an outage that the configuration file will not show. Whether your application is in that category is not in the HAProxy manual. Know it before you call the restore complete.
What the manual does say about the content of the sync: pushed values overwrite, they are not aggregated. The exception is the data type conn_cur, which is never learned from peers, because it is supposed to reflect local connections. The manual says earlier versions did synchronise it and produced negative values in active-active setups, and always-growing values on reloads or active-passive switches, because the local value counted more connections than were local. Current behaviour, in this 3.0 text, is that it is not learned. conn_cur represents local connections and is not learned as replicated state. Summing deliberately collected local counters may be useful for monitoring, but it does not prove that connections migrated or affinity synchronized. Do not use it as evidence that the restored node has picked up the other's sessions.
A correctly configured soft restart provides the documented old-to-new table handoff. Peer replication is another source of entries; neither mechanism transfers an application’s session store or the live TCP connections merely by copying stick-table values. Killing the process and starting the restored binary is not that path. The manual does not call the second path a supported table restore. Do not describe it as one.
The stats socket is part of the file
The manual's stats socket binds a UNIX socket or a TCP address. Connections return statistics and can allow some commands. A restored configuration that binds that socket to an address you did not mean to expose is a management interface, not a harmless metric port. The review of a restored file includes where that socket binds, and who can connect, in the same pass as the frontend bind. This article does not list the commands the socket accepts. The fact that it can accept commands is the reason it is in the review.
What to decide
The file you will start is a whole configuration: global, defaults, the frontend listener and its separate host/network address prerequisites, the backend or listen servers that are the pool, the server IDs if peers are in use, and the peers section itself. A file that is only the frontend is not a pool.
The address in the bind exists on the host before you expect traffic. If it is an address that moves between machines, the move is a separate step from the file. The manual does not describe address failover.
Server lines match the servers you still intend to use, with the same IDs as the other peers. A backup from before a server was added is incomplete. A backup from before a server was removed can make that target eligible again, depending on health checks, administrative state and routing rules. Compare the file to the current pool, not only to the last backup.
You know whether this start is a soft restart, with the old process able to push the stick table, or a cold start, which the manual does not describe as a table restore. If the application cannot tolerate clients landing on a different server, a cold start is not finished when the process is listening. Assess peer synchronization, configured persistence and the application’s actual session recovery requirements before admitting traffic. New traffic alone does not recover session data that existed only on a failed application server. Do not invent one in the incident.
conn_cur is not the check for "sessions came across". It is local. For a soft restart, the documented handoff is the old process pushing entries before the new one contacts peers. For a cold node, verify its configured peer synchronization separately; neither case alone proves application-session recovery. This article did not run that reload and does not name a command to print the table.
Peers overwrite. Do not bring a restored node into a peer group if it holds a stick table you do not want copied over the others, and verify the actual peer synchronization outcome instead of assuming an empty node is already caught up. If you cannot say which tables it holds, do not connect it to the peers until you can.
Risks and limits
This is HAProxy 3.0 as specified on 14 October 2026. The manual says it does not provide operational advice. The recovery decisions above are editorial, built on the statements about bind, server, server IDs, peers, overwrite, conn_cur, and the soft-restart push. They are not a vendor runbook.
Other load balancers use a virtual server object, a pool object and a persistence table under different names. This article does not map those products. F5, cloud load balancers and others were not opened.
No process was started, no socket was bound, and no table was inspected. "Typically a fraction of a second" is the manual's statement about soft-restart replication. It was not measured here.
Research and verification
Drafted with AI assistance on 11 November 2026 and independently source-reviewed on 13 November 2026. No equipment was configured, no article commands were executed and no lab behaviour is claimed. This is educational source research, not an approved production recovery procedure.
Sources
- HAProxy Technologies, HAProxy configuration manual, version 3.0, 14 October 2026. https://www.haproxy.org/download/3.0/doc/configuration.txt — section structure;
serverdeclaring a backend server by name and address; section 3.5 peers, including multi-master push, overwrite without aggregation,conn_curnot learned, recovery of interrupted exchanges, soft-restart push of all entries, and server IDs;stats socketreturning statistics and allowing some commands. Independently reopened 13 November 2026. The manual's header says it does not provide hints, examples or advice.
This article was originally published on .