DOC/MINOR: userlists: mention solutions to high cpu with hashes

This change adds a paragraph to the documentation regarding "userlists"
and the use of hashed password value.

It indicates what a user can do to address the high CPU cost of
having to calculate the hash at each request, such as reducing the
number of rounds or the cost complexity, if the algorithm allows for it.

I believe it is necessary to mention how the musl C library
impacts performance of hashing functions, as this has already led to a
few issues:

https://github.com/haproxy/haproxy/issues/1298
https://github.com/haproxy/haproxy/issues/2008
https://github.com/haproxy/haproxy/issues/2251

The performance impact is significant enough to mention it.

Acked-by: Lukas Tribus <lukas@ltri.eu>

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 47f5153104555fd2839d20381f5b872ee90956c7..e09468ff0771beaf5298f5c00aa1ac11da679bc7 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -3998,7 +3998,15 @@ user <username> [password|insecure-password <password>]
   designed to be expensive to compute to achieve resistance against brute
   force attacks. They do not simply salt/hash the clear text password once,
   but thousands of times. This can quickly become a major factor in HAProxy's
-  overall CPU consumption!
+  overall CPU consumption, and can even lead to application crashes!
+
+  To address the high CPU usage of hash functions, one approach is to reduce
+  the number of rounds of the hash function (SHA family algorithms) or decrease
+  the "cost" of the function, if the algorithm supports it.
+
+  As a side note, musl (e.g. Alpine Linux) implementations are known to be
+  slower than their glibc counterparts when calculating hashes, so you might
+  want to consider this aspect too.
 
   Example:
         userlist L1