--- myst: html_meta: "description lang=en": "Run Kasm Windows Service on an RDP endpoint to enable enhanced Workspaces features." "keywords": "Kasm, Windows, Service, Upload, Download, Screenshot" "property=og:locale": "en_US" --- ```{title} Windows Service ``` ## 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](./windows_service.md#scripts) on session start, session end, or service start - [Kasm managed local Windows users](./authentication.md#single-sign-on-with-dynamic-local-accounts) and credentials - [File Mapping](../file_mappings.md) - 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.2.22550d18 | [kasm_windows_service_installer_x86_64_1.2.22550d18.exe](https://kasm-static-content.s3.amazonaws.com/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](https://kasm-static-content.s3.amazonaws.com/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](https://kasm-static-content.s3.amazonaws.com/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](https://kasm-static-content.s3.amazonaws.com/kasm_windows_service_installer_x86_64_02beec.exe) | 1.12.0, 1.13.0 | | 0.8 | [kasm_windows_service_installer_x86_64_5a2950.exe](https://kasm-static-content.s3.amazonaws.com/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](./auto_scaled_servers.md#vm-startup-scripts) for more details. 1. Login to Kasm as an administrator 2. Create a [new Server](./static_servers.md#servers), you can optionally make the server part of a [Pool](./static_servers.md#server-pools) 3. Ensure the `Agent Installed` option is enabled when creating the server. 4. 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. ```Powershell 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 ``` 5. In the Kasm Admin UI, Navigate to Infrastructure->Servers, find the server and edit it. 6. 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. ```{figure} /images/windows_service/windows_service_install_instructions.png :align: center :width: 90% ```

```{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](https://github.com/winfsp/winfsp) to facilitate [Cloud Storage Mappings](../storage_mappings.md) in Windows. Download the latest Windows msi installer from the WinSfp [release page](https://github.com/winfsp/winfsp/releases). Alternatively, you can use the following PowerShell script to install WinFsp non-interactively. ```Powershell $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 ``` ### 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 `` 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. ``` ```bash # 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](../windows/authentication.md#single-sign-on-with-active-directory), [static accounts](../windows/authentication.md#single-sign-on-with-static-local-accounts), [Kasm managed Windows accounts](../windows/authentication.md#single-sign-on-with-dynamic-local-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. ```{figure} /images/windows_service/api_key.webp :align: center **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](./windows_service.md#variables) section for more details. The default location for scripts is `C:\Program Files\Kasm\scripts`. [File Mapping](../file_mappings.md) 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](./authentication.md#single-sign-on-with-dynamic-local-accounts) 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](./windows_service.md#variables). 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](../storage_mappings.md) definitions for users. This script has access to [builtin variables](./windows_service.md#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\\Desktop\OneDrive on a Windows system. This script requires [WinSfp](#optional-dependencies). **unmap_storage.ps1** This script is called during session termination, after the user is logged off. The script removes any mapped [Cloud Storage](../storage_mappings.md) volumes that were added with the map_storage script. This script has access to [builtin variables](./windows_service.md#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. ```PowerShell 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](./windows_service.md#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.