From 3b5fa05f68ad641485834d8c1b6b480fc1db5c0d Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 26 Mar 2026 22:07:50 +0530 Subject: [PATCH 01/14] PSMDB-1947 LDAP User Cache Refresh options --- docs/authorization.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/authorization.md b/docs/authorization.md index c09969327..3f85fb3e6 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -120,6 +120,15 @@ For example, to set the number of connections in the pool to 5, use the [setPara ldapConnectionPoolSizePerHost: 5 ``` + +### LDAP cache refresh parameters + +As of version **7.0.17-31**, Percona Server for MongoDB introduces parameters to optimize authentication performance and reduce unnecessary load on the LDAP server. These settings control how cached user information is refreshed, allowing administrators to fine-tune the balance between maintaining up-to-date user data and minimizing LDAP query overhead—especially in high-scale environments with many concurrent users. + +- `ldapUserCacheRefreshInterval` defines how often (in seconds) the server refreshes cached user information from LDAP. + +- `ldapShouldRefreshUserCacheEntries` determines whether the refresh strategy is interval‑based (using `ldapUserCacheRefreshInterval`) or expiration‑based (using `ldapUserCacheInvalidationInterval`, already supported in PSMDB). + ### Support for multiple LDAP servers As of version 6.0.2-1, you can specify multiple LDAP servers for failover. Percona Server for MongoDB sends bind requests to the first server defined in the list. When this server is down or unavailable, it sends requests to the next server and so on. Note that Percona Server for MongoDB keeps sending requests to this server even after the unavailable server recovers. From bd8cc398c19453c467d938251b21fe65f3c0e152 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 26 Mar 2026 22:20:06 +0530 Subject: [PATCH 02/14] Update docs/authorization.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/authorization.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/authorization.md b/docs/authorization.md index 3f85fb3e6..73156723c 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -129,6 +129,32 @@ As of version **7.0.17-31**, Percona Server for MongoDB introduces parameters to - `ldapShouldRefreshUserCacheEntries` determines whether the refresh strategy is interval‑based (using `ldapUserCacheRefreshInterval`) or expiration‑based (using `ldapUserCacheInvalidationInterval`, already supported in PSMDB). +You can configure these parameters at runtime, on the command line, or in the configuration file. + +=== "Runtime (setParameter)" + + ```{.javascript data-prompt=">"} + > db.adminCommand({ + ... setParameter: 1, + ... ldapUserCacheRefreshInterval: 300, + ... ldapShouldRefreshUserCacheEntries: true + ... }) + ``` + +=== "Command line" + + ```bash + mongod --setParameter "ldapUserCacheRefreshInterval=300" \ + --setParameter "ldapShouldRefreshUserCacheEntries=true" + ``` + +=== "Configuration file" + + ```yaml + setParameter: + ldapUserCacheRefreshInterval: 300 + ldapShouldRefreshUserCacheEntries: true + ``` ### Support for multiple LDAP servers As of version 6.0.2-1, you can specify multiple LDAP servers for failover. Percona Server for MongoDB sends bind requests to the first server defined in the list. When this server is down or unavailable, it sends requests to the next server and so on. Note that Percona Server for MongoDB keeps sending requests to this server even after the unavailable server recovers. From 38a4fbebda0a05d51819035f0bc8b54da558c585 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 26 Mar 2026 22:20:33 +0530 Subject: [PATCH 03/14] Update docs/authorization.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/authorization.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/authorization.md b/docs/authorization.md index 73156723c..d7dbf5b75 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -125,10 +125,14 @@ For example, to set the number of connections in the pool to 5, use the [setPara As of version **7.0.17-31**, Percona Server for MongoDB introduces parameters to optimize authentication performance and reduce unnecessary load on the LDAP server. These settings control how cached user information is refreshed, allowing administrators to fine-tune the balance between maintaining up-to-date user data and minimizing LDAP query overhead—especially in high-scale environments with many concurrent users. -- `ldapUserCacheRefreshInterval` defines how often (in seconds) the server refreshes cached user information from LDAP. +- `ldapUserCacheRefreshInterval` defines how often (in seconds) the server refreshes cached user information from LDAP **when interval-based refresh is enabled** (see `ldapShouldRefreshUserCacheEntries` below). -- `ldapShouldRefreshUserCacheEntries` determines whether the refresh strategy is interval‑based (using `ldapUserCacheRefreshInterval`) or expiration‑based (using `ldapUserCacheInvalidationInterval`, already supported in PSMDB). +- `ldapShouldRefreshUserCacheEntries` selects the refresh strategy and has the following semantics: + - When set to `true`, the server uses **interval-based** refresh. Cached LDAP user entries are proactively refreshed on the schedule defined by `ldapUserCacheRefreshInterval`, regardless of their individual age, until they are explicitly removed or invalidated. + - When set to `false`, the server uses **expiration-based** refresh. Cached LDAP user entries are refreshed only when they have expired according to `ldapUserCacheInvalidationInterval` and are subsequently accessed. This preserves the behavior that existed before `ldapUserCacheRefreshInterval` and `ldapShouldRefreshUserCacheEntries` were introduced. + + The default value is `false` (expiration-based refresh using `ldapUserCacheInvalidationInterval`), to maintain backward-compatible behavior unless interval-based refreshing is explicitly enabled. You can configure these parameters at runtime, on the command line, or in the configuration file. === "Runtime (setParameter)" From cac5460f453a2883c3c12d69cab0355196967e39 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Thu, 26 Mar 2026 22:20:51 +0530 Subject: [PATCH 04/14] Update docs/authorization.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authorization.md b/docs/authorization.md index d7dbf5b75..9b8c350a8 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -123,7 +123,7 @@ For example, to set the number of connections in the pool to 5, use the [setPara ### LDAP cache refresh parameters -As of version **7.0.17-31**, Percona Server for MongoDB introduces parameters to optimize authentication performance and reduce unnecessary load on the LDAP server. These settings control how cached user information is refreshed, allowing administrators to fine-tune the balance between maintaining up-to-date user data and minimizing LDAP query overhead—especially in high-scale environments with many concurrent users. +As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to optimize authentication performance and reduce unnecessary load on the LDAP server. These settings control how cached user information is refreshed, allowing administrators to fine-tune the balance between maintaining up-to-date user data and minimizing LDAP query overhead—especially in high-scale environments with many concurrent users. - `ldapUserCacheRefreshInterval` defines how often (in seconds) the server refreshes cached user information from LDAP **when interval-based refresh is enabled** (see `ldapShouldRefreshUserCacheEntries` below). From fa305a45751e54fcb58b18c12ff5650eb31debea Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 27 Mar 2026 15:55:04 +0530 Subject: [PATCH 05/14] Update authorization.md --- docs/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authorization.md b/docs/authorization.md index 9b8c350a8..198f6d08e 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -130,7 +130,7 @@ As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to opt - `ldapShouldRefreshUserCacheEntries` selects the refresh strategy and has the following semantics: - When set to `true`, the server uses **interval-based** refresh. Cached LDAP user entries are proactively refreshed on the schedule defined by `ldapUserCacheRefreshInterval`, regardless of their individual age, until they are explicitly removed or invalidated. - - When set to `false`, the server uses **expiration-based** refresh. Cached LDAP user entries are refreshed only when they have expired according to `ldapUserCacheInvalidationInterval` and are subsequently accessed. This preserves the behavior that existed before `ldapUserCacheRefreshInterval` and `ldapShouldRefreshUserCacheEntries` were introduced. + - When set to `false`, all $external users are evicted from the user cache each `ldapUserCacheInvalidationInterval` seconds. This preserves the behavior that existed before `ldapUserCacheRefreshInterval` and `ldapShouldRefreshUserCacheEntries` were introduced. The default value is `false` (expiration-based refresh using `ldapUserCacheInvalidationInterval`), to maintain backward-compatible behavior unless interval-based refreshing is explicitly enabled. You can configure these parameters at runtime, on the command line, or in the configuration file. From cd69222c0c34747076cbad17484c4c3fad5bf06e Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 27 Mar 2026 16:46:33 +0530 Subject: [PATCH 06/14] Update authorization.md --- docs/authorization.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/authorization.md b/docs/authorization.md index 198f6d08e..f1d774028 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -129,11 +129,14 @@ As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to opt - `ldapShouldRefreshUserCacheEntries` selects the refresh strategy and has the following semantics: - - When set to `true`, the server uses **interval-based** refresh. Cached LDAP user entries are proactively refreshed on the schedule defined by `ldapUserCacheRefreshInterval`, regardless of their individual age, until they are explicitly removed or invalidated. + - When set to `true`, each cached $`external` user is periodically re-fetched from the LDAP server at the interval defined by `ldapUserCacheRefreshInterval`. The cache is updated only if the user’s roles have changed; otherwise, existing entries remain untouched, ensuring no disruption. If a user no longer exists in LDAP, their cache entry is invalidated individually. + - When set to `false`, all $external users are evicted from the user cache each `ldapUserCacheInvalidationInterval` seconds. This preserves the behavior that existed before `ldapUserCacheRefreshInterval` and `ldapShouldRefreshUserCacheEntries` were introduced. - The default value is `false` (expiration-based refresh using `ldapUserCacheInvalidationInterval`), to maintain backward-compatible behavior unless interval-based refreshing is explicitly enabled. -You can configure these parameters at runtime, on the command line, or in the configuration file. + The default value is `false` (expiration-based invalidation using `ldapUserCacheInvalidationInterval`), to maintain backward-compatible behavior unless interval-based refreshing is explicitly enabled. + +`ldapShouldRefreshUserCacheEntries` can only be set at startup. Interval parameters may be configured both at startup and during runtime. + === "Runtime (setParameter)" From ccb2db07ee594be4e219b0250b45737d5e1626cb Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 27 Mar 2026 16:58:37 +0530 Subject: [PATCH 07/14] Update authorization.md --- docs/authorization.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/authorization.md b/docs/authorization.md index f1d774028..88a004b8f 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -137,6 +137,8 @@ As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to opt `ldapShouldRefreshUserCacheEntries` can only be set at startup. Interval parameters may be configured both at startup and during runtime. +!!! note + The default value will be changed to **true** in all major versions released after March 1, 2026. === "Runtime (setParameter)" From ad2e6e18cc4221adea097eae1d7be038c993941b Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 27 Mar 2026 17:09:47 +0530 Subject: [PATCH 08/14] Update authorization.md --- docs/authorization.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/authorization.md b/docs/authorization.md index 88a004b8f..424528478 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -129,16 +129,16 @@ As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to opt - `ldapShouldRefreshUserCacheEntries` selects the refresh strategy and has the following semantics: - - When set to `true`, each cached $`external` user is periodically re-fetched from the LDAP server at the interval defined by `ldapUserCacheRefreshInterval`. The cache is updated only if the user’s roles have changed; otherwise, existing entries remain untouched, ensuring no disruption. If a user no longer exists in LDAP, their cache entry is invalidated individually. + - When set to `true`, each cached $`external` user is periodically re-fetched from the LDAP server at the interval defined by `ldapUserCacheRefreshInterval`. The cache is updated only if the user’s roles have changed; otherwise, existing entries remain untouched, ensuring no disruption. If a user no longer exists in LDAP, their cache entry is invalidated individually. - - When set to `false`, all $external users are evicted from the user cache each `ldapUserCacheInvalidationInterval` seconds. This preserves the behavior that existed before `ldapUserCacheRefreshInterval` and `ldapShouldRefreshUserCacheEntries` were introduced. + - When set to `false`, all `$external` users are evicted from the cache at intervals defined by `ldapUserCacheInvalidationInterval`. This preserves the behavior that existed prior to the introduction of `ldapUserCacheRefreshInterval` and `ldapShouldRefreshUserCacheEntries`. The default value is `false` (expiration-based invalidation using `ldapUserCacheInvalidationInterval`), to maintain backward-compatible behavior unless interval-based refreshing is explicitly enabled. -`ldapShouldRefreshUserCacheEntries` can only be set at startup. Interval parameters may be configured both at startup and during runtime. + `ldapShouldRefreshUserCacheEntries` can only be set at startup. Interval parameters may be configured both at startup and during runtime. -!!! note - The default value will be changed to **true** in all major versions released after March 1, 2026. + !!! note + The default value will be changed to **true** in all major versions released after March 1, 2026. === "Runtime (setParameter)" From 9fe3fc5eefd3e3ca98f4ff0f89514969aa0cecff Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 27 Mar 2026 17:16:03 +0530 Subject: [PATCH 09/14] Update authorization.md --- docs/authorization.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/authorization.md b/docs/authorization.md index 424528478..0a2067a80 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -138,6 +138,7 @@ As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to opt `ldapShouldRefreshUserCacheEntries` can only be set at startup. Interval parameters may be configured both at startup and during runtime. !!! note + The default value will be changed to **true** in all major versions released after March 1, 2026. === "Runtime (setParameter)" From 041e2efe1523e169141e0d9d05dc107fdf8f804e Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 27 Mar 2026 17:16:39 +0530 Subject: [PATCH 10/14] added warning instead of note --- docs/authorization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/authorization.md b/docs/authorization.md index 0a2067a80..16b7a7315 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -137,8 +137,8 @@ As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to opt `ldapShouldRefreshUserCacheEntries` can only be set at startup. Interval parameters may be configured both at startup and during runtime. - !!! note - + !!! warning + The default value will be changed to **true** in all major versions released after March 1, 2026. === "Runtime (setParameter)" From bc513eb4a4e8f86b7f4812f9e48dbdfeb04797eb Mon Sep 17 00:00:00 2001 From: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 27 Mar 2026 17:17:46 +0530 Subject: [PATCH 11/14] Update authorization.md --- docs/authorization.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/authorization.md b/docs/authorization.md index 16b7a7315..1b9f3a2cc 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -129,17 +129,16 @@ As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to opt - `ldapShouldRefreshUserCacheEntries` selects the refresh strategy and has the following semantics: - - When set to `true`, each cached $`external` user is periodically re-fetched from the LDAP server at the interval defined by `ldapUserCacheRefreshInterval`. The cache is updated only if the user’s roles have changed; otherwise, existing entries remain untouched, ensuring no disruption. If a user no longer exists in LDAP, their cache entry is invalidated individually. + - When set to `true`, each cached $`external` user is periodically re-fetched from the LDAP server at the interval defined by `ldapUserCacheRefreshInterval`. The cache is updated only if the user’s roles have changed; otherwise, existing entries remain untouched, ensuring no disruption. If a user no longer exists in LDAP, their cache entry is invalidated individually. - - When set to `false`, all `$external` users are evicted from the cache at intervals defined by `ldapUserCacheInvalidationInterval`. This preserves the behavior that existed prior to the introduction of `ldapUserCacheRefreshInterval` and `ldapShouldRefreshUserCacheEntries`. + - When set to `false`, all `$external` users are evicted from the cache at intervals defined by `ldapUserCacheInvalidationInterval`. This preserves the behavior that existed prior to the introduction of `ldapUserCacheRefreshInterval` and `ldapShouldRefreshUserCacheEntries`. - The default value is `false` (expiration-based invalidation using `ldapUserCacheInvalidationInterval`), to maintain backward-compatible behavior unless interval-based refreshing is explicitly enabled. + The default value is `false` (expiration-based invalidation using `ldapUserCacheInvalidationInterval`), to maintain backward-compatible behavior unless interval-based refreshing is explicitly enabled. - `ldapShouldRefreshUserCacheEntries` can only be set at startup. Interval parameters may be configured both at startup and during runtime. + `ldapShouldRefreshUserCacheEntries` can only be set at startup. Interval parameters may be configured both at startup and during runtime. - !!! warning - - The default value will be changed to **true** in all major versions released after March 1, 2026. + !!! warning + The default value will be changed to **true** in all major versions released after March 1, 2026. === "Runtime (setParameter)" From 34ca85836ce49a22f9e390e48eb3cb66dffa4a51 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 27 Mar 2026 17:40:03 +0530 Subject: [PATCH 12/14] Update docs/authorization.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authorization.md b/docs/authorization.md index 1b9f3a2cc..42850a67c 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -129,7 +129,7 @@ As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to opt - `ldapShouldRefreshUserCacheEntries` selects the refresh strategy and has the following semantics: - - When set to `true`, each cached $`external` user is periodically re-fetched from the LDAP server at the interval defined by `ldapUserCacheRefreshInterval`. The cache is updated only if the user’s roles have changed; otherwise, existing entries remain untouched, ensuring no disruption. If a user no longer exists in LDAP, their cache entry is invalidated individually. + - When set to `true`, each cached `$external` user is periodically re-fetched from the LDAP server at the interval defined by `ldapUserCacheRefreshInterval`. The cache is updated only if the user’s roles have changed; otherwise, existing entries remain untouched, ensuring no disruption. If a user no longer exists in LDAP, their cache entry is invalidated individually. - When set to `false`, all `$external` users are evicted from the cache at intervals defined by `ldapUserCacheInvalidationInterval`. This preserves the behavior that existed prior to the introduction of `ldapUserCacheRefreshInterval` and `ldapShouldRefreshUserCacheEntries`. From 829a92fe3f224e5773fb846e5d38d71f0482f0d9 Mon Sep 17 00:00:00 2001 From: Rasika Chivate <95711051+rasika-chivate@users.noreply.github.com> Date: Fri, 27 Mar 2026 17:40:26 +0530 Subject: [PATCH 13/14] Update docs/authorization.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/authorization.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/authorization.md b/docs/authorization.md index 42850a67c..65c9e3ccd 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -145,8 +145,7 @@ As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to opt ```{.javascript data-prompt=">"} > db.adminCommand({ ... setParameter: 1, - ... ldapUserCacheRefreshInterval: 300, - ... ldapShouldRefreshUserCacheEntries: true + ... ldapUserCacheRefreshInterval: 300 ... }) ``` From abd4e0b89874df08c0693304dd7bd25d4c8431f8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 12:14:01 +0000 Subject: [PATCH 14/14] Add description of ldapUserCacheInvalidationInterval parameter Agent-Logs-Url: https://github.com/percona/psmdb-docs/sessions/81d763b8-97e9-4465-9940-7a368d54973c Co-authored-by: rasika-chivate <95711051+rasika-chivate@users.noreply.github.com> --- docs/authorization.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/authorization.md b/docs/authorization.md index 65c9e3ccd..049e40ecc 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -127,6 +127,8 @@ As of version 7.0.17-31, Percona Server for MongoDB introduces parameters to opt - `ldapUserCacheRefreshInterval` defines how often (in seconds) the server refreshes cached user information from LDAP **when interval-based refresh is enabled** (see `ldapShouldRefreshUserCacheEntries` below). +- `ldapUserCacheInvalidationInterval` controls how long (in seconds) cached LDAP user entries remain valid before they expire and are evicted from the cache. If you do not set this parameter explicitly, Percona Server for MongoDB uses the built-in default for your version. This parameter applies when `ldapShouldRefreshUserCacheEntries` is set to `false`. + - `ldapShouldRefreshUserCacheEntries` selects the refresh strategy and has the following semantics: - When set to `true`, each cached `$external` user is periodically re-fetched from the LDAP server at the interval defined by `ldapUserCacheRefreshInterval`. The cache is updated only if the user’s roles have changed; otherwise, existing entries remain untouched, ensuring no disruption. If a user no longer exists in LDAP, their cache entry is invalidated individually.