Hello,
The attached patch polishes cache_peer_access and related documentation.
It was inspired by an admin complaint that the existing documentation
did not make it clear how cache_peer_access is evaluated and how it
interacts with cache peer selection algorithms.
I do not think we should provide a comprehensive peer selection
documentation inside squid.conf.documented (because the algorithm is too
complex to clearly explain in this format), but I hope this patch
clarifies things a bit.
HTH,
Alex.
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.
=== modified file 'src/cf.data.pre'
--- src/cf.data.pre 2015-10-11 14:08:47 +0000
+++ src/cf.data.pre 2015-11-04 23:23:08 +0000
@@ -3257,45 +3257,46 @@ DOC_START
See MS KB document Q307347 for details on this header.
If set to auto the header will only be added if the
request is forwarded as a https:// URL.
tls-no-default-ca
Do not use the system default Trusted CA.
==== GENERAL OPTIONS ====
connect-timeout=N
A peer-specific connect timeout.
Also see the peer_connect_timeout directive.
connect-fail-limit=N
How many times connecting to a peer must fail before
it is marked as down. Standby connection failures
count towards this limit. Default is 10.
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
and standby connections. There is no peer-specific
connection limit by default.
A peer exceeding the limit is not used for new
requests unless a standby connection is available.
max-conn currently works poorly with idle persistent
connections: When a peer reaches its max-conn limit,
and there are idle persistent connections to the peer,
the peer may not be selected because the limiting code
does not know whether Squid can reuse those idle
connections.
standby=N Maintain a pool of N "hot standby" connections to an
UP peer, available for requests when no idle
persistent connection is available (or safe) to use.
By default and with zero N, no such pool is maintained.
@@ -3312,66 +3313,92 @@ DOC_START
Squid never opens multiple new standby connections
concurrently. This one-at-a-time approach minimizes
flooding-like effect on peers. Furthermore, just a few
standby connections should be sufficient in most cases
to supply most new requests with a ready-to-use
connection.
Standby connections obey server_idle_pconn_timeout.
For the feature to work as intended, the peer must be
configured to accept and keep them open longer than
the idle timeout at the connecting Squid, to minimize
race conditions typical to idle used persistent
connections. Default request_timeout and
server_idle_pconn_timeout values ensure such a
configuration.
name=xxx Unique name for the peer.
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.
no-tproxy Do not use the client-spoof TPROXY support when forwarding
requests to this peer. Use normal address selection instead.
This overrides the spoof_client_ip ACL.
proxy-only objects fetched from the peer will not be stored locally.
DOC_END
NAME: cache_peer_access
TYPE: peer_access
DEFAULT: none
LOC: none
DOC_START
- Use to limit the requests for which a neighbor proxy will be
- queried. Peers with no restrictions are queried for all requests.
+ Restricts usage of cache_peer proxies.
Usage:
- cache_peer_access cache-host allow|deny [!]aclname ...
+ cache_peer_access peer-host allow|deny [!]aclname ...
+
+ For the required peer-host parameter, use either the cache_peer
+ hostname parameter or the value of the cache_peer name 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.
+
+ This clause only supports fast acl types.
+ See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
+
+ By default, there are no peer usage restrictions.
- The syntax is identical to 'http_access' and the other lists of
- ACL elements. See the comments for 'http_access', or the
- Squid FAQ (http://wiki.squid-cache.org/SquidFaq/SquidAcl).
DOC_END
NAME: neighbor_type_domain
TYPE: hostdomaintype
DEFAULT: none
DEFAULT_DOC: The peer type from cache_peer directive is used for all requests to that peer.
LOC: none
DOC_START
Modify the cache_peer neighbor type when passing requests
about specific domains to the peer.
Usage:
neighbor_type_domain neighbor parent|sibling domain domain ...
For example:
cache_peer foo.example.com parent 3128 3130
neighbor_type_domain foo.example.com sibling .au .de
The above configuration treats all requests to foo.example.com as a
parent proxy unless the request is for a .au or .de ccTLD domain name.
_______________________________________________
squid-dev mailing list
[email protected]
http://lists.squid-cache.org/listinfo/squid-dev
