Workspaces

Kasm Workspaces allows administrators to define workspaces that users can use to access a desktop, a single application, or another webpage. There are four types of workspaces that can be defined in Kasm Workspaces. Those are: Containers, Servers, Server Pools, and Links

Add / Edit Workspaces

From the Workspaces menu you can edit existing Workspaces or add new Workspaces. Each Workspace has a number of properties, the following properties are common for each Workspace type.

Name	Description
Enabled	The Workspace is enabled for use. If unchecked the Workspace will not be available for users to provision. For Container-type Workspaces, Agents will not be given instructions to download disabled images.
Workspace Type	The type of Workspace, options are Container, Server, Server Pool and Link.
Friendly Name	Workspace name shown to user.
Description	Description of Workspace.
Thumbnail URL	(Optional) URL of Workspace icon.
Include Labels	(Optional) When this setting is configured, sessions will only start on servers or agents that have at least one of the specified labels.
Exclude Labels	(Optional) When this setting is configured, sessions will only start on servers or agents that do not have any of the specified labels.
Enabled	The Workspace is enabled for use. If unchecked the Workspace will not be available for users to provision. For Container type Worksapaces Agents will not be given instructions to download Images that are disabled.
Categories	(Optional) Define a list of categories the Workspace belongs to. These categories will be displayed on the Workspaces dashboard for uses to select. The first category listed is the one displayed for the Workspace when looking at a list of all Workspaces.
Session Banner	Inherit will use any banners that are applied by a group setting. Force disable will override any group settings and not show a banner. Selecting a specific banner will override any group settings and display that banner for this workspace. See Banners documentation.
Hide Workspace on Dashboard	Do not show the Workspace as available on the user dashboard.
Notes	(Optional) A free form field used for taking notes about the Workspace. This is only displayed when editing or viewing a Workspace configuration. This is a great way to let other admins know about anything specific to this Workspace.

Note

The Workspaces are by default added to the all users group. This behavior can be changed with the Add Workspaces To Default Group server setting.

Containers

Containers are what have been traditionally referred to as images in the Kasm Workspaces ecosystem. These are Linux docker images that have applications installed, that are then provision by docker as containers and streamed to the user over KasmVNC. See Images for more details on available default docker images and creating custom docker images. Attributes that are specific to Container type Workspaces are below:

Name	Description
Docker Image	The Docker Image and tag.
Cores	Amount of CPU cores allocated per Workspace.
Memory	Amount of Memory allocated per Workspace, in megabytes.
GPU Count	When the session is created, the system will map in this many GPUs into the the container. See Agent Settings.
Uncompressed Image Size (MB)	The estimated size of a container image (in megabytes) when extracted to disk. When defined, the Agent can guard against pulling an image if it would result in filling the disk. More specifically, the volume where the Docker Root Directory resides (default: /var/lib/docker). By default the Agent will avoid pulling an image if it would result in the disk becoming over 90% full. The disk_usage_limit setting can be changed in the Agents config: /opt/kasm/current/conf/app/agent/agent.app.config.yaml
CPU Allocation Method	Sets the CPU Allocation Method for the Workspace. Selecting Inherit will cause the Workspace to use the Global Setting Default CPU Allocation Method. See CPU Allocation Method for more details.
Docker Registry	The docker registry to pull the docker images from For Docker Hub use https://index.docker.io/v1/ Leave this option blank if you intend to use local images built directly on the Agent server.
Docker Registry Username	(Optional) Username.
Docker Registry Password	(Optional) Password.
Hash	(Optional) hash of docker image.
Persistent Profile Path	(Optional) Absolute path of the location to store user's persistent profile or S3 URL. See Persistent Profiles for more details.
Enforce Workspace Persistent Profile	Enabling this option will ensure that persistent profiles for this workspace are always enabled.
Volume Mappings	(Optional) Json data for Volume Mappings.
Docker Run Config Override	(Optional) Json data for specifying additional docker run arguments, see Docker Run Config for more info.
Docker Exec Config	(Optional) Json data for specifying commands to be executed when a Workspace container is started or resumed. See the Docker Exec Config for details.
Launch Config	(Optional) Json data for specifying a custom form to present to the user when the workspace is launched. See Workspace Launch Forms for more details.
Web Filter Policy	Enables web filtering and sets the Web Filter Policy to be used. Policies can also be set via Group Settings. Policies assigned to Workspaces take priority over those defined via Group Settings. Selecting Inherit will instruct the system to use a policy if defined on a Group Setting. Selecting Force Disabled will instruct the system to not use a policy even if one is defined in a Group Setting.
Allow Network Selection	When enabled, users will be presented with a dropdown of available docker networks when creating a session. The list of available networks can be limited if Restrict Workspace to Docker Network is configured.
Restrict Workspace to Docker Network	(Optional) Instances of this Workspace will only be created on agent servers with this docker network.
Restrict Workspace to Kasm Agent	(Optional) Instances of this Workspace will only be created on this agent server.
Restrict Workspace to Deployment Zone	(Optional) Instances of this Workspace will only be created on Agents within the selected Deployment Zone.
Session Time Limit	The amount of time (in seconds) before a session will automatically expire. A countdown timer will be displayed to the user.
Direct Install URL	Workspaces and casting links can be installed as standalone PWA applications, this is the direct url that can be used for automatic installation via management systems such as Windows Group Policy and Chrome Managed Policies.
Override Egress Gateways	When Enabled, the Egress Gateways mapped to this Workspace will be the only gateways available to select during launch. Users will also be required to launch this Workspace using an Egress Gateway if one there is one mapped.

