Persistent Profiles

Administrators may desire to give each user a personal persistent profile that is restored during each session. This can be achieved in one of three ways: volume mounted profiles, storage mapping based profiles and S3 based profiles.

Storage Mapping Based Profiles

warning

This feature is in Preview and not currently recommended for production use.

The Storage Mapping provides a way to attach external storage to sessions. Kasm's Storage Mapping supports many different backend storage providers, such as Google Drive, Dropbox, S3, and others. The issue with many of these providers is that they cannot be used for a user's home profile in Linux. To alleviate this issue, Kasm has developed its own storage provider, Kasm Profile Sync. The Kasm Profile Sync storage provider supports AWS S3 storage with support for more storage solutions coming. While it has not been tested on all S3 compatible storage solutions, it is known to work on services that are S3 compatible, such as Oracle object storage, GCP, and Wasabi.

The Kasm Profile Sync storage provider is meant to replace the S3 Based Profiles and provides many advantages over this legacy solution.

• SSE-C is used so that each user's profile has a different encryption key managed by Kasm.
• Support for unlimited file and profile sizes. The legacy version is limited in both the maximum file size and the total profile size.
• Centralized logging of profile sync operations.
• S3 credentials are managed per Storage Mapping configuration, instead of globally, allowing for multi-tenancy usage.
• Supports for AWS STS credentials, ensuring profile sync uses short-lived limited credentials.
• Easier to configure details of profile sync in the admin UI.

If both Storage Mapping based profiles are configured alongside Volume Mount profiles or the legacy S3 based profiles, the Storage Mapping based profile configuration takes precedence. Any existing data will be migrated to the Storage Mapping profiles, allowing admins to easily migrate to this new solution.

warning

While persistent profiles may work on S3 compatible solutions, Kasm cannot provide support for 3rd party products that claim to be S3 compatible.

The first step in configuring Storage Mapping based profiles using the Kasm Profile Sync provider is to create a Storage Provider configuration.

Storage Provider Configuration

1. Log into the Kasm UI as an administrator.
2. Select Settings -> Storage -> Add.
3. Provide a name and configure the Volume Config json field.

{
		"backend_storage" : "s3",
		"log_level" : "info",
		"filter" : "Downloads/*",
		"storage_limit" : "20g",
		"sts" : true
}

Field	Description
backend_storage	The type of storage to use on the backend, currently only s3 is supported.
log_level	The logging level, expected values of debug, info, warning, and error.
filter	Directories or files within the user's home profile to ignore, supports Linux globbing format.
storage_limit	Sets a maximum storage size limit. Users will get pop up notifications within the desktop when the profile size has exceeded 90% of the limit. Use the labels m or g to specify MegaBytes or GigaBytes respectively. A value of 0g or 0m disables storage limits.
sts	Determines if AWS STS will be used for authentication by the profile-sync binary running inside the user's container. This provides additional security by ensuring that temporary limited use tokens are used by endpoints for authentication to S3. This is only supported for AWS S3, other S3 compatible solutions will not work with STS enabled.

Create Profile Sync Provider

After the Storage Provider details are configured, the storage provider can be used to create Storage Mappings on each desired Workspaces Image.

Storage Mapping Configuration

1. Log into the Kasm UI as an administrator.
2. Select Workspaces -> Workspaces
3. Edit the desired Workspace Image
4. Click the Storage Mapping tab
5. Click the Add button
6. From the Type drop down, select the provider you created in the previous section.
7. Enter the S3 Access Key ID, S3 Secret Access Key, and the bucket.

Create Profile Sync Provider

AWS IAM Role

To use an IAM Role assigned to EC2 instances instead of an AWS Access Key and Access Key Secret, use the value {IAM} in the S3 Access Key ID field and use any value for the S3 Secret Access Key field on the Storage Mapping configuration. An IAM role with the polices covered in the below section needs to exist on all Kasm Agents and all Kasm WebApp EC2 instances. Additionally, the Storage Provider configuration needs to disable sts.

S3 Endpoints

You can force Kasm to use a specific endpoint by using this format in the Bucket name field of the Storage Mapping defined on the Workspace. This can be used to ensure all requests go directly to the region the bucket resides in, it can be used to send requests to an VNC S3 endpoint, or it can be used to specify an S3 compatible service.

<bucket-name>@<endpoint>

For example: my-bucket@s3.eu-central-1.amazonaws.com

S3 Compatible Solutions

