diff --git a/content/en/docs/refguide/runtime/custom-settings/_index.md b/content/en/docs/refguide/runtime/custom-settings/_index.md index 1a5f48d8766..aad5a5f0007 100644 --- a/content/en/docs/refguide/runtime/custom-settings/_index.md +++ b/content/en/docs/refguide/runtime/custom-settings/_index.md @@ -52,7 +52,7 @@ The following custom settings can be configured: | ClientCertificates | 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` | | | ClientCertificateUsages | Only use this when you have multiple client certificates and you want to configure specific certificates for specific servers.
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"`.
For web services, use the imported web service name as the identifier.
For REST services, use the host name of the remote server as the identifier.
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" >}} | | | NoClientCertificateUsages | Comma-separated list of host names or imported web service names that should never be contacted using a client certificate. | | -| 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) | +| ClusterManagerActionInterval | The interval (in milliseconds) used for performing all cluster manager actions. These are actions such as unblocking users and removing invalid sessions. See [Session Timing Constraints and Defaults](/refguide/tricky-custom-runtime-settings/#session-timing) in *Advanced Custom Settings* for important details about valid values and their relationship to other session settings. | 300000 (5 minutes) | | com.mendix.core.isClusterSlave | 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` | | com.mendix.core.LenientDateTimeParsing | 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` | | com.mendix.core.SameSiteCookies | 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,9 +73,9 @@ The following custom settings can be configured: | JavaKeyStorePassword | Password for the default Java keystore. | changeit | | MyScheduledEvents | 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 %}} | | | ScheduledEventExecution | 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 | -| SessionKeepAliveUpdatesInterval | Defines how often a runtime writes session LastActive dates in its memory back to 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) | +| SessionKeepAliveUpdatesInterval | Defines how often a runtime writes session LastActive dates in its memory back to the database. See [Session Timing Constraints and Defaults](/refguide/tricky-custom-runtime-settings/#session-timing) in *Advanced Custom Settings* for important details about valid values and their relationship to other session settings. | 100000 (100 seconds) | | SessionTimeout | 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.
{{% 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) | -| AbsoluteSessionTimeout | 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`, 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.* | +| AbsoluteSessionTimeout | 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.* | | SessionValidationTimeout | 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) | | Headers | A JSON object containing custom headers as key/value pairs, and can be used to define a `Content-Security-Policy`. For example, `{ "Content-Security-Policy": "script-src 'nonce-{{ NONCE }}'" }`. | `{}` | | TaskQueue.ShutdownGracePeriod | Time in ms to wait for task in a task queue to finish when shutting down. | 10000 (10 seconds) | @@ -283,7 +283,7 @@ The settings below influence the behavior of the Mendix web client. | Name | Description | Default Value | | --- | --- | --- | -| EnableKeepAlive | Defines whether the web client sends a keep alive request every `SessionTimeout`/2 milliseconds in order to prevent a session timeout. Each click in the browser also acts as `KeepAlive`. Disabling this property will result in the user being logged out automatically after `SessionTimeout` milliseconds of inactivity (default 10 minutes), even if the browser remains open. See `SessionTimeout` in the next section for more information. | true | +| EnableKeepAlive | Defines whether the web client sends a keep alive request every `SessionTimeout`/2 milliseconds in order to prevent a session timeout. Each click in the browser also acts as `KeepAlive`. Disabling this property will result in the user being logged out automatically after `SessionTimeout` milliseconds of inactivity (default 10 minutes), even if the browser remains open. See [`SessionTimeout`](#SessionTimeout) for more information. | true | | com.mendix.webui.AuthTokenTimeout | Determines how many minutes your token will remain valid before re-authenticating using your full credentials. If no value is set, the token will expire after One year. | Introduced in Mendix 11.3. Use [com.mendix.webui.HybridAppLoginTimeOut](#commendixwebuiHybridAppLoginTimeOut) in earlier versions. | | com.mendix.webui.HybridAppLoginTimeOut | Legacy alias of com.mendix.webui.AuthTokenTimeout | | | com.mendix.webui.FeedbackSizeWarningThreshold | A warning is logged when the feedback size exceeds the threshold. Feedback is sent from server to client to instruct (for example, to refresh objects or to open a page). They are serialized as "instructions" in the server response. If there are too many instructions, this can have performance implications, as they all have to be serialized to the client. For this reason, a warning is logged when the threshold is exceeded. | 5000 | diff --git a/content/en/docs/refguide/runtime/custom-settings/tricky-custom-runtime-settings.md b/content/en/docs/refguide/runtime/custom-settings/tricky-custom-runtime-settings.md index 92095534540..244920e69bb 100644 --- a/content/en/docs/refguide/runtime/custom-settings/tricky-custom-runtime-settings.md +++ b/content/en/docs/refguide/runtime/custom-settings/tricky-custom-runtime-settings.md @@ -29,23 +29,44 @@ 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. +Changing these settings can have a significant impact on your app, particularly regarding memory usage, security, and user experience. Consider the following points carefully before altering any of these values. -Since the frequency of the session timeout checks and other important events is tied to the `ClusterManagerActionInterval`, it makes sense to not use the default of half the session timeout when the value is increased by a lot (for example, 24 hours or more). It might make sense to put a maximum value on `ClusterManagerActionInterval`, regardless of how high the value of `SessionTimeout` is set. An approximate figure is 15 minutes, but ultimately this will depend on the functional requirements of the application. +Increasing the session timeout can improve the user experience, especially on mobile devices. -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. +When increasing the session timeout, be aware of the user restrictions imposed by your Mendix license. If the end-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 sessions continuing for idle sessions. 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. If the browser tab remains open, setting the `EnableKeepAlive` custom setting to false will ensure, in most browsers, that the session timeout will apply to any idle browser tab. -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. +Increasing the session timeout could also have an impact on the security of your app. An idle session means that there is a potential for a session to be hijacked in case the user does not follow standard security procedures. If they leave their computer unlocked at any given time and do not remain present at their computer afterwards, any person with physical access to that user’s computer could steal or use it and would be able to make use of the session for their own gain. With the default session timeout value this risk is reduced, as the window in which physical access is possible is much more limited (meaning, a session timeout of 24 hours is riskier than a session timeout of 10 minutes). How much of a concern this is will depend on the application’s core business goal and the type of people working with the app. For example, IT professionals are more likely to follow standard security procedures than most other user groups. -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. +Since the frequency of session timeout checks and other important events is tied to `ClusterManagerActionInterval`, using the default value (half the session timeout) does not make sense when `SessionTimeout` is increased significantly (for example, to 24 hours or more). In this case Mendix recommends that you set a lower value for `ClusterManagerActionInterval`, regardless of how high the value of `SessionTimeout` is set. Mendix suggests a value of around 15 minutes, but ultimately this will depend on the functional requirements of the application. -Finally, there is a security consideration to be made. An idle session means that there is a potential for a session to be hijacked in case the user does not follow standard security procedures. If they leave their computer unlocked at any given time and do not remain present at the their computer afterwards, any person with physical access to that user’s computer could steal or use it and would be able to make use of the session for their own gain. With the default session timeout value this risk is reduced, as the window in which physical access is possible is much more limited (meaning, a session timeout of 24 hours is riskier than a session timeout of 10 minutes). How much of a concern this is will depend on the application’s core business goal and the type of people working with the app. For example, IT professionals should be more likely to follow standard security procedures than most other user groups. +If you set `ClusterManagerActionInterval` to be much longer than `SessionTimeout`, this will lead to expired sessions remaining in the database longer. On the other hand, if you set `SessionKeepAliveUpdatesInterval` to be longer than `ClusterManagerActionInterval` or set `SessionKeepAliveUpdatesInterval` to be longer than `SessionTimeout`, active sessions will be cleaned up. -So, make sure to keep in mind all of the above when changing these values. Also, make sure your decision to alter any of these values is made with the right considerations. +{{% alert color="warning" %}} +The Runtime will fail to start if `ClusterManagerActionInterval`, `SessionKeepAliveUpdatesInterval`, and `SessionTimeout` are not configured correctly. The valid relationships between the three settings are described below. +{{% /alert %}} + +### Session Timing Constraints and Defaults {#session-timing} + +The following constraints apply to `ClusterManagerActionInterval` and `SessionKeepAliveUpdatesInterval`: + +**ClusterManagerActionInterval:** + +* Must not exceed twice `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: + * Below 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 the default (5 minutes) would exceed twice the `SessionTimeout`, in which case it is automatically set to `SessionTimeout` / 2 (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) ## Query Logging