bionic (5) cache.config.5.gz

Provided by: trafficserver_7.1.2+ds-3_amd64 bug

NAME

       cache.config  - the cache.config file  defines how Traffic Server caches web objects. 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:
          After modifying cache.config, run traffic_ctl config reload to  apply  changes.  When  you  apply  the
          changes  to one node in a cluster, Traffic Server automatically applies the changes to all other nodes
          in the cluster.

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.        │
                               ├───────────────────────┼───────────────────────────────────────┤
                               │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. │
                               ├───────────────────────┼───────────────────────────────────────┤
                               │cluster-cache-local    │ Allow for this content to  be  stored │
                               │                       │ locally on every cluster node.        │
                               └───────────────────────┴───────────────────────────────────────┘

       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 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.

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

       2018, dev@trafficserver.apache.org