Kasm Desktop Service

Kasm Desktop 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 Desktop 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
Developer Preview	kasm_windows_service_installer_x86_64_develop.exe	Developer Preview
1.5.5972ac21d	kasm_windows_service_installer_x86_64_1.5_5972ac21d.exe	1.16.0, 1.16.1
1.4.7f51b2de	kasm_windows_service_installer_x86_64_1.4_7f51b2de.exe	1.16.0, 1.16.1
1.3.af09998b6	kasm_windows_service_installer_x86_64_1.3.af09998b6.exe	1.16.0
1.2.22550d18	kasm_windows_service_installer_x86_64_1.2.22550d18.exe	1.15.0
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

The Developer Preview Build of the Kasm Desktop Service listed above should only be used with the developer preview build of Kasm Workspaces on non-production systems.

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 Desktop 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 Desktop 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 Kasm Desktop Service Installed option is enabled when creating the server.
On the Windows server download the appropriate version of the Kasm Desktop Service from the table above.
Launch the Kasm Desktop Service installer. You will be prompted to provide information.

../../_images/kasm_windows_service_install.webp

Enter the hostname or IP address of the Kasm API (WebApp Role) services. This is normally the same hostname or IP that end-users use to access your Kasm deployment.
Enter the port number for Kasm Workspaces, the default is port 443.
Provide the registration token for this server. In the Kasm Admin UI, Navigate to Infrastructure->Servers, find the target server and click Edit. In the Kasm Agent section, press the copy button on the Registration Token field and paste this into the Kasm Desktop Service installer Registration Token field.

../../_images/kasm_server_agent-1.16.0.webp

Press Ok on the above dialog after you have filled in the required information. When registration is complete the above dialog will close and the installer will show completed. You may close the installer.

../../_images/kasm_windows_service_install_complete.webp

Installation Troubleshooting

During the installation, the Kasm Desktop Service will attempt to register itself with the Kasm Workspaces deployment using the registration token provided. During the registration process the following checks are performed.

Can the Kasm Desktop Service talk to the Kasm Workspaces deployment on the specified port and hostname.
Can the Kasm Workspaces deployment talk to the Kasm Desktop Service on port 4902 using the hostname/IP specified in the Server record in Kasm Workspaces.
Is the registration token digitally signed by the Kasm Workspaces deployment, not expired, and assigned to the server being registered.

If any of these conditions fail, you will get an error message during the installation when hitting Ok on the below dialog box. Attempt to correct issues such as DNS reslolution of hostname, firewall rules, or expired registration tokens and press Ok again to try again.

../../_images/kasm_windows_service_install_error.png

Scripted Installation

The installation and registration of the Kasm Desktop Service can also be scripted. In the example below, replace kasm.exmaple.net with the hostname or IP address of your Kasm deployment, the port number if different than 443, and the registration token for the server.

# Download appropraite version of the kasm installer from the above table
kasm_windows_service_installer_x86_64_1.2.22550d18.exe /S
net stop kasm
cd "C:\Program Files\Kasm"
.\agent.exe --register-host kasm.example.net --register-port 443 --register-token "<registration-token>"

Warning

The installation directory, C:\Program Files\Kasm will inherit Windows ACL permissions from the parent directory. For the best possible security, ensure that normal users do not have read access to the Kasm service installation directory as the directory contains potentially sensitive information.

Optional Dependencies

Kasm uses WinSfp to facilitate Cloud Storage Mappings in Windows. Download the latest Windows msi installer from the WinSfp release page. Alternatively, you can use the following PowerShell script to install WinFsp non-interactively.

$winfsp_url = "https://github.com/winfsp/winfsp/releases/download/v2.0/winfsp-2.0.23075.msi"
$winfsp_msi = "winfsp-2.0.23075.msi"

Function Install-Winfsp {
  Invoke-WebRequest -Uri $winfsp_url -OutFile $Env:temp\$winfsp_msi
  Write-Host "Installing WinFSP"
  Start-Process -FilePath $Env:temp\$winfsp_msi -ArgumentList '/q' -WorkingDirectory "C:\Windows\Temp\" -Wait
  Remove-Item $Env:temp\$winfsp_msi -Force
}

Install-Winfsp

SSL Certificates

As part of the installation, 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 Desktop 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 Desktop 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 Desktop 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 Desktop 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 in Kasm are mapped to Windows users through SSO.
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.

The multi_user and user_sso are updated automatically when the serivce checks into the deployment, based on the configuration in Kasm Workspaces for this server.

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, or Smart card authentication. 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 Kasm Desktop 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.
registry	Registry setting export files.

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). This script is used to map in Cloud Storage definitions 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. All Windows storage mappings are placed on the user’s Desktop. If, for exmaple, a Storage Mapping with a target of /OneDrive would be mapped to C:\Users<username>\Desktop\OneDrive on a Windows system. This script requires WinSfp.

unmap_storage.ps1 This script is called during session termination, after the user is logged off. The script removes any mapped 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.
ts_session_id	The associated Windows Terminal Session ID.
is_remote_app	Is the session a RemoteApp.
is_web_native	Is the user’s session using Kasm’s web native access or is the user connected with an RDP client.
auto_logout_user	Will the Kasm Desktop Service automatically log the user out when the session closes.

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.

Manage Registry Settings

Kasm administrators can use File Mappings to map registry setting export files to C:\Program Files\Kasm\scripts\registry. These files must end in .reg and should be exports created by Microsoft regedit. When the Kasm Desktop Service starts, it will download new file mappings and apply any .reg files that exist in that directory. This can be used, for example, to configure RDP settings for systems outside of a domain..