Move some info to advanced settings page

Author: emirmx

content/en/docs/refguide/runtime/custom-settings/_index.md

@@ -52,7 +52,7 @@ The following custom settings can be configured:
 | <a id="ClientCertificates" href="#ClientCertificates">ClientCertificates</a> | Comma-separated list of paths to Client Certificates. Example: `D:\App\Mx1.pfx, D:\App\Mx2.pfx, D:\App\Mx3.pfx, D:\App\Mx4.pfx` | |
 | <a id="ClientCertificateUsages" href="#ClientCertificateUsages">ClientCertificateUsages</a> | Only use this when you have multiple client certificates and you want to configure specific certificates for specific servers.<br/> This setting defines which service must use which client certificate. See **NoClientCertificateUsages** if you want to make sure that no client certificate is used for a certain host or web service. The value of **ClientCertificateUsages** must be a comma-separated list of key/value items. A key/value item must be specified as `"identifier": "path to certificate"`.<br/>For web services, use the imported web service name as the identifier.<br/>For REST services, use the host name of the remote server as the identifier.<br/>Please note that any backslash in the path must be doubled. The whole value must be enclosed by braces (`{ }`). For example: {{< figure src="/attachments/refguide/runtime/custom-settings/code_snippet.png" class="no-border" >}} | |
 | <a id="NoClientCertificateUsages" href="#NoClientCertificateUsages">NoClientCertificateUsages</a> | Comma-separated list of host names or imported web service names that should never be contacted using a client certificate. | |
