From: Willy Tarreau <w@1wt.eu>
Date: Wed, 4 Feb 2026 09:44:30 +0000 (+0100)
Subject: DOC: config: mention the limitation on server id range for consistent hash
X-Git-Tag: v3.4-dev4~3
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3edf6008591515db8f7d7bdc4a4906e09345e622;p=thirdparty%2Fhaproxy.git

DOC: config: mention the limitation on server id range for consistent hash

When using "hash-type consistent", we default to using the server's ID
as the insertion key. However, that key is scaled to avoid collisions
when inserting multiple slots for a server (16 per weight unit), and
that scaling loses the 4 topmost bits of the ID, so the only effective
range of IDs is 1..268435456, and anything above will provide the same
hashing keys again.

Let's mention this in the documentation, and also remind that it can
affect "balance random". This can be backported to all versions.
---

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 260fa021b..886b5fd54 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -18335,7 +18335,10 @@ hash-key <key>
 
       id         The node keys will be derived from the server's numeric
                  identifier as set from "id" or which defaults to its position
-                 in the server list.
+                 in the server list. This is the default. Note that only the 28
+                 lowest bits of the ID will be used (i.e. (id % 268435456)), so
+                 better only use values comprised between 1 and this value to
+                 avoid overlap.
 
       addr       The node keys will be derived from the server's address, when
                  available, or else fall back on "id".
@@ -18347,7 +18350,9 @@ hash-key <key>
   HAProxy processes are balancing traffic to the same set of servers. If the
   server order of each process is different (because, for example, DNS records
   were resolved in different orders) then this will allow each independent
-  HAProxy processes to agree on routing decisions.
+  HAProxy processes to agree on routing decisions. Note: "balance random" also
+  uses "hash-type consistent", and the quality of the distribution will depend
+  on the quality of the keys.
 
 id <value>
   May be used in the following contexts: tcp, http, log