Polished cache_peer_access and related documentation.

Admins complained that it is not clear how cache_peer_access is
evaluated and how it interacts with cache peer selection algorithms.

diff --git a/src/cf.data.pre b/src/cf.data.pre
index 36d2ecbee707535249c2c5d5eec9601fb0140f01..f5fb23a64d2c69690526cbb30ebbd01c83e6022f 100644 (file)
--- a/src/cf.data.pre
+++ b/src/cf.data.pre
@@ -3288,11 +3288,12 @@ DOC_START
        
        allow-miss      Disable Squid's use of only-if-cached when forwarding
                        requests to siblings. This is primarily useful when
-                       icp_hit_stale is used by the sibling. To extensive use
-                       of this option may result in forwarding loops, and you
-                       should avoid having two-way peerings with this option.
-                       For example to deny peer usage on requests from peer
-                       by denying cache_peer_access if the source is a peer.
+                       icp_hit_stale is used by the sibling. Excessive use
+                       of this option may result in forwarding loops. One way
+                       to prevent peering loops when using this option, is to
+                       deny cache peer usage on requests from a peer:
+                       acl fromPeer ...
+                       cache_peer_access peerName deny fromPeer
        
        max-conn=N      Limit the number of concurrent connections the Squid
                        may open to this peer, including already opened idle
@@ -3343,7 +3344,7 @@ DOC_START
                        Required if you have multiple peers on the same host
                        but different ports.
                        This name can be used in cache_peer_access and similar
-                       directives to dentify the peer.
+                       directives to identify the peer.
                        Can be used by outgoing access controls through the
                        peername ACL type.
        
@@ -3391,17 +3392,42 @@ DOC_END
 NAME: cache_peer_access
 TYPE: peer_access
 DEFAULT: none
+DEFAULT_DOC: No peer usage restrictions.
 LOC: none
 DOC_START
-       Similar to 'cache_peer_domain' but provides more flexibility by
-       using ACL elements.
+       Restricts usage of cache_peer proxies.
 
        Usage:
-               cache_peer_access cache-host allow|deny [!]aclname ...
+               cache_peer_access peer-name allow|deny [!]aclname ...
+
+       For the required peer-name parameter, use either the value of the
+       cache_peer name=value parameter or, if name=value is missing, the
+       cache_peer hostname parameter.
+
+       This directive narrows down the selection of peering candidates, but
+       does not determine the order in which the selected candidates are
+       contacted. That order is determined by the peer selection algorithms
+       (see PEER SELECTION sections in the cache_peer documentation).
+
+       If a deny rule matches, the corresponding peer will not be contacted
+       for the current transaction -- Squid will not send ICP queries and
+       will not forward HTTP requests to that peer. An allow match leaves
+       the corresponding peer in the selection. The first match for a given
+       peer wins for that peer.
+
+       The relative order of cache_peer_access directives for the same peer
+       matters. The relative order of any two cache_peer_access directives
+       for different peers does not matter. To ease interpretation, it is a
+       good idea to group cache_peer_access directives for the same peer
+       together.
+
+       A single cache_peer_access directive may be evaluated multiple times
+       for a given transaction because individual peer selection algorithms
+       may check it independently from each other. These redundant checks
+       may be optimized away in future Squid versions.
 
-       The syntax is identical to 'http_access' and the other lists of
-       ACL elements.  See the comments for 'http_access' below, or
-       the Squid FAQ (http://wiki.squid-cache.org/SquidFaq/SquidAcl).
+       This clause only supports fast acl types.
+       See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
 DOC_END
 
 NAME: neighbor_type_domain