---
myst:
  html_meta:
    "description lang=en": "Create File Mappings in Kasm Workspaces."
    "keywords": "Kasm, Users, Groups, Configuration, Workspaces"
    "property=og:locale": "en_US"
---
```{title} File Mappings
```

# 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 {doc}`manage Chrome Policies <../how_to/chrome_managed_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 {doc}`Workspaces <workspaces>`, {doc}`Groups <groups>`, and {doc}`Users <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.
```

```{figure} /images/images/file_mappings.webp
:align: center
**File Mappings Table**
```

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

```{figure} /images/images/file_mapping.png
:align: center
**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 {doc}`security hardening <../security>` 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](./file_mappings.md#windows-sessions-1), 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](./windows/windows_service.md#scripts) 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 {doc}`Persistent Profiles <persistent_data/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 {doc}`Persistent Profiles <persistent_data/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`.
```

(file-mapping-windows)=

### 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](./windows/windows_service.md) 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.

```{figure} /images/file_mapping/windows_user_profile_mapping.png
:align: center
:width: 80%

File Mapping Definition placing file on user Desktop
```

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

```{figure} /images/file_mapping/windows_user_profile_mapping_screenshot.png
:align: center
:width: 80%

File Mapping Definition placing file on user Desktop
```

## Volume Mappings
File Mappings can target locations inside a {doc}`Volume Mapping <persistent_data/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.

1. 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*. 
2. Click the arrow menu and select *Edit* and select the *File Mapping* tab and click *Add File Mapping*.
3. Fill in the details of the file to be mapped and click *Save*. 
```{figure} /images/file_mapping/syllabus_file_mapping.png
:align: center
**Syllabus File Mapping Definition**
```
4. Now select the created Workspace from the Workspaces launcher.
```{figure} /images/file_mapping/ubuntu_focal_student_desktop_launcher.png
:align: center
**Workspace Launcher Icon for the Syllabus**
```
5. The syllabus.pdf will be present on the Desktop.
```{figure} /images/file_mapping/syllabus_on_desktop.png
:align: center
**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.

1. 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*.
2. Click the arrow menu and select *Edit* and select the *File Mapping* tab and click *Add File Mapping*. 
3. Fill in the details of the file to be mapped ensure to mark the file as executable and click *Save*. 
   ```bash
   #!/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"
   ```
   
```{figure} /images/file_mapping/sudo_file_mapping.png
:align: center
**Sudo Install File Mapping Definition**
```
4. Now select the created Workspace from the Workspaces launcher.
```{figure} /images/file_mapping/ubuntu_focal_sudo_desktop_launcher.png
:align: center
**Workspace Launcher Icon for Sudo Install**
```
5. Open the terminal and execute `sudo whoami` to observe that sudo is installed and working.
```{figure} /images/file_mapping/sudo_on_desktop.png
:align: center
**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`

1. 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*.
2. Click the arrow menu and select *Edit* and select the *File Mapping* tab and click *Add File Mapping*. 
3. Fill in the details of the file to be mapped ensure to mark the file as executable and click *Save*. 
   ```bash
   #!/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 
   ```
   
```{figure} /images/file_mapping/vscode_file_mapping.png
:align: center
**Repo Clone and Open VScode File Mapping Definition**
```
4. Now select the created Workspace from the Workspaces launcher.
```{figure} /images/file_mapping/ubuntu_focal_vscode_desktop_launcher.png
:align: center
**Workspace Launcher Icon for Repo Clone and VScode**
```
5. When launching the Workspace, the KasmVNC repo will be cloned, and VScode will be opened with the KasmVNC readme.
```{figure} /images/file_mapping/vscode_on_desktop.png
:align: center
**VScode Opened with KasmVNC repo loaded on the Desktop**
```


(file-mapping-background)=
### 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.

1. 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*.
2. Click the arrow menu and select *Edit* and select the *File Mapping* tab and click *Add File Mapping*.
3. Fill in the details of the file to be mapped ensure to mark the file as executable and click *Save*.
```{figure} /images/file_mapping/new_background_file_mapping.png
:align: center
**New Background File Mapping Definition**
```
4. Now select the created Workspace from the Workspaces launcher.
```{figure} /images/file_mapping/ubuntu_focal_new_background_desktop_launcher.png
:align: center
**Workspace Launcher Icon with New Background**
```
5. When launching the Workspace observe the new background that was configured in the File Mapping.
```{figure} /images/file_mapping/new_background_on_desktop.png
:align: center
**New Background in Session**
```


(file-mapping-kasmvnc)=
### Using File Mapping to Apply a Custom KasmVNC Watermark
This example replaces the default `/etc/kasmvnc/kasmvnc.yaml` configuration file in container-based workspaces. 

1. 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*.
2. Click the arrow menu and select *Edit* and select the *File Mapping* tab and click *Add File Mapping*.
3. 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](../how_to/kasmvnc_dlp_policies.md)
```{figure} /images/file_mapping/kasmvnc_file_mapping.png
:align: center
**New Background File Mapping Definition**
```

```yaml
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

```
5. When launching the Workspace observe the watermark that is applied.
```{figure} /images/file_mapping/watermark_desktop.png
:align: center
**New Background in Session**
```