Servers

Kasm Workspaces provides session management and rendering of sessions for fixed systems or auto scaled systems that support either KasmVNC, RDP, SSH, or VNC. Workspaces can be created and assigned to Groups, providing users access to the servers from their dashboard.

Servers List

Create Server

To create a new server, navigate to Infrastructure->Servers->Servers and click Add. Fill in the required information about the server. In order for the server to be accessible to users, a Workspace must be created and then add the Workspace to a Group.

Property	Description
Enabled	Show and allow connections to this server.
Friendly Name	The server name displayed to users.
Deployment Zone	Which deployment zone to set for the server.
Pool	Which pool does the server belong to.
Assigned User	(Optional) Select a User to assign to this Server. Only available for members of Server type Pools with user-server assignment enabled.
Kasm Desktop Service	Whether this is a Windows host with Kasm Desktop Service installed
Connection Type	Whether to use KasmVNC, RDP, SSH, or VNC.
IP/Hostname	The IP or Hostname used to connect to the server.
Connection Port	Which port to connect to the server on.
Connection Credential Type	Which type of credentials are used for this server. Options are Static Credentials, Dynamic User Accounts, SSO User Accounts, Authenticate with Smartcard, and Prompt User
SSO Domain	This field applies when Connection Credential Type is set to SSO User Accounts. Use this field to modify the username. For example, in Kasm the username may be john.smith@acme.com, but Windows may expect john.smith@acme.local. A value of localhost strips the domain name from the username, i.e. john.smith. A value ending in \ prepends this field to the username, i.e. acme.local\john.smith. All other values are appended to the username with @, i.e. john.smith@acme.local.
Connection Username	The username to use to connect to the server. Only visible with Static Credentials Connection Credential Type.
Connection Password	The password to use to connect to the server. Only visible with Static Credentials Connection Credential Type.
Use User SSH Key	(Optional) This only applies to the SSH Connection type. When selected Kasm uses the User's SSH Keys to authenticate against the server.
Connection Private Key	(Optional) This only applies to the SSH Connection type. This is the private key to be used to authenticate to the server.
Connection Private Key Passphrase	(Optional) This only applies to the SSH Connection type. This is the passphrase of the Private Key specified above.
Connection Info	(Optional) Additional connection info that needs to be passed to the server. For more information see the Connections section of the global settings
Max Simultaneous Sessions	The maximum amount of sessions that can connect to the server at a time. For RDP servers with RemoteApps, admins may want to set this value higher than then Max Simultaneous Users setting to allow for multiple RemoteApps per user.
Max Simultaneous Users	For RDP and SSH servers, the number of concurrently connected users per server.
Labels	Labels assigned to this Server. These labels can be used to control where Workspace sessions are launched. You can specify these labels in a Workspace's "Include Labels" or "Exclude Labels" settings to ensure sessions run only on certain servers.

Single Sign-On to Windows Systems via LDAP

When users login to Kasm via LDAP Authentication, they are able to create sessions to Windows systems that are joined to the same Active Directory domain and are configured for SSO credential pass-through. In the above table covering the configuration fields for Servers is the Connection Credential Type field. Select the value SSO User Accounts in the Connection Credential Type field. This requires that all users accessing this server are authenticated to Kasm using LDAP authentication. See our Windows Deployment Guide video for a walk through of this topic and more.

Authentication Options When Connecting to an SSH Server

Kasm Workspaces has the ability to connect to arbitrary SSH servers. It can use SSH key or password authentication. There are a few combinations of options on the Server edit screen that can be selected.

The server can be configured to use:

• Username/password authentication
• Username and select the Use User SSH Key to send the username and private key stored with the Kasm user.
• Username and a pasted in private key, optionally including a passphrase if the key requires one.

Select the value SSO User Accounts in the Connection Credential Type field and check the Use User SSH Key checkbox and Kasm Workspaces will send the user's Kasm Workspaces username along with the user's Kasm Workspaces SSH key allowing easy multiple user support on SSH servers.

There are some restrictions on the ssh keys supported that are enforced by the connection proxy library used for the ssh server connections: The SSH key can be in either OpenSSH format (beginning with -----BEGIN OPENSSH PRIVATE KEY-----) or RSA PKCS1 format (beginning with -----BEGIN RSA PRIVATE KEY----- or -----BEGIN PRIVATE KEY-----) with a key size of 2048.

When using RSA keys with some newer Linux distributions such as Ubuntu 22.04 LTS, you may need to edit the /etc/ssh/sshd_config file on the target server and add these two lines to the config:

HostKeyAlgorithms +ssh-rsa
PubkeyAcceptedKeyTypes +ssh-rsa

SSH session continuity

Kasm Workspaces uses Guacamole to provide SSH connectivity for SSH server definitions. Guacamole does not provide the ability to resume SSH sessions. This means that when disconnecting from an SSH Workspace such as when clicking Workspaces from the control panel it will not be possible to resume the same session when clicking Resume and a fresh SSH session will be created. This also applies to disconnections caused by network interruptions. To avoid this a user can utilize a utility such as screen/tmux to have a persistent terminal session on the server.

Tmux Connection Settings Example