-| <a id="ClusterManagerActionInterval" href="#ClusterManagerActionInterval">ClusterManagerActionInterval</a> | The interval (in milliseconds) used for performing all cluster manager actions, such as unblocking users and removing invalid sessions. Must not exceed twice the [`SessionTimeout`](#SessionTimeout), or expired sessions may remain in the database too long. If explicitly set to a value exceeding twice the `SessionTimeout`, startup fails with an error. | 300000 (5 minutes).<br /> In Mendix 11.11.0 and above, if `SessionTimeout` ≤ 10 minutes and this default exceeds twice the `SessionTimeout`, `SessionTimeout` / 2 is used as the default (and a warning is logged). |
+| <a id="ClusterManagerActionInterval" href="#ClusterManagerActionInterval">ClusterManagerActionInterval</a> | The interval (in milliseconds) used for performing all cluster manager actions, such as unblocking users and removing invalid sessions. See [Advanced Custom Settings](/refguide/tricky-custom-runtime-settings/) for important details about valid values and their relationship to other session settings. | 300000 (5 minutes) |
 | <a id="commendixcoreisClusterSlave" href="#commendixcoreisClusterSlave">com.<wbr>mendix.<wbr>core.<wbr>isClusterSlave</a> | Set to `true` in a high-availability scenario when this is *not* the [Cluster Leader](/refguide/clustered-mendix-runtime/#cluster-leader-follower). The buildpack will usually enforce this setting, but it may need to be set for some on-premises deployments. | `false` |
 | <a id="commendixcoreLenientDateTimeParsing" href="#commendixcoreLenientDateTimeParsing">com.<wbr>mendix.<wbr>core.<wbr>LenientDateTimeParsing</a> | When set to `true`, the `parseDateTime` function will use more lenient parsing, as it did in Mendix 9. For example `parseDateTime("yyyyMMdd", "2021-11-10")` will return `2020-11-01` as a date if this is set to true, which is probably not the intended result.. If set to `false`, which is the default, this example will throw an error as it is expecting `20211110`. It is recommended to not enable this setting to avoid unexpected results. | `false` |
 | <a id="commendixcoreSameSiteCookies" href="#commendixcoreSameSiteCookies">com.<wbr>mendix.<wbr>core.<wbr>SameSiteCookies</a> | The [SameSite](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) property can be included in all cookies that are returned by the embedded HTTP server. The possible values are `Strict`, `Lax`, and `None`. The default is `Strict`. Setting it to `None` is typically needed only when an application is embedded in an iframe of another application with a different domain. Newer browsers may require the connection to be secure (HTTPS) when set to `None`. If the connection is plain HTTP, then this setting must be changed to `Strict` (recommended) or `Lax`. | |
@@ -73,7 +73,7 @@ The following custom settings can be configured:
 | <a id="JavaKeyStorePassword" href="#JavaKeyStorePassword">JavaKeyStorePassword</a> | Password for the default Java keystore. | changeit |
 | <a id="MyScheduledEvents" href="#MyScheduledEvents">MyScheduledEvents</a> | A comma-separated string with the names of the events. Please don't forget the name of the module (a name can be, for example, `CRM.UpdateCustomerStatistics`). {{% alert color="warning" %}}When running in multiple nodes, each node should have the same value for all runtime settings. Setting different values for different nodes to force specific scheduled events to be executed by specific nodes is not supported. It will not work and can lead to unexpected runtime errors.{{% /alert %}} | |
 | <a id="ScheduledEventExecution" href="#ScheduledEventExecution">ScheduledEventExecution</a> | Specify which scheduled events should be executed. Choices are `ALL`, `NONE`, or `SPECIFIED`. In the case of `SPECIFIED`, enumerate the scheduled events using the `MyScheduledEvents` configuration option described below. {{% alert color="warning" %}}This setting cannot be configured when running locally. To enable and disable scheduled events when running locally, please use the 'Enabled' setting on the [Scheduled Events execution properties](/refguide/scheduled-events/) in Studio Pro.{{% /alert %}} {{% alert color="warning" %}}When running in multiple nodes, each node should have the same value for all runtime settings. Setting different values for different nodes to force specific scheduled events to be executed by specific nodes is not supported. It will not work and can lead to unexpected runtime errors.{{% /alert %}} | NONE |
-| <a id="SessionKeepAliveUpdatesInterval" href="#SessionKeepAliveUpdatesInterval">SessionKeepAliveUpdatesInterval</a> | Defines how often a runtime writes session LastActive dates in its memory back to the database. The value must not be greater than half the [`ClusterManagerActionInterval`](#ClusterManagerActionInterval) and must not be greater than the [`SessionTimeout`](#SessionTimeout), or else active sessions may be cleaned up. | 100000 (100 seconds).<br />In Mendix 11.11.0 and above, if `SessionTimeout` or half the `ClusterManagerActionInterval` is less than or equal to 100 seconds, `ClusterManagerActionInterval` / 3 is used as the default (and a warning is logged).|
+| <a id="SessionKeepAliveUpdatesInterval" href="#SessionKeepAliveUpdatesInterval">SessionKeepAliveUpdatesInterval</a> | Defines how often a runtime writes session LastActive dates in its memory back to the database. See [Advanced Custom Settings](/refguide/tricky-custom-runtime-settings/) for important details about valid values and their relationship to other session settings. | 100000 (100 seconds) |
 | <a id="SessionTimeout" href="#SessionTimeout">SessionTimeout</a> | Defines after how much time a session becomes invalid (in milliseconds). After that timeout,  a session becomes eligible for removal. The session will not be destroyed until the next time a scheduled task runs to clean up the active sessions. <br> {{% alert color="warning" %}} Sessions can be removed immediately by a query to the runtime after the session becomes eligible for removal. Navigating between pages is not enough to trigger a query to the runtime. To force a query to the runtime, use a microflow. For example, create a microflow that shows the Home page, then configure your app's navigation to call this microflow rather than relying on the navigation to directly show the page itself. This will ensure the runtime is queried and the user session is removed. {{% /alert %}} | 600000 (10 minutes) |
 | <a id="AbsoluteSessionTimeout" href="#AbsoluteSessionTimeout">AbsoluteSessionTimeout</a> | Defines after how much time a session becomes invalid (in milliseconds). After that timeout, a session becomes eligible for removal. As opposed to the `SessionTimeout`, the `AbsoluteSessionTimeout` timeout is not affected by user interactions. This does not override [`SessionTimeout`](#SessionTimeout), sessions also become invalid if `SessionTimeout` is reached. The session will be destroyed in the same way as for [`SessionTimeout`](#SessionTimeout), above. If the setting is not set then this behavior is disabled, which is the default. | Disabled. *Introduced in Mendix 11.4.0.* |
 | <a id="SessionValidationTimeout" href="#SessionValidationTimeout">SessionValidationTimeout</a> | Defines the maximum caching time (in milliseconds) for sessions. This means that after signing out of a session, the session might still be accessible for the configured time on other nodes of the cluster, but only if that node has handled a previous request on that session just before the logout happened. Lowering it makes the cluster more secure, because the chance that the session is still accessible within the configured time window is smaller. However, this also requires more frequent roundtrips to the database (which impacts performance). Increasing the timeout has the opposite effect | 30000 (30 seconds) |

content/en/docs/refguide/runtime/custom-settings/tricky-custom-runtime-settings.md

@@ -29,8 +29,8 @@ The following custom settings can be configured:
 | --- | --- | --- |
 | `SessionTimeout` | Defines after how much time the session becomes invalid (in milliseconds). After that timeout, a session becomes applicable for removal. The session won't be destroyed until the next time the cluster manager evaluates the active sessions. | 600000 (10 minutes) |
 | `com.mendix.offline.DeleteAutoCommittedObjectsAfterSync` | Defines if auto-committed created during offline synchronization will be deleted from the database immediately. | true |
-| `ClusterManagerActionInterval` | The interval (in milliseconds) used for performing all cluster manager actions. These actions include unblocking users and removing invalid sessions. If nothing is specified, the interval is half the `SessionTimeout`. | 300000 (5 minutes) |
-| `SessionKeepAliveUpdatesInterval` | Defines after how much time expired sessions can be removed from the database. | one sixth of the value configured for the `SessionTimeout` setting; if the `SessionTimeout` is not set, this value defaults to 100000 (100 seconds) |
+| `ClusterManagerActionInterval` | The interval (in milliseconds) used for performing all cluster manager actions. These actions include unblocking users and removing invalid sessions. See the constraints section below for default value details. | |
+| `SessionKeepAliveUpdatesInterval` | Defines how often a runtime writes session LastActive dates in its memory back to the database. See the constraints section below for default value details. | |
 
 Increasing the session timeout can improve the user experience, especially on mobile devices. It is important to keep in mind that entities used to present data to the user or entities that are created or retrieved when a user executes a microflow are tied to that user's session, and those entities can remain in memory for long periods of time. When a user signs out, these entities will be removed from memory, but if the user idles but does not sign out (for example, if they leave the browser tab open while executing other tasks or simply close the browser without signing out), the session timeout can act as a safeguard that prevents memory usage from being tied up by idle sessions. The first case can also be mitigated by setting the `EnableKeepAlive` custom setting to false. On most browsers, this setting will ensure that any idle browser tab will be affected by the session timeout as well.
 
@@ -39,6 +39,26 @@ Since the frequency of the session timeout checks and other important events is
 Another consideration is that configuring `ClusterManagerActionInterval` to be much longer than the `SessionTimeout` will lead to expired sessions remaining in the database longer.
 Configuring `SessionKeepAliveUpdatesInterval` to be longer than the `ClusterManagerActionInterval` or configuring `SessionKeepAliveUpdatesInterval` to be longer than the `SessionTimeout` will cause active sessions to be cleaned up. The Runtime will fail to start if these three settings are not configured correctly.
 
+### Session Timing Constraints and Defaults
+
+The following constraints apply to `ClusterManagerActionInterval` and `SessionKeepAliveUpdatesInterval`:
+
+**ClusterManagerActionInterval:**
+
+* Must not exceed twice the `SessionTimeout`, or expired sessions may remain in the database too long
+* If explicitly set to a value exceeding twice the `SessionTimeout`, startup fails with an error
+* Default value:
+  * Before Mendix 11.11.0: 300000 (5 minutes), or half the `SessionTimeout` if not explicitly specified
+  * In Mendix 11.11.0 and above: 300000 (5 minutes), unless `SessionTimeout` ≤ 10 minutes and this default exceeds twice the `SessionTimeout`, in which case `SessionTimeout` / 2 is used (and a warning is logged)
+
+**SessionKeepAliveUpdatesInterval:**
+
+* Must not be greater than half the `ClusterManagerActionInterval`, or else active sessions may be cleaned up
+* Must not be greater than the `SessionTimeout`, or else active sessions may be cleaned up
+* Default value:
+  * Before Mendix 11.11.0: one sixth of the `SessionTimeout`, or 100000 (100 seconds) if `SessionTimeout` is not set
+  * In Mendix 11.11.0 and above: 100000 (100 seconds), unless `SessionTimeout` or half the `ClusterManagerActionInterval` is ≤ 100 seconds, in which case `ClusterManagerActionInterval` / 3 is used (and a warning is logged)
+
 With stateless runtime, the potential of memory usage leading to problems has been reduced for two reasons. The first reason is the ability to run in a horizontally scaled environment. Multiple runtimes will mean unintended memory usage is also divided over those runtimes, reducing the impact of any one idle user session. But the main (and second) reason is that most of the memory usage has been moved to the client. So instead of all entities in the memory ending up on the application node, a large share of them will end up in the browser of the client. This should significantly reduce the potential strain on the application node that can be caused by increasing the `SessionTimeout` default value to a much higher value.
 
 Another important matter that can be affected by increasing the session timeout is the user restrictions imposed by your Mendix license. Longer sessions might mean more concurrent users at any given time. This is something to keep in mind when deciding on the specifics of the license you will need to run your application.