From 3edf6008591515db8f7d7bdc4a4906e09345e622 Mon Sep 17 00:00:00 2001 From: Willy Tarreau Date: Wed, 4 Feb 2026 10:44:30 +0100 Subject: [PATCH] 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. --- doc/configuration.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) 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 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 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 May be used in the following contexts: tcp, http, log