apache · bneradt · Aug 4, 2025 · Aug 1, 2025
diff --git a/doc/admin-guide/files/records.yaml.en.rst b/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.
 

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

diff --git a/doc/admin-guide/tools/converting-records-to-yaml.en.rst b/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:

diff --git 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.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`.
 

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
@@ -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
 

diff --git a/doc/release-notes/upgrading.en.rst b/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

diff --git a/include/records/RecDefs.h b/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 {

diff --git a/src/iocore/net/SSLConfig.cc b/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,87 @@ 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 changed the default value via TSMgmtIntCreate)
+ * - 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()
+{
+  //
+  // TODO: in 11.x, we can simply remove this function and use only proxy.config.ssl.session_cache.mode.
+  //
+
+  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;
+      }
+    } else {
+      // We need to update our logic here if any of these configs are removed.
+      ink_release_assert(false);
+    }
+  }
+  return highest_priority_config->value;
+}
+
 SSLConfigParams::SSLConfigParams()
 {
   ink_mutex_init(&ctxMapLock);
@@ -452,7 +536,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 =

diff --git a/src/records/RecordsConfig.cc b/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}
   ,

diff --git a/tests/gold_tests/pluginTest/stek_share/stek_share.test.py b/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,

diff --git a/tests/gold_tests/records/gold/full_records.yaml b/tests/gold_tests/records/gold/full_records.yaml
@@ -564,11 +564,11 @@ records:
         filename: null
     session_cache:
       auto_clear: 1
+      mode: 2
       num_buckets: 256
       size: 102400
       skip_cache_on_bucket_contention: 0
       timeout: 0
-      value: 2
   stop:
     shutdown_timeout: 0
   system:

diff --git a/tests/gold_tests/records/gold/renamed_records.gold b/tests/gold_tests/records/gold/renamed_records.gold
@@ -5,7 +5,7 @@
  ├──» #3 : proxy.config.hostdb -> proxy.config.hostdb.enabled
  ├──» #4 : proxy.config.tunnel.prewarm -> proxy.config.tunnel.prewarm.enabled
  ├──» #5 : proxy.config.ssl.origin_session_cache -> proxy.config.ssl.origin_session_cache.enabled
- ├──» #6 : proxy.config.ssl.session_cache -> proxy.config.ssl.session_cache.value
+ ├──» #6 : proxy.config.ssl.session_cache -> proxy.config.ssl.session_cache.mode
  ├──» #7 : proxy.config.ssl.TLSv1_3 -> proxy.config.ssl.TLSv1_3.enabled
  └──» #8 : proxy.config.ssl.client.TLSv1_3 -> proxy.config.ssl.client.TLSv1_3.enabled
 ```
diff --git a/tests/gold_tests/records/gold/renamed_records.yaml b/tests/gold_tests/records/gold/renamed_records.yaml
@@ -16,7 +16,7 @@ records:
     origin_session_cache:
       enabled: 0
     session_cache:
-      value: 0
+      mode: 0
   tunnel:
     prewarm:
       enabled: 0
diff --git a/tests/gold_tests/tls/tls_0rtt_server.test.py b/tests/gold_tests/tls/tls_0rtt_server.test.py
@@ -104,7 +104,7 @@
         'proxy.config.exec_thread.limit': 8,
         'proxy.config.ssl.server.cert.path': '{0}'.format(ts1.Variables.SSLDir),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(ts1.Variables.SSLDir),
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 512000,
         'proxy.config.ssl.session_cache.timeout': 7200,
         'proxy.config.ssl.session_cache.num_buckets': 32768,
@@ -133,7 +133,7 @@
         'proxy.config.exec_thread.limit': 8,
         'proxy.config.ssl.server.cert.path': '{0}'.format(ts1.Variables.SSLDir),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(ts1.Variables.SSLDir),
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 512000,
         'proxy.config.ssl.session_cache.timeout': 7200,
         'proxy.config.ssl.session_cache.num_buckets': 32768,

diff --git a/tests/gold_tests/tls/tls_origin_session_reuse.test.py b/tests/gold_tests/tls/tls_origin_session_reuse.test.py
@@ -64,7 +64,7 @@
         'proxy.config.ssl.server.cert.path': '{0}'.format(ts1.Variables.SSLDir),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(ts1.Variables.SSLDir),
         'proxy.config.exec_thread.autoconfig.scale': 1.0,
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 4096,
         'proxy.config.ssl.session_cache.num_buckets': 256,
         'proxy.config.ssl.session_cache.skip_cache_on_bucket_contention': 0,
@@ -83,7 +83,7 @@
         'proxy.config.ssl.server.cert.path': '{0}'.format(ts2.Variables.SSLDir),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(ts2.Variables.SSLDir),
         'proxy.config.exec_thread.autoconfig.scale': 1.0,
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 4096,
         'proxy.config.ssl.session_cache.num_buckets': 256,
         'proxy.config.ssl.session_cache.skip_cache_on_bucket_contention': 0,
@@ -100,7 +100,7 @@
         'proxy.config.ssl.server.cert.path': '{0}'.format(ts3.Variables.SSLDir),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(ts3.Variables.SSLDir),
         'proxy.config.exec_thread.autoconfig.scale': 1.0,
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 4096,
         'proxy.config.ssl.session_cache.num_buckets': 256,
         'proxy.config.ssl.session_cache.skip_cache_on_bucket_contention': 0,
@@ -119,7 +119,7 @@
         'proxy.config.ssl.server.cert.path': '{0}'.format(ts4.Variables.SSLDir),
         'proxy.config.ssl.server.private_key.path': '{0}'.format(ts4.Variables.SSLDir),
         'proxy.config.exec_thread.autoconfig.scale': 1.0,
-        'proxy.config.ssl.session_cache.value': 2,
+        'proxy.config.ssl.session_cache.mode': 2,
         'proxy.config.ssl.session_cache.size': 4096,
         'proxy.config.ssl.session_cache.num_buckets': 256,
         'proxy.config.ssl.session_cache.skip_cache_on_bucket_contention': 0,