1.. Licensed to the Apache Software Foundation (ASF) under one 2 or more contributor license agreements. See the NOTICE file 3 distributed with this work for additional information 4 regarding copyright ownership. The ASF licenses this file 5 to you under the Apache License, Version 2.0 (the 6 "License"); you may not use this file except in compliance 7 with the License. You may obtain a copy of the License at 8 9 http://www.apache.org/licenses/LICENSE-2.0 10 11 Unless required by applicable law or agreed to in writing, 12 software distributed under the License is distributed on an 13 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 14 KIND, either express or implied. See the License for the 15 specific language governing permissions and limitations 16 under the License. 17 18.. include:: ../../common.defs 19 20.. configfile:: cache.config 21 22cache.config 23************ 24 25The :file:`cache.config` file allows you to overrule the origin's cache 26policies. You can add caching rules to specify the following: 27 28- Not to cache objects from specific IP addresses. 29- How long to pin particular objects in the cache. 30- How long to consider cached objects as fresh. 31- Whether to ignore no-cache directives from the server. 32 33.. important:: 34 35 Generally, using this file to define cache policies is an antipattern. 36 It's usually better to have the origin specify the cache policy via the 37 `Cache-Control: <https://tools.ietf.org/html/rfc7234#section-5.2>`_ header. 38 That way, all the business logic stays with the content generation. The 39 origin is in a much better position to know which content can be safely 40 cached, and for how long. It can make fine grained decisions, changing 41 Cache-Control: header value per object. This file allows for some overrides 42 but, is relatively crude compared to what the origin can provide. 43 44 After modifying :file:`cache.config`, run :option:`traffic_ctl config reload` 45 to apply changes. 46 47Format 48====== 49 50Each line in the :file:`cache.config` file contains a caching rule. |TS| 51recognizes three space-delimited tags:: 52 53 primary_destination=value secondary_specifier=value action=value 54 55You can use more than one secondary specifier in a rule. However, you 56cannot repeat a secondary specifier. The following list shows the 57possible primary destinations with allowed values. 58 59Primary Destinations 60-------------------- 61 62The primary destination field on each line is used to restrict the requests to 63which the caching rule will apply. 64 65.. _cache-config-format-dest-domain: 66 67``dest_domain`` 68 A requested domain name. |TS| matches the host name of the destination from 69 the URL in the request. 70 71.. _cache-config-format-dest-host: 72 73``dest_host`` 74 Alias for ``dest_domain``. 75 76.. _cache-config-format-dest-ip: 77 78``dest_ip`` 79 A requested IP address. |TS| matches the IP address of the destination in 80 the request. 81 82.. _cache-config-format-dest-host-regex: 83 84``host_regex`` 85 A regular expression to be tested against the destination host name in the 86 request. 87 88.. _cache-config-format-url-regex: 89 90``url_regex`` 91 A regular expression to be tested against the URL in the request. 92 93Secondary Specifiers 94-------------------- 95 96The secondary specifiers are optional and may be used to further restrict 97which requests are impacted by the caching rule. Multiple secondary specifiers 98may be used within a single rule, though each type of specifier can appear at 99most one time. In other words, you may have both a ``port`` and ``scheme`` in 100the same rule, but you may not have two ``port``\ s. 101 102.. _cache-config-format-port: 103 104``port`` 105 Request URL port. 106 107.. _cache-config-format-scheme: 108 109``scheme`` 110 Request URL protocol (http or https). 111 112.. _cache-config-format-prefix: 113 114``prefix`` 115 Prefix in the path part of a URL. 116 117.. _cache-config-format-suffix: 118 119``suffix`` 120 File suffix in the URL. 121 122.. _cache-config-format-method: 123 124``method`` 125 Request URL method (get, put, post, trace, etc.). 126 127.. _cache-config-format-time: 128 129``time`` 130 A time range, such as 08:00-14:00. Specified using a 24-hour clock in the 131 timezone of the |TS| server. 132 133.. _cache-config-format-src-ip: 134 135``src_ip`` 136 Client IP address. 137 138.. _cache-config-format-internal: 139 140``internal`` 141 A boolean value, ``true`` or ``false``, specifying if the rule should 142 match (or not match) a transaction originating from an internal API. This 143 is useful to differentiate transactions originating from a |TS| plugin. 144 145Actions 146------- 147 148The final component of a caching rule is the action, which determines what |TS| 149will do with all objects matching the primary destinations and secondary 150specifiers of the rule in question. 151 152.. _cache-config-format-action: 153 154``action`` 155 One of the following values: 156 157 =========================== ================================================ 158 Value Effect 159 =========================== ================================================ 160 ``never-cache`` Never cache specified objects, it will be 161 overwritten by ``ttl-in-cache``. 162 ``ignore-no-cache`` Ignore all ``Cache-Control: no-cache`` headers. 163 ``ignore-client-no-cache`` Ignore ``Cache-Control: no-cache`` headers from 164 client requests. 165 ``ignore-server-no-cache`` Ignore ``Cache-Control: no-cache`` headers from 166 origin server responses. 167 =========================== ================================================ 168 169.. _cache-responses-to-cookies: 170 171``cache-responses-to-cookies`` 172 Change the style of caching with regard to cookies. This effectively 173 overrides the configuration parameter 174 :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies` 175 and uses the same values with the same semantics. The override happens 176 only for requests that match. 177 178.. _cache-config-format-pin-in-cache: 179 180``pin-in-cache`` 181 Preserves objects in cache, preventing them from being overwritten. 182 Does not affect objects that are determined not to be cacheable. This 183 setting can have performance issues, and severely affect the cache. 184 For instance, if the primary destination matches all objects, once the 185 cache is full, no new objects could get written as nothing would be 186 evicted. Similarly, for each cache-miss, each object would incur extra 187 checks to determine if the object it would replace could be overwritten. 188 189 The value is the amount of time you want to keep the object(s) in the cache. 190 The following time formats are allowed: 191 192 - ``d`` for days; for example: 2d 193 - ``h`` for hours; for example: 10h 194 - ``m`` for minutes; for example: 5m 195 - ``s`` for seconds; for example: 20s 196 - mixed units; for example: 1h15m20s 197 198.. _cache-config-format-revalidate: 199 200``revalidate`` 201 For objects that are in cache, overrides the amount of time the object(s) 202 are to be considered fresh. Use the same time formats as ``pin-in-cache``. 203 204.. _cache-config-format-ttl-in-cache: 205 206``ttl-in-cache`` 207 Forces object(s) to become cached, as if they had a 208 ``Cache-Control: max-age:<time>`` header. Can be overruled by requests with 209 cookies. The value is the amount of time object(s) are to be kept in the 210 cache, regardless of ``Cache-Control`` response headers from the origin 211 server. Use the same time formats as ``pin-in-cache``. 212 213Matching Multiple Rules 214======================= 215 216When multiple rules are specified in :file:`cache.config`, |TS| will check all 217of them in order for each request. Thus, two rules which match the same request 218but have conflicting actions will result in their actions being compounded. In 219other words, |TS| does not stop on the first match. 220 221In some cases, this may lead to confusing behavior. For example, consider the 222following two rules:: 223 224 dest_domain=example.com prefix=foo suffix=js revalidate=7d 225 dest_domain=example.com suffix=js action=never-cache 226 227Reading that under the assumption that |TS| stops on the first match might lead 228one to assume that all Javascript files will be excluded from the |TS| cache, 229except for those whose paths begin with ``foo``. This, however, is not correct. 230Instead, the first rule establishes that all Javascript files with the path 231prefix ``foo`` will be forced to revalidate every seven days, and then the 232second rule also sets an action on all Javascript files, regardless of their 233path prefix, to never be cached at all. Because none of the Javascript files 234will be cached at all, the first rule is effectively voided. 235 236A similar example, but at least one with a correct solution, might be an 237attempt to set differing values for the same action, as so:: 238 239 # Incorrect! 240 dest_domain=example.com prefix=foo suffix=js revalidate=7d 241 dest_domain=example.com suffix=js revalidate=1d 242 243 # Correct! 244 dest_domain=example.com suffix=js revalidate=1d 245 dest_domain=example.com prefix=foo suffix=js revalidate=7d 246 247The latter accomplishes the implied goal of having a default, or global, timer 248for cache object revalidations on Javascript files, as well as a more targeted 249(and longer) revalidation time on just those Javascript files with a particular 250prefix. The former fails at this goal, because the second rule will match all 251Javascript files and will override any previous ``revalidate`` values that may 252have been set by prior rules. 253 254ttl-in-cache and never-cache 255---------------------------- 256 257When multiple rules are matched in the same request, ``never-cache`` will always 258be overwritten by ``ttl-in-cache``. For example:: 259 260 # ttl-in-cache=1d never-cache=false 261 dest_domain=example.com action=never-cache 262 dest_domain=example.com ttl-in-cache=1d 263 264Examples 265======== 266 267The following example configures |TS| to revalidate ``gif`` and ``jpeg`` 268objects in the domain ``mydomain.com`` every 6 hours, and all other objects in 269``mydomain.com`` every hour. The rules are applied in the order listed. :: 270 271 dest_domain=mydomain.com revalidate=1h 272 dest_domain=mydomain.com suffix=gif revalidate=6h 273 dest_domain=mydomain.com suffix=jpeg revalidate=6h 274 275Force a specific regex to be in cache between 7-11pm of the server's time for 27626 hours. :: 277 278 url_regex=example.com/articles/popular.* time=19:00-23:00 ttl-in-cache=1d2h 279 280Prevent objects from being evicted from cache:: 281 282 url_regex=example.com/game/.* pin-in-cache=1h 283 284