File Mappings

File mappings allow the administrator to manage files to be mapped to the inside of a user’s Workspace session. This can be used, for example, to manage Chrome Policies. This reduces the need to create custom images. Text based files can be edited directly in the Kasm Admin UI. There is also the ability to upload arbitrary files, with a file size limit of 5MB. Arbitrary files that are scripts should have UNIX style line endings.

File mappings can be applied to Workspaces, Groups, and Users. When a user creates a session, the File Mappings are applied in the order of Workspace, Groups, and User defined File Mappings. Only the first File Mapping targeting the same destination will be added to the session. Subsequent File Mapping definitions targeting the same destination will be skipped and logged when a user creates a session.

The Kasm Desktop Service must be installed on Windows systems for file mapping to work. File mappings defined at the Workspace level are applied on service start.

Note

When a user belongs to multiple Groups that define a File Mapping with the same destination, the group with the lowest priority value gets mapped into the user’s container.

../_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**

File Permissions and Ownership

Container Sessions

File Mapping definitions can be marked as Writable and Executable. By default, a file is owned by root and the container user does not have write permissions to the file. Marking the File Mapping as Writable changes the owner to the container user and provides write access to the file. Marking the File Mapping as Executable adds the executable permission to the file.

Directories that do not already exist within the target path, will automatically be created and owned by root. For example, if you defined a writable File Mapping with a target location of /data/bin/script.sh and the location /data/bin did not already exist inside the container, the path /data/bin would get created with ownership belonging to root. The file, script.sh would be owned by the container user. The result is that the user would be able to edit the file script.sh, but would be unable to create new files within the containing directory. Permissions and ownership of existing paths will not be modified.

Note

Marking File Mappings as Writable is only supported when when the kasm_agent container is running as root. By default Kasm Workspaces runs the kasm_agent container as root, however, when security hardening is applied to Kasm Workspaces the kasm_agent container runs as a non-root user. The kasm_agent will detect that it is not running as root and skip changing ownership for File Mappings marked as writable.

Windows Sessions

In Windows, permissions and ownership are determined by the destination directory that the file is created in. Files placed in a user’s HOMEPATH, for example, are owned by the user. For this reason, the read-only and executable settings in the Kasm Admin UI for file mapping definitions are not affective on Windows. A potential work around would be to use a PowerShell session start script to customize advanced file permissions.

User Home Profile

Container Sessions

A user’s home profile for a containerized Workspace is located at /home/kasm-user. Many applications save configurations and other files in the user’s home profile. For this reason, it is often advantageous to use File Mappings to manage files in the users home profile. There are, however, several things to be aware of when mapping files to a users home profile.

Kasm containers use a default profile located at /home/kasm-default-profile, this directory contains the starting state for the container users home profile. If Persistent Profiles are enabled, different logic is used for the home directory. The following logic is followed on startup of a container.

Persistent Profiles are not configured.
- Copy /home/kasm-default-profile to /home/kasm-user
Persistent Profiles are configured and enabled.
- First time this user has started a session, no existing persistent profile for this user.
  - Copy /home/kasm-default-profile to /home/kasm-user.
- Persistent profile already exists.
  - No action taken, /home/kasm-user is volume mapped into the container

Due to the above logic, it is not possible to define File Mappings that target /home/kasm-user, since that directory is populated on container start. Instead, File Mappings should target /home/kasm-default-profile. When the container starts, the files mapped in at /home/kasm-default-profile will be copied to /home/kasm-user.

Note

If Persistent Profiles are enabled, users will not pickup changes to File Mappings. Users would either need to clear their persistent profile so that the profile is recreated or they would need to copy the specific files from /home/kasm-default-profile to /home/kasm-user.

Windows Sessions

Windows home profile is typically stored under C:\Users\{username}, however, the environmental variable %HOMEPATH% contains the actual path of the user. Environmental variables, to include %HOMEPATH% can be used in file mapping destination paths for Windows sessions. The Kasm Desktop Service is required to be installed on the Windows server to support file mapping. File mappings mapped into a user’s home profile path are automatically deleted on session termination. Only file mappings defined at the group and user levels can target a user’s home profile. File mappings defined at the Workspace Image level are processed on the start of the Kasm Desktop Service and thus are processed with no associated user.

The following example shows a file mapping that places a file on a user’s Desktop on a Windows system.

File Mapping Definition placing file on user Desktop

The above definition results in the file being placed on the user’s desktop.

File Mapping Definition placing file on user Desktop

Volume Mappings

File Mappings can target locations inside a Volume Mapping. It should be noted, however, that mapping to directories that do not exist on a volume mapping will result in directories being created on the volume map that are owned by root. For example, consider a volume mapping of /mnt/nfs_share/finance:/shares/finance, where /mnt/nfs_share/finance was the location on the host and /shares/finance was the location inside the container and you created a File Mapping that targeted a destination of /shares/finance/does_not_exist_on_share/policy.pdf. The file, policy.pdf would never get saved on the host at /mnt/nfs_share/finance, because it is itself a mapping into the container. However, due to the behavior of Docker, the folder /shares/finance/does_not_exist_on_share would get created if it did not exist and it would be owned by root. This would result in the folder being created at /mnt/nfs/share/finance/does_not_exist_on_share on the host and/or the remote NFS share mounted to that location on the host.

File Mapping Usage Examples

Here are a few prepared examples of using the File Mapping feature. These examples will work with the User, Group, and Workspace iterations of the File Mapping feature.

Mapping in a File to The User’s Desktop

This example will be a straightforward example of preparing a Syllabus to be mapped onto the desktop of an image. This eliminates the need to create a new image just to have the syllabus file available to students on container start.

