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 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:
The Administrator configures a Storage Provider (e.g Google Drive)
The Administrator may now create Storage Mappings that leverage the Storage Provider. The mappings may be placed on a User, Group or Workspace object.
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.
If allowed via group settings, end-users can configure Storage Mappings to the registered Providers via the Cloud Storage section of the profile widget.
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.
When the session is destroyed, the previously created docker volume is also destroyed.
Storage Providers
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 |
Volume Config |
A json structure representing the volume to be created during a session. See Volume Config for more details. |
Mount Config |
A json structure representing how the volume is mounted into a session. See 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. |
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 |
Root Drive URL |
(Oneddrive Only). The OAuth URL used to query the Onedrive user’s root drive.
(e.g |
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.
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
{
"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"
}
}
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
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.
Variable Substitution
The following variables can be templated into the storage mapping Default Target and Volume Config properties to support additional use-cases.
Note: Variable substitution is not compatible with Session Staging.
{username}- The username of the user provisioning the session. e.guser@kasm.local{user_id}- The user_id of the user provisioning the session . e.g6c0535dc02eb49c4a556cae9816a585d{image_id}- The image ,aka workspace, id used for the session. eg.9de4ea298f064e6999c5b9b164e2c04c{user_crypt_password}- A cryptographic key used when leveraging Rclone’s crypt provider. Used in place of the--crypt-passwordattribute.{user_crypt_salt}- A cryptographic key used when leveraging Rclone’s crypt provider. Used in place of the--crypt-password2attribute.
Configuration Examples
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.
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
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.
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="<Default Target>|<type>,<Default Target2>|<type2>"
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 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:
{
"environment": {
"CLOUD_MOUNTS" : "/s3|s3,/nextcloud|nextcloud,/onedrive|onedrive,/gdrive|gdrive,/dropbox|dropbox"
}
}
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 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.
{
"environment": {
"KASM_RESTRICTED_FILE_CHOOSER" : "0"
}
}