---
myst:
  html_meta:
    "description lang=en": "How to mount persistent host level folders into Kasm Workspaces for the users Home directory."
    "keywords": "Kasm, How to, How-to, Persistent Profiles, NFS, Customization, Home Folder"
    "property=og:locale": "en_US"
---
```{title} Persistent Profiles
```

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

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

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](../settings.md#storage). 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.

```{note}
Container based images must support S3 persistent profiles. All Kasm maintained images support S3 persistent profiles with the exception of the following images.

kasmweb/core-centos-7  
kasmweb/centos-7-desktop  
```

#### S3 Policy Configurations

```{include} /guide/s3_policy_configurations.md
```

#### 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:
```text
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.
```text
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: 

```{figure} /images/persistent_profiles/profile_workspace_edit.webp
:align: center
**Edit a Workspace**
```

### How to configure a persistent profile in a workspace

- Configure the persistent profile path on the {term}`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}
```

```{figure} /images/persistent_profiles/Persistent_Profile_Path.webp
:align: center
**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}

```

```{figure} /images/persistent_profiles/profile_path_setting.webp
:align: center
**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](../groups.md#group-settings) for more details.**

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

```{figure} /images/persistent_profiles/profile_select_group.webp
:align: center
**Edit a Group**
```

Under **Settings** find the `allow_persistent_profile` group setting and click edit:

```{figure} /images/persistent_profiles/profile_select_group_setting.webp
:align: center
**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.


```{figure} /images/persistent_profiles/profile_set_group_setting.webp
:align: center
**Enabling Persistent Profiles at the Group Level**
```

### Utilize a persistent profile with creating a Kasm

```{figure} /images/persistent_profiles/profile_launch_option.webp
:align: center
**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](../workspaces.md#docker-run-config) 
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.

```bash
.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](../workspaces.md#docker-run-config) 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.

```{raw} html
<iframe src="https://www.youtube.com/embed/teJSUxKEbfE?start=414" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
```