Clone the Workspace to be used. Here the Ubuntu Focal workspace has been cloned and named Ubuntu Focal Student Desktop. After editing the name and description click Submit.
Click the arrow menu and select Edit and select the File Mapping tab and click Add File Mapping.
Fill in the details of the file to be mapped and click Save.

../_images/syllabus_file_mapping.png — **Syllabus File Mapping Definition**

Now select the created Workspace from the Workspaces launcher.

../_images/ubuntu_focal_student_desktop_launcher.png — **Workspace Launcher Icon for the Syllabus**

The syllabus.pdf will be present on the Desktop.

../_images/syllabus_on_desktop.png — **Syllabus.pdf Present on the Desktop of the Configured Workspace**

Using File Mapping to Install and Enable Sudo

This example utilizes a feature in Kasm docker images to run a bash script as root after the container starts. This script is located in the image at /dockerstartup/kasm_post_run_root.sh and a custom version can be mapped in using the File Mapping feature. The script used in this example will install the sudo binary and add the kasm-user to the sudoers group. By using the file mapping feature, sudo can be added to any of the existing Kasm Workspaces without having to create a custom image.

Clone the Workspace to be used. Here the Ubuntu Focal workspace has been cloned and named Ubuntu Focal Sudo Desktop. After editing the name and description click Submit.
Click the arrow menu and select Edit and select the File Mapping tab and click Add File Mapping.

Fill in the details of the file to be mapped ensure to mark the file as executable and click Save.

#!/usr/bin/env bash
set -ex
apt-get update
apt-get install -y sudo
echo "kasm-user  ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
notify-send "Script Complete" "sudo is now installed"

../_images/sudo_file_mapping.png — **Sudo Install File Mapping Definition**

Now select the created Workspace from the Workspaces launcher.

../_images/ubuntu_focal_sudo_desktop_launcher.png — **Workspace Launcher Icon for Sudo Install**

Open the terminal and execute sudo whoami to observe that sudo is installed and working.

../_images/sudo_on_desktop.png — **Sudo Installed and Working on the Desktop**

Using File Mapping to Clone a Repo and Start VScode

This example uses another script in the Kasm docker images that is the non-root user equivalent of the script used in the Using File Mapping to Install and Enable Sudo example. This script is located in the image at /dockerstartup/kasm_post_run_user.sh

Clone the Workspace to be used. Here the Ubuntu Focal workspace has been cloned and named Ubuntu Focal VScode Desktop. After editing the name and description click Submit.
Click the arrow menu and select Edit and select the File Mapping tab and click Add File Mapping.

Fill in the details of the file to be mapped ensure to mark the file as executable and click Save.

#!/usr/bin/env bash
set -ex
/usr/bin/desktop_ready
git clone https://github.com/kasmtech/KasmVNC /home/kasm-user/Desktop/KasmVNC/
code  --no-sandbox  -a /home/kasm-user/Desktop/KasmVNC/ -g /home/kasm-user/Desktop/KasmVNC/README.md 

../_images/vscode_file_mapping.png — **Repo Clone and Open VScode File Mapping Definition**

Now select the created Workspace from the Workspaces launcher.

../_images/ubuntu_focal_vscode_desktop_launcher.png — **Workspace Launcher Icon for Repo Clone and VScode**

When launching the Workspace, the KasmVNC repo will be cloned, and VScode will be opened with the KasmVNC readme.

../_images/vscode_on_desktop.png — **VScode Opened with KasmVNC repo loaded on the Desktop**

Using File Mapping to Change the Default Background of a Workspace

This example replaces the default background of a workspace, for Ubuntu that is located at /usr/share/backgrounds/bg_default.png, it may be in a different location for other distros or Workspace images.

Clone the Workspace to be used. Here the Ubuntu Focal workspace has been cloned and named Ubuntu Focal New Background Desktop. After editing the name and description click Submit.
Click the arrow menu and select Edit and select the File Mapping tab and click Add File Mapping.
Fill in the details of the file to be mapped ensure to mark the file as executable and click Save.

../_images/new_background_file_mapping.png — **New Background File Mapping Definition**

Now select the created Workspace from the Workspaces launcher.

../_images/ubuntu_focal_new_background_desktop_launcher.png — **Workspace Launcher Icon with New Background**

When launching the Workspace observe the new background that was configured in the File Mapping.

../_images/new_background_on_desktop.png — **New Background in Session**

Using File Mapping to Apply a Custom KasmVNC Watermark

This example replaces the default /etc/kasmvnc/kasmvnc.yaml configuration file in container-based workspaces.

Clone the Workspace to be used. Here the Ubuntu Focal workspace has been cloned and named Ubuntu Focal Watermark. After editing the name and description click Submit.
Click the arrow menu and select Edit and select the File Mapping tab and click Add File Mapping.
Fill in the details of the file to be mapped ensure to mark the file as executable and click Save. More details about found in the Applying KasmVNC DLP Policies

../_images/kasmvnc_file_mapping.png — **New Background File Mapping Definition**

network: 
  ssl:
   pem_certificate: ${HOME}/.vnc/self.pem
   pem_key: ${HOME}/.vnc/self.pem
  udp:
    public_ip: 127.0.0.1
data_loss_prevention:
  watermark:
    repeat_spacing: 50
    tint: 0,255,0,80
    text:
      template: "Kasm Workspaces User ${KASM_USER} (${KASM_ID}) at %F %H:%M"
      font: auto
      angle: 45
      font_size: 24
      timezone_name: Asia/Taipei

When launching the Workspace observe the watermark that is applied.

../_images/watermark_desktop.png — **New Background in Session**