You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by cm...@apache.org on 2024/08/20 14:58:54 UTC
(trafficserver) 01/06: Document records.yaml changes (#11702)
This is an automated email from the ASF dual-hosted git repository.
cmcfarlen pushed a commit to branch 10.0.x
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
commit a48fd33e4e8ed63d11f2745b70d361136e2be7c6
Author: Damian Meden <dm...@apache.org>
AuthorDate: Sat Aug 17 00:47:07 2024 +0200
Document records.yaml changes (#11702)
* Document records.yaml changes
* Update links
---------
Co-authored-by: Chris McFarlen <ch...@mcfarlen.us>
(cherry picked from commit 0b8a88cdce15ab63ee7903cc5a629b62677c8532)
---
doc/admin-guide/files/records.yaml.en.rst | 26 ++++++------
doc/admin-guide/files/sni.yaml.en.rst | 8 ++--
doc/admin-guide/performance/index.en.rst | 2 +-
.../api/functions/TSSslSession.en.rst | 2 +-
.../hooks-and-transactions/ssl-session-api.en.rst | 2 +-
doc/release-notes/upgrading.en.rst | 48 +++++++++++++++++++++-
6 files changed, 66 insertions(+), 22 deletions(-)
diff --git a/doc/admin-guide/files/records.yaml.en.rst b/doc/admin-guide/files/records.yaml.en.rst
index 7f9d1ab148..c1a1e85a01 100644
--- a/doc/admin-guide/files/records.yaml.en.rst
+++ b/doc/admin-guide/files/records.yaml.en.rst
@@ -281,14 +281,14 @@ System Variables
of the contents and interpretations of log files.
-.. ts:cv:: CONFIG proxy.config.output.logfile STRING traffic.out
+.. ts:cv:: CONFIG proxy.config.output.logfile.name STRING traffic.out
This is used for log rolling configuration so |TS| knows the path of the
output file that should be rolled. This configuration takes the name of the
file receiving :program:`traffic_server`
process output that is set via the ``--bind_stdout`` and ``--bind_stderr``
:ref:`command-line options <traffic_server>`.
- :ts:cv:`proxy.config.output.logfile` is used only to identify the name of
+ :ts:cv:`proxy.config.output.logfile.name` is used only to identify the name of
the output file for log rolling purposes and does not override the values
set via ``--bind_stdout`` and ``--bind_stderr``.
@@ -3289,7 +3289,7 @@ Logging Configuration
If set to a non-zero value :arg:`N` then any connection that takes longer than :arg:`N` milliseconds from accept to
completion will cause its timing stats to be written to the :ts:cv:`debugging log file
- <proxy.config.output.logfile>`. This is identifying data about the transaction and all of the :cpp:type:`transaction milestones <TSMilestonesType>`.
+ <proxy.config.output.logfile.name>`. This is identifying data about the transaction and all of the :cpp:type:`transaction milestones <TSMilestonesType>`.
.. ts:cv:: CONFIG proxy.config.http2.connection.slow.log.threshold INT 0
:reloadable:
@@ -3298,7 +3298,7 @@ Logging Configuration
If set to a non-zero value :arg:`N` then any HTTP/2 connection
that takes longer than :arg:`N` milliseconds from open to close will cause
its timing stats to be written to the :ts:cv:`debugging log file
- <proxy.config.output.logfile>`. This is identifying data about the
+ <proxy.config.output.logfile.name>`. This is identifying data about the
transaction and all of the :cpp:type:`transaction milestones <TSMilestonesType>`.
.. ts:cv:: CONFIG proxy.config.http2.stream.slow.log.threshold INT 0
@@ -3308,7 +3308,7 @@ Logging Configuration
If set to a non-zero value :arg:`N` then any HTTP/2 stream
that takes longer than :arg:`N` milliseconds from open to close will cause
its timing stats to be written to the :ts:cv:`debugging log file
- <proxy.config.output.logfile>`. This is identifying data about the
+ <proxy.config.output.logfile.name>`. This is identifying data about the
transaction and all of the :cpp:type:`transaction milestones <TSMilestonesType>`.
.. ts:cv:: CONFIG proxy.config.log.config.filename STRING logging.yaml
@@ -3722,7 +3722,7 @@ SSL Termination
Enables (``1``) or disables (``0``) TLS v1.2. If not specified, enabled by default. [Requires OpenSSL v1.0.1 and higher]
-.. ts:cv:: CONFIG proxy.config.ssl.TLSv1_3 INT 1
+.. ts:cv:: CONFIG proxy.config.ssl.TLSv1_3.enabled INT 1
:deprecated:
This setting is deprecated in favor of :ts:cv:`proxy.config.ssl.server.version.min` and
@@ -3843,7 +3843,7 @@ SSL Termination
a single segment after ~1 second of inactivity and the record size ramping
mechanism is repeated again.
-.. ts:cv:: CONFIG proxy.config.ssl.origin_session_cache INT 1
+.. ts:cv:: CONFIG proxy.config.ssl.origin_session_cache.enabled INT 1
This configuration enables the SSL session cache for the origin server
when set to ``1``.
@@ -3858,7 +3858,7 @@ SSL Termination
Setting a value less than or equal to ``0`` effectively disables
SSL session cache for the origin server.
-.. ts:cv:: CONFIG proxy.config.ssl.session_cache INT 2
+.. ts:cv:: CONFIG proxy.config.ssl.session_cache.enabled INT 2
Enables the SSL session cache:
@@ -3878,7 +3878,7 @@ SSL Termination
entries in seconds. If it is ``0``, then the SSL library will use
a default value, typically 300 seconds. Note: This option has no affect
when using the |TS| session cache (option ``2`` in
- ``proxy.config.ssl.session_cache``)
+ ``proxy.config.ssl.session_cache.enabled``)
See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
@@ -3920,9 +3920,9 @@ SSL Termination
Take into account that setting the value to 0 will disable session caching for TLSv1.3
connections.
- Lowering this setting to ``1`` can be interesting when ``proxy.config.ssl.session_cache`` is enabled because
+ Lowering this setting to ``1`` can be interesting when ``proxy.config.ssl.session_cache.enabled`` is enabled because
otherwise for every new TLSv1.3 connection two session IDs will be inserted in the session cache.
- On the other hand, if ``proxy.config.ssl.session_cache`` is disabled, using the default value is recommended.
+ On the other hand, if ``proxy.config.ssl.session_cache.enabled`` is disabled, using the default value is recommended.
In those scenarios, increasing the number of tickets could be potentially beneficial for clients performing
multiple requests over concurrent TLS connections as per RFC 8446 clients SHOULDN'T reuse TLS Tickets.
@@ -4182,7 +4182,7 @@ Client-Related Configuration
Enables (``1``) or disables (``0``) TLSv1_2 in the ATS client context. If not specified, enabled by default
-.. ts:cv:: CONFIG proxy.config.ssl.client.TLSv1_3 INT 1
+.. ts:cv:: CONFIG proxy.config.ssl.client.TLSv1_3.enabled INT 1
:deprecated:
This setting is deprecated in favor of :ts:cv:`proxy.config.ssl.client.version.min` and
@@ -4288,7 +4288,7 @@ SNI Routing
Frequency of checking the activity of SNI Routing Tunnel. Set to ``0`` to disable monitoring of the activity of the SNI tunnels.
The feature is disabled by default.
-.. ts:cv:: CONFIG proxy.config.tunnel.prewarm INT 0
+.. ts:cv:: CONFIG proxy.config.tunnel.prewarm.enabled INT 0
Enable :ref:`pre-warming-tls-tunnel`. The feature is disabled by default.
diff --git a/doc/admin-guide/files/sni.yaml.en.rst b/doc/admin-guide/files/sni.yaml.en.rst
index 191fefb010..569d176f9c 100644
--- a/doc/admin-guide/files/sni.yaml.en.rst
+++ b/doc/admin-guide/files/sni.yaml.en.rst
@@ -155,7 +155,7 @@ valid_tls_version_min_in Inbound This specifies the minimum TL
the TLS negotiation. This replaces the global settings in
:ts:cv:`proxy.config.ssl.server.version.min`,
:ts:cv:`proxy.config.ssl.TLSv1`, :ts:cv:`proxy.config.ssl.TLSv1_1`,
- :ts:cv:`proxy.config.ssl.TLSv1_2`, and :ts:cv:`proxy.config.ssl.TLSv1_3`. The potential
+ :ts:cv:`proxy.config.ssl.TLSv1_2`, and :ts:cv:`proxy.config.ssl.TLSv1_3.enabled`. The potential
values are TLSv1, TLSv1_1, TLSv1_2, and TLSv1_3. This key is only valid for OpenSSL
1.1.0 and later and BoringSSL. Older versions of OpenSSL do not provide a hook early enough to update
the SSL object. It is a syntax error for |TS| built against earlier versions.
@@ -164,7 +164,7 @@ valid_tls_version_max_in Inbound This specifies the minimum TL
the TLS negotiation. This replaces the global settings in
:ts:cv:`proxy.config.ssl.server.version.max`,
:ts:cv:`proxy.config.ssl.TLSv1`, :ts:cv:`proxy.config.ssl.TLSv1_1`,
- :ts:cv:`proxy.config.ssl.TLSv1_2`, and :ts:cv:`proxy.config.ssl.TLSv1_3`. The potential
+ :ts:cv:`proxy.config.ssl.TLSv1_2`, and :ts:cv:`proxy.config.ssl.TLSv1_3.enabled`. The potential
values are TLSv1, TLSv1_1, TLSv1_2, and TLSv1_3. This key is only valid for OpenSSL
1.1.0 and later and BoringSSL. Older versions of OpenSSL do not provide a hook early enough to update
the SSL object. It is a syntax error for |TS| built against earlier versions.
@@ -172,7 +172,7 @@ valid_tls_version_max_in Inbound This specifies the minimum TL
valid_tls_versions_in Inbound Deprecated. This specifies the list of TLS protocols that will be offered to user agents during
the TLS negotiation. This replaces the global settings in
:ts:cv:`proxy.config.ssl.TLSv1`, :ts:cv:`proxy.config.ssl.TLSv1_1`,
- :ts:cv:`proxy.config.ssl.TLSv1_2`, and :ts:cv:`proxy.config.ssl.TLSv1_3`. The potential
+ :ts:cv:`proxy.config.ssl.TLSv1_2`, and :ts:cv:`proxy.config.ssl.TLSv1_3.enabled`. The potential
values are TLSv1, TLSv1_1, TLSv1_2, and TLSv1_3. You must list all protocols that |TS|
should offer to the client when using this key. This key is only valid for OpenSSL
1.1.0 and later and BoringSSL. Older versions of OpenSSL do not provide a hook early enough to update
@@ -295,7 +295,7 @@ Pre-warming TLS Tunnel
=============================== ========================================================================================
Key Meaning
=============================== ========================================================================================
-tunnel_prewarm Override :ts:cv:`proxy.config.tunnel.prewarm` in records.yaml.
+tunnel_prewarm Override :ts:cv:`proxy.config.tunnel.prewarm.enabled` in records.yaml.
tunnel_prewarm_srv Enable SRV record lookup on pre-warming. Default is ``false``.
diff --git a/doc/admin-guide/performance/index.en.rst b/doc/admin-guide/performance/index.en.rst
index 797d543965..689ef41ea4 100644
--- a/doc/admin-guide/performance/index.en.rst
+++ b/doc/admin-guide/performance/index.en.rst
@@ -528,7 +528,7 @@ SSL-Specific Options
~~~~~~~~~~~~~~~~~~~~
:ts:cv:`proxy.config.ssl.max_record_size`
-:ts:cv:`proxy.config.ssl.session_cache`
+:ts:cv:`proxy.config.ssl.session_cache.enabled`
:ts:cv:`proxy.config.ssl.session_cache.size`
Thread Types
diff --git a/doc/developer-guide/api/functions/TSSslSession.en.rst b/doc/developer-guide/api/functions/TSSslSession.en.rst
index 0c43b6faac..2e0ab9230b 100644
--- a/doc/developer-guide/api/functions/TSSslSession.en.rst
+++ b/doc/developer-guide/api/functions/TSSslSession.en.rst
@@ -38,7 +38,7 @@ Description
===========
These functions work with the internal ATS session cache. These functions are only useful if the ATS internal
-session cache is enabled by setting :ts:cv:`proxy.config.ssl.session_cache` has been set to 2.
+session cache is enabled by setting :ts:cv:`proxy.config.ssl.session_cache.enabled` has been set to 2.
These functions tend to be used with the :enumerator:`TS_SSL_SESSION_HOOK`.
diff --git a/doc/developer-guide/plugins/hooks-and-transactions/ssl-session-api.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/ssl-session-api.en.rst
index 32b89a570a..d6f050872d 100644
--- a/doc/developer-guide/plugins/hooks-and-transactions/ssl-session-api.en.rst
+++ b/doc/developer-guide/plugins/hooks-and-transactions/ssl-session-api.en.rst
@@ -31,7 +31,7 @@ to enable the plugin to update the session cache based on outside information, e
This hook is invoked when a change has been made to the ATS session cache or a session has been accessed
from ATS via OpenSSL. These hooks are only activated if the ATS implementation of the session cache is in
-use. This means :ts:cv:`proxy.config.ssl.session_cache` has been set to 2.
+use. This means :ts:cv:`proxy.config.ssl.session_cache.enabled` has been set to 2.
The hook callback has the following signature
diff --git a/doc/release-notes/upgrading.en.rst b/doc/release-notes/upgrading.en.rst
index 9ea3fcffa5..cba3b3d419 100644
--- a/doc/release-notes/upgrading.en.rst
+++ b/doc/release-notes/upgrading.en.rst
@@ -64,11 +64,55 @@ Configuration changes
---------------------
The following incompatible changes to the configurations have been made in this version of ATS.
-The records.yaml entry proxy.config.http.down_server.abort_threshold has been removed.
+The ``records.config`` file has been renamed to :file:`records.yaml` and now it is structured in YAML format.
+Check :ref:`rec-config-to-yaml` and :file:`records.yaml` for more details.
The records.yaml entry proxy.config.http.connect_attempts_max_retries_dead_server has been renamed to proxy.config.http.connect_attempts_max_retries_down_server.
-The records.yaml entry proxy.config.http.connect.dead.policy has been renamed to proxy.config.http.connect.down.policy.
+- The records.yaml entry ``proxy.config.http.down_server.abort_threshold`` has been removed.
+- The records.yaml entry ``proxy.config.http.connect_attempts_max_retries_dead_server`` has been renamed to :ts:cv:`proxy.config.http.connect_attempts_max_retries_down_server`.
+- The entry ``proxy.config.http.connect.dead.policy`` has been renamed to :ts:cv:`proxy.config.http.connect.down.policy`.
+- The records.yaml entry ``proxy.config.http.parent_proxy.connect_attempts_timeout`` and
+ ``proxy.config.http.post_connect_attempts_timeout`` have been removed. Instead use
+ :ts:cv:`proxy.config.http.connect_attempts_timeout` to control all connection to origin timeouts.
+- The per server origin connection feature had a few configurations that were not used removed.
+ ``proxy.config.http.per_server.connection.queue_size`` and ``proxy.config.http.per_server.connection.queue_delay``
+ have been removed.
+- The default value for records.yaml entry ``proxy.config.ssl.client.verify.server.policy`` has been changed
+ from ``PERMISSIVE`` to ``STRICT``.
+- The records.yaml entry ``proxy.config.http.keepalive_internal_vc`` has been removed. This entry
+ was previously undocumented.
+- The records.yaml entries ``proxy.config.http.parent_proxy.connect_attempts_timeout`` and
+ ``proxy.config.http.post_connect_attempts_timeout`` were previously referenced in default config
+ files, but they did not have any effect. These have been removed from default configs files.
+- The default values for :ts:cv:`proxy.config.http.request_header_max_size`, :ts:cv:`proxy.config.http.response_header_max_size`, and
+ :ts:cv:`proxy.config.http.header_field_max_size` have been changed to 32KB.
+- The records.yaml entry :ts:cv:`proxy.config.http.server_ports` now also accepts the
+ ``allow-plain`` option
+- The records.yaml entry :ts:cv:`proxy.config.http.cache.max_open_write_retry_timeout` has been added to specify a timeout for starting a write to cache
+- The records.yaml entry :ts:cv:`proxy.config.net.per_client.max_connections_in` has
+ been added to limit the number of connections from a client IP. This works the
+ same as :ts:cv:`proxy.config.http.per_server.connection.max`
+- The records.yaml entry :ts:cv:`proxy.config.http.no_dns_just_forward_to_parent` is
+ not overridable
+- The records.yaml entry ``proxy.config.output.logfile`` has been renamed to :ts:cv:`proxy.config.output.logfile.name`.
+- The records.yaml entry ``proxy.config.exec_thread.autoconfig`` has been renamed to :ts:cv:`proxy.config.exec_thread.autoconfig.enabled`.
+- The records.yaml entry ``proxy.config.tunnel.prewarm`` has been renamed to :ts:cv:`proxy.config.tunnel.prewarm.enabled`.
+- The records.yaml entry ``proxy.config.ssl.origin_session_cache`` has been renamed to :ts:cv:`proxy.config.ssl.origin_session_cache.enabled`.
+- The records.yaml entry ``proxy.config.ssl.session_cache`` has been renamed to :ts:cv:`proxy.config.ssl.session_cache.enabled`.
+- The records.yaml entry ``proxy.config.ssl.TLSv1_3`` has been renamed to :ts:cv:`proxy.config.ssl.TLSv1_3.enabled`.
+- The records.yaml entry ``proxy.config.ssl.client.TLSv1_3`` has been renamed to :ts:cv:`proxy.config.ssl.client.TLSv1_3.enabled`.
+- The records.yaml entry :ts:cv:`proxy.config.allocator.iobuf_chunk_sizes` has been added
+ to enable more control of iobuffer allocation.
+- The records.yaml entry :ts:cv:`proxy.config.allocator.hugepages` will enable
+ allocating iobuffers and cache volumes from hugepages if configured in the
+ system.
+
+The following changes have been made to the :file:`sni.yaml` file:
+
+- ``disable_h2`` has been removed. Use ``http2`` with :code:`off` instead.
+- The ``ip_allow`` key can now take a reference to a file containing the ip
+ allow rules
The records.yaml entry proxy.config.http.parent_proxy.connect_attempts_timeout and proxy.config.http.post_connect_attempts_timeout
have been removed. Instead use proxy.config.http.connect_attempts_timeout to control all connection to origin timeouts.