cache_peer

Okay, this one's long, so hang on...

This directive defines your neighbor caches and tells Squid how to communicate with them. See Chapter 10 for the lowdown on neighbor caches.

The first argument is the neighbor cache's hostname, or IP address. You can safely use hostnames here because Squid doesn't block while resolving them. In fact, Squid periodically re-resolves the hostname so that if the address changes, you won't need to restart. Neighbor hostnames must be unique; you can't have two neighbors with the same name, even if they have different ports.

The second argument specifies the type of neighbor cache. The choices are parent, sibling, or multicast. Recall from Section 10.6.3 that for a multicast neighbor, Squid sends ICP queries only to the neighbor's IP address, which must be a valid multicast address. Squid makes HTTP requests to parents and siblings but never to a multicast neighbor.

The third and fourth arguments are HTTP and ICP/HTCP port numbers. The HTTP port number corresponds to the neighbor cache's http_port (or equivalent) setting. A value of 0 for the ICP/HTCP port disables those protocols for the neighbor. If you add the htcp option (described in the subsequent paragraphs), Squid sends HTCP queries to the neighbor. Otherwise, Squid sends ICP queries. If you choose not to use ICP or HTCP, you must specify the neighbor as a parent cache.

This brings us to the options field. The cache_peer directive has numerous options, which can be very confusing:

proxy-only

Instructs Squid to not store any responses received from the neighbor. This is often useful when you have a cluster and don't want a resource to be stored on more than one cache.

weight= n

Allows you to weight parent caches artificially when using ICP/HTCP and all parents report a cache miss. Normally Squid selects the parent whose reply arrived first. In fact, it remembers which parent has the best round-trip time for the query. Squid actually divides the RTT by the weight, so that a parent with weight=2 has lower (better) round-trip times and should be selected more often.

ttl= n

An option for multicast neighbors only. It is the multicast TTL value to use for ICP queries and it controls how far away the ICP queries can travel. The valid range is 0-128. A larger value allows the multicast queries to travel farther and possibly be intercepted by outsiders. Use a lower number to keep the queries close to the source and within your network.

no-query

Disables ICP/HTCP for the neighbor. That is, your cache won't send any queries to the neighbor for cache misses. It is often used with the default option.

default

Specifies the neighbor as a suitable choice in the absence of other hints. Squid would prefer to forward a cache miss to a parent that is likely to have a cached copy of the particular resource. Sometimes Squid won't have any clues (e.g., if you disable ICP/HTCP with no-query). In these cases, Squid looks for a parent that has been marked as a default choice.

round-robin

A simple load-sharing technique. It only makes sense when you mark two or more parent caches as round-robin. Squid keeps a counter for each parent. When it needs to forward a cache miss, Squid selects the parent with the lowest counter.

multicast-responder

Tells Squid to expect ICP replies from the neighbor in response to multicast queries.

closest-only

Refers to Squid's netdb features. When your neighbor has enabled the network database, it may return ICMP RTT measurements in ICP miss replies. This option instructs Squid to select a parent based on the RTT between the parent and the origin server, rather than the RTT between your cache and the parent.

no-digest

Tells Squid not to request a Cache Digest from the neighbor. See Section 10.7.

no-netdb-exchange

Tells Squid not to request the neighbor's netdb database. Note, this refers to the bulk transfer of the RTT measurements, not the inclusion of these measurements in ICP miss replies.

no-delay

Tells Squid to ignore any delay pools settings for requests to the neighbor. See Appendix C.

login= credentials

Instructs Squid to send authentication credentials to the neighbor. This option has three different formats, which I've fully described in Section 10.3.1.

connect-timeout=n

Specifies how long Squid should wait when establishing a TCP connection to the neighbor. Without this option, the timeout is taken from the global connect_timeout directive. By using a lower timeout, Squid gives up on the neighbor quickly and tries forwarding the request elsewhere.

digest-url=url

Specifies the URL for the neighbor's Cache Digest. Without this option, Squid assumes the digest URL is http://neighbor.host.name:port/squid-internal-periodic/store_digest.

allow-miss

Instructs Squid to omit the Cache-control: only-if-cached directive for requests sent to a sibling. You should use this only if the neighbor is using the icp_hit_stale and isn't using a miss_access list.

max-conn

Places a limit on the number of simultaneous connections that Squid can open to the neighbor. When this limit is reached, Squid excludes the neighbor from its selection algorithm.

htcp

Tells Squid to send HTCP, instead of ICP, queries to this neighbor. If you add this option, don't forget to also change the port number. Squid uses 4827 as the default HTCP port. See Chapter 10.

carp-load-factor= f

Tells Squid that this neighbor is a member of a CARP array. The load factor value specifies the fraction of requests that this neighbor will receive. The load factor values for all neighbors must add up to 1.0. See Chapter 10.

cache_peer hostname type http-port icp-port [options]

cache_peer bigcache.isp.net parent  3128 3130

cache_peer medcache.isp.net sibling 3128 4827 htcp

cache_peer 172.16.45.111    parent  3128 0 no-query default