.. 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 Image <../guide/custom_images.html>`_. .. figure:: /images/volume_mappings/volume_mappings.png :width: 90% :align: center **Configuring Volume Mappings on the Kasm Image** Volume Mappings may also be applied as a `Group Setting <../guide/groups.html#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 :width: 60% :align: center **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 image to a folder named ``/share``. This effectively will act as a file share. All users's who have access to provision the image 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. .. code-block:: 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. .. code-block:: Bash sudo mkdir /var/kasm_user_share sudo chown 1000:1000 /var/kasm_user_share/ echo "test" > /var/kasm_user_share/test.txt Configure Image Volume Mappings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * Log into the Kasm UI as an administrator. * Select Images, and click edit (pencil) next to the Kasm Desktop image * In the Volume Mappings field, paste the following configuration and click Submit .. code-block:: 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. .. code-block:: 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 Image. * Verify the user can read and write to the ``/share`` location. .. figure:: /images/volume_mappings/verification.png :width: 90% :align: center **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. .. code-block:: 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 `__ for more details. .. code-block:: 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. .. code-block:: Bash sudo exportfs -ar NFS Client ^^^^^^^^^^ * Create a directory for the mount. .. code-block:: 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`` .. code-block:: Bash 192.168.1.2:/kasmdata /mnt/kasm-nfs nfs defaults 0 0 * Mount the share. .. code-block:: Bash sudo mount /mnt/kasm-nfs * Test creating a file. .. code-block:: Bash sudo touch /mnt/kasm-nfs/example.txt * Inspect the file from the NFS Server to ensure the permissions are UID/GID 1000. .. code-block:: 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. .. code-block:: JSON { "/mnt/kasm-nfs":{ "bind":"/share", "mode":"rw", "uid": 1000, "gid": 1000, "required": true, "skip_check": false } }