From: Willy Tarreau <w@1wt.eu>
Date: Fri, 25 Nov 2022 10:06:20 +0000 (+0100)
Subject: DOC: config: clarify the fact that "retries" is not just for connections
X-Git-Tag: v2.7.0~33
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=0b4a622b49437e9f41f764a3909f43b7cbd04f61;p=thirdparty%2Fhaproxy.git

DOC: config: clarify the fact that "retries" is not just for connections

In issue #412 it was rightfully reported that the wording in "retries"
still exclusively speaks about connection attempts, while since L7
retries with "retry-on" it's no longer a limitation. Let's update the
text.
---

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 94a9a5aba2..3514ebf05c 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -10631,24 +10631,26 @@ redirect scheme   <sch> [code <code>] <option> [{if | unless} <condition>]
 
 
 retries <value>
-  Set the number of retries to perform on a server after a connection failure
+  Set the number of retries to perform on a server after a failure
   May be used in sections:    defaults | frontend | listen | backend
                                  yes   |    no    |   yes  |   yes
   Arguments :
-    <value>   is the number of times a connection attempt should be retried on
-              a server when a connection either is refused or times out. The
-              default value is 3.
+    <value>   is the number of times a request or connection attempt should be
+              retried on a server after a failure.
 
-  It is important to understand that this value applies to the number of
-  connection attempts, not full requests. When a connection has effectively
-  been established to a server, there will be no more retry.
+  By default, retries apply only to new connection attempts. However, when
+  the "retry-on" directive is used, other conditions might trigger a retry
+  (e.g. empty response, undesired status code), and each of them will count
+  one attempt, and when the total number attempts reaches the value here, an
+  error will be returned.
 
   In order to avoid immediate reconnections to a server which is restarting,
   a turn-around timer of min("timeout connect", one second) is applied before
-  a retry occurs.
+  a retry occurs on the same server.
 
-  When "option redispatch" is set, the last retry may be performed on another
-  server even if a cookie references a different server.
+  When "option redispatch" is set, some retries may be performed on another
+  server even if a cookie references a different server. By default this will
+  only be the last retry unless an argument is passed to "option redispatch".
 
   See also : "option redispatch"