Skip to content

Documentation-only changes from #9282 for 9.2.x #9291

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zwoop merged 5 commits into from
Jan 10, 2023
Merged

Documentation-only changes from #9282 for 9.2.x #9291

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1513b4f
update documentation for certain cache behaviors
Jan 3, 2023
f57bdb8
remove trailing whitespaces
Jan 3, 2023
ea4c0f2
reformated the doc
Jan 3, 2023
85de1b7
Fixed typo
Jan 3, 2023
53e0c0c
Update doc for ignore_client_no_cache and ignore_server_no_cache
Jan 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 52 additions & 43 deletions doc/admin-guide/configuration/cache-basics.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,14 +178,14 @@ To specify an absolute freshness limit:
Specifying Header Requirements
------------------------------

To further ensure freshness of the objects in the cache, configure
Traffic Server to cache only objects with specific headers. By default,
Traffic Server caches all objects (including objects with no headers);
you should change the default setting only for specialized proxy
situations. If you configure Traffic Server to cache only HTTP objects
with ``Expires`` or ``max-age`` headers, then the cache hit rate will be
noticeably reduced (since very few objects will have explicit expiration
information).
To further ensure freshness of the objects in the cache, Traffic Server by
default caches only HTTP objects with ``Expires`` or ``max-age`` headers. It can
also be configured to cache all objects (including objects with no headers).
Different configurations of header requirements would have a noticeable effect
on cache hit rate. For instance, if Traffic Server is configured to cache only
HTTP objects with ``Expires`` or ``max-age`` headers (the default setting), then
the cache hit rate will be noticeably reduced (since very few objects will have
explicit expiration information).

To configure Traffic Server to cache objects with specific headers:

Expand All @@ -207,12 +207,12 @@ Traffic Server bases the servability of a cached object on ``Cache-Control``
headers that appear in both client requests and server responses. The following
``Cache-Control`` headers affect whether objects are served from cache:

- The ``no-cache`` header, sent by clients, tells Traffic Server that
it should not serve any objects directly from the cache. When present in a
client request, Traffic Server will always obtain the object from the
origin server. You can configure Traffic Server to ignore client
``no-cache`` headers. Refer to `Configuring Traffic Server to Ignore Client no-cache Headers`_
for more information.
- The ``no-cache`` header, sent by clients, tells Traffic Server that it should
not serve any objects directly from the cache. When present in a client
request, Traffic Server will always obtain the object from the origin server.
By default, Traffic Server ignores this header. You can configure Traffic
Server to honor client ``no-cache`` headers. Refer to `Configuring Traffic
Server to Honor Client no-cache Headers`_ for more information.

- The ``max-age`` header, sent by servers, is compared to the object
age. If the age is less than ``max-age``, then the object is fresh
Expand Down Expand Up @@ -374,17 +374,17 @@ and files.
Client Directives
-----------------

By default, Traffic Server does not cache objects with the following
request headers:

- ``Authorization``
Configurations can be set to determine whether to cache objects with the
following client directives (by default, Traffic Server caches objects with
these request headers):

- ``Cache-Control: no-store``

- ``Cache-Control: no-cache``

To configure Traffic Server to ignore this request header, refer to
`Configuring Traffic Server to Ignore Client no-cache Headers`_.
To configure Traffic Server to honor the ``Cache-Control: no-store`` and
``Cache-Control: no-cache`` request headers, refer to `Configuring Traffic
Server to Honor Client no-cache Headers`_.

- ``Cookie`` (for text objects)

Expand All @@ -394,21 +394,26 @@ request headers:
cache all cookied content, or cache cookied content that is of image
type only. For more information, refer to `Caching Cookied Objects`_.

Configuring Traffic Server to Ignore Client no-cache Headers
Configuring Traffic Server to Honor Client no-cache Headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, Traffic Server strictly observes client
``Cache-Control: no-cache`` directives. If a requested object contains a
``no-cache`` header, then Traffic Server forwards the request to the
origin server even if it has a fresh copy in cache. You can configure
Traffic Server to ignore client ``no-cache`` directives such that it
ignores ``no-cache`` headers from client requests and serves the object
from its cache.
By default, Traffic Server ignores client ``Cache-Control: no-cache``
directives. Even if a requested object contains a ``no-cache`` directive,
Traffic Server serves the object from its cache. You can configure Traffic
Server to honor this header and forward the request to the origin server even
if it has a fresh copy in cache.

