Change non-boolean enabled configs to mode

Most "enabled" configurations are booleans that toggle on or off a
feature. But we have a few that are named "enabled" but actually take an
enumeration of values to control behavior. This is confusing
terminology. This patch keeps support for the enabled configuration as
currently named, adds a new "mode" configuration for these, and
deprecates the old "enabled" config in the docs.

proxy.config.ssl.session_cache.enabled was somewhat complicated: with
the 10.0.0 release, we implemented it as "value" to try to address the
issue of this patch just for that parameter, but kept the "enabled"
config description in the docs. So the docs were out of sync with the
code. This adds support for "enabled" and immediately deprecates that,
since users may have tried to use that, silently keeps support for
"value" in case that was used, and adds the now desired "mode"
configuration.

If a user passes both the deprecated "enabled" config as well as the new
"mode" config, then they must be the same value, otherwise an Emergency
message is logged because it is impossible for ATS to discern which
value should be used.

Aside from this Emergency log on mismatch just mentioned, this patch
should be backwards compatible without introducing any changes in
behavior for current configs.

Fixes: #11901

Author: bneradt

contrib/set_trafficserver.sh

@@ -46,7 +46,7 @@ function recordsConfig() {
     traffic_ctl config set proxy.config.exec_thread.autoconfig.scale 1.000000
 
     traffic_ctl config set proxy.config.accept_threads 1
-    traffic_ctl config set proxy.config.log.logging_enabled 0
+    traffic_ctl config set proxy.config.log.logging.mode 0
     traffic_ctl config set proxy.config.http.server_port 8080
     traffic_ctl config set proxy.config.url_remap.pristine_host_hdr 1
 

doc/admin-guide/files/logging.yaml.en.rst

@@ -289,7 +289,11 @@ filename               string      The name of the logfile relative to the defau
 format                 string      a string with a valid named format specification.
 header                 string      If present, emitted as the first line of each
                                    new log file.
-rolling_enabled        *see below* Determines the type of log rolling to use (or
+rolling_mode           *see below* Determines the type of log rolling to use (or
+                                   whether to disable rolling). Overrides
+                                   :ts:cv:`proxy.config.log.rolling.mode`.
+rolling_enabled        *see below* **Deprecated in 10.1.0**. Use ``rolling_mode``
+                                   instead. Determines the type of log rolling to use (or
                                    whether to disable rolling). Overrides
                                    :ts:cv:`proxy.config.log.rolling_enabled`.
 rolling_interval_sec   number      Interval in seconds between log file rolling.
@@ -310,12 +314,17 @@ filters                array of    The optional list of filter objects which
 ====================== =========== =================================================
 
 Enabling log rolling may be done globally in :file:`records.yaml`, or on a
-per-log basis by passing appropriate values for the ``rolling_enabled`` key. The
+per-log basis by passing appropriate values for the ``rolling_mode`` key. The
 latter method may also be used to effect different rolling settings for
 individual logs. The numeric values that may be passed are the same as used by
-:ts:cv:`proxy.config.log.rolling_enabled`. For convenience and readability,
+:ts:cv:`proxy.config.log.rolling.mode`. For convenience and readability,
 the following predefined variables may also be used in :file:`logging.yaml`:
 
+.. deprecated:: 10.1.0
+
+   The ``rolling_enabled`` parameter is deprecated. Use ``rolling_mode`` instead.
+   ``rolling_enabled`` will continue to work for backwards compatibility.
+
 log.roll.none
     Disable log rolling.
 
@@ -389,3 +398,18 @@ matched the REFRESH_HIT filter we created.
      format: summaryfmt
      filters:
      - refreshhitfilter
+
+The following is an example of a log specification that creates a rolling log
+that rolls every hour when the size reaches 100MB. This shows the new ``rolling_mode``
+parameter (recommended) which replaces the deprecated ``rolling_enabled`` parameter.
+Mode 4 combines both time and size rolling triggers.
+
+.. code:: yaml
+
+   logs:
+   - mode: ascii
+     filename: combined_rolling
+     format: minimalfmt
+     rolling_mode: 4                # Roll on time when size reached
+     rolling_interval_sec: 3600     # Check every hour
+     rolling_size_mb: 100           # Roll when 100MB is reached

doc/admin-guide/files/records.yaml.en.rst

@@ -320,6 +320,29 @@ System Variables
 
 .. ts:cv:: CONFIG proxy.config.output.logfile.rolling_enabled INT 0
    :reloadable:
+   :deprecated:
+
+   .. deprecated:: 10.1.0
+
+      This configuration is deprecated. Use :ts:cv:`proxy.config.output.logfile.rolling.mode` instead.
+
+   Specifies how the output log is rolled. You can specify the following values:
+
+   ===== ======================================================================
+   Value Description
+   ===== ======================================================================
+   ``0`` Disables output log rolling.
+   ``1`` Enables output log rolling at specific intervals (specified with the
+         :ts:cv:`proxy.config.output.logfile.rolling_interval_sec` variable).
+         The clock starts ticking on |TS| boot.
+   ``2`` Enables output log rolling when the output log reaches a specific size
+         (specified with :ts:cv:`proxy.config.output.logfile.rolling_size_mb`).
+   ``3`` Enables output log rolling at specific intervals or when the output log
+         reaches a specific size (whichever occurs first).
+   ===== ======================================================================
+
+.. ts:cv:: CONFIG proxy.config.output.logfile.rolling.mode INT 0
+   :reloadable:
 
    Specifies how the output log is rolled. You can specify the following values:
 
@@ -443,6 +466,35 @@ Thread Variables
    that :program:`traffic_server` crashes. ``-1`` means there is
    no limit. A value of ``0`` prevents core dump creation.
 
+.. ts:cv:: CONFIG proxy.config.mlock_enabled INT 0
+   :deprecated:
+
+   .. deprecated:: 10.1.0
+
+      This configuration is deprecated. Use :ts:cv:`proxy.config.mlock.mode` instead.
+
+   Controls memory locking behavior for Traffic Server:
+
+   ===== ======================================================================
+   Value Description
+   ===== ======================================================================
+   ``0`` Disabled - no memory locking.
+   ``1`` Enabled for important pages (e.g. cache directory).
+   ``2`` Enabled for all pages.
+   ===== ======================================================================
+
+.. ts:cv:: CONFIG proxy.config.mlock.mode INT 0
+
+   Controls memory locking behavior for Traffic Server:
+
+   ===== ======================================================================
+   Value Description
+   ===== ======================================================================
+   ``0`` No memory locking.
+   ``1`` Memory locking enabled for important pages (e.g. cache directory).
+   ``2`` Memory locking enabled for all pages.
+   ===== ======================================================================
+
 .. ts:cv:: CONFIG proxy.config.restart.stop_listening INT 0
    :reloadable:
 
@@ -967,6 +1019,11 @@ allow-plain
 .. ts:cv:: CONFIG proxy.config.http.response_server_enabled INT 1
    :reloadable:
    :overridable:
+   :deprecated:
+
+   .. deprecated:: 10.1.0
+
+      This configuration is deprecated. Use :ts:cv:`proxy.config.http.response_server.mode` instead.
 
    You can specify one of the following:
 
@@ -980,6 +1037,22 @@ allow-plain
          not have one already.
    ===== ======================================================================
 
+.. ts:cv:: CONFIG proxy.config.http.response_server.mode INT 1
+   :reloadable:
+   :overridable:
+
+   Specifies how the ``Server`` header is handled in responses:
+
+   ===== ======================================================================
+   Value Description
+   ===== ======================================================================
+   ``0`` No ``Server`` header is added to the response.
+   ``1`` The ``Server`` header is added according to
+         :ts:cv:`proxy.config.http.response_server_str`.
+   ``2`` The ``Server`` header is added only if the response from origin does
+         not have one already.
+   ===== ======================================================================
+
 .. ts:cv:: CONFIG proxy.config.http.response_server_str STRING ATS/${PACKAGE_VERSION}
    :reloadable:
    :overridable:
@@ -3175,6 +3248,11 @@ Logging Configuration
 
 .. ts:cv:: CONFIG proxy.config.log.logging_enabled INT 3
    :reloadable:
+   :deprecated:
+
+   .. deprecated:: 10.1.0
+
+      This configuration is deprecated. Use :ts:cv:`proxy.config.log.logging.mode` instead.
 
    Enables and disables event logging:
 
@@ -3189,6 +3267,22 @@ Logging Configuration
 
    Refer to :ref:`admin-logging` for more information on event logging.
 
+.. ts:cv:: CONFIG proxy.config.log.logging.mode INT 3
+   :reloadable:
+
+   Enables and disables event logging:
+
+   ===== ===================================================================
+   Value Effect
+   ===== ===================================================================
+   ``0`` Logging disabled.
+   ``1`` Log errors only.
+   ``2`` Log transactions only.
+   ``3`` Dual logging (errors and transactions).
+   ===== ===================================================================
+
+   Refer to :ref:`admin-logging` for more information on event logging.
+
 .. ts:cv:: CONFIG proxy.config.log.log_fast_buffer INT 0
    :reloadable:
 
@@ -3264,6 +3358,32 @@ Logging Configuration
 
 .. ts:cv:: CONFIG proxy.config.log.rolling_enabled INT 1
    :reloadable:
+   :deprecated:
+
+   .. deprecated:: 10.1.0
+
+      This configuration is deprecated. Use :ts:cv:`proxy.config.log.rolling.mode` instead.
+
+   Specifies how log files are rolled. You can specify the following values:
+
+   ===== ======================================================================
+   Value Description
+   ===== ======================================================================
+   ``0`` Disables log file rolling.
+   ``1`` Enables log file rolling at specific intervals during the day
+         (specified with the :ts:cv:`proxy.config.log.rolling_interval_sec` and
+         :ts:cv:`proxy.config.log.rolling_offset_hr` variables).
+   ``2`` Enables log file rolling when log files reach a specific size
+         (specified with :ts:cv:`proxy.config.log.rolling_size_mb`).
+   ``3`` Enables log file rolling at specific intervals during the day or when
+         log files reach a specific size (whichever occurs first).
+   ``4`` Enables log file rolling at specific intervals during the day when log
+         files reach a specific size (i.e. at a specified time if the file is
+         of the specified size).
+   ===== ======================================================================
+
+.. ts:cv:: CONFIG proxy.config.log.rolling.mode INT 1
+   :reloadable:
 
    Specifies how log files are rolled. You can specify the following values:
 
@@ -3497,16 +3617,37 @@ Diagnostic Logging Configuration
 
 .. ts:cv:: CONFIG proxy.config.diags.debug.enabled INT 0
    :reloadable:
+   :deprecated:
+
+   .. deprecated:: 10.1.0
+
+      This configuration is deprecated. Use :ts:cv:`proxy.config.diags.debug.mode` instead.
 
    When set to 1, enables logging for diagnostic messages whose log level is `diag` or `debug`.
 
    When set to 2, interprets the :ts:cv:`proxy.config.diags.debug.client_ip` setting determine whether diagnostic messages are logged.
 
    See the :ref:`Enable debug using traffic_ctl<traffic-control-command-server-debug>` for a convenient way to handle this.
 
+.. ts:cv:: CONFIG proxy.config.diags.debug.mode INT 0
+   :reloadable:
+
+   Controls diagnostic debug message logging:
+
+   ===== ======================================================================
+   Value Description
+   ===== ======================================================================
+   ``0`` Disables debug message logging.
+   ``1`` Enables logging for diagnostic messages whose log level is `diag` or `debug`.
+   ``2`` Interprets the :ts:cv:`proxy.config.diags.debug.client_ip` setting to
+         determine whether diagnostic messages are logged.
+   ===== ======================================================================
+
+   See the :ref:`Enable debug using traffic_ctl<traffic-control-command-server-debug>` for a convenient way to handle this.
+
 .. ts:cv:: CONFIG proxy.config.diags.debug.client_ip STRING NULL
 
-   if :ts:cv:`proxy.config.diags.debug.enabled` is set to 2, this value is tested against the source IP of the incoming connection.  If there is a match, all the diagnostic messages for that connection and the related outgoing connection will be logged.
+   if :ts:cv:`proxy.config.diags.debug.mode` is set to 2, this value is tested against the source IP of the incoming connection.  If there is a match, all the diagnostic messages for that connection and the related outgoing connection will be logged.
 
 .. ts:cv:: CONFIG proxy.config.diags.debug.tags STRING http|dns
 
@@ -3578,6 +3719,30 @@ Diagnostic Logging Configuration
 
 .. ts:cv:: CONFIG proxy.config.diags.logfile.rolling_enabled INT 0
    :reloadable:
+   :deprecated:
+
+   .. deprecated:: 10.1.0
+
+      This configuration is deprecated. Use :ts:cv:`proxy.config.diags.logfile.rolling.mode` instead.
+
+   Specifies how the diagnostics log is rolled. You can specify the following values:
+
+   ===== ======================================================================
+   Value Description
+   ===== ======================================================================
+   ``0`` Disables diagnostics log rolling.
+   ``1`` Enables diagnostics log rolling at specific intervals (specified with
+         :ts:cv:`proxy.config.diags.logfile.rolling_interval_sec`). The "clock"
+         starts ticking on |TS| startup.
+   ``2`` Enables diagnostics log rolling when the diagnostics log reaches a
+         specific size (specified with
+         :ts:cv:`proxy.config.diags.logfile.rolling_size_mb`).
+   ``3`` Enables diagnostics log rolling at specific intervals or when the
+         diagnostics log reaches a specific size (whichever occurs first).
+   ===== ======================================================================
+
+.. ts:cv:: CONFIG proxy.config.diags.logfile.rolling.mode INT 0
+   :reloadable:
 
    Specifies how the diagnostics log is rolled. You can specify the following values:
 
@@ -3959,6 +4124,11 @@ SSL Termination
   SSL session cache for the origin server.
 
 .. ts:cv:: CONFIG proxy.config.ssl.session_cache.enabled INT 2
+   :deprecated:
+
+   .. deprecated:: 10.1.0
+
+      This configuration is deprecated. Use :ts:cv:`proxy.config.ssl.session_cache.mode` instead.
 
    Enables the SSL session cache:
 
@@ -3972,13 +4142,27 @@ SSL Termination
          implementation.
    ===== ======================================================================
 
+.. ts:cv:: CONFIG proxy.config.ssl.session_cache.mode INT 2
+
+   Specifies how the SSL session cache is configured:
+
+   ===== ======================================================================
+   Value Description
+   ===== ======================================================================
+   ``0`` Disables the session cache entirely.
+   ``1`` Enables the session cache using OpenSSL's implementation.
+   ``2`` Default. Enables the session cache using |TS|'s implementation. This
+         implementation should perform much better than the OpenSSL
+         implementation.
+   ===== ======================================================================
+
 .. ts:cv:: CONFIG proxy.config.ssl.session_cache.timeout INT 0
 
   This configuration specifies the lifetime of SSL session cache
   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.enabled``)
+  ``proxy.config.ssl.session_cache.mode``)
 
    See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
 