This is an example of how it would be possible to configure the Kasm connection settings for a Server to use tmux to have a preserved environment on an SSH server.

{
  "guac": {
    "type": "ssh",
    "settings": {
      "font-size": "11",
      "color-scheme": "gray-black",
      "font-name": "monospace",
      "scrollback": "1000",
      "command": "tmux a || tmux"
    }
  }
}

Screen Connection Settings Example

This is an example of how it would be possible to configure the Kasm connection settings for a Server to use screen to have a preserved environment on an SSH server.

{
  "guac": {
    "type": "ssh",
    "settings": {
      "command": "screen -R my_session"
    }
  }
}

Creating Templates For Use With The VMware vSphere Provider

When using the VMware vSphere provider the administrator must create templates on the cluster for the provider to clone from.

Linux Templates

When creating Linux VM templates ensure that:

• VMware tools, either the official version or the open-vm-tools are installed.
• If SSH access is desired ensure that a public SSH certificate is installed on the machine, and use the matching private key when creating the Autoscale documentation.
• If creating this template for use in a Docker Agent pool take note of the primary ethernet interface name as that will be needed for the autoscale startup scripts.

Troubleshooting Linux Startup Script Execution

The startup script will be copied to a temporary directory on the Linux host, this is usually /tmp. inside the temporary directory VMware will create a folder named vmware-root_ followed by a set of random numbers e.g. vmware-root_437-1849036237. Then VMware will create the script file inside this directory also randomly named e.g. vmware119.sh. VMware does not provide a logging facility for executing these scripts but the script writer could log important events by creating an adjacent file and writing to it. If the script fails during testing of the Autoscale/vm-provider configuration the administrator can bring up VMware console access to the cloned machine, find the script in the temporary directory and manually execute the script to observe it's output.

Windows Templates

When creating a Windows VM template ensure that:

• VMware tools is installed.
• Remote desktop has been enabled on the VM.
• The startup script entered into the VM Config Provider will be run as a Powershell script, so ensure that unrestricted remote scripting is enabled.
• If desired ensure that the Kasm Desktop Service is installed, this will make uploads and downloads available from the Kasm Control Panel.

Troubleshooting Windows Startup Script Execution

The startup script will be copied to a temporary directory on the Windows host, this is usually the directory pointed to by %TEMP%. This environment variable must be resolved when logged in as the user the script will be executed as to give an accurate location. Inside the temporary directory VMware will create a folder named vmware-root_ followed by a set of random numbers e.g. vmware-root_437-1849036237. Then VMware will create the script file inside this directory also randomly named e.g. vmware119.sh. VMware does not provide a logging facility for executing these scripts but the script writer could log important events by creating an adjacent file and writing to it. If the script fails during testing of the Autoscale/vm-provider configuration the administrator can bring up VMware console access to the cloned machine, find the script in the temporary directory and manually execute the script to observe it's output.

Bulk Import

Servers can be created in bulk through the "Import Servers" button on the Server administration page.

The ensuing import wizard will expect a utf-8 encoded CSV file, with a size limit of 10,000 records. Bulk import is an all-or-nothing operation; if any errors are found, none of the CSV data is imported into Kasm. If there are errors in the file, the interface will present an interactive table that displays the errors alongside the CSV data. The field(s) for each error are enclosed in parentheses ( ).

Click the information button for a row to inspect the errors:

Inspecting CSV Import Errors

The import wizard provides the option to download the marked-up data for further inspection. This format adds an "issues" column to the beginning of the data that lists all of the errors for each row. In addition to the localized error messages shown in the import wizard, this data also includes the untranslated error message from the Kasm server for each field. The untranslated message is enclosed by square brackets [ ]. Below is an abridged sample from the exported CSV error report produced by clicking "Export error report" in the image above:

issues,name,zone_name,connection_type,connection_credential_type,ip_hostname,port,pool_id,assigned_username,windows_service_installed,connection_username,connection_password,sso_username_domain,passphrase,private_key,use_user_private_key,connection_info,max_simultaneous_sessions,max_simultaneous_users,labels
"(name) Wrong data type [Input should be a valid string]; (zone_name) Wrong data type [Input should be a valid string]; (connection_type) Bad value for enum [Input should be 'KasmVNC', 'RDP', 'VNC' or 'SSH']; (connection_credential_type) Bad value for enum [Input should be 'STATIC', 'SSO_CREATE_USER', 'SSO_USERNAME', 'SMARTCARD' or 'PROMPT_USER']; (ip_hostname) Wrong data type [Input should be a valid string]; (port) Wrong data type [Input should be a valid integer]",,,,,,,,,,,,,,,,,,,
"(zone_name) Required resource does not exist [Zone(not a zone) does not exist]; (connection_type) Bad value for enum [Input should be 'KasmVNC', 'RDP', 'VNC' or 'SSH']; (connection_credential_type) Bad value for enum [Input should be 'STATIC', 'SSO_CREATE_USER', 'SSO_USERNAME', 'SMARTCARD' or 'PROMPT_USER']; (port) Value is too small [Input should be greater than or equal to 0]; (connection_info) Invalid JSON [Value is not a valid JSON string]; (max_simultaneous_sessions) Value is too small [Input should be greater than or equal to 1]; (max_simultaneous_users) Value is too small [Input should be greater than or equal to 1]",test_server,not a zone,not a connection type,not a credential type,192.168.0.2,-1,,,,,,,,,,{test,0,0,
"(assigned_username, pool_id) Invalid combination [User assignment requires a Server Pool]",test_server,default,ssh,Static,192.168.0.2,443,,user@kasm.local,,,,,,,,,,,

The Developer API also exposes the /api/public/batch_create_server endpoint for programmatic use.

CSV Formatting

Kasm Workspaces requires that imported CSV files to adhere to the following format specifications.

1. The file must be utf-8 encoded.
2. Fields are comma-separated (,). Commas and linebreaks inside of a double-quoted field value will be interpreted as part of the value and not as a new field or line marker. Example: a,"b,c",d would separate into three fields,a, b,c, and d.
3. A header row is required.
4. Empty fields, which includes those whose content is a quoted empty string (""), will be interpreted as null.
5. Double-quote characters inside of a field can be escaped with duplication. Example: "12""34" in a CSV field would produce 12"34.
6. All rows must have the same number of columns.

Server CSV Schema

The CSV file for Server bulk imports recognizes the following columns. Optional columns may be omitted if they are not needed for any record. The descriptions from the "Create Server" properties table above apply to these fields, except where noted.

Info

A Server's combination of Zone, IP / Hostname, and Port is unique during import. A CSV record that duplicates an existing Server will cause the import to fail.

Column Header	Required	Default	User Property	Notes
name	Yes		Friendly Name
zone_name	yes		Deployment Zone
connection_type	yes		Connection Type	Values: "KasmVNC", "RDP", "VNC", and "SSH"
connection_credential_type	yes		Connection Credential Type	Values: "STATIC", "SSO_CREATE_USER", "SSO_USERNAME", "SMARTCARD", "PROMPT_USER"
ip_hostname	yes		IP/Hostname
port	yes		Connection Port
pool_id	No	null	Pool	This is the pool_id (UUID) of the Server Pool.
assigned_username	No	null	Assigned User	See notes above about pool requirements.
windows_service_installed	No	"false"	Kasm Desktop Service
connection_username	Conditionally	null	Connection Username	See notes below
connection_password	Conditionally	null	Connection Password	See notes below
sso_username_domain	No	null	SSO Domain
private_key	No	null	Connection Private Key
passphrase	No	null	Connection Private Key Passphrase
use_user_private_key	No	"false"	Use User SSH Key	Paste the contents of the SSH keyfile (inside quotes) in this field, including linebreaks.
connection_info	No	null	Connection Info
max_simultaneous_sessions	No	1	Max Simultaneous Sessions
max_simultaneous_users	No	1	Max Simultaneous Users
labels	No	null	Labels	Labels assigned to this Server. These labels can be used to control where Workspace sessions are launched

Valid Credential Type Combinations

• "KasmVNC" connections require "STATIC" credentials and values for connection_username and connection_password
• "RDP" connections support all types. The "SSO_CREATE_USER" credential setting requires windows_service_installed to be true
• "VNC" connections only support "STATIC" credentials
• "SSH" connections support "STATIC" and "SSO_USERNAME" credential types

Below is an example of a valid Server CSV file containing all columns. It would generate five servers:

1. A KasmVNC server
2. A RDP server in a Server Pool that creates users in the SSO Domain on demand
3. A VNC server
4. A SSH Server that is assigned to an initial User and uses the connecting User's SSH certificate for authentication.
5. A SSH Server that uses an encrypted SSH private key for all connections

name,zone_name,connection_type,connection_credential_type,ip_hostname,port,pool_id,assigned_username,windows_service_installed,connection_username,connection_password,sso_username_domain,passphrase,private_key,use_user_private_key,connection_info,max_simultaneous_sessions,max_simultaneous_users,labels
KasmVNC Server,default,KasmVNC,STATIC,internal.host.local,6901,,,,test_user,SuperPassword1!,,,,,,,
RDP Server 1,default,RDP,SSO_CREATE_USER,192.168.10.24,3389,00001111-2222-3333-4444-5555-666677778888,,true,,,localssodomain,,,,,1,1,"production,windows"
VNC Server,default,VNC,STATIC,192.168.20.5,5900,,,,vnc_user,vnc_pass,,,,,,,
Personal SSH Server,default,SSH,STATIC,bob.host.local,22,,bob@local,false,,,,,,true,,24,1,"development,personal"
Shared SSH Server,default,SSH,STATIC,192.168.20.15,22,,,,,,,super_securePASSPHRASE!2,"-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: AES-128-CBC,F399B33DA2403C6087C082C64C9ABD25

Nr/Qzem29v5dkE/bKsOOg8tJvzsSBncoiUysfZ2gpTLrILDRPMYb9fh36HrAJVSO
...
vUmKldKBvmfBFOoAUc1MqUNO8gxuEGEU37FGdiZG7EZmSSjphR3Q//zFbGyC4myl
-----END RSA PRIVATE KEY-----",,,,"shared,production"