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
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 |
Developer Preview |
|
1.5.5972ac21d |
1.16.0, 1.16.1 |
|
1.4.7f51b2de |
1.16.0, 1.16.1 |
|
1.3.af09998b6 |
1.16.0 |
|
1.2.22550d18 |
1.15.0 |
|
1.1.2b3f26b |
1.14.0 |
|
1.0.e2600c4b |
1.12.0, 1.13.0, 1.14.0 |
|
0.9 |
1.12.0, 1.13.0 |
|
0.8 |
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.
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.
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.
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.
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 |
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.
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..