Docker Exec Config

The Docker Exec configurations allow administrators to configure custom commands to be executed when a user creates or resumes a Kasm.

This JSON dictionary configuration accepts three top-level keys first_launch, go, and assign.

• first_launch : This command is executed after the session is launched.
• go : This command is executed when the user requests to create or resume a session via the /go url. If the session doesn't exist yet, and will be created for the first time, the first_launch command will take priority. If the user is assigned a Staged Session as part of the request, the assign command will take priority.
• assign : This command is executed when the user is assigned a Staged Session via direct request, the /go url, or via request_kasm api

The following example demonstrates how to use the Docker Exec Config for the default kasmweb/chrome Image for a seamless browser isolation configuration.

See Browser Isolation for more details.

{
    "first_launch": {
        "cmd": "bash -c 'google-chrome --start-maximized \"$KASM_URL\"'",
        "environment": {
            "LAUNCH_URL": ""
        }
    },
    "go": {
        "cmd": "bash -c 'google-chrome --start-maximized \"$KASM_URL\"'"
    },
    "assign": {
        "cmd": "bash -c 'google-chrome --start-maximized \"$KASM_URL\"'"
    }
}

Docker Run Config

The Docker Run Config Override setting may be used by administrators to pass custom docker run options when the session container is created. Many items that can be invoked by the docker run commandline tool can be defined in the json structure mirroring the keyword arguments defined in the docker python API Container.run function. Detailed specs can be found in the Docker SDK for Python Documentation

Variable Substitution

The following variables can be templated into the storage mapping Default Target and Volume Config properties to support additional use-cases. Note: Variable substitution is not compatible with Session Staging.

• {username} - The username of the user provisioning the session. e.g user@kasm.local
• {user_id} - The user_id of the user provisioning the session . e.g 6c0535dc02eb49c4a556cae9816a585d
• {image_id} - The image ,aka workspace, id used for the session. eg. 9de4ea298f064e6999c5b9b164e2c04c
• {custom_attribute_1} - The custom attribute 1 value from the user.
• {custom_attribute_2} - The custom attribute 2 value from the user.
• {custom_attribute_3} - The custom attribute 3 value from the user.

Examples

Setting environment variables.

{
    "environment": {
        "FOO": "BAR",
        "BIN" : "BAZ",
        "CUSTOM_ATTRIBUTE_1": "{custom_attribute_1}"
    }
}

Setting the language and timezone. Using the above environment variables syntax it's possible to set the language and timezone that the Kasm container will use. In Kasm Workspaces 1.14.0 many locales were added to the Kasm containerized workspaces in the official Workspaces Registry. See Valid Timezones and Valid Locales

{
    "environment": {
        "LC_ALL": "fr_FR.UTF-8",
        "TZ" : "Europe/Paris"
    }
}

