# Enable Application Settings Persistence for Your WorkSpaces Applications Users
WorkSpaces Applications supports persistent application settings for Windows-based stacks. 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 Applications streaming session.
**Note**
Enabling application settings persistence is currently not supported for Linux-based stacks.
**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 stack on which application settings persistence is enabled. If the fleet associated with the stack is based on an image that contains default application and Windows settings, the default settings are used for the user's first streaming session. For more information about default settings, see *Step 3: Create Default Application and Windows Settings* in [Tutorial: Create a Custom WorkSpaces Applications Image by Using the WorkSpaces Applications Console](tutorial-image-builder.md).
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 stack 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 streaming instance in both C:\$1Users\$1%username% and D:\$1%username%. If your instance is not joined to an Active Directory domain, the Windows user name is PhotonUser. If your instance 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 on a stack and the stack is associated with a fleet that uses a Windows Server 2012 R2 image, if you update the fleet to use an image that runs a different operating system (such as Windows Server 2016), settings from previous streaming sessions are not saved for users of the stack. Instead, after you update the fleet to use the new image, when users launch a streaming session from a fleet instance, 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 fleet instance.
**Important**
WorkSpaces Applications supports applications that rely on the [Microsoft Data Protection API](https://docs.microsoft.com/en-us/windows/desktop/seccng/cng-dpapi) only when the streaming instance is joined to a Microsoft Active Directory domain. In cases where a streaming instance is not joined to an Active Directory domain, the Windows user, PhotonUser, is different on each fleet instance. 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 streaming instances 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 Applications 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 1GB for Elastic fleets and 5GB for Always-On and On-Demand fleets. The size of the saved VHD is the total size of the files and folders that it contains. WorkSpaces Applications automatically saves the HKEY\$1CURRENT\$1USER registry hive for the user. For new users (users whose profiles don't exist in Amazon S3), WorkSpaces Applications creates the initial profile by using the default profile. This profile is created in the following location on the image builder: C:\$1users\$1default.
**Note**
The entire VHD must be downloaded to the streaming instance 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](best-practices-app-settings-persistence.md).
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 stack. WorkSpaces Applications 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 stacks, the same application settings are used in each stack. If a stack requires its own application settings, specify a unique settings group for the stack.
# Enabling Application Settings Persistence
Review the following topics to learn how to enable application settings persistence for your WorkSpaces Applications users.
**Topics**
+ [
# Prerequisites for Enabling Application Settings Persistence
](prerequisites-app-settings-persistence.md)
+ [
# Best Practices for Enabling Application Settings Persistence
](best-practices-app-settings-persistence.md)
+ [
# How to Enable Application Settings Persistence
](howto-enable-app-settings-persistence.md)
# Prerequisites for Enabling Application Settings Persistence
To enable application settings persistence, you must first do the following:
+ Check that you have the correct AWS Identity and Access Management (IAM) permissions for Amazon S3 actions. For more information, see the *IAM Policies and the Amazon S3 Bucket for Home Folders* section in [Identity and Access Management for Amazon WorkSpaces Applications](controlling-access.md).
+ Use an image that was created from a base image published by AWS on or after December 7, 2017. For a current list of released AWS base images, see [WorkSpaces Applications Base Image and Managed Image Update Release Notes](base-image-version-history.md).
+ Associate the stack on which you plan to enable this feature with a fleet based on an image that uses a version of the WorkSpaces Applications agent released on or after August 29, 2018. For more information, see [WorkSpaces Applications Agent Release Notes](agent-software-versions.md).
+ 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 Amazon WorkSpaces Applications](managing-network.md).
# Best Practices for Enabling Application Settings Persistence
To enable application settings persistence without providing internet access to your instances, use a VPC endpoint. This endpoint must be in the VPC to which your WorkSpaces Applications instances are connected. You must attach a custom policy to enable WorkSpaces Applications 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 Amazon WorkSpaces Applications](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 stack or after the stack is created by using the WorkSpaces Applications console, WorkSpaces Applications API, an AWS SDK, or the AWS Command Line Interface (CLI). 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 stack in an AWS Region, WorkSpaces Applications 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 stacks 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 stack**
+ Follow the steps in [Create a Stack in Amazon WorkSpaces Applications](set-up-stacks-fleets-install.md), and make sure that **Enable Application Settings Persistence** is selected.
**To enable application settings persistence for an existing stack**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the left navigation pane, choose **Stacks**, and select the stack for which to enable application settings persistence.
1. Below the stacks list, choose **User Settings**, **Application Settings Persistence**, **Edit**.
1. In the **Application Settings Persistence** dialog box, choose **Enable Application Settings Persistence**.
1. Confirm the current settings group or type the name of a new settings group. When you're done, choose **Update**.
New streaming sessions now have application settings persistence enabled.
# Administer the VHDs for Your Users' Application Settings
Review the following topics to learn how to administer the Virtual Hard Disks (VHD) files for your WorkSpaces Applications users' application settings.
**Topics**
+ [
# Amazon S3 Bucket Storage
](app-persistence-s3-buckets.md)
+ [
# Reset a User's Application Settings
](app-persistence-s3-reset.md)
+ [
# Enable Amazon S3 Object Versioning and Revert a User's Application Settings
](app-persistence-enable-versions-revert-settings.md)
+ [
# Increase the Size of the Application Settings VHD
](app-persistence-increase-VHD-size.md)
# 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 Applications 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 Applications 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:
```
appstream-app-settings-region-code-account-id-without-hyphens-random-identifier
```
***region-code***
This is the AWS Region code in which the stack 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, `appstream-app-settings`, does not change across accounts or Regions.
For example, if you enable application settings persistence for stacks in the US West (Oregon) Region (us-west-2) on account number 123456789012, WorkSpaces Applications 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.
```
appstream-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 Applications adds a bucket policy that prevents accidental deletion of the bucket. For more information, see *IAM Policies and the Amazon S3 Bucket for Application Settings Persistence* in [Identity and Access Management for Amazon WorkSpaces Applications](controlling-access.md).
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 stacks that share the same the same application settings.
***access-mode***
The identity method of the user: `custom` for the WorkSpaces Applications 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):
```
appstream-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 Applications 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 fleet 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 fleet 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 1 GB for Elastic fleets and 5GB for Always-On and On-Demand fleets. 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* 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:
`select 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 "AppStreamUsers". In the next step, you select this volume so that you can enlarge it.
1. Type the following command:
`select volume ###`
where \$1\$1\$1 is the number in the list volume output.
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 (2 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 fleet on which application settings persistence is enabled with the applicable settings group, the larger application settings VHD is available.