/
Understanding Session Expiration

Understanding Session Expiration

Owned by Justin Travis, created
Last updated: Aug 01, 2025

This document will go over the machinery by which a session will expire or be kept alive via user activity.

 Settings

Various settings are available within the application. We will briefly describe them as they will be used in the more detailed workflow

  • keepalive_expiration: (Group Setting) This value determines how long Kasm will wait before destroying, stopping or pausing a session if no keepalive is received from the client. Keepalives are sent whenever a user is connected to a Kasm session even if the user is not actively using the Kasm Session. This value should be at least twice the keepalive_interval. This setting is 1 hour by default in the “All Users Group”. The action taken is determined by the keepalive_expiration_action Group Setting.

  • keepalive_interval: (Group Setting) The keepalive_interval is how often the client will send a keepalive request to Kasm when the user has a browser tab open to the session. This setting is 300 seconds by default for the “All Users Group”.

  • keepalive_expiration_action: (Group Setting) Administrators can decide what happens to sessions once they expire. Valid options are:

    • delete - The session is destroyed.

    • pause - The session is paused, preserving the disk, process and memory state. Paused sessions will still consume resources in physical memory and/or swap. Sessions resumed from a paused state will still have the previous programs launched and active. This action is valid for container-based sessions only. All other types will utilize the delete action.

    • stop - The session is stopped, preserving the disk state. Sessions resumed from a stopped state will have the previous files intact, but previously running programs will need to be restarted. This action is valid for container-based sessions only. All other types will utilize the delete action.

  • idle_disconnect: (Group Setting) This setting is the number of minutes Kasm will wait when the user is idle before taking an action. This action will depend on the user context. If the user is in a Kasm session when the idle timeout expires the user is disconnected from the Kasm session and sent back to the dashboard. Any Kasm sessions that the user was connected to will be disconnected and those sessions will be subject to the keepalive_expiration. If the user is at the dashboard when the idle timeout expires the user is logged out of Kasm. This setting is set to 20 minutes by default in the “All Users Group”. This setting must be higher than the keepalive_interval setting to function properly.

  • session_time_limit: (Group Setting) The session_time_limit is a set amount of time that a workspace will be allowed to run once that workspace is created. This time limit is irrespective of whether the user is actively using the session or if the session is disconnected and running in the background. When session_time_limit is configured, the keepalive_expiration setting is not used. This setting is not enabled by default

     

 How it Works

 

  1. When a session is created, the session is given an expiration time. That value is the current time + the keepalive_expiration

    1. Admins can view the expiration time by adding the Expiration column to the Sessions table view, or in the details view of the specific session. In this example you can see the session expires an hour after initial creation based on the keepalive_expiration of 3600 seconds or 1 hour

      1. image-20250731-123047.png
      2. image-20250731-123107.png

         

  2. The primary manager (e.g the kasm_manager service container ) in each zone is responsible for monitoring the system for expired sessions. It regularly queries the database looking for sessions in its zone that have reached the expiration. Upon expiration, the manager will take the predefined keepalive_expiration_action which is delete by default.

    1. The file based logs for the kasm_manager are set to DEBUG level which will show this activity. (e.g sudo tail -f /opt/kasm/current/log/manager_api_server.log) This log will be seen each time the manager evaluates sessions:

      1. [DEBUG] manager_api_server: Looking for expired kasms

    2. The following are a sample of logs that would be see if a session is expired and the manager takes action on it

      1. 2025-07-31 12:58:16,982 [DEBUG] manager_api_server: Looking for expired kasms 2025-07-31 12:58:16,995 [INFO] manager_api_server: Handling expired session (4c625fc7-c1eb-4d95-97de-f0544763b3e5): action (delete) 2025-07-31 12:58:17,030 [DEBUG] manager_api_server: Requesting Hello for Server(33d95e56-4ff2-4174-a0b8-b5662e3cdd8b) via URL: (https://proxy:443/agent/api/v1/hello/) 2025-07-31 12:58:17,058 [DEBUG] manager_api_server: Server(33d95e56-4ff2-4174-a0b8-b5662e3cdd8b) is alive 2025-07-31 12:58:17,059 [DEBUG] manager_api_server: Function (provider_manager.is_host_alive) executed in (0.06109285354614258) seconds 2025-07-31 12:58:17,059 [INFO] manager_api_server: Destroying Container via URL: (https://proxy:443/agent/api/v1/destroy_container/) 2025-07-31 12:58:17,090 [INFO] manager_api_server: Removing Kasm (4c625fc7-c1eb-4d95-97de-f0544763b3e5) with operational status of (running) for User (a6cec5b4-30be-45ff-aa3c-23bbc0b538a7) 2025-07-31 12:58:17,115 [DEBUG] manager_api_server: Requesting Hello for Server(33d95e56-4ff2-4174-a0b8-b5662e3cdd8b) via URL: (https://proxy:443/agent/api/v1/destroy_container/) 2025-07-31 12:58:18,575 [DEBUG] manager_api_server: Updated Accounting record for kasm_id (4c625fc7-c1eb-4d95-97de-f0544763b3e5) 2025-07-31 12:58:18,581 [INFO] manager_api_server: Kasm (4c625fc7-c1eb-4d95-97de-f0544763b3e5) destroyed after (455.761753) seconds of total uptime

         

    3. Note: The primary manager may not take action on the session at the precise time of the expiration. For example if the manager is actively conducting an autoscale routine, that routine must finish before the manager will process expired sessions again. A good tip is to look for the previous occurrence of this message Looking for expired kasms in the logs before the one where the specific session in question is processed. The logs in between would so all of the operations the manager was processing between it looking for expired sessions , such as handling autoscale routines , staged sessions etc.

  3. When users connect to session via their browsers, the browser will continually send keepalive API calls to the backend to extend the expiration. The frequency at which the client sends keepalives is defined by the keepalive_interval group setting. The default is 5 minutes. For each keepalive request, the session expiration is extend by the value defined by keepalive_expiration (1 hour by default). Practically this means, that while a user’s browser is connected to the session, the session’s expiration is extended by an hour every 5 minutes

    1. The keepalive requests as observed from the developer tools of the client browser:

      1. image-20250731-131303.png

    2. The kasm_api container will process the keepalive requests. A sample of these logs can be seen below

      1. 2025-07-31 13:13:49,031 [DEBUG] client_api_server: Successfully authenticated request (keepalive) for user (test_user_1) at (108.45.110.181) 2025-07-31 13:13:49,038 [DEBUG] client_api_server: Using group-level keepalive_expiration of (300) 2025-07-31 13:13:49,045 [INFO] client_api_server: Set keepalive for kasm_id (91b35198-a009-4042-9553-65900c8ee930) at (172.18.0.10) for user (test_user_1) from IP (108.45.110.181)

  4. While a user is connected to a KasmVNC based session with their browser, the monitors for mouse movements or keyboard strokes within the session. If neither of these activities are seen for some period of time (as defined by the idle_disconnect group setting), the user will be disconnected from the session and placed back in the application dashboard. Once the user is disconnected and placed back at the dashboard, keepalive requests are no longer sent thus the session will expire in accordance with the previously defined logic. This action is not currently logged

 

 Notes and tips

  • Ensure all servers in your deployment are using synchronized time. Systems that have large drifts in time may cause sessions to be see as expired before or after the administrators intended settings

  • Changing the keepalive_expiration will take effect on either new sessions that are created after the change, or any active session where user sends a keepalive request after the change. Existing sessions aren't automatically updated otherwise.

  • The sending of keepalives and the tracking of user input for the idle_disconnect are handled on a per-tab basis, meaning that if a user has 2 tabs open to the same session, both tabs will send independent keepalive. If one tab is disconnected due to inactivity, the second would not be disconnected if it was otherwise active.

  • Since user’s can be a member of multiple groups, its can sometimes be confusing what group setting actually being used. The best way to verify , is to utilize the Resultant Group Settings widget tab via the Update User page as an admin. All the group settings are listed as well as the value that is applied for this particular user.

    • image-20250801-000626.png

       

Related Docs:

 Related articles

  • Links to related kb articles in the Confluence project