Setting Virtual Printer Name Using the environment variables it's possible to set the name of virtual printer that the Kasm container will use. Please note that the name should not include any spaces.

{
    "environment": {
        "KASM_PRINTER_NAME": "Virtual-Printer"
    }
}

Setting the container hostname.

{
    "hostname": "HOST-123"
}

{
    "hostname": "{user_id}"
}

Setting the user. see Running as root for more details

{
    "user": "root"
}

Mapping in devices.

{
    "devices":
        [
            "/dev/input/event0:/dev/input/event0:rwm",
            "/dev/net/tun:/dev/net/tun:rwm"
        ]
}

Adjusting security options.

{
    "security_opt":
        [
            "seccomp=unconfined"
        ]
}

Adjusting the size of /dev/shm.

{
    "shm_size" : "4g"
}

Running the container as privileged.

{
    "privileged" : true
}

Adding / Removing Linux Kernel capabilities.

{
    "cap_add" : ["SYS_ADMIN", "MKNOD"],
    "cap_drop" : ["SYS_RESOURCE"]
}

Adding Custom DNS Servers. See Custom DNS Servers for more info.

{
  "dns": [
    "208.67.220.220",
    "208.67.222.222"
  ]
}

Adding fixed hostname mappings to /etc/hosts.

{
  "extra_hosts": {
    "testing1.example.com": "10.0.0.1",
    "testing2.example.com": "10.0.0.2",
    "testing3.example.com": "10.0.0.3"
  }
}

File Mapping

File Mappings allow the administrator to manage files to be mapped to the inside of a user's container based Workspace session. File Mappings can be defined on a User, Group, and/or Workspace. See the primary documentation on File mappings for more details.

Note

File Mappings are only visible when editing an existing container based Workspace. To configure File mappings for a Workspace, Navigate to Workspaces, then select Edit next to desired container based workspace.

File Mappings Table

The following is an example File Mapping of a Chrome Managed Policy to define bookmarks in Chrome.

File Mapping Definition

Links

Links are a way to define another webpage that will be presented in the workspaces dashboard for users to access. This could be a company website like time sheet tracking or a ticketing system, or an external website such as Google Drive or microsoft OneDrive. Attributes that are specific to Link type Workspaces are below:

Name	Description
URL	The URL to direct the user to when clicking on this Workspace in the dashboard.

Servers

Servers are workspaces intended to define a single physical or virtual server. This server can be connected to from Kasm Workspaces via KasmVNC, RDP, VNC, or SSH. Attributes that are specific to Server type Workspaces are below:

