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:

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 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

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 /dropbox)
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. https://<hostname>/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 https://<hostname>:<port>/remote.php/dav/file/
Root Drive URL	(Oneddrive Only). The OAuth URL used to query the Onedrive user’s root drive. (e.g 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.

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.

Configuration Examples

• Dropbox Storage Provider Setup
• Google Drive Storage Provider Setup
• Nextcloud Storage Provider Setup
• OneDrive Storage Provider Setup
• S3 Storage Provider Setup
• Custom Storage Provider Setup

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"
    }
}