There are many object storage solutions out there that claim to be compatible with AWS S3 clients, such as GCP, OCI, and MinIO object storage. No AWS S3 compatible service is 100% compatible and Kasm Technologies cannot feasibly support all providers that claim to be compatible, however, this section documents what we do know that might help our clients configure Kasm to work on these type of services.

• You must set sts to false in the Storage Provider configuration. This disables sts tokens for authentication, which is not supported by AWS compatible services.
• You must specify an endpoint in the bucket name of the Storage Mapping configuration.

AWS S3 now chunks all upload operations and not all "S3 Compatible" services support this. There is a work around for the following providers known not to support chunked uploads. This list may not be all inclusive, if you are having issues with your S3 Compatible service you may try this work around.

• OCI

To work around the lack of support for chunked uploads for the above list of S3 Compatible services, you must set two environmental variables on the Workspace Image settings. The following example json would go in the Docker Run Configuration Override field in the Workspace Image settings.

{
  "environment": {
    "AWS_REQUEST_CHECKSUM_CALCULATION": "WHEN_REQUIRED",
    "AWS_RESPONSE_CHECKSUM_VALIDATION": "WHEN_REQUIRED"
  }
}

Volume Mount Profiles

This is achieved by mounting in a host level directory into the container meaning the top level folders used for this setting should exist on the host beforehand. When configured, the user's home directory will be stored at the specified location and mapped in each time the user loads that Workspace. Administrators must use the {username} or {user_id} variables in the mapping to ensure they are unique per user. {image_id} may also be used as a variable. Persistent profiles are configured on a per Workspace basis and should be isolated in their pathing IE if you have a Chrome and Firefox image on your Workspaces deployment and the users are user@kasm.local and admin@kasm.local the directory structure would look like:

warning

It is important that each workspace's profile path is unique. There are some use cases where you would want the profile for different workspaces to be identical. One example would be cloned workspaces. However, even in this scenario it is highly recommended that workspaces have unique profile paths to prevent the files from one workspace conflicting with the files in another. This can happen because most applications will attempt to store their session configuration data at the same file location, however when using shared profile paths this file already exist with a possibly incompatible setting such as a resource lock. The easiest way to ensure unique profile paths is to use a format similar to "/mnt/kasm_profiles/{username}/{image_id}" or "/mnt/kasm_profiles/{user_id}/{image_id}".

/mnt/kasm_profiles/
├── admin@kasm.local
│   ├── chrome
│   └── firefox
└── user@kasm.local
    ├── chrome
    └── firefox

The only folder the administrator needs to create is /mnt/kasm_profiles/ and the rest will be generated on Workspace launch.

S3 Based Profiles

AWS S3 object storage can be used for persistent profiles. The advantages of using S3 for persistent profiles are:

• Redundancy
• Data management policies in S3
• Globally distributed
• Security

The user's session container does not have direct authenticated access to S3. When the container starts, it makes an API call to the Kasm API service to request the profile manifest. The Kasm API returns a manifest that contains presigned URLs for each layer of the profile. The S3 presigned URLs are only authorized for each object they are signed for and only for a limited amount of time. This architecture ensures that a single S3 bucket can be securely used for all users in the system.

The administrator needs to define the AWS Access Key ID and Access Secret in the Server Settings. The access key should be defined on a user that only has access to the specific bucket in question, with no other permissions. The user should be able to read and write to the bucket, and create pre-signed URLs. Kasm API services need to be restarted after changing/setting the AWS Access Key ID or Access Key Secret.

Finally, the administrator will need to specify the S3 URL path in the Workspace settings, in the format of s3://bucket-name/folder/{username}/. Replace bucket-name with the target S3 bucket name. Each Workspace in Kasm should have its own folder, if the folder does not exist, it will be created. Use the {username} or {user_id} token in the path, to ensure each user has their own directory. Administrators can use different buckets for different Workspaces, as long as the AWS Access Key used in the global settings has the required access to all configured buckets.

S3 Policy Configurations

This feature utilizes pre-signed URLs to facilitate uploading artifacts to S3.

The minimum S3 bucket policy required to use this feature is:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PolicyForAllowKasmS3UserReadWrite",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<s3 persistent profile user arn>"
      },
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListBucket",
        "s3:DeleteObject"
      ],
      "Resource": "<s3 bucket arn>/*"
    },
    {
      "Sid": "PolicyForAllowKasmS3UserListLocate",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<s3 persistent profile user arn>"
      },
      "Action": [
        "s3:GetBucketLocation"
      ],
      "Resource": "<s3 bucket arn>"
    }
  ]
}

