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 two ways: volume mounted profiles and S3 based profiles.

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:

../../_images/profile_select_group.webp — **Edit a Group**

Under Settings find the allow_persistent_profile group setting and click edit:

../../_images/profile_select_group_setting.webp — **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.

../../_images/profile_set_group_setting.webp — **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.