Name	Description
Server	Dropdown to select the defined Server entity to use for this Workspace.
Session Time Limit	The amount of time (in seconds) before a session will automatically expire. A countdown timer will be displayed to the user.
Launch Config	(Optional) Json data for specifying a custom form to present to the user when the workspace is launched. See launch-config for more details.
RDP Client Options	When the workspace definition targets a server with RDP connection type the administrator has the option of having the Workspace use Web native client for using Kasm's browser native connection to the RDP target or RDP local client to use the RDP thick client that is installed on the users client machine. Admins can allow the user to choose when they launch a session by setting this to User Selectable.
Enable RemoteApp	Uses Microsoft RemoteApp to provide a user an application running remotely that appears to be running on the user's local system.
RemoteApp Program Name/Path	The registered RemoteApp name in the format of the RemoteApp as registered in the backend system. Alternatively, the full path to the application executable can be provided if the server is configured to allow this,C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe` for example. See the RemoteApp subsection below for more details.
RemoteApp Arguments	(Optional) Arguments to be provided when executing the RemoteApp program.

Server Assignment

Servers can be assigned to specific Users if they are part of a Server Pool that allows assignment. See the Server Pool section below for more information.

RemoteApp

Microsoft's RemoteApp feature of Windows and Remote Desktop Services allows for users to run applications on remote systems, but make them appear as if they are running on their local system. Kasm supports RemoteApps as either WebNative and displayed within the user's browser or via RDP where the apps appear to be running as local applications. When the Workspace RDP Client Option is set to Web native client there is a current limitation that Kasm can only assign a single concurrent sesssion per user on each server. When selecting RDP local client as the RDP Client Option setting, there is no such limit.

RemoteApps can be configured in Kasm by a RemoteApp name or by a fully qualified path to the application's executable, as covered in the following two sub-sections. For servers that are not part of an RDS deployment, whether AD joined or not, it is generally not required to register the RemoteApp or configure a group policy as shown below. Adminstrators can instead set the RemoteApp Program Name/Path value to the fully qualified path to the executable. RDS deployments will require a group policy to allow specifying an executable path or you will need to register the RemoteApp in RDS to reference it by name in the Kasm Workspaces settings.

Administrators should install the Kasm Desktop Service when users will access RemoteApps using Kasm's web native client. The Kasm Desktop Service will ensure that when a user closes a web native session, the associated RemoteApp and Terminal Session on the Windows server will be closed. This is not required for RemoteApps where a RDP native client is used.

Registering a RemoteApp

RemoteApps can be created in an RDS deployment and then referenced in Kasm Workspace settings by the RemoteApp name. See the Microsoft documentation for more details on publishing RemoteApps in RDS: https://learn.microsoft.com/en-us/windows-server/remote/remote-desktop-services/rds-create-collection.

Following these steps, you can configure a Workspace's RemoteApp Program Name to ||Microsoft Edge, for example. Ensure the name is prepended with the two pipe characters.

To register RemoteApps on servers that are not part of RDS, whether domain joined or not, follow these steps. This is not required if you prefer to provide the full path to the executable as covered in the next section.

• Launch regedit.exe as an adminstrator
• Naviate to HKLM\Software\Microsoft\Windows NT\CurrentVersion\Terminal Server
• Create a new key Applications
• Create a new key in Applications named after your application, such as Microsoft Edge.
• Create the following values under your new key created in the previous step. The following is an example for Microsoft Edge.

The Name and Path are required, the rest are optional registry entries:

Name	Type	Example
Name	string	Microsoft Edge
Path	string	C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
VPath	string	C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
RequiredCommandLine	dword	00000001
IconPath	string	C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
IconIndex	dword	00000000
ShowInTSWA	dword	00000000

Following these steps, you can configure a Workspace's RemoteApp Program Name to ||Microsoft Edge.

Configure RemoteApp Path

Rather than registering a RemoteApp and specifying the name in the RemoteApp Program Name/Path field of the Workspace settings, administrators can specify the fully qualified path to the executable of the application on the remote system.

For RDS deployments a group policy must be applied to the system that allows this. The Group/Local Policy is found under Computer Configuration > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Connections called Allow remote start of unlisted programs.

For standalone servers that are not part of an RDS deployment, it is not necessary to apply this change.

Server Pools

Server Pools are groups of Servers that are to be treated equally by Kasm Workspaces. These server instances don't need to be identical, but Kasm Workspaces will treat each server in a Server Pool as interchangeable. For instance, you may have a Server Pool that contains a Windows server with Microsoft Office installed and a Linux Ubuntu server with LibreOffice installed. When a user requests a server from this Server Pool, Kasm Workspaces will use whichever of the two servers is available.

Attributes that are specific to Server Pool type Workspaces are below:

Name	Description
Pool	Dropdown to select the defined Server Pool entity to use for this Workspace.
Session Time Limit	The amount of time (in seconds) before a session will automatically expire. A countdown timer will be displayed to the user.
Launch Config	(Optional) Json data for specifying a custom form to present to the user when the workspace is launched. See Workspace Launch Forms for more details.

User-Server Assignment

Server Pools of the Server type support assignment of specific Users to specific Servers. Workspaces for pools with assignment enabled will create sessions only on Servers within the pool that are assigned to a given User. For example, if User 1 is assigned only to User1 Linux in the Server Pool, then User 1 will always receive a Session on User1 Linux.

If a User is assigned to more than one Server:

• They may pick which server to use for the new session

• If they do not choose a server, then one will be selected based on Zone load distribution configurations

If a User does not have an assigned Server but has the Workspace on their dashboard, then the Workspace will show with a warning. They will be instructed to contact an Administrator for support.

Reverting to an Unassigned Pool

If assignment is turned off for a Server Pool, all Servers in the pool are considered available for use by all Users that can access the Workspace.

Additional Resources

See the User-Server Assignment page for more information.