Provided by: trafficserver_9.2.3+ds-1+deb12u1build4_amd64 bug

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