# Enable application settings persistence for your WorkSpaces Pools users WorkSpaces Pools supports persistent application settings for Windows-based directories. This means that your users' application customizations and Windows settings are automatically saved after each streaming session and applied during the next session. Examples of persistent application settings that your users can configure include, but are not limited to, browser favorites, settings, webpage sessions, application connection profiles, plugins, and UI customizations. These settings are saved to an Amazon Simple Storage Service (Amazon S3) bucket in your account, within the AWS Region in which application settings persistence is enabled. They are available in each WorkSpaces Pools streaming session. **Note** Standard Amazon S3 charges may apply to data that is stored in your S3 bucket. For more information, see [Amazon S3 Pricing](https://aws.amazon.com/s3/pricing/). **Topics** + [How application settings persistence works](how-it-works-app-settings-persistence.md) + [Enabling application settings persistence](enabling-app-settings-persistence.md) + [Administer the VHDs for your users' application settings](administer-app-settings-vhds.md) # How application settings persistence works Persistent application settings are saved to a Virtual Hard Disk (VHD) file. This file is created the first time a user streams an application from a directory on which application settings persistence is enabled. If the WorkSpace Pool associated with the directory is based on an image that contains default application and Windows settings, the default settings are used for the user's first streaming session. When the streaming session ends, the VHD is unmounted and uploaded to an Amazon S3 bucket within your account. The bucket is created when you enable persistent application settings for the first time for a directory in an AWS Region. The bucket is unique to your AWS account and the Region. The VHD is encrypted in transit using Amazon S3 SSL endpoints, and at rest using [AWS Managed CMKs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk). The VHD is mounted to the WorkSpace in both `C:\Users\%username%` and `D:\%username%`. If your WorkSpace is not joined to an Active Directory domain, the Windows user name is PhotonUser. If your WorkSpace is joined to an Active Directory domain, the Windows user name is that of the logged in user. Application settings persistence does not work across different operating system versions. For example, if you enable application settings persistence for a WorkSpace Pool that uses a Windows Server 2019 image, if you update the WorkSpace Pool to use an image that runs a different operating system (such as Windows Server 2022), settings from previous streaming sessions are not saved for users of the directory. Instead, after you update the WorkSpace Pool to use the new image, when users launch a streaming session from a WorkSpace, a new Windows user profile is created. However, if you apply an update to the same operating system on the image, users' customizations and settings from previous streaming sessions are saved. When updates to the same operating system are applied to an image, the same Windows user profile is used when users launch a streaming session from the WorkSpace. **Important** WorkSpaces Pools supports applications that rely on the [Microsoft Data Protection API](https://docs.microsoft.com/en-us/windows/desktop/seccng/cng-dpapi) only when the WorkSpace is joined to a Microsoft Active Directory domain. In cases where a WorkSpace is not joined to an Active Directory domain, the Windows user, PhotonUser, is different on each WorkSpace. Due to the way in which the DPAPI security model works, users' passwords don’t persist for applications that use DPAPI in this scenario. In cases where WorkSpaces are joined to an Active Directory domain and the user is a domain user, the Windows user name is that of the logged in user, and users’ passwords persist for applications that use DPAPI. WorkSpaces Pools automatically saves all files and folders in this path, except for the following folders: + Contacts + Desktop + Documents + Downloads + Links + Pictures + Saved Games + Searches + Videos Files and folders created outside of these folders are saved within the VHD and synced to Amazon S3. The default VHD maximum size is 5 GB for Pools. The size of the saved VHD is the total size of the files and folders that it contains. WorkSpaces Pools automatically saves the `HKEY_CURRENT_USER` registry hive for the user. For new users (users whose profiles don't exist in Amazon S3), WorkSpaces Pools creates the initial profile by using the default profile. This profile is created in the following location on the image builder: `C:\users\default`. **Note** The entire VHD must be downloaded to the WorkSpace before a streaming session can begin. For this reason, a VHD that contains a large amount of data can delay the start of the streaming session. For more information, see [Best practices for enabling application settings persistence](enabling-app-settings-persistence.md#best-practices-app-settings-persistence). When you enable application settings persistence, you must specify a settings group. The settings group determines which saved application settings are used for a streaming session from this directory. WorkSpaces Pools creates a new VHD file for the settings group that is stored separately within the S3 bucket in your AWS account. If the settings group is shared between directories, the same application settings are used in each directory. If a directory requires its own application settings, specify a unique settings group for the directory. # Enabling application settings persistence **Topics** + [Prerequisites for enabling application settings persistence](#prerequisites-app-settings-persistence) + [Best practices for enabling application settings persistence](#best-practices-app-settings-persistence) + [How to enable application settings persistence](#howto-enable-app-settings-persistence) ## Prerequisites for enabling application settings persistence To enable application settings persistence, you must first do the following: + Use an image that was created from a base image published by AWS on or after December 7, 2017. + Enable network connectivity to Amazon S3 from your virtual private cloud (VPC) by configuring internet access or a VPC endpoint for Amazon S3. For more information, see the *Home Folders and VPC Endpoints* section in [Networking and Access for WorkSpaces Pools](managing-network.md). ## Best practices for enabling application settings persistence To enable application settings persistence without providing internet access to your WorkSpaces, use a VPC endpoint. This endpoint must be in the VPC to which your WorkSpaces in WorkSpaces Pools are connected. You must attach a custom policy to enable WorkSpaces Pools access to the endpoint. For information about how to create the custom policy, see the *Home Folders and VPC Endpoints* section in [Networking and Access for WorkSpaces Pools](managing-network.md). For more information about private Amazon S3 endpoints, see [VPC Endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.html) and [Endpoints for Amazon S3](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-s3.html) in the *Amazon VPC User Guide*. ## How to enable application settings persistence You can enable or disable application settings persistence while creating a directory or after the directory is created by using the WorkSpaces console. For each AWS Region, persistent application settings are stored in an S3 bucket in your account. The first time you enable application settings persistence for a directory in an AWS Region, WorkSpaces Pools creates an S3 bucket in your AWS account in the same Region. The same bucket stores the application settings VHD file for all users and all directories in that AWS Region. For more information, see *Amazon S3 Bucket Storage* in [Administer the VHDs for your users' application settings](administer-app-settings-vhds.md). **To enable application settings persistence while creating a directory** + Follow the steps in [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md), and make sure that **Enable Application Settings Persistence** is selected. **To enable application settings persistence for an existing directory** 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. In the left navigation pane, choose **Pools**, and select the pool for which to enable application persistence. 1. Choose **Edit** in the **Settings** section of the page. 1. In the **Application Persistence** section of the page, select **Enable Application settings persistence**. 1. Choose **Save changes**. New streaming sessions now have application settings persistence enabled. # Administer the VHDs for your users' application settings **Topics** + [Amazon S3 bucket storage](#app-persistence-s3-buckets) + [Reset a user's application settings](#app-persistence-s3-reset) + [Enable Amazon S3 object versioning and revert a user's application settings](#app-persistence-enable-versions-revert-settings) + [Increase the size of the application settings VHD](#app-persistence-increase-VHD-size) ## Amazon S3 bucket storage When you enable application settings persistence, your users’ application customizations and Windows settings are automatically saved to a Virtual Hard Disk (VHD) file that is stored in an Amazon S3 bucket created in your AWS account. For every AWS Region, WorkSpaces Pools creates a bucket in your account that is unique to your account and the Region. All application settings configured by your users are stored in the bucket for that Region. You do not need to perform any configuration tasks to manage these S3 buckets; they are fully managed by the WorkSpaces Pools service. The VHD file that is stored in each bucket is encrypted in transit using Amazon S3's SSL endpoints and at rest using [AWS Managed CMKs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk). The buckets are named in a specific format as follows: ``` wspool-app-settings--- ``` ***region-code*** This is the AWS Region code in which the directory is created with application settings persistence. ***account-id-without-hyphens*** Your AWS account ID. The random identifier ensures there is no conflict with other buckets in that Region. The first part of the bucket name, `wspool-app-settings`, does not change across accounts or Regions. For example, if you enable application settings persistence for directories in the US West (Oregon) Region (us-west-2) on account number 123456789012, WorkSpaces Pools creates an Amazon S3 bucket within your account in that Region with the name shown. Only an administrator with sufficient permissions can delete this bucket. ``` wspool-app-settings-us-west-2-1234567890123-abcdefg ``` Disabling application settings persistence does not delete any VHDs stored in the S3 bucket. To permanently delete settings VHDs, you or another administrator with adequate permissions must do so by using the Amazon S3 console or API. WorkSpaces Pools adds a bucket policy that prevents accidental deletion of the bucket. When application settings persistence is enabled, a unique folder is created for each settings group to store the settings VHD. The hierarchy of the folder in the S3 bucket depends on how the user launches a streaming session, as described in the following section. The path for the folder where the settings VHD is stored in the S3 bucket in your account uses the following structure: ``` bucket-name/Windows/prefix/settings-group/access-mode/user-id-SHA-256-hash ``` ***bucket-name*** The name of the S3 bucket in which users' application settings are stored. The name format is described earlier in this section. ***prefix*** The Windows version-specific prefix. For example, v4 for Windows Server 2012 R2. ***settings-group*** The settings group value. This value is applied to one or more directories that share the same the same application settings. ***access-mode*** The identity method of the user: `custom` for the WorkSpaces Pools API or CLI, `federated` for SAML, and `userpool` for user pool users. ***user-id-SHA-256-hash*** The user-specific folder name. This name is created using a lowercase SHA-256 hash hexadecimal string generated from the user ID. The following example folder structure applies to a streaming session that is accessed using the API or CLI with a user ID of `testuser@mydomain.com`, an AWS account ID of `123456789012`, and the settings group `test-stack` in the US West (Oregon) Region (us-west-2): ``` wspool-app-settings-us-west-2-1234567890123-abcdefg/Windows/v4/test-stack/custom/a0bcb1da11f480d9b5b3e90f91243143eac04cfccfbdc777e740fab628a1cd13 ``` You can identify the folder for a user by generating the lowercase SHA-256 hash value of the user ID using websites or open source coding libraries available online. ## Reset a user's application settings To reset a user's application settings, you must find and delete the VHD and associated metadata file from the S3 bucket in your AWS account. Make sure that you do not do this during a user's active streaming session. After you delete the user's VHD and the metadata file, the next time the user launches a session from a streaming instance that has application settings persistence enabled, WorkSpaces Pools creates a new settings VHD for that user. **To reset a user's application settings** 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Bucket name** list, choose the S3 bucket that contains the application settings VHD that you want to reset. 1. Locate the folder that contains the VHD. For more information about how to navigate the S3 bucket folder structure, see *Amazon S3 Bucket Storage* earlier in this topic. 1. In the **Name** list, select the check box next to the VHD and the REG, choose **More**, and then choose **Delete**. 1. In the **Delete objects** dialog box, verify that the VHD and the REG are listed, and then choose **Delete**. The next time the user streams from a pool on which application settings persistence is enabled with the applicable settings group, a new application settings VHD is created. This VHD is saved to the S3 bucket at the end of the session. ## Enable Amazon S3 object versioning and revert a user's application settings You can use Amazon S3 object versioning and lifecycle policies to manage your users’ application settings when your users change them. With Amazon S3 object versioning, you can preserve, retrieve, and restore every version of the settings VHD. This enables you to recover from both unintended user actions and application failures. When versioning is enabled, after each streaming session, a new version of the application settings VHD is synced to Amazon S3. The new version does not overwrite the previous version, so if an issue with your users' settings occurs, you can revert to a previous version of the VHD. **Note** Each version of the application settings VHD is saved to Amazon S3 as a separate object and is charged accordingly. Object versioning is not enabled by default in your S3 bucket, so you must explicitly enable it. **To enable object versioning for your application settings VHD** 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Bucket name **list, choose the S3 bucket that contains the application settings VHD on which to enable object versioning. 1. Choose **Properties**. 1. Choose **Versioning**, **Enable versioning**, and then choose **Save**. To expire older versions of your application settings VHDs, you can use Amazon S3 lifecycle policies. For information, see [How Do I Create a Lifecycle Policy for an S3 Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-lifecycle.html) in the *Amazon Simple Storage Service User Guide*. **To revert a user's application settings VHD** You can revert to a previous version of a user's application settings VHD by deleting newer versions of the VHD from the applicable S3 bucket. Do not do this when the user has an active streaming session. 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Bucket name** list, choose the S3 bucket that contains the user's application settings VHD version to revert to. 1. Locate and select the folder that contains the VHD. For information about how to navigate the S3 bucket folder structure, see *Amazon S3 Bucket Storage* earlier in this topic. When you select the folder, the settings VHD and associated metadata file display. 1. To display a list of the VHD and metadata file versions, choose **Show**. 1. Locate the version of the VHD to revert to. 1. In the **Name** list, select the check boxes next to the newer versions of the VHD and associated metadata files, choose **More**, and then choose **Delete**. 1. Verify that the application settings VHD that you want to revert to and the associated metadata file are the newest versions of these files. The next time the user streams from a pool on which application settings persistence is enabled with the applicable settings group, the reverted version of the user's settings displays. ## Increase the size of the application settings VHD The default VHD maximum size is 5 GB for Pools. If a user requires additional space for application settings, you can download the applicable application settings VHD to a Windows computer to expand it. Then, replace the current VHD in the S3 bucket with the larger one. Do not do this when the user has an active streaming session. **Note** To reduce the physical size of the virtual hard disk (VHD), clear the recycle bin before ending a session. This also reduces upload and download times, and improves the overall user experience. **To increase the size of the application settings VHD** **Note** The full VHD must be downloaded before a user can stream applications. Increasing the size of an application settings VHD can increase the time it takes for users to start application streaming sessions. 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Bucket name** list, choose the S3 bucket that contains the application settings VHD to expand. 1. Locate and select the folder that contains the VHD. For information about how to navigate the S3 bucket folder structure, see [Amazon S3 bucket storage](#app-persistence-s3-buckets) earlier in this topic. When you select the folder, the settings VHD and associated metadata file display. 1. Download the `Profile.vhdx` file to a directory on your Windows computer. Do not close your browser after the download completes, because you'll use the browser again later to upload the expanded VHD. 1. To use Diskpart to increase the size of the VHD to 7 GB, open the command prompt as an administrator, and type the following commands. ``` diskpart ``` ``` select vdisk file="C:\path\to\application\settings\profile.vhdx" ``` ``` expand vdisk maximum=7000 ``` 1. Then, type the following Diskpart commands to find and attach the VHD, and display the list of volumes: ``` elect vdisk file="C:\path\to\application\settings\profile.vhdx" ``` ``` attach vdisk ``` ``` list volume ``` In the output, make note of the volume number with the label "AwsEucUsers". In the next step, you select this volume so that you can enlarge it. 1. Type the following command in which `` is the number in the list volume output. ``` select volume ``` 1. Type the following command: ``` extend ``` 1. Type the following commands to confirm that the size of the partition on the VHD increased as expected (7 GB in this example): ``` diskpart ``` ``` select vdisk file="C:\path\to\application\settings\profile.vhdx" ``` ``` list volume ``` 1. Type the following command to detach the VHD so that it can be uploaded: ``` detach vdisk ``` 1. Return to your browser with the Amazon S3 console, choose **Upload**, **Add files**, and then select the enlarged VHD. 1. Choose **Upload**. After the VHD is uploaded, the next time the user streams from a pool on which application settings persistence is enabled with the applicable settings group, the larger application settings VHD is available.