Provided by: trafficserver_9.2.3+ds-1+deb12u1build4_amd64 
NAME
cache.config - the cache.config file allows you to overrule the origin's cache policies.
You can add caching rules to specify the following:
• Not to cache objects from specific IP addresses.
• How long to pin particular objects in the cache.
• How long to consider cached objects as fresh.
• Whether to ignore no-cache directives from the server.
IMPORTANT:
Generally, using this file to define cache policies is an antipattern. It's usually
better to have the origin specify the cache policy via the Cache-Control: header. That
way, all the business logic stays with the content generation. The origin is in a much
better position to know which content can be safely cached, and for how long. It can
make fine grained decisions, changing Cache-Control: header value per object. This file
allows for some overrides but, is relatively crude compared to what the origin can
provide.
After modifying cache.config, run traffic_ctl config reload to apply changes.
FORMAT
Each line in the cache.config file contains a caching rule. Traffic Server recognizes
three space-delimited tags:
primary_destination=value secondary_specifier=value action=value
You can use more than one secondary specifier in a rule. However, you cannot repeat a
secondary specifier. The following list shows the possible primary destinations with
allowed values.
Primary Destinations
The primary destination field on each line is used to restrict the requests to which the
caching rule will apply.
dest_domain
A requested domain name. Traffic Server matches the host name of the destination
from the URL in the request.
dest_host
Alias for dest_domain.
dest_ip
A requested IP address. Traffic Server matches the IP address of the destination in
the request.
host_regex
A regular expression to be tested against the destination host name in the request.
url_regex
A regular expression to be tested against the URL in the request.
Secondary Specifiers
The secondary specifiers are optional and may be used to further restrict which requests
are impacted by the caching rule. Multiple secondary specifiers may be used within a
single rule, though each type of specifier can appear at most one time. In other words,
you may have both a port and scheme in the same rule, but you may not have two ports.
port Request URL port.
scheme Request URL protocol (http or https).
prefix Prefix in the path part of a URL.
suffix File suffix in the URL.
method Request URL method (get, put, post, trace, etc.).
time A time range, such as 08:00-14:00. Specified using a 24-hour clock in the timezone
of the Traffic Server server.
src_ip Client IP address.
internal
A boolean value, true or false, specifying if the rule should match (or not match)
a transaction originating from an internal API. This is useful to differentiate
transactions originating from a Traffic Server plugin.
Actions
The final component of a caching rule is the action, which determines what Traffic Server
will do with all objects matching the primary destinations and secondary specifiers of the
rule in question.
action One of the following values:
┌───────────────────────┬──────────────────────────────────┐
│Value │ Effect │
├───────────────────────┼──────────────────────────────────┤
│never-cache │ Never cache specified objects, │
│ │ it will be overwritten by │
│ │ ttl-in-cache. │
├───────────────────────┼──────────────────────────────────┤
│ignore-no-cache │ Ignore all Cache-Control: │
│ │ no-cache headers. │
├───────────────────────┼──────────────────────────────────┤
│ignore-client-no-cache │ Ignore Cache-Control: no-cache │
│ │ headers from client requests. │
├───────────────────────┼──────────────────────────────────┤
│ignore-server-no-cache │ Ignore Cache-Control: no-cache │
│ │ headers from origin server │
│ │ responses. │
└───────────────────────┴──────────────────────────────────┘
cache-responses-to-cookies
Change the style of caching with regard to cookies. This effectively overrides the
configuration parameter proxy.config.http.cache.cache_responses_to_cookies and uses
the same values with the same semantics. The override happens only for requests
that match.
pin-in-cache
Preserves objects in cache, preventing them from being overwritten. Does not
affect objects that are determined not to be cacheable. This setting can have
performance issues, and severely affect the cache. For instance, if the primary
destination matches all objects, once the cache is full, no new objects could get
written as nothing would be evicted. Similarly, for each cache-miss, each object
would incur extra checks to determine if the object it would replace could be
overwritten.
The value is the amount of time you want to keep the object(s) in the cache. The
following time formats are allowed:
• d for days; for example: 2d
• h for hours; for example: 10h
• m for minutes; for example: 5m
• s for seconds; for example: 20s
• mixed units; for example: 1h15m20s
revalidate
For objects that are in cache, overrides the amount of time the object(s) are to be
considered fresh. Use the same time formats as pin-in-cache.
ttl-in-cache
Forces object(s) to become cached, as if they had a Cache-Control: max-age:<time>
header. Can be overruled by requests with cookies. The value is the amount of time
object(s) are to be kept in the cache, regardless of Cache-Control response headers
from the origin server. Use the same time formats as pin-in-cache.
MATCHING MULTIPLE RULES
When multiple rules are specified in cache.config, Traffic Server will check all of them
in order for each request. Thus, two rules which match the same request but have
conflicting actions will result in their actions being compounded. In other words, Traffic
Server does not stop on the first match.
In some cases, this may lead to confusing behavior. For example, consider the following
two rules:
dest_domain=example.com prefix=foo suffix=js revalidate=7d
dest_domain=example.com suffix=js action=never-cache
Reading that under the assumption that Traffic Server stops on the first match might lead
one to assume that all Javascript files will be excluded from the Traffic Server cache,
except for those whose paths begin with foo. This, however, is not correct. Instead, the
first rule establishes that all Javascript files with the path prefix foo will be forced
to revalidate every seven days, and then the second rule also sets an action on all
Javascript files, regardless of their path prefix, to never be cached at all. Because none
of the Javascript files will be cached at all, the first rule is effectively voided.
A similar example, but at least one with a correct solution, might be an attempt to set
differing values for the same action, as so:
# Incorrect!
dest_domain=example.com prefix=foo suffix=js revalidate=7d
dest_domain=example.com suffix=js revalidate=1d
# Correct!
dest_domain=example.com suffix=js revalidate=1d
dest_domain=example.com prefix=foo suffix=js revalidate=7d
The latter accomplishes the implied goal of having a default, or global, timer for cache
object revalidations on Javascript files, as well as a more targeted (and longer)
revalidation time on just those Javascript files with a particular prefix. The former
fails at this goal, because the second rule will match all Javascript files and will
override any previous revalidate values that may have been set by prior rules.
ttl-in-cache and never-cache
When multiple rules are matched in the same request, never-cache will always be
overwritten by ttl-in-cache. For example:
# ttl-in-cache=1d never-cache=false
dest_domain=example.com action=never-cache
dest_domain=example.com ttl-in-cache=1d
EXAMPLES
The following example configures Traffic Server to revalidate gif and jpeg objects in the
domain mydomain.com every 6 hours, and all other objects in mydomain.com every hour. The
rules are applied in the order listed.
dest_domain=mydomain.com revalidate=1h
dest_domain=mydomain.com suffix=gif revalidate=6h
dest_domain=mydomain.com suffix=jpeg revalidate=6h
Force a specific regex to be in cache between 7-11pm of the server's time for 26 hours.
url_regex=example.com/articles/popular.* time=19:00-23:00 ttl-in-cache=1d2h
Prevent objects from being evicted from cache:
url_regex=example.com/game/.* pin-in-cache=1h
COPYRIGHT
2024, dev@trafficserver.apache.org