@@ -4020,9 +4204,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.enabled`` is enabled because
+  Lowering this setting to ``1`` can be interesting when ``proxy.config.ssl.session_cache.mode`` 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.enabled``  is disabled, using the default value is recommended.
+  On the other hand, if ``proxy.config.ssl.session_cache.mode``  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.
 

doc/admin-guide/logging/rotation.en.rst

@@ -148,9 +148,9 @@ To set log file rolling options and/or configure |TS| to roll log files when
 they reach a certain size, adjust the following settings in
 :file:`records.yaml`:
 
-#. Enable log rolling with :ts:cv:`proxy.config.log.rolling_enabled`. ::
+#. Enable log rolling with :ts:cv:`proxy.config.log.rolling.mode`. ::
 
-    CONFIG proxy.config.log.rolling_enabled INT 1
+    CONFIG proxy.config.log.rolling.mode INT 1
 
 #. Configure the upper limit on log file size with
    :ts:cv:`proxy.config.log.rolling_size_mb`. ::

doc/admin-guide/logging/understanding.en.rst

@@ -40,7 +40,7 @@ Enabling Logs
 By default, |TS| creates both error and event log files and
 records system information in system log files. You can disable event
 logging and/or error logging by setting the configuration variable
-:ts:cv:`proxy.config.log.logging_enabled` in :file:`records.yaml`
+:ts:cv:`proxy.config.log.logging.mode` in :file:`records.yaml`
 to one of the following values:
 
 ===== =========================================================================

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.enabled`
+:ts:cv:`proxy.config.ssl.session_cache.mode`
 :ts:cv:`proxy.config.ssl.session_cache.size`
 
 Thread Types

doc/admin-guide/plugins/tcpinfo.en.rst

@@ -121,7 +121,7 @@ The following options may be specified in :file:`plugin.config`:
   This logfile option allows you to set logfile rolling behaviour of
   the output log file  without making any changes to the global
   logging configurations.  This option overrides the
-  :ts:cv:`proxy.config.output.logfile.rolling_enabled` setting in :file:`records.yaml`
+  :ts:cv:`proxy.config.output.logfile.rolling.mode` setting in :file:`records.yaml`
   for the ``tcpinfo`` plugin.  The setting may range from ``0`` to ``3``.
   ``0`` disables logfile rolling.  ``1`` is the ``default`` and enables logfile
   rolling at specific intervals set by ``--rolling-interval-sec`` discussed