The minimum IAM policy for the S3 credentials used in Kasm are:

{
  "Statement": [
    {
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListBucket",
        "s3:DeleteObject"
      ],
      "Effect": "Allow",
      "Resource": [
        "<s3 bucket arn>",
        "<s3 bucket arn>/*"
      ]
    },
    {
      "Action": [
        "s3:GetBucketLocation"
      ],
      "Effect": "Allow",
      "Resource": "<s3 bucket arn>"
    }
  ],
  "Version": "2012-10-17"
}

S3 Endpoints

By default, the endpoint used for S3 access is s3.amazonaws.com. Administrators may desire to specify a custom endpoint in order to support the following use cases.

• A private VPC Endpoint
• AWS Gov Cloud end-points
• Region specific end-points
• AWS S3 Accelerated Endpoints
• S3 Compatible Solutions

warning

While persistent profiles may work on S3 compatible solutions, Kasm cannot provide support for 3rd party products that claim to be S3 compatible. Kasm utilizes pre-signed S3 URLs and only supports version 4 signatures.

To specify a custom endpoint, in the Workspaces settings, format the Persistent Profile path in the following format:

s3://bucket-name@endpoint/folder/{username}/

The following example configures Kasm to use Wasabi (an S3 compliant cloud storage provider) for a persistent profile, where kasm is the bucket name, wasabisys.com is the endpoint name, and the remaining is the path with {username} replaced by the Kasm username.

s3://kasm@s3.wasabisys.com/ubuntu2/{username}/

Adding a persistent profile to a Workspace

To add a persistent profile path to a Workspace from the administrator menu first click on Workspaces -> Workspaces and edit your desired Workspace:

Edit a Workspace

How to configure a persistent profile in a workspace

• Configure the persistent profile path on the workspace.

Variables can be used for the Image ID and User ID so that the persistent profile path is uniform across all images:

/mnt/kasm_profiles/{image_id}/{user_id}

Configuring persistent profile path with Image ID and User ID

Alternatively, if the paths should be human-readable the image name can be specified in the path and the Username as a variable:

/mnt/kasm_profiles/firefox/{username}

Configuring persistent profile path with image name

Note

If Kasm is installed in a multi-server deployment path 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. Kasm will create the directory if it does not exist.

Limiting group access to persistent profiles

It may be necessary to limit which users can access the persistent profile feature, this can be achieved with a group setting. See Group Setting for more details.

From the administrator menu first click on Access Management -> Groups and click Edit on your desired group:

Edit a Group

Under Settings find the allow_persistent_profile group setting and click edit:

Select Persistent Profile Group Setting

This is a Boolean value, set it to true to enable access and false to disable access for this particular group.

Enabling Persistent Profiles at the Group Level

Utilize a persistent profile with creating a Kasm

Using a persistent profile

When creating a Kasm, the user will now be presented with a Persistent Profile Option. Multiple Settings are available.

• Enabled
  • The persistent profile path defined on the workspace will be loaded during creation.
• Disabled
  • The persistent profile will NOT be loaded on creation.
• Reset
  • The existing persistent profile will be deleted and re-created. The is useful if the user desires to clear old profile data and start fresh.

Size Limits

Administrators can place a size limit on S3-based persistent profiles and a size warning for volume mapped profiles. When a user's home profile exceeds the limit, the user will get a warning message within the Workspace desktop session. For S3-based profiles, the user's changes will not be saved between sessions until they reduce the size of their profile. The size limit can be set using the environmental variable KASM_PROFILE_SIZE_LIMIT, specified in KB. To specify a persistent profile size limit of 2GB, you would set a value of 2000000. To set the environmental variable, use the Docker Run Override setting in the Workspace definition. By default, there is no limit.

Filters

S3-based persistent profiles support filters that will ignore files and/or directories. The filter is a comma separated list of file or directory names, relative from the user's home profile path.

The default filter is.

.cache,.vnc,Downloads,Uploads

This default filter ignores the .cache, .vnc, Downloads, and Uploads directories within the user's home profile. This default filter can be overridden by setting the KASM_PROFILE_FILTER environmental variable. To set the environmental variable, use the Docker Run Override setting in the Workspace definition.

Globing is supported, such as Documents/*.docx, to mean any file ending in '.docx' or Documents/**.docx, meaning any file ending in '.docx' in the Documents directory or any child directory within.

Video Example

This video shows an example of configuring persistent profiles.