This is an automated email from the ASF dual-hosted git repository.
maskit pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 0b8a88cdce Document records.yaml changes (#11702)
0b8a88cdce is described below
commit 0b8a88cdce15ab63ee7903cc5a629b62677c8532
Author: Damian Meden <[email protected]>
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 <[email protected]>
---
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 | 8 +++++++
6 files changed, 28 insertions(+), 20 deletions(-)
diff --git a/doc/admin-guide/files/records.yaml.en.rst
b/doc/admin-guide/files/records.yaml.en.rst
index 4b19da4798..2612ffed5b 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.
@@ -4187,7 +4187,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
@@ -4293,7 +4293,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 59330e35ad..3a2e96f277 100644
--- a/doc/release-notes/upgrading.en.rst
+++ b/doc/release-notes/upgrading.en.rst
@@ -131,6 +131,7 @@ Configuration Changes
The following incompatible changes to the configurations have been made in
this version of ATS.
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 following :file:`records.yaml` changes have been made:
@@ -160,6 +161,13 @@ The following :file:`records.yaml` changes have been made:
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
