---
myst:
html_meta:
"description lang=en": "How to mount arbitrary host folders into Kasm Workspaces sessions."
"keywords": "Kasm, How to, How-to, Persistent Data, NFS,Customization"
"property=og:locale": "en_US"
---
```{title} Persistent Data
```
# Persistent Data
## Overview
Kasm Workspaces allows administrators to configure folders to be mapped inside a Kasm each
time it is provisioned. This is done by configuring the **Volume Mappings** field on the
[Kasm Workspace](../guide/workspaces.md).
> ```{figure} /images/volume_mappings/volume_mappings.png
> :align: center
> :width: 90%
>
> **Configuring Volume Mappings on the Kasm Workspace**
> ```
Volume Mappings may also be applied as a [Group Setting](../guide/groups.md#group-settings) . This may be useful
if a certain set of users should have the mapping. When applied at the group level, all sessions created by members of this
group will have the mapping applied.
> ```{figure} /images/volume_mappings/group_volume_mappings.png
> :align: center
> :width: 60%
>
> **Configuring Volume Mappings as a Group Setting**
> ```
In this guide we will configure a folder on the host `/var/kasm_user_share` to be mapped inside the Kasm Desktop
workspace to a folder named `/share`. This effectively will act as a file share. All users's who have access to provision
the workspace will have access to this folder.
## Volume Mapping Config
> - **bind**
> - The path inside the Kasm where the volume will be mounted.
> - **mode**
> - `rw` for Read-Write , `ro` for Read-Only.
> - **uid**
> - The linux user id ownership that should be given to the volume. This permission is applied to the folder on the host.
> The uid must be `1000` in order for the Kasm container use to access the files.
> - **gid**
> - The linux group id ownership that should be given to the volume. This permission is applied to the folder on the
> host. The gid must be `1000` in order for the Kasm container use to access the files.
> - **required**
> - If `true` the volume must be accessible in order to provision the Kasm when requested. If `false` the
> system will allow the Kasm to be provision even if connectivity to the volume cannot be established. If not specified
> the default is `true`.
> - **timeout**
> - When a Kasm is provisioned , the system will attempt to establish connectivity to the volume specified. The system
> will wait the specified number of seconds before deeming the connectivity has failed. If not specified the default is
> `10` seconds
> - **skip_check (optional)**
> - When a Kasm is provisioned , the system will attempt to establish connectivity to the volume specified and ensure
> the ownership of that directory matches the uid:gid specified with a :code:'chown'. On some filesystems such as
> those mounted as read only, this check will fail or error. The administrator may choose to set this
> value to `true` so the system will skip the check. The default is `false` if not specified.
### User Tokens
The volume mapping config supports the use of `{user_id}` and `{username}` tokens in the mapping
name and bind attribute. This allows the administrator to create unique share locations per user.
> ```JSON
> {
> "/var/kasm_user_share/{user_id}":{
> "bind":"/share/{username}",
> "mode":"rw",
> "uid": 1000,
> "gid": 1000,
> "required": true,
> "skip_check": false
> }
> }
> ```
## Configuration Example
### Create Host Directory
On the Kasm Workspaces server, create the directory and change the ownership to user and group **1000**.
```{note}
If Kasm is installed in a multi-server deployment, `/var/kasm_user_share` in this example should reference a
shared data storage solution (e.g NFS, HDFS, GFS, SMB, SSHFS) to ensure data continuity. Administrators must ensure
this path is accessible from the hosts of all Agent services.
```
```Bash
sudo mkdir /var/kasm_user_share
sudo chown 1000:1000 /var/kasm_user_share/
echo "test" > /var/kasm_user_share/test.txt
```
### Configure Workspace Volume Mappings
- Log into the Kasm UI as an administrator.
- Select Workspaces, and click edit (pencil) next to the Kasm Desktop workspace
- In the Volume Mappings field, paste the following configuration and click Submit
> ```JSON
> {
> "/var/kasm_user_share":{
> "bind":"/share",
> "mode":"rw",
> "uid": 1000,
> "gid": 1000,
> "required": true,
> "skip_check": false
> }
> }
> ```
```{note}
Although this guide demonstrate mapping a single volume, multiple volume mappings can be defined.
> ```JSON
> {
> "/var/kasm_user_share1":{
> "bind":"/share1",
> "mode":"rw",
> "uid": 1000,
> "gid": 1000,
> "required": true
> },
> "/var/kasm_user_share2":{
> "bind":"/share2",
> "mode":"rw",
> "uid": 1000,
> "gid": 1000,
> "required": true
> }
> }
> ```
```
### Verify Access
- Launch the Kasm Desktop Workspace.
- Verify the user can read and write to the `/share` location.
```{figure} /images/volume_mappings/verification.png
:align: center
:width: 90%
**Verifying Volume Access**
```
## NFS Examples
This example assumes NFS Server and client software is installed on the respective servers.
### NFS Server
- Create the folder to host the share.
> ```Bash
> sudo mkdir /kasmdata
> sudo chown -R 1000:1000 /kasmdata/
> ```
- Add the entry to `/etc/exports`. In this example the IP of the NFS Client is `192.168.1.3`.
Note the use of `all_squash`, `anonuid`, and `anongid` settings
to ensure that all files are accessed and written as the default Kasm session UID 1000.
See [https://linux.die.net/man/5/exports](https://linux.die.net/man/5/exports) for more details.
> ```Bash
> /kasmdata 192.168.1.3(rw,sync,all_squash,anonuid=1000,anongid=1000,no_subtree_check)
> ```
- Expose the new additions defined in the exports.
> ```Bash
> sudo exportfs -ar
> ```
### NFS Client
- Create a directory for the mount.
> ```Bash
> sudo mkdir -p /mnt/kasm-nfs
> ```
- Add an entry to `` `/etc/fstab `` for the NFS mount. In this example the IP of the NFS Server is `192.168.1.2`
> ```Bash
> 192.168.1.2:/kasmdata /mnt/kasm-nfs nfs defaults 0 0
> ```
- Mount the share.
> ```Bash
> sudo mount /mnt/kasm-nfs
> ```
- Test creating a file.
> ```Bash
> sudo touch /mnt/kasm-nfs/example.txt
> ```
- Inspect the file from the NFS Server to ensure the permissions are UID/GID 1000.
> ```Bash
> ls -la /kasmdata/
> total 8
> drwxr-xr-x 2 1000 1000 4096 Feb 24 08:39 .
> drwxr-xr-x 20 root root 4096 Feb 23 16:00 ..
> -rw-r--r-- 1 1000 1000 0 Feb 24 08:39 example.txt
> ```
- You can now reference the NFS share in volume mappings or persistent profile configurations.
> ```JSON
> {
> "/mnt/kasm-nfs":{
> "bind":"/share",
> "mode":"rw",
> "uid": 1000,
> "gid": 1000,
> "required": true,
> "skip_check": false
> }
> }
> ```