10.3 Telling Squid About Your Neighbors

The cache_peer directive defines your neighbor caches and tells Squid how to communicate with them:

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

The first argument is the neighbor's hostname, or IP address. You can safely use hostnames here because Squid doesn't block while resolving them. In fact, Squid periodically resolves the hostname in case the IP address changes while Squid is running. 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. Parent and sibling are straightforward. I'll talk about multicast in Section 10.6.3.

The third argument is the neighbor's HTTP port number. It should correspond to the neighbor's http_port (or equivalent) setting. You must always specify a nonzero HTTP port number.

The fourth argument specifies either the ICP or HTCP port number. By default, Squid uses ICP to query other caches. That is, Squid sends ICP queries to the neighbor on the port given here. If you add the htcp option, Squid sends HTCP queries to this port instead. The default ICP port is 3130, and the default HTCP port is 4827. Make sure that you change the port number if you add the htcp option. Setting this port number to zero disables both ICP and HTCP. However, you should instead (or also) use the no-query option to disable these protocols.

10.3.1 cache_peer Options

The cache_peer directive has quite a few options. I'll describe some of them here, and the others in the sections relating to specific protocols.

proxy-only

This option instructs Squid not to store any responses it receives 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

This option is specific to ICP/HTCP. See Section 10.6.2.1.

ttl= n

This option is specific to multicast ICP. See Section 10.6.3.

no-query

This option is specific to ICP/HTCP. See Section 10.6.2.1.

default

This option specifies the neighbor as a suitable choice in the absence of other hints. Squid normally prefers 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

This option is a simple load-sharing technique. It makes sense only 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

This option is specific to multicast ICP. See Section 10.6.3.

closest-only

This option is specific to ICP/HTCP. See Section 10.6.2.1.

no-digest

This option is specific to Cache Digests. See Section 10.7.

no-netdb-exchange

This option tells Squid not to request the neighbor's netdb database (see Section 10.5). Note, this refers to the bulk transfer of the RTT measurements, not the inclusion of these measurements in ICP miss replies.

no-delay

This option tells Squid to ignore any delay pools settings for requests to the neighbor. See Appendix C for more information on delay pools.

login= credentials

This option instructs Squid to send HTTP authentication credentials to the neighbor. It has three different formats:

login =user:password

This is the most commonly used form. It causes Squid to add the same username and password in every request going to the neighbor. Your users don't need to enter any authentication information.

login=PASS

Setting the value to PASS causes Squid to pass the user's authentication credentials to the neighbor cache. It works only for HTTP basic authentication. Squid doesn't add or modify any authentication information.

If your Squid is configured to require proxy authentication (i.e., with a proxy_auth ACL), the neighbor cache must use the same username and password database. In other words, you should use the PASS form only for a group of caches owned and operated by a single organization. This feature is dangerous because Squid doesn't remove the authentication credentials from forwarded requests.

login =* :password

With this form, Squid changes the password, but not the username, in requests that it forwards. It allows the neighbor cache to identify individual users, but doesn't expose their passwords. This form is less dangerous than using PASS, but does have some privacy implications.

Use this feature with extreme caution. Even if you ignore the privacy issues, this feature may cause undesirable side effects with upstream proxies. For example, I know of at least one other caching product that only looks at the credentials of the first request on a persistent connection. It apparently assumes (incorrectly) that all requests on a single connection come from the same user.

connect-timeout= n

This option 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, which has a default value of 120 seconds. By using a lower timeout, Squid gives up on the neighbor quickly and may try to send the request to another neighbor or directly to the origin server.

digest-url= url

This option is specific to Cache Digests. See Section 10.7.

allow-miss

This option 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 has enabled the icp_hit_stale directive and isn't using a miss_access list.

max-conn= n

This option 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

This option designates the neighbor as an HTCP server. In other words, Squid sends HTCP queries, instead of ICP, to the neighbor. Note that Squid doesn't accept ICP and HTCP queries on the same port. When you add this option, don't forget to change the icp-port value as well. See Section 10.8.1. HTCP support requires the enable-htcp option when running ./configure.

carp-load-factor= f

This option makes the neighbor, which must be a parent, a member of a CARP array. The sum of all f values, for all parents, must equal 1. I cover CARP in Section 10.9. CARP support requires the enable-carp option when running ./configure.

10.3.2 Neighbor State

Squid keeps a variety of statistics and state information about each of its neighbors. One of the most important is whether Squid thinks the neighbor is alive (up) or dead (down). The neighbor's alive/dead state affects many aspects Squid's selection procedures. The algorithm for determining the alive/dead state is a little bit complicated, so I'll go through it here. If you want to follow along in the source code, look at the neighborUp( ) function.

Squid uses both TCP (HTTP) and UDP (ICP/HTCP) communication to determine the state. The TCP state defaults to alive, but changes to dead if 10 consecutive TCP connections fail. When this happens, Squid initiates probe connections, no more than once every connect_timeout time period (the global directive, not the cache_peer option). The state remains dead until one of the probe connections succeeds.

If the no-query option isn't set (meaning Squid is sending ICP/HTCP queries to the neighbor), the UDP layer communication also factors into the alive/dead algorithm. The UDP state defaults to alive, but changes to dead if Squid doesn't get any ICP/HTCP replies for a certain amount of timethe value of the dead_peer_timeout directive.

Squid also marks a neighbor dead if its hostname doesn't resolve to any IP addresses. When Squid determines a neighbor is dead, it writes an entry in cache.log. Here's an example:

2003/09/29 01:13:46| Detected DEAD Sibling: bo2.us.ircache.net/3128/3130

When communication with the neighbor is reestablished, Squid logs a message like this:

2003/09/29 01:13:49| Detected REVIVED Sibling: bo2.us.ircache.net/3128/3130

A neighbor's state affects neighbor-selection algorithms in the following ways:

Squid doesn't expect to receive ICP/HTCP replies from dead neighbors. Squid sends ICP queries to dead neighbors no more than once each dead_peer_timeout interval. See Appendix A.
A dead parent is excluded from the following algorithms: Cache Digests, round-robin parent, first up parent, default parent, and closest parent.
CARP is special: any failed TCP connections (not the 10 required to become dead) excludes the parent from the CARP algorithm.

There is no way to force Squid to send HTTP requests to a dead neighbor. If all neighbors are dead, Squid will try connecting to the origin server. If you don't allow Squid to talk to the origin server (with never_direct, for example), Squid returns a cannot forward error message:

This request could not be forwarded to the origin server or to any

parent caches.  The most likely cause for this error is that:



  * The cache administrator does not allow this cache to make

    direct connections to origin servers, and

  * All configured parent caches are currently unreachable.

10.3.3 Altering the Relationship

The neighbor_type_domain directive allows you to change the relationship with your neighbor based on the origin server's hostname. This is useful, for example, if your neighbor is willing to serve cache hits for any request but misses only for certain nearby domains. The syntax is:

neighbor_type_domain neighbor.host.name relationship [!]domain ...

For example:

cache_peer squid.uk.web-cache.net sibling 3128 3130

neighbor_type_domain squid.uk.web-cache.net parent .uk

Of course, the squid.uk.web-cache.net cache in this example should utilize appropriate miss_access rules to enforce the sibling relationship for non-UK requests. Note that domain names are matched to hostnames as described in Section 6.1.1.2.