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 <[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]> (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.