Likewise, by default Traffic Server also ignores client ``Cache-Control:
no-store`` directives. Traffic Server caches response from the server regardless
of the ``no-store`` headers from client requests.

You can configure Traffic Server to honor both of these client directives with
the following:

#. Edit :ts:cv:`proxy.config.http.cache.ignore_client_no_cache` in
:file:`records.config`. ::

CONFIG proxy.config.http.cache.ignore_client_no_cache INT 1
CONFIG proxy.config.http.cache.ignore_client_no_cache INT 0

#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.

Expand All @@ -420,19 +425,18 @@ headers:

- ``Cache-Control: no-store``

- ``Cache-Control: private``

- ``WWW-Authenticate``
- ``Cache-Control: no-cache``

To configure Traffic Server to ignore ``WWW-Authenticate`` headers,
refer to `Configuring Traffic Server to Ignore WWW-Authenticate Headers`_.
To configure Traffic Server to ignore ``no-cache`` and ``no-store`` headers,
refer to `Configuring Traffic Server to Ignore Server no-cache Headers`_.

- ``Set-Cookie``
- ``Cache-Control: private``

- ``Cache-Control: no-cache``
- ``WWW-Authenticate``

To configure Traffic Server to ignore ``no-cache`` headers, refer to
`Configuring Traffic Server to Ignore Server no-cache Headers`_.
To configure Traffic Server to ignore ``WWW-Authenticate`` headers and cache
the corresponding objects, refer to `Configuring Traffic Server to Ignore
WWW-Authenticate Headers`_.

- ``Expires`` header with a value of 0 (zero) or a past date.

Expand Down Expand Up @@ -547,18 +551,23 @@ Caching Cookied Objects

By default, Traffic Server caches objects served in response to requests
that contain cookies. This is true for all types of objects including
text. Traffic Server does not cache cookied text content because object
headers are stored along with the object, and personalized cookie header
values could be saved with the object. With non-text objects, it is
unlikely that personalized headers are delivered or used.
text.

You can reconfigure Traffic Server to:

- Not cache cookied content of any type.

- Cache all cookied content regardless of type.

- Cache cookied content that is of image type only.

- Cache all cookied content regardless of type.
- Cache all cookied content except text type.

It may be appropriate to configure Traffic Server to not cache cookied text
content because object headers are stored along with the object, and
personalized cookie header values could be saved with the object. With
non-text objects, it is unlikely that personalized headers are delivered or
used.

To configure how Traffic Server caches cookied content:

Expand Down
8 changes: 4 additions & 4 deletions doc/admin-guide/files/records.config.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2186,7 +2186,7 @@ Cache Control
:reloadable:
:overridable:

When enabled (``1``), |TS| ignores client requests to bypass the cache.
When enabled (``1``), |TS| ignores client requests to bypass the cache. Specifically, ``Pragma: no-cache``, ``Cache-Control: no-cache`` and ``Cache-Control: no-store`` in requests are ignored.

.. ts:cv:: CONFIG proxy.config.http.cache.ims_on_client_no_cache INT 1
:reloadable:
Expand All @@ -2198,7 +2198,7 @@ Cache Control
:reloadable:
:overridable:

When enabled (``1``), |TS| ignores origin server requests to bypass the cache.
When enabled (``1``), |TS| ignores origin server requests to bypass the cache. Specifically, ``Pragma: no-cache``, ``Cache-Control: no-cache`` and ``Cache-Control: no-store`` in responses are ignored.

.. ts:cv:: CONFIG proxy.config.http.cache.cache_responses_to_cookies INT 1
:reloadable:
Expand All @@ -2220,8 +2220,8 @@ Cache Control
.. ts:cv:: CONFIG proxy.config.http.cache.ignore_authentication INT 0
:overridable:

When enabled (``1``), |TS| ignores ``WWW-Authentication`` headers in responses ``WWW-Authentication`` headers are removed and
not cached.
When enabled (``1``), |TS| ignores ``WWW-Authentication`` headers in
responses and the responses are cached.

.. ts:cv:: CONFIG proxy.config.http.cache.cache_urls_that_look_dynamic INT 1
:reloadable:
Expand Down