--- myst: html_meta: "description lang=en": "Create Storage Mappings in Kasm Workspaces." "keywords": "Storage Mappings, Cloud Storage, Google Drive, Dropbox, NextCloud, OneDrive, S3" "property=og:locale": "en_US" --- ```{title} Storage Mappings ``` # Storage Mappings Storage Mappings allow administrators to create and attach custom and ephemeral docker volumes in Kasm Workspace Containers. This feature can also be used to allow end users to map popular {ref}`user-cloud-storage` services like Google Drive, Dropbox, NextCloud, and Onedrive. In order to use Storage Mappings, administrators must first create **Storage Providers**, which contain the volume and mount configurations, in addition to applicable settings for supported cloud storage providers. The process is as follows: 1. The Administrator configures a **Storage Provider** (e.g Google Drive) 2. The Administrator may now create **Storage Mappings** that leverage the Storage Provider. The mappings may be placed on a User, Group or Workspace object. 3. The Administrator can allow end-users to create their own **Storage Mappings** by configuring the following group settings: - `allow_user_storage_mapping`: When enabled the user is allowed to configure their own **Storage Mappings** via their profile. When disabled, new user configuration will not be allowed, nor will using any previously configured mappings be allowed when new sessions are created. - `max_user_storage_mappings`: The maximum number of Storage Mappings a user is allowed to have registered to their account. - `read_only_user_storage_mappings`: When enabled, any storage mappings configured on the user account will be forced to read-only. 4. If allowed via group settings, end-users can configure Storage Mappings to the registered Providers via the {ref}`user-cloud-storage` section of the profile widget. 5. When a container-based Workspaces session is created, a docker volume is created on the Agent and mounted inside the session based on the Storage Provider and Storage Mapping configurations. The remote files become available for use within the session. 6. When the session is destroyed, the previously created docker volume is also destroyed. ## Storage Providers ```{eval-rst} +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Name | A custom name given to the Storage Provider | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Storage Provider Type | Workspaces supports a number of Cloud Storage Provider types inlcuding **(Dropbox, Google Drive, NextCloud | | | OneDrive, and S3)**. Each of these implementations levege `Rclone `__ docker volume plugi | | | which is automatically installed as part of Workspaces. A **Custom** type may be used to give | | | administrators the ability to create additional interfaces as desired. | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Enabled | If disabled, any Storage Mappings referencing this Storage Provider will not be utilze when creating new sessions. | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Default Target | The folder path where any Storage Mappings created with this provider will be mounted to inside the Kasm | | | session. This should be an absolute path (e.g :code:`/dropbox`) | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Volume Config | A json structure representing the volume to be created during a session. See :ref:`storage-provider-volume-config` | | | for more details. | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Mount Config | A json structure representing how the volume is mounted into a session. See :ref:`storage-provider-mount-config` | | | for more details. | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Client ID | The Client ID for OAuth based Storage Provider types (e.g Google Drive). | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Client Secret | The Client Secret for OAuth based Storage Provider types (e.g Google Drive). | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Authorization URL | The Authorization URL for OAuth based Storage Provider types (e.g Google Drive). | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Token URL | The Token URL for OAuth based Storage Provider types (e.g Google Drive). | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Redirect URL | The URL an OAuth provider will use to redirect the user back to Workspace. The URL should be in the following | | | format. :code:`https:///api/cloud_storage_callback` | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Scopes | The Scopes to request for OAuth based Storage Providers. Enter one entry per line. | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Webdav URL | (Nextcloud Only). The base Webdav URL for the Nextcloud deployment | | | (e.g :code:`https://:/remote.php/dav/file/` | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ | Root Drive URL | (Oneddrive Only). The OAuth URL used to query the Onedrive user's root drive. | | | (e.g :code:`https://graph.microsoft.com/v1.0/me/drive/root` | +-------------------------------+--------------------------------------------------------------------------------------------------------------------+ ``` ```{important} In Windows, the Target directory is relative to the user's Desktop within their profile. Therefore, /dropbox would get placed on C:\Users\kasm-user\Desktop\dropbox for the user kasm-user. ``` (storage-provider-volume-config)= ### Volume Config The volume config, is a JSON structure that represents how the docker volume is to be created. The available options are defined by the Docker SDK for python [create_volume](https://docker-py.readthedocs.io/en/stable/api.html#docker.api.volume.VolumeApiMixin.create_volume) ```json { "driver" : "rclone", "driver_opts" : { "type" : "s3", "s3-provider" : "AWS", "s3-env-auth" : "false", "s3-region" : "us-east-1", "uid" : "1000", "gid" : "1000", "allow_other" : "true" } } ``` (storage-provider-mount-config)= ### Mount Config The mount config, is a JSON structure that represents how the docker volume mounted (aka mapped) to the container session. The available options are defined by the Docker SDK for Python: [Mount](https://docker-py.readthedocs.io/en/stable/api.html#docker.types.Mount) Kasm will automatically assign the only two required parameters `target` and `source` since they will reference the **Default Target** , and the volume created by the **Volume Config**, so in most cases this can be set to an empty dict unless other advanced needs are required. ### Configuration Examples ```{toctree} :maxdepth: 1 storage_providers/dropbox storage_providers/gdrive storage_providers/nextcloud storage_providers/onedrive storage_providers/s3 storage_providers/custom ``` ### Troubleshooting #### Failures to Provision Sessions If something goes wrong with the storage mapping during the creation of a session, a user will get typically get an "Unexpected Error" message. ```{figure} /images/storage_mapping/error_provisioning.png :align: center **User Dashboard Error** ``` Administrators should review the application logs for errors either via the application dashboard, or tailing the `kasm_api` and `kasm_agent` containers while reproducing the errors ```bash sudo docker logs -f kasm_agent sudo docker logs -f kasm_api ``` In this case, there was an improper configuration for a driver options in the **Volume Config**. ```{figure} /images/storage_mapping/volume_config_error.png :align: center **Error in Logs** ``` ### File Browser shortcuts (Bookmarks) Kasm Workspaces images support setting file browser shortcuts in Thunar via the environment variable `CLOUD_MOUNTS` in the format: ``` CLOUD_MOUNTS="|,|" ``` By default, Workspaces will automatically create the `CLOUD_MOUNTS` environment variable according to the storage mappings configured. If desired, the administrator can override this behavior by manually defining the `CLOUD_MOUNTS` environment variable via {ref}`docker-run-config`. This environment variable is a comma and pipe seperated list of mounts and their accompanying type. The type sets an emblem icon on the folder shortcut for easier identification with the supported types: * s3 * nextcloud * onedrive * gdrive * dropbox * kasm (placeholder emblem if Kasm Workspaces logo is preferred) To configure this in Kasm Workspaces navigate to Admin > Workspaces > Edit > "Docker Run Config Override (JSON)", in this example we will be configuring a shortcut for every storage mapping type: ```JSON { "environment": { "CLOUD_MOUNTS" : "/s3|s3,/nextcloud|nextcloud,/onedrive|onedrive,/gdrive|gdrive,/dropbox|dropbox" } } ``` ```{figure} /images/storage_providers/bookmarks.png :align: center **Themed filebrowser shortcuts in the Workspace** ``` If using the examples provided above this environment variable can be passed as is to most Workspaces images and it will only show paths that are available in the Workspace on startup. If using the Kasm provided browser images (e.g `kasmweb/chrome`, `kasmweb/firefox`) administrators will need to disable the restricted file chooser in order for users to access the cloud mounts by manually defining the `KASM_RESTRICTED_FILE_CHOOSER` environment variable via {ref}`docker-run-config`. Setting the value to `0` will disable the restrictions, so the user can have access to cloud mounts and the rest of the file system. ```JSON { "environment": { "KASM_RESTRICTED_FILE_CHOOSER" : "0" } } ```