7.7 refresh_pattern

The refresh_pattern directive controls the disk cache only indirectly. It helps Squid decide whether or not a given request can be a cache hit or must be treated as a miss. Liberal settings increase your cache hit ratio but also increase the chance that users receive a stale response. Conservative settings, on the other hand, decrease hit ratios and stale responses.

The refresh_pattern rules apply only to responses without an explicit expiration time. Origin servers can specify an expiration time with either the Expires header, or the Cache-Control: max-age directive.

You can put any number of refresh_pattern lines in the configuration file. Squid searches them in order for a regular expression match. When Squid finds a match, it uses the corresponding values to determine whether a cached response is fresh or stale. The refresh_pattern syntax is as follows:

refresh_pattern [-i] regexp min percent max [options]

For example:

refresh_pattern -i \.jpg$ 30 50% 4320 reload-into-ims

refresh_pattern -i \.png$ 30 50% 4320 reload-into-ims

refresh_pattern -i \.htm$ 0 20% 1440

refresh_pattern -i \.html$ 0 20% 1440

refresh_pattern -i . 5 25% 2880

The regexp parameter is a regular expression that is normally case-sensitive. You can make them case-insensitive with the -i option. Squid checks the refresh_pattern lines in order; it stops searching when one of the regular expression patterns matches the URI.

The min parameter is some number of minutes. It is, essentially, a lower bound on stale responses. A response can't be stale unless its time in the cache exceeds the minimum value. Similarly, max is an upper limit on fresh responses. A response can't be fresh unless its time in the cache is less than the maximum time.

Responses that fall between the minimum and maximum are subject to Squid's last-modified factor (LM-factor) algorithm. For such responses, Squid calculates the response age and the LM-factor and compares it to the percent value. The response age is simply the amount of time passed since the origin server generated, or last validated, the response. The resource age is the difference between the Last-Modified and Date headers. The LM-factor is the ratio of the response age to the resource age.

Figure 7-2 demonstrates the LM-factor algorithm. Squid caches an object that is 3 hours old (based on the Date and Last-Modified headers). With an LM-factor value of 50%, the response will be fresh for the next 1.5 hours, after which the object expires and is considered stale. If a user requests the cached object during the fresh period, Squid returns an unvalidated cache hit. For a request that occurs during the stale period, Squid forwards a validation request to the origin server.

Figure 7-2. Calculating expiration times based on LM-factor

It's important to understand the order that Squid checks the various values. Here is a simplified description of Squid's refresh_pattern algorithm:

  • The response is stale if the response age is greater than the refresh_pattern max value.

  • The response is fresh if the LM-factor is less than the refresh_pattern percent value.

  • The response is fresh if the response age is less than the refresh_pattern min value.

  • Otherwise, the response is stale.

The refresh_pattern directive also has a handful of options that cause Squid to disobey the HTTP protocol specification. They are as follows:


When set, this option causes Squid to check the min value before checking the Expires header. Thus, a non-zero min time makes Squid return an unvalidated cache hit even if the response is preexpired.


When set, this option causes Squid to check the min value before the LM-factor percentage.


When set, this option makes Squid transform a request with a no-cache directive into a validation (If-Modified-Since) request. In other words, Squid adds an If-Modified-Since header to the request before forwarding it on. Note that this only works for objects that have a Last-Modified timestamp. The outbound request retains the no-cache directive, so that it reaches the origin server.


When set, this option causes Squid to ignore the no-cache directive, if any, in the request.

    Appendix A. Config File Reference