---
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 container based 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 docker 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.

```{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.jpg
:align: center
:width: 60%

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
:width: 80%

File Mapping Definition
```

## File Permissions and Ownership
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.
```

## User Home Profile
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`.
```

## 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 three dot menu and select *View* and scroll to the bottom of the workspace configuration 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
   :width: 100%

   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
   :width: 50%

   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
   :width: 80%

   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 three dot menu and select *View* and scroll to the bottom of the workspace configuration 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
   :width: 100%

   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
   :width: 50%

   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
   :width: 80%

   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 three dot menu and select *View* and scroll to the bottom of the workspace configuration 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
   :width: 100%

   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
   :width: 50%

   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
   :width: 80%

   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/extra/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 three dot menu and select *View* and scroll to the bottom of the workspace configuration 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
   :width: 100%

   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
   :width: 50%

   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
   :width: 80%

   Workspace Loaded With New Background