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

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.

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.

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.

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.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.

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.

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

Examples

Setting environment variables.

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

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"
}

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.

../_images/file_mappings.webp

File Mappings Table

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

../_images/file_mapping.png

File Mapping Definition

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 Workspace Launch Forms 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.

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 ||Excel, where Excel is the name 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)MicrosoftEdgeApplicationmsedge.exe for example. See the RemoteApp subsection below for more details.

RemoteApp Arguments

(Optional) Arguments to be provided when executing the RemoteApp program.

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.

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 Destkop Session Host > Connections called Allow remote start of unlisted programs.

For stand-alone servers that are not part of an RDS deployment, it is not neccessary to apply this change.

Server Pools

Server Pools are groups of Servers that are to be treated equally be 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 Windows server that has Microsoft Office installed, and have a Linux Ubuntu server with LibreOffice installed Kasm workspaces will use which ever of the servers is available when a user requests a server form this server pool. 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.