| .. Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| .. include:: ../../common.defs |
| |
| .. configfile:: cache.config |
| |
| cache.config |
| ************ |
| |
| The :file:`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: <https://tools.ietf.org/html/rfc7234#section-5.2>`_ 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 :file:`cache.config`, run :option:`traffic_ctl config reload` |
| to apply changes. |
| |
| Format |
| ====== |
| |
| Each line in the :file:`cache.config` file contains a caching rule. |TS| |
| 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. |
| |
| .. _cache-config-format-dest-domain: |
| |
| ``dest_domain`` |
| A requested domain name. |TS| matches the host name of the destination from |
| the URL in the request. |
| |
| .. _cache-config-format-dest-host: |
| |
| ``dest_host`` |
| Alias for ``dest_domain``. |
| |
| .. _cache-config-format-dest-ip: |
| |
| ``dest_ip`` |
| A requested IP address. |TS| matches the IP address of the destination in |
| the request. |
| |
| .. _cache-config-format-dest-host-regex: |
| |
| ``host_regex`` |
| A regular expression to be tested against the destination host name in the |
| request. |
| |
| .. _cache-config-format-url-regex: |
| |
| ``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 ``port``\ s. |
| |
| .. _cache-config-format-port: |
| |
| ``port`` |
| Request URL port. |
| |
| .. _cache-config-format-scheme: |
| |
| ``scheme`` |
| Request URL protocol (http or https). |
| |
| .. _cache-config-format-prefix: |
| |
| ``prefix`` |
| Prefix in the path part of a URL. |
| |
| .. _cache-config-format-suffix: |
| |
| ``suffix`` |
| File suffix in the URL. |
| |
| .. _cache-config-format-method: |
| |
| ``method`` |
| Request URL method (get, put, post, trace, etc.). |
| |
| .. _cache-config-format-time: |
| |
| ``time`` |
| A time range, such as 08:00-14:00. Specified using a 24-hour clock in the |
| timezone of the |TS| server. |
| |
| .. _cache-config-format-src-ip: |
| |
| ``src_ip`` |
| Client IP address. |
| |
| .. _cache-config-format-internal: |
| |
| ``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 |TS| plugin. |
| |
| Actions |
| ------- |
| |
| The final component of a caching rule is the action, which determines what |TS| |
| will do with all objects matching the primary destinations and secondary |
| specifiers of the rule in question. |
| |
| .. _cache-config-format-action: |
| |
| ``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: |
| |
| ``cache-responses-to-cookies`` |
| Change the style of caching with regard to cookies. This effectively |
| overrides the configuration parameter |
| :ts:cv:`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. |
| |
| .. _cache-config-format-pin-in-cache: |
| |
| ``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 |
| |
| .. _cache-config-format-revalidate: |
| |
| ``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``. |
| |
| .. _cache-config-format-ttl-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 :file:`cache.config`, |TS| 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, |TS| 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 |TS| stops on the first match might lead |
| one to assume that all Javascript files will be excluded from the |TS| 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 |TS| 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 |
| |