From 1513b4f987e164235dd3c2ef1fdc79e1b19453f1 Mon Sep 17 00:00:00 2001 From: Zhengxi Li Date: Tue, 3 Jan 2023 19:41:59 +0000 Subject: [PATCH 1/5] update documentation for certain cache behaviors --- .../configuration/cache-basics.en.rst | 91 ++++++++++--------- doc/admin-guide/files/records.config.en.rst | 4 +- 2 files changed, 49 insertions(+), 46 deletions(-) diff --git a/doc/admin-guide/configuration/cache-basics.en.rst b/doc/admin-guide/configuration/cache-basics.en.rst index ffdace636e4..ffffc33247f 100644 --- a/doc/admin-guide/configuration/cache-basics.en.rst +++ b/doc/admin-guide/configuration/cache-basics.en.rst @@ -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 to cache +only HTTP objects with ``Expires`` or ``max-age`` headers(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: @@ -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 @@ -374,18 +374,18 @@ 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) By default, Traffic Server caches objects served in response to @@ -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`` header, Traffic +Server serves the object from its cache. You can configure Traffic Server to +honor this header and forwards the request to the origin server even if it has a +fresh copy in cache. + +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 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. @@ -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. @@ -547,18 +551,17 @@ 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. To configure how Traffic Server caches cookied content: diff --git a/doc/admin-guide/files/records.config.en.rst b/doc/admin-guide/files/records.config.en.rst index 5dc6670f50e..45cec12e56b 100644 --- a/doc/admin-guide/files/records.config.en.rst +++ b/doc/admin-guide/files/records.config.en.rst @@ -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: From f57bdb80b7774cb9b168f2de194e98c0f0aea88d Mon Sep 17 00:00:00 2001 From: Zhengxi Li Date: Tue, 3 Jan 2023 20:12:00 +0000 Subject: [PATCH 2/5] remove trailing whitespaces --- doc/admin-guide/configuration/cache-basics.en.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/admin-guide/configuration/cache-basics.en.rst b/doc/admin-guide/configuration/cache-basics.en.rst index ffffc33247f..14b60f51748 100644 --- a/doc/admin-guide/configuration/cache-basics.en.rst +++ b/doc/admin-guide/configuration/cache-basics.en.rst @@ -385,7 +385,7 @@ these request 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) By default, Traffic Server caches objects served in response to @@ -401,14 +401,14 @@ By default, Traffic Server ignores client ``Cache-Control: no-cache`` directives. Even if a requested object contains a ``no-cache`` header, Traffic Server serves the object from its cache. You can configure Traffic Server to honor this header and forwards the request to the origin server even if it has a -fresh copy in cache. +fresh copy in cache. 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. +``no-store`` headers from client requests. You can configure Traffic Server to honor both client directives with the -following: +following: #. Edit :ts:cv:`proxy.config.http.cache.ignore_client_no_cache` in :file:`records.config`. :: From ea4c0f232e9eefc3740c7b74293682fbc949d032 Mon Sep 17 00:00:00 2001 From: Zhengxi Li Date: Tue, 3 Jan 2023 21:32:09 +0000 Subject: [PATCH 3/5] reformated the doc --- .../configuration/cache-basics.en.rst | 30 +++++++++++-------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/doc/admin-guide/configuration/cache-basics.en.rst b/doc/admin-guide/configuration/cache-basics.en.rst index 14b60f51748..148ac92aa70 100644 --- a/doc/admin-guide/configuration/cache-basics.en.rst +++ b/doc/admin-guide/configuration/cache-basics.en.rst @@ -182,8 +182,8 @@ 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 to cache -only HTTP objects with ``Expires`` or ``max-age`` headers(default setting), then +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). @@ -375,7 +375,7 @@ Client Directives ----------------- Configurations can be set to determine whether to cache objects with the -following client directives (By default, Traffic Server caches objects with +following client directives (by default, Traffic Server caches objects with these request headers): - ``Cache-Control: no-store`` @@ -398,17 +398,17 @@ Configuring Traffic Server to Honor Client no-cache Headers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, Traffic Server ignores client ``Cache-Control: no-cache`` -directives. Even if a requested object contains a ``no-cache`` header, Traffic -Server serves the object from its cache. You can configure Traffic Server to -honor this header and forwards the request to the origin server even if it has a -fresh copy in 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. -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. +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 client directives with the -following: +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`. :: @@ -563,6 +563,12 @@ You can reconfigure Traffic Server to: - Cache all cookied content except text type. + It may be approprite 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: #. Edit :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies` in From 85de1b71e86e696254965be5997a4e1f6152c794 Mon Sep 17 00:00:00 2001 From: Zhengxi Li Date: Tue, 3 Jan 2023 23:25:37 +0000 Subject: [PATCH 4/5] Fixed typo --- doc/admin-guide/configuration/cache-basics.en.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/admin-guide/configuration/cache-basics.en.rst b/doc/admin-guide/configuration/cache-basics.en.rst index 148ac92aa70..273005b9b8d 100644 --- a/doc/admin-guide/configuration/cache-basics.en.rst +++ b/doc/admin-guide/configuration/cache-basics.en.rst @@ -563,7 +563,7 @@ You can reconfigure Traffic Server to: - Cache all cookied content except text type. - It may be approprite to configure Traffic Server to not cache cookied text + 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 From 53e0c0c1ecf15fc29726678b1103617ff9ca523a Mon Sep 17 00:00:00 2001 From: Zhengxi Li Date: Thu, 5 Jan 2023 20:31:28 +0000 Subject: [PATCH 5/5] Update doc for ignore_client_no_cache and ignore_server_no_cache Make it clear that what ATS would ignore with ignore_client_no_cache and ignore_server_no_cache. --- doc/admin-guide/files/records.config.en.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/admin-guide/files/records.config.en.rst b/doc/admin-guide/files/records.config.en.rst index 45cec12e56b..2c9c7e9926a 100644 --- a/doc/admin-guide/files/records.config.en.rst +++ b/doc/admin-guide/files/records.config.en.rst @@ -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: @@ -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: