Kasm Windows Service

Kasm Windows Service is a Windows service that provides additional capabilities to users that are connected to the desktop through Kasm Workspaces:

Upload files to the remote desktop
Download files from the remote desktop
See a preview screenshot of the desktop in the Kasm Workspaces dashboard
Run PowerShell scripts on session start, session end, or service start
Kasm managed local Windows users and credentials
File Mapping
Supports multiple concurrent users on the same Windows system

System Requirements

Supported Operating Systems
Windows 10 (x86_64)
Windows 11 (x86_64)
Windows 2019 (x86_64)
Windows 2022 (x86_64)

Installation

The Kasm Windows Service can be installed using one of the installers below which places all the necessary files in C:\Program Files\Kasm. You should use the latest version that supports the version of Kasm Workspaces you have installed.

Installer Version	Installer Link	Kasm Workspaces Compatibility
1.1.2b3f26b	kasm_windows_service_installer_x86_64_1.1.2b3f26b.exe	1.14.0
1.0.e2600c4b	kasm_windows_service_installer_x86_64_1.0.616b3bea.exe	1.12.0, 1.13.0, 1.14.0
0.9	kasm_windows_service_installer_x86_64_02beec.exe	1.12.0, 1.13.0
0.8	kasm_windows_service_installer_x86_64_5a2950.exe	1.12.0, 1.13.0

Note

The documentation on this page is for the latest version of the installer listed in the table above and may not be accurate for older versions.

The Kasm Windows Service uses HTTPS/SSL to communicate with the rest of the Kasm Workspace services. The service installer will open the Windows firewall for TCP port 4902, ensure that firewalls and/or cloud security groups allow inbound TCP port 4902 coming from Kasm API server and Connection Proxy servers. The Kasm Windows service will talk outbound to the API Server on the port your deployment utilizes, TCP port 443 by default. Ensure security groups and our firewall rules allow this communication.

The following instructions are for static Windows servers. Auto scaled servers will install the service as part of the PowerShell startup scripts, see Auto Scaled Servers startup scripts for more details.

Login to Kasm as an administrator
Create a new Server, you can optionally make the server part of a Pool
Ensure the Agent Installed option is enabled when creating the server.
On the Windows server, open an elevated PowerShell prompt and download the agent. You can optionally download using a browser. Note that the download command names the file kasm_service_installer.exe and that name will be used later.

Invoke-Webrequest -URI https://kasm-static-content.s3.amazonaws.com/kasm_windows_service_installer_x86_64_1.1.2b3f26b.exe -OutFile kasm_service_installer.exe

In the Kasm Admin UI, Navigate to Infrastructure->Servers, find the server and edit it.
In the Kasm Agent section, expand the Agent Installation Instructions section. The following screenshot is an example. Copy these commands and run them on the target Windows server on an elevated command prompt.

../../_images/windows_service_install_instructions.png

Registration

The service is now installed and registered with the Kasm Workspaces deployment. As part of registration, the service is automatically configured based on the settings in Kasm Workspaces. You can rerun registration at any time, if the Server settings have changed in Kasm Workspaces. To rerun registration, run all the commands in step 6 above, with the exception of kasm_service_installer.exe /S.

Note

As part of this registration, the service is assigned an SSL certificate. Kasm utilizes a self sign certificate for the service. You can optionally replace the auto generated self-signed certs with certs that are signed by your organization’s CA. The cert and key need to be in PEM format and are stored at C:\Program Files\Kasm\certs.

Upgrade

When running the installer on a machine with an existing Kasm Windows Service an upgrade will be performed. The existing configuration file, as well as the certificates and any files in the upload and download folders will be preserved.

Uninstall

If the Kasm Windows Service needs to be uninstalled it can be removed by going to Add or remove programs / Apps & features on the Windows server and selecting the Kasm - KasmAgent <agent version number> and then selecting Uninstall. There will be a dialog box asking you to confirm you wish to remove the Kasm Windows Service, click OK to continue.

Warning

All files under C:\Program Files\Kasm will be deleted during the uninstall process.

Configuration

Below is an example config with the appropriate settings for Kasm Windows Service annotated. This file is automatically generated during the registration process, however, it can be overridden for custom deployments.

Important

All paths should be absolute and without slashes at the end. Backslashes should be escaped with a backslash. The referenced PEM formatted certificate files must not have Windows carriage returns.

# server HTTP(s) configuration
ssl: true
port: 4902
server_private_key: "C:\\Program Files\\Kasm\\certs\\key.pem"
server_public_key: "C:\\Program Files\\Kasm\\certs\\cert.pem"

# path to JWT's RSA certificate for token verification
jwt_public_key: "C:\\Program Files\\Kasm\\certs\\jwt.pem"

# path to upload/download folders
upload_dir: "C:\\Program Files\\Kasm\\Upload"
download_dir: "C:\\Program Files\\Kasm\\Download"

# (optional) path to the log file
log_file: "C:\\Program Files\\Kasm\\log.txt"

# Settings for multiple user machines
multi_user: false
user_sso: false

debug: false

Settings

