--- myst: html_meta: "description lang=en": "Pre-Provision Kasm Workspaces sessions to improve user experience." "keywords": "Kasm, Session, Staging" "property=og:locale": "en_US" --- ```{title} Session Staging ``` # Session Staging By default, when users create a new Kasm session, the container for that session is created on-demand. In some use-cases, administrators may wish to **Stage** (Pre-Provision) containers, so when a user requests a session, it pulls from a pool of staged containers that are already running. This may be useful to reduce the time it takes for a user to connect to a session, or if the Image has a lengthy run-time initialization routine. As part of the configuration, administrators must configure a set of default permissions (e.g. **Allow Audio**) that will be enabled/disabled for the session. Because these settings must be configured at the invocation of the container, for enhanced security, users whose group permissions do not match these will not be assigned a staged session and instead will trigger the system to create one on demand. ## Configuration - Log into the Kasm Web UI as an administrator. - Click **Sessions** -> **Staging**. - Click **Add Config**. ```{figure} /images/staging/create_staging_config.webp :align: center **Staging Config** ``` ```{eval-rst} .. table:: :widths: 100 +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Property** | **Description** | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Zone** | The :doc:`Deployment Zone ` for the configuration | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Workspace** | The desired :doc:`Workspace ` to be staged. | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Desired Sessions** | The number of sessions the system will attempt to have staged at any given time. As users are assigned sessions from the pool, the system will automatically attempt to provision more to keep the pool at this number. | | | Reducing this number will cause the system to destroy excess staged sessions. | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Expiration (Hours)** | Staged sessions that have not been assigned to a user will expire after this amount of time. The system will destroy the staged sessions and re-created them. | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Audio** | When enabled, the staged session will support streaming audio from the session to the user. | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Clipboard Down** | When enabled, the staged session will allow copying data from the session to the users local computer via the clipboard | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Clipboard Up** | When enabled, the staged session will allow copying data from the user's local computer to the session. | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Downloads** | When enabled, the staged session will allow download files from the session to their local computer via the control panel download widget. | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Microphone** | When enabled, the staged session will allow the user to pass their local microphone into the session. | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Uploads** | When enabled, the staged session will allow the user to upload files from their local computer to the session via the upload widget in the control panel. | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Allow Gamepad** | When enabled, the staged session will allow the user to pass through gamepads from their local computer to the session via the gamepads widget in the control panel. | +------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ``` - Fill out the form then click **Save**. - Click **Infrastructure** -> **Zones**. - Click **Edit** next to the desired Zone. - Update the **Allow Origin Domain** and the **Upstream Auth Address** settings to be the appropriate domain. The default {code}`$request_host$` variable cannot be used for staged sessions. ## Desired Sessions The system will begin creating the staged sessions a few moments after the configuration is applied. If the **Current Sessions** does not match the **Desired Sessions** after a few minutes , consult the logs for warning or error messages. It is likely the system doesn't have enough resources (Agent Capacity) to fulfill the request, or an Image is disabled or unavailable ```{figure} /images/staging/staging_list.webp :align: center **Staging Configs** ``` ## Session List Staged sessions will appear without a User assigned in the **Sessions** list. Once the sessions are **assigned** to a user, the username will appear. ```{figure} /images/staging/staged_sessions.webp :align: center **Staged Sessions** ``` ## Incompatible Settings Certain Group and Image level settings are not compatible with Staged Sessions as they require the workspace to be originally created with the settings applied. If a user requests a Kasm session but has an incompatible setting applied, the violation will be logged, and the system will provision a workspace on-demand. | Setting Location | Setting | Notes | |------------------|------------------------------|----------------------------------------------------------------------------------------| | Workspace | Persistent Profiles | | | Workspace | Volume Mappings* | Volume mappings cannot reference `{username}` or `{user_id}` tokens. | | User | File Mappings | Administrators can apply a File Mapping to a Workspace instead. | | User | Kasm Session Language | This only fails if the user language and the staged session language are not the same. | | User | Kasm Session Timezone | This only fails if the user timezone and the staged session timezone are not the same. | | Group | File Mappings | Administrators can apply a File Mapping to a Workspace instead. | | Group Setting | expose_user_environment_vars | | | Group Setting | inject_ssh_keys | | | Group Setting | run_config | | | Group Setting | volume_mapping | | | Group Setting | web_filter_policy | Administrators can apply a filter policy to the Image instead. | ### Language and Timezone settings Users can set specific language and timezone settings on their profile or automatically use the language and timezone settings from their browser. By default, when accessing a staged session Kasm will attempt to match a staged session with the user preferred language and timezone settings. If a staged session with those settings is unavailable then a new session on-demand is created for the user. As the default settings for Kasm workspaces are Etc/UTC timezone and en_EN.UTF-8 language users may find that they frequently are using workspace on-demand instead of staged sessions. To avoid this the Administrator has a few options. Administrators can override this behavior with the group setting **staged_session_language_and_timezone_preference_override** see the {doc}`group settings ` documentation for more information. Administrators can also override the default language and timezone settings for a Workspace using the {ref}`docker-run-config` section on configuring the language and timezone to match the language and timezone settings of their users. Administrators can check the logs to see if staged sessions are being used to fulfill user session requests and if not, what the cause is. ```{figure} /images/staging/incompatible_settings.webp :align: center **Logged settings violation** ``` ## Multi-Zone Behavior When a user makes a request to launch a session the system will prefer to assign a staged session in all applicable Zones prior to attempting to create an on-demand container. The process is as follows: 1. Attempt to assign a staged session in the current Zone. 2. Attempt to assign a staged session in other Zones if **Search Alternate Zones** is configured on the current Zone. 3. Attempt to create a new on-demand session in the existing Zone. 4. Attempt to create a new on-demand session in other Zones if **Search Alternate Zones** is configured on the current Zone. ## Docker Exec The Docker Exec Config supports a top level key named {code}`assign`. This command is executed when the user is assigned a staged session. For more information please see {doc}`Docker Exec Config `