Bug 4458: Squid 4 behaviour change with external ACL arguments

[thirdparty/squid.git] / src / cf.data.pre

diff --git a/src/cf.data.pre b/src/cf.data.pre
index dfe482b14b84abf7f0633b1293a6182c82be6de8..b538696ac2800d818a93194362403fe0524030fc 100644 (file)
--- a/src/cf.data.pre
+++ b/src/cf.data.pre
@@ -712,7 +712,7 @@ DOC_START
        This option defines external acl classes using a helper program
        to look up the status
 
-         external_acl_type name [options] FORMAT.. /path/to/helper [helper arguments..]
+         external_acl_type name [options] FORMAT /path/to/helper [helper arguments]
 
        Options:
 
@@ -774,13 +774,21 @@ DOC_START
 
          %ACL          The name of the ACL being tested.
 
-         %DATA         The ACL arguments. If a logformat encoding modifier
-                       is used it will encode the whole set of arguments
-                       as a single token.
+         %DATA         The ACL arguments specified in the referencing config
+                       'acl ... external' line, separated by spaces (an
+                       "argument string"). see acl external.
 
-                       If not used; then any arguments are automatically
-                       added at the end of the line sent to the helper
-                       as separately URL-encoded fields.
+                       If there are no ACL arguments %DATA expands to '-'.
+
+                       If you do not specify a DATA macro inside FORMAT,
+                       Squid automatically appends %DATA to your FORMAT.
+
+                       By default, Squid applies URL-encoding to each ACL
+                       argument inside the argument string. If an explicit
+                       encoding modifier is used (e.g., %#DATA), then Squid
+                       encodes the whole argument string as a single token
+                       (e.g., with %#DATA, spaces between arguments become
+                       %20).
 
        If SSL is enabled, the following formating codes become available:
 
@@ -796,16 +804,13 @@ DOC_START
 
        General request syntax:
 
-         [channel-ID] FORMAT-values [acl-values ...]
+         [channel-ID] FORMAT-values
 
 
        FORMAT-values consists of transaction details expanded with
        whitespace separation per the config file FORMAT specification
        using the FORMAT macros listed above.
 
-       acl-values consists of any string specified in the referencing
-       config 'acl ... external' line. see the "acl external" directive.
-
        Request values sent to the helper are URL escaped to protect
        each value in requests against whitespaces.
 
@@ -9627,4 +9632,42 @@ DOC_START
        that the request body is needed. Delaying is the default behavior.
 DOC_END
 
+NAME: server_pconn_for_nonretriable
+TYPE: acl_access
+DEFAULT: none
+DEFAULT_DOC: Open new connections for forwarding requests Squid cannot retry safely.
+LOC: Config.accessList.serverPconnForNonretriable
+DOC_START
+       This option provides fine-grained control over persistent connection
+       reuse when forwarding HTTP requests that Squid cannot retry. It is useful
+       in environments where opening new connections is very expensive
+       (e.g., all connections are secured with TLS with complex client and server
+       certificate validation) and race conditions associated with persistent
+       connections are very rare and/or only cause minor problems.
+
+       HTTP prohibits retrying unsafe and non-idempotent requests (e.g., POST).
+       Squid limitations also prohibit retrying all requests with bodies (e.g., PUT).
+       By default, when forwarding such "risky" requests, Squid opens a new
+       connection to the server or cache_peer, even if there is an idle persistent
+       connection available. When Squid is configured to risk sending a non-retriable
+       request on a previously used persistent connection, and the server closes
+       the connection before seeing that risky request, the user gets an error response
+       from Squid. In most cases, that error response will be HTTP 502 (Bad Gateway)
+       with ERR_ZERO_SIZE_OBJECT or ERR_WRITE_ERROR (peer connection reset) error detail.
+
+       If an allow rule matches, Squid reuses an available idle persistent connection
+       (if any) for the request that Squid cannot retry. If a deny rule matches, then
+       Squid opens a new connection for the request that Squid cannot retry.
+
+       This option does not affect requests that Squid can retry. They will reuse idle
+       persistent connections (if any).
+
+       This clause only supports fast acl types.
+       See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
+
+       Example:
+               acl SpeedIsWorthTheRisk method POST
+               server_pconn_for_nonretriable allow SpeedIsWorthTheRisk
+DOC_END
+
 EOF