Name	Description
ssl	Enables SSL for the services. Kasm Workspaces only supports communications with this service over SSL.
port	The port to run the services on. Kasm Workspaces uses port `4902` for this service by default.
server_private_key	The private key used for the SSL service.
server_public_key	The public key used for the SSL service.
jwt_public_key	The public key used to authenticate API calls received from Kasm Workspaces.
upload_dir	Directory to place files uploaded by users.
download_dir	Directory to allow users to download files from.
log_file	Optionally writes logs to this file. Logs can also be viewed in Windows Event Viewer.
multi_user	Boolean indicating the Windows instance the service is installed on will support multiple users
user_sso	Boolean indicating that users
api_host	The hostname or ip address of an API server or load balancer in front of Kasm API servers.
api_port	The port number used for your deployments API Servers, port 443 by default.
registered	Has the agent already been registered with the deployment.
script_path	Directory where scripts are located.
server_id	The UUID of the server in Kasm Workspaces.
debug	Enable verbose logging.

Uploads and Downloads on Multi-user Systems

When a user uploads files from their local computer to the remote Kasm Windows session, the file is placed in the Downloads directory of their home path. When a user wants to download a file from the remote Kasm Windows session to their local computer, they can use the control panel. The control panel will display files located in the Downloads directory of their home path.

There may be security concerns when Kasm and the Windows environment is not setup for SSO either using LDAP SSO, static accounts, Kasm managed Windows accounts. If all users are connecting to the remote Windows server using the same credentials, they will all share the same Windows profile.

Authentication of Service

All requests to the application must contain a JWT token parameter that will be verified against the provided JWT key. The JWT key (also referred to as the API Cert) is generated upon Kasm Workspaces installation and can be retrieved from Kasm Settings panel section.

../../_images/api_key1.webp — **Setting Public Cert**

The public JWT token is retrieved during registration. If you change the JWT cert and key on your Kasm Workspaces deployment, you will need to re-register your Windows service.

Scripts

Kasm utilizes a number of PowerShell scripts and provides administrators hooks to execute their own PowerShell scripts during certain events. When PowerShell scripts get executed by the Kasm Service, PowerShell variables are automatically injected so that your script has access to contextually relevant information. See the variables section for more details.

The default location for scripts is C:\Program Files\Kasm\scripts. File Mapping can be used to manage custom scripts within the Kasm UI. With this directory there are the following sub directories with the following purposes.

Script Directories

Directory	Description
builtin	Scripts ran by the Kasm Service to execute specific actions. See the following section for details.
service_startup	Scripts placed here will automatically be executed when the Kasm service starts.
session_start	Scripts placed here will automatically be executed before a user session starts.
session_end	Scripts placed here will automatically be executed before a user session is terminated.

Builtin Scripts

The following builtin scripts exist for the defined purpose.

create_local_account.ps1 This script is executed during session creation, if Dynamic Local Account SSO is configured. This script creates a local Windows account for the requesting user, if it does not already exist, and retrieves a one-time random password to set for the Windows account. The API call to retrieve the one-time password uses a JWT token that is defined in a builtin variable. The JWT token has short expiration time and can only be used once to retrieve the one-time password.

logoff_user.ps1 This script will log the user off the Windows session when the user deletes their Kasm session.

load_persistent_profile.ps1 This script is called during session creation, before a user connects and after create_local_account.ps1 is called (if required). The script is empty in the current version but provides the administrator the ability to define their own hook to load persistent profiles from users using third party solutions. The script has access to builtin variables defined below.

save_persistent_profile.ps1 This script is called during session termination, after the user is logged out. The script is empty in the current version but provides the administrator the ability to define their own hook to save persistent profiles for users using third party solutions. The script has access to builtin variables defined below.

map_storage.ps1 This script is called during session creation, before a user connects and after create_local_account.ps1 is called (if required). The script is empty in the current version but provides the administrator the ability to define their own hook to map in Cloud Storage for users. This script has access to builtin variables in addition to a storage_mapping variable, which contains the storage mapping definition in JSON format. This script is called for each storage mapping that is applicable to the user that is creating the session.

unmap_storage.ps1 This script is called during session termination, after the user is logged off. The script is empty in the current version but provides the administrator the ability to define their own hook to remove Cloud Storage volumes that were added with the map_storage script. This script has access to builtin variables in addition to a storage_mapping variable, which contains the storage mapping definition in JSON format. This script is called for each storage mapping that is applicable to the user that is creating the session.

Variables

The following variables are builtin and available for any PowerShell script executed by the Kasm Service.

Name	Description
user_id	The Kasm User ID for the user creating/terminating the session.
username	The Windows username of the user creating/terminating the session.
kasm_id	The Kasm session ID for the session being created/terminated.
jwt_token	A limited access and short lived JWT token that can be used to make API calls to Kasm.
api_host	The IP address or hostname of the API server or load balancer for the API servers.
api_port	The port number of the API server.

These variables can be referenced in PowerShell scripts defined by the administrator as such.

Write-Host "Session starting for $username"

The full output of scripts is logged if either the exit code is a non-zero value or if debug is enabled in the configuration.

Logging

By default, all log messages are written to Windows event log (under Applications->KasmService) but can be also redirected to a file by specifying the log_file parameter in config.yaml. Logs are also sent to the Kasm Workspaces deployment and can be searched for the Kasm Admin UI under Diagnostics->Logging.