proxy.config.ssl.session_cache.mode

In the 10.0.0 release, we renamed proxy.config.ssl.session_cache.enabled
to proxy.config.ssl.session_cache.value because enabled seemed incorrect
for a configuration that took a non-boolean enumeration of values. We
accidentially left the documentation describing
proxy.config.ssl.session_cache.enabled, however. In discussion about
this, we decided to rename such configurations to "mode" instead of
value. Another issue (#12412) records making these renames for 11.0.0.
This PR just addresses the current issues with
proxy.config.ssl.session_cache.enabled by:

* Adding implementation support for
  proxy.config.ssl.session_cache.enabled since we documented that
  already but document it as deprecated.
* Keep implementation support for proxy.config.ssl.session_cache.value
  since users might be using that.
* Add proxy.config.ssl.session_cache.mode as the preferred new mode.

The user can set values for any of these via:

* implicit default config values,
* plugin default values via TSMgmtIntCreate,
* explicit records.yaml values, or
* override via environment variable.

It will probably be a very rare user that implements any of these across
values, but in case they do, this patch implements a selection of the
finally chosen config value based on a priority base of the above, with
"mode" valued over "value" valued over "enabled".

Fixes: 11901

Author: bneradt

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

@@ -3958,9 +3958,9 @@ 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.enabled INT 2
+.. ts:cv:: CONFIG proxy.config.ssl.session_cache.mode INT 2
 
-   Enables the SSL session cache:
+   Sets the SSL session cache mode:
 
    ===== ======================================================================
    Value Description
@@ -3972,13 +3972,22 @@ SSL Termination
          implementation.
    ===== ======================================================================
 
+.. ts:cv:: CONFIG proxy.config.ssl.session_cache.enabled INT 2
+
+   .. deprecated:: 10.1.0
+      Use :ts:cv:`proxy.config.ssl.session_cache.mode` instead.
+
+   This configuration exists for historical reasons and is deprecated in favor of
+   :ts:cv:`proxy.config.ssl.session_cache.mode`. It accepts the same values and
+   has identical behavior, so see that documentation for details.
+
 .. 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 +4029,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/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/tools/converting-records-to-yaml.en.rst

@@ -158,7 +158,7 @@ Converting a file with a detailed output.
     ├──» #5 : proxy.config.ssl.TLSv1_3 -> proxy.config.ssl.TLSv1_3.enabled
     ├──» #6 : proxy.config.ssl.client.TLSv1_3 -> proxy.config.ssl.client.TLSv1_3.enabled
     ├──» #7 : proxy.config.ssl.origin_session_cache -> proxy.config.ssl.origin_session_cache.enabled
-    └──» #8 : proxy.config.ssl.session_cache -> proxy.config.ssl.session_cache.value
+    └──» #8 : proxy.config.ssl.session_cache -> proxy.config.ssl.session_cache.mode
 
 
 There are a few things to note here:

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.enabled` has been set to 2.
+session cache is enabled by setting :ts:cv:`proxy.config.ssl.session_cache.mode` has been set to 2.
 
 These functions tend to be used with the :enumerator:`TS_SSL_SESSION_HOOK`.
 

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.enabled` has been set to 2.
+use.  This means :ts:cv:`proxy.config.ssl.session_cache.mode` has been set to 2.
 
 The hook callback has the following signature
 

doc/release-notes/upgrading.en.rst

@@ -172,7 +172,7 @@ The following :file:`records.yaml` changes have been made:
 - 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.session_cache`` has been renamed to :ts:cv:`proxy.config.ssl.session_cache.mode`.
 - 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

include/records/RecDefs.h

@@ -115,11 +115,11 @@ enum RecCheckT {
 /// @internal @c REC_SOURCE_NULL is useful for a return value, I don't see using it in the actual data.
 /// @internal If this is changed, TSMgmtSource in apidefs.h.in must also be changed.
 enum RecSourceT {
-  REC_SOURCE_NULL,     ///< No source / value not set.
-  REC_SOURCE_DEFAULT,  ///< Built in default.
-  REC_SOURCE_PLUGIN,   ///< Plugin supplied default.
+  REC_SOURCE_NULL,     ///< No source / value not set. Not used in the actual data.
+  REC_SOURCE_DEFAULT,  ///< Built in records.yaml default.
+  REC_SOURCE_PLUGIN,   ///< Plugin supplied default. See TSMgmtIntCreate/TSMgmtStringCreate.
   REC_SOURCE_EXPLICIT, ///< Set by administrator (config file, external API, etc.)
-  REC_SOURCE_ENV       ///< Process environment variable.
+  REC_SOURCE_ENV       ///< Process environment variable override.
 };
 
 enum RecAccessT {

src/iocore/net/SSLConfig.cc

@@ -42,10 +42,13 @@
 #include "tscore/ink_config.h"
 #include "tscore/Layout.h"
 #include "records/RecHttp.h"
+#include "records/RecCore.h"
 
 #include <openssl/pem.h>
+#include <array>
 #include <cstring>
 #include <cmath>
+#include <unordered_map>
 
 int                SSLConfig::config_index                                = 0;
 int                SSLConfig::configids[]                                 = {0, 0};
@@ -89,6 +92,80 @@ DbgCtl dbg_ctl_ssl_client_ctx{"ssl_client_ctx"};
 
 } // end anonymous namespace
 
+/** Determines the SSL session cache configuration value using a priority-based selection scheme.
+ *
+ * This function resolves the SSL session cache configuration by evaluating multiple potential
+ * configuration sources and selecting the one with the highest priority. The priority calculation
+ * combines two factors:
+ *
+ * Configuration Name Priority (base priority):
+ * - `proxy.config.ssl.session_cache.mode`: 3 (highest preference)
+ * - `proxy.config.ssl.session_cache.value`: 2 (medium preference)
+ * - `proxy.config.ssl.session_cache.enabled`: 1 (lowest preference)
+ *
+ * Configuration Source Priority (added to base priority):
+ * - Environment variable (`REC_SOURCE_ENV`): +0x30 (highest precedence)
+ * - Explicit configuration (`REC_SOURCE_EXPLICIT`): +0x20 (config file, API)
+ * - Plugin default (`REC_SOURCE_PLUGIN`): +0x10 (plugin-supplied)
+ * - Built-in default (`REC_SOURCE_DEFAULT`): +0x00 (lowest precedence)
+ *
+ * Priority Calculation:
+ * `total_priority = base_priority + source_priority`
+ *
+ * Examples:
+ * - `mode` set via environment variable: 3 + 0x30 = 0x33 (highest possible)
+ * - `mode` set explicitly in config: 3 + 0x20 = 0x23
+ * - `value` set via environment variable: 2 + 0x30 = 0x32
+ * - `enabled` set explicitly in config: 1 + 0x20 = 0x21
+ *
+ * The configuration with the highest total priority is selected. This ensures that:
+ * 1. Environment variables always override other sources.
+ * 2. Among configurations from the same source, `mode` > `value` > `enabled`.
+ * 3. Explicit configuration overrides plugin defaults and built-in defaults.
+ *
+ * @return The SSL session cache mode value.
+ */
+static int
+get_ssl_session_cache_config()
+{
+  struct ConfigOption {
+    const char *name;     ///< Configuration parameter name (e.g., "proxy.config.ssl.session_cache.mode").
+    int         value;    ///< The configured value if explicitly set.
+    int         priority; ///< The inherit priority of the config name, higher is more preferred.
+  };
+
+  /// The priority of the source. Higher is more preferred.
+  std::unordered_map<int, int> source_priorities = {
+    {REC_SOURCE_ENV,      0x30},
+    {REC_SOURCE_EXPLICIT, 0x20},
+    {REC_SOURCE_PLUGIN,   0x10},
+    {REC_SOURCE_DEFAULT,  0x0 },
+    {REC_SOURCE_NULL,     0x0 }, // For completeness, no record should have this set.
+  };
+
+  std::array<ConfigOption, 3> configs = {
+    {
+     {"proxy.config.ssl.session_cache.mode", 0, 0x3},
+     {"proxy.config.ssl.session_cache.value", 0, 0x2},
+     {"proxy.config.ssl.session_cache.enabled", 0, 0x1},
+     }
+  };
+
+  // Loop over the config names, updating their priority score per their source.
+  auto *highest_priority_config = &configs[0];
+  for (auto &config : configs) {
+    RecSourceT source;
+    if (RecGetRecordSource(config.name, &source) == REC_ERR_OKAY) {
+      config.priority += source_priorities[source];
+      config.value     = RecGetRecordInt(config.name).value_or(0);
+      if (config.priority > highest_priority_config->priority) {
+        highest_priority_config = &config;
+      }
+    }
+  }
+  return highest_priority_config->value;
+}
+
 SSLConfigParams::SSLConfigParams()
 {
   ink_mutex_init(&ctxMapLock);
@@ -452,7 +529,8 @@ SSLConfigParams::initialize()
   // SSL session cache configurations
   ssl_origin_session_cache      = RecGetRecordInt("proxy.config.ssl.origin_session_cache.enabled").value_or(0);
   ssl_origin_session_cache_size = RecGetRecordInt("proxy.config.ssl.origin_session_cache.size").value_or(0);
-  ssl_session_cache             = RecGetRecordInt("proxy.config.ssl.session_cache.value").value_or(0);
+  ssl_session_cache             = get_ssl_session_cache_config();
+
   ssl_session_cache_size        = RecGetRecordInt("proxy.config.ssl.session_cache.size").value_or(0);
   ssl_session_cache_num_buckets = RecGetRecordInt("proxy.config.ssl.session_cache.num_buckets").value_or(0);
   ssl_session_cache_skip_on_contention =

src/records/RecordsConfig.cc

@@ -1193,7 +1193,11 @@ static const RecordElement RecordsConfig[] =
   ,
   {RECT_CONFIG, "proxy.config.ssl.origin_session_cache.size", RECD_INT, "10240", RECU_RESTART_TS, RR_NULL, RECC_NULL, nullptr, RECA_NULL}
   ,
-  {RECT_CONFIG, "proxy.config.ssl.session_cache.value", RECD_INT, "2", RECU_RESTART_TS, RR_NULL, RECC_NULL, nullptr, RECA_NULL}
+  {RECT_CONFIG, "proxy.config.ssl.session_cache.mode", RECD_INT, "2", RECU_RESTART_TS, RR_NULL, RECC_INT, "[0-2]", RECA_NULL}
+  ,
+  {RECT_CONFIG, "proxy.config.ssl.session_cache.enabled", RECD_INT, "2", RECU_RESTART_TS, RR_NULL, RECC_INT, "[0-2]", RECA_NULL}
+  ,
+  {RECT_CONFIG, "proxy.config.ssl.session_cache.value", RECD_INT, "2", RECU_RESTART_TS, RR_NULL, RECC_INT, "[0-2]", RECA_NULL}
   ,
   {RECT_CONFIG, "proxy.config.ssl.session_cache.size", RECD_INT, "102400", RECU_RESTART_TS, RR_NULL, RECC_NULL, nullptr, RECA_NULL}
   ,

tests/gold_tests/pluginTest/stek_share/stek_share.test.py

@@ -164,7 +164,7 @@
         'proxy.config.exec_thread.limit': 4,
         'proxy.config.ssl.server.cert.path': '{0}'.format(Test.RunDirectory),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(Test.RunDirectory),
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 1024,
         'proxy.config.ssl.session_cache.timeout': 7200,
         'proxy.config.ssl.session_cache.num_buckets': 16,
@@ -184,7 +184,7 @@
         'proxy.config.exec_thread.limit': 4,
         'proxy.config.ssl.server.cert.path': '{0}'.format(Test.RunDirectory),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(Test.RunDirectory),
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 1024,
         'proxy.config.ssl.session_cache.timeout': 7200,
         'proxy.config.ssl.session_cache.num_buckets': 16,
@@ -204,7 +204,7 @@
         'proxy.config.exec_thread.limit': 4,
         'proxy.config.ssl.server.cert.path': '{0}'.format(Test.RunDirectory),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(Test.RunDirectory),
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 1024,
         'proxy.config.ssl.session_cache.timeout': 7200,
         'proxy.config.ssl.session_cache.num_buckets': 16,
@@ -224,7 +224,7 @@
         'proxy.config.exec_thread.limit': 4,
         'proxy.config.ssl.server.cert.path': '{0}'.format(Test.RunDirectory),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(Test.RunDirectory),
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 1024,
         'proxy.config.ssl.session_cache.timeout': 7200,
         'proxy.config.ssl.session_cache.num_buckets': 16,
@@ -244,7 +244,7 @@
         'proxy.config.exec_thread.limit': 4,
         'proxy.config.ssl.server.cert.path': '{0}'.format(Test.RunDirectory),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(Test.RunDirectory),
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 1024,
         'proxy.config.ssl.session_cache.timeout': 7200,
         'proxy.config.ssl.session_cache.num_buckets': 16,