--- myst: html_meta: "description lang=en": "How to mount arbitrary host folders into Kasm Workspaces sessions." "keywords": "Kasm, How to, How-to, Persistent Data, Customization, Volume Mapping" "property=og:locale": "en_US" --- ```{title} Volume Mapping ``` ## Volume Mapping ### Configuration Example 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](../workspaces.md). In this guide we will configure a folder on the host `/mnt/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. #### 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, `/mnt/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. Please see [Using NFS](./host_guides.md#using-nfs) for configuration. ``` **Create Host Directory Example** ```Bash sudo mkdir -p /mnt/kasm_user_share sudo echo "test" | tee /mnt/kasm_user_share/test.txt sudo chown -R 1000:1000 /mnt/kasm_user_share/ ``` #### Workspace Volume Mapping Settings From the administrator dashboard click on Workspaces -> Workspaces and select a Workspace to edit: ```{figure} /images/persistent_profiles/profile_workspace_edit.webp :align: center **Edit a Workspace** ``` Scroll down to **Volume Mappings (JSON)** and use the following configuration: ``` { "/mnt/kasm_user_share":{ "bind":"/share", "mode":"rw", "uid": 1000, "gid": 1000, "required": true, "skip_check": false } } ``` ```{figure} /images/volume_mappings/volume_mapping_setting.webp :align: center **Configuring Volume Mappings on the Kasm Workspace** ``` Click save and the `/share` directory will be available on any user that launches this Workspace. ```{note} Although this guide demonstrate mapping a single volume, multiple volume mappings can be defined. > ```JSON > { > "/mnt/kasm_user_share1":{ > "bind":"/share1", > "mode":"rw", > "uid": 1000, > "gid": 1000, > "required": true > }, > "/mnt/kasm_user_share2":{ > "bind":"/share2", > "mode":"rw", > "uid": 1000, > "gid": 1000, > "required": true > } > } > ``` ``` #### Verify Functionality - Launch the Workspace the volume mapping was added to - Verify the user can read and write to the `/share` location. ```{figure} /images/volume_mappings/volume_mapping_verify.png :align: center **Verifying Volume Access** ``` ### User and Image Tokens The volume mapping config supports the use of `{user_id}`, `{username}`, and `{image_id}` tokens in the mapping name and bind attribute. This allows the administrator to create unique share locations per user. > ```JSON > { > "/mnt/kasm_user_share/{image_id}/{user_id}":{ > "bind":"/share/{username}", > "mode":"rw", > "uid": 1000, > "gid": 1000, > "required": true, > "skip_check": false > } > } > ``` ### Volume Mapping Configuration options > - **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. ### Configure Volume Mapping at a Group Level Volume Mappings may also be applied as a [Group Setting](../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. From the administrator menu first click on Access Management -> Groups and click Edit on your desired group: ```{figure} /images/persistent_profiles/profile_select_group.webp :align: center **Edit a Group** ``` Select the **Settings** tab and click on **Add Settings**, select **volume_mapping** from the dropdown. ```{figure} /images/volume_mappings/volume_mapping_add.webp :align: center **Add a New Group Setting** ``` Enter this example to mount `/mnt/kasm_user_share` from the host to `/share` in all containers launched by this group. ``` { "/mnt/kasm_user_share":{ "bind":"/share", "mode":"rw", "uid": 1000, "gid": 1000, "required": true, "skip_check": false } } ``` And click Submit: ```{figure} /images/volume_mappings/volume_mapping_group_add.webp :align: center **Configuring Volume Mappings as a Group Setting** ``` Now all sessions created by members of this group will have the mapping applied. ### Video Example This video shows an example of using Volume Mapping to create an organizational share. ```{raw} html ```