# Images
You can create Amazon WorkSpaces Applications images that contain applications you can stream to your users and default system and application settings to enable your users to get started with those applications quickly. However, after you create an image, you can't change it. To add other applications, update existing applications, or change image settings, you must start and reconnect to the image builder that you used to create the image. If you deleted that image builder, launch a new image builder that is based on your image. Then make your changes and create a new image. For more information, see [Launch an Image Builder to Install and Configure Streaming Applications](tutorial-image-builder-create.md) and [Tutorial: Create a Custom WorkSpaces Applications Image by Using the WorkSpaces Applications Console](tutorial-image-builder.md).
Images that are available to you are listed in the **Image Registry** in the WorkSpaces Applications console. They are categorized as public, private, or shared. You can use any of these image types to launch an image builder and set up an WorkSpaces Applications fleet. Shared images are owned by other Amazon Web Services accounts and shared with you. Permissions set on images that are shared with you may limit what you can do with those images. For more information, see [Administer Your Amazon WorkSpaces Applications Images](administer-images.md).
**Topics**
+ [Default Application and Windows Settings and Application Launch Performance in Amazon WorkSpaces Applications](customizing-appstream-images.md)
+ [Manage WorkSpaces Applications Agent Versions](base-images-agent.md)
+ [WorkSpaces Applications Agent Release Notes](agent-software-versions.md)
+ [Tutorial: Create a Custom WorkSpaces Applications Image by Using the WorkSpaces Applications Console](tutorial-image-builder.md)
+ [Administer Your Amazon WorkSpaces Applications Images](administer-images.md)
+ [Create Your Amazon WorkSpaces Applications Image Programmatically by Using the Image Assistant CLI Operations](programmatically-create-image.md)
+ [Create Your Linux-Based Images](create-linux-based-images.md)
+ [Use Session Scripts to Manage Your Amazon WorkSpaces Applications Users' Streaming Experience](use-session-scripts.md)
# Default Application and Windows Settings and Application Launch Performance in Amazon WorkSpaces Applications
You can create default application and Windows settings to enable your users to get started with their applications quickly, so that they won't need to create or configure the settings themselves.
WorkSpaces Applications optimizes the launch performance of your applications for your users' streaming sessions. To ensure that all of the required files are included in this process, you may need to manually add certain files and folders to the optimization manifest.
**Topics**
+ [Creating Default Application and Windows Settings for Your WorkSpaces Applications Users](creating-default-app-Windows-settings.md)
+ [Optimizing the Launch Performance of Your Applications in Amazon WorkSpaces Applications](optimizing-app-launch-performance.md)
# Creating Default Application and Windows Settings for Your WorkSpaces Applications Users
Application customizations and Windows settings that are saved to the Windows user profile folder or the user registry hive can be set as defaults. When you save the default settings by using the **Template User** in Image Assistant, WorkSpaces Applications replaces the Windows default user profile with the profile that you configure. The Windows default user profile is then used to create the initial settings for users in the fleet instance. If the application or Windows settings that you configure don't work in the fleet, confirm that they are saved in the Windows user profile. For more information, 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).
Default settings that you can create and configure include:
+ Application preferences, including a browser home page, toolbar customizations, and security settings.
+ Application data settings, including browser bookmarks and connection profiles.
+ Windows experience settings, including displaying file name extensions and hidden folders.
Additionally, you can modify or disable Internet Explorer security settings, such as Enhanced Security Configuration (ESC). For more information, see [Disable Internet Explorer Enhanced Security Configuration in Amazon WorkSpaces Applications](customize-fleets-disable-ie-esc.md).
# Optimizing the Launch Performance of Your Applications in Amazon WorkSpaces Applications
When you create an image, WorkSpaces Applications requires that you optimize the launch performance of your applications for your users' streaming sessions. When your applications are opened during this process, make sure that they use the initial components required by your users. Doing so ensures that these components are captured by the optimization process. In some cases, not all of the files required for the optimizations are detected. Examples of such files would be plug-ins or components that aren't opened in the image builder. To ensure that all of the files needed for your application are captured, you can include them in the optimization manifest. Adding files to the optimization manifest may increase the time it takes for fleet instances to be created and made available for users. Doing so, however, reduces the time it takes for the application to be launched the first time on the fleet instance.
To optimize all the files in a folder, open PowerShell and use the following PowerShell command:
```
dir -path "C:\Path\To\Folder\To\Optimize" -Recurse -ErrorAction SilentlyContinue | %{$_.FullName} | Out-File "C:\ProgramData\Amazon\Photon\Prewarm\PrewarmManifest.txt" -encoding UTF8 -append
```
By default, Image Assistant replaces the application optimization manifest each time the Image Assistant **Optimize** step runs. You must run the PowerShell command to optimize all files in a folder:
+ Each time after the **Optimize **step runs.
+ Before you choose **Disconnect and create image** on the Image Assistant **Review** page.
Alternatively, you can specify the optimization manifest on a per-application basis by using the Image Assistant command line interface (CLI) operations. When you specify the optimization manifest by using the Image Assistant CLI operations, WorkSpaces Applications merges the specified application optimization manifest with the files identified by the Image Assistant **Optimize** step. For more information, see [Create Your Amazon WorkSpaces Applications Image Programmatically by Using the Image Assistant CLI Operations](programmatically-create-image.md).
# Manage WorkSpaces Applications Agent Versions
The WorkSpaces Applications agent is software that runs on your streaming instances and enables users to stream applications. When you create a new image, the **Always use latest agent version** option is selected by default. When this option is selected, new image builders or fleet instances that are launched from your image always use the latest WorkSpaces Applications agent version. You might want to control agent updates to ensure compatibility with your software or to qualify the updated environment before you deploy it for your end users.
The following procedures describe how to manage WorkSpaces Applications agent versions.
**Topics**
+ [Create an Image That Always Uses the Latest Version of the WorkSpaces Applications Agent](create-image-that-always-uses-latest-agent.md)
+ [Create an Image That Uses a Specific Version of the WorkSpaces Applications Agent](create-image-that-uses-specific-agent.md)
+ [Create an Image That Uses a Newer Version of the WorkSpaces Applications Agent](create-image-that-uses-newer-agent.md)
# Create an Image That Always Uses the Latest Version of the WorkSpaces Applications Agent
When your images are configured to always use the latest WorkSpaces Applications agent version, your streaming instances are automatically updated with the latest features, performance improvements, and security updates that are available from AWS when a new agent version is released.
**Note**
In some cases, a new WorkSpaces Applications agent version might conflict with your software. We recommend that you qualify the new WorkSpaces Applications agent version before deploying it to your production fleets.
**To create an image that always uses the latest version of the WorkSpaces Applications agent**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2/home](https://console.aws.amazon.com/appstream2/home).
1. Do either of the following:
+ If you have an image builder that you want to use to create the image, start the image builder and then connect to it. If the image builder is not running the latest version of the WorkSpaces Applications agent, you are prompted to choose whether to start the image builder with the latest agent. Make sure that this option is selected, choose **Start**, and then connect to the image builder.
+ If you do not have an image builder that you want to use to create the image, launch a new image builder. In **Step 1: Choose Image**, choose an AWS base image or a custom image. In **Step 2: Configure Image Builder**, if the image that you choose is not running the latest version of the WorkSpaces Applications agent, the **WorkSpaces Applications** section displays. In the **Agent version** list, select the latest agent version. Complete the remaining steps to create the image builder, and then connect to it. For more information, see [Launch an Image Builder to Install and Configure Streaming Applications](tutorial-image-builder-create.md).
1. On the image builder desktop, open Image Assistant and follow the steps to create your new image. For the **Configure Image** step, make sure that **Always use the latest agent version** is selected. For more information, see [Tutorial: Create a Custom WorkSpaces Applications Image by Using the WorkSpaces Applications Console](tutorial-image-builder.md).
If you decide later to not always use the latest version of the WorkSpaces Applications agent, you must create a new image and clear that option.
1. Create a new fleet or modify an existing one. When you configure the fleet, select the new image that you created. For more information, see [Create an Amazon WorkSpaces Applications Fleet and Stack](set-up-stacks-fleets.md).
1. Create a new stack or modify an existing one and associate it with your fleet.
# Create an Image That Uses a Specific Version of the WorkSpaces Applications Agent
You may want to control WorkSpaces Applications agent updates rather than always using the latest version so that you can test for compatibility first. To ensure that the version of the WorkSpaces Applications agent you use is compatible with your streaming applications, you can create an image that uses a specific version of the agent software. Then perform your qualification tests in a separate fleet before deploying to your production fleet.
When you create the image, make sure that the **Always use latest agent version** option is not selected. Doing so pins your image to the version of the WorkSpaces Applications agent that you selected when you launched the image builder, rather than always using the latest version. After you finish your qualification tests, you can update your production fleet with the image.
**To create an image that uses a specific version of the WorkSpaces Applications agent**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2/home](https://console.aws.amazon.com/appstream2/home).
1. Do either of the following:
+ If you have an image builder that you want to use to create the image, start the image builder and then connect to it.
+ If you do not have an image builder that you want to use to create the image, launch a new image builder. In **Step 1: Choose Image**, choose an AWS base image or a custom image. In **Step 2: Configure Image Builder**, if the image that you choose is not running the latest version of the WorkSpaces Applications agent, the **WorkSpaces Applications** section displays. In the **Agent version** list, do not select the latest agent version. Complete the remaining steps to create the image builder, and then connect to it. For more information, see [Launch an Image Builder to Install and Configure Streaming Applications](tutorial-image-builder-create.md).
1. On the image builder desktop, open Image Assistant and follow the steps to create your new image. For the **Configure Image** step in Image Assistant, make sure that **Always use the latest agent version** is not selected. For more information, see [Tutorial: Create a Custom WorkSpaces Applications Image by Using the WorkSpaces Applications Console](tutorial-image-builder.md).
If you decide later to always use the latest version of the WorkSpaces Applications agent, you must create a new image and select that option.
1. Create a new fleet or modify an existing one. When you configure the fleet, select the new image that you created. For more information, see [Create an Amazon WorkSpaces Applications Fleet and Stack](set-up-stacks-fleets.md).
1. Create a new stack or modify an existing one and associate it with your fleet.
1. Connect to your fleet and test your applications for compatibility.
# Create an Image That Uses a Newer Version of the WorkSpaces Applications Agent
If you pin your image to a specific WorkSpaces Applications agent version, you must update to a newer version by creating a new image. This approach lets you test each agent update for compatibility first, and then update your fleet incrementally.
When you create the image, make sure that the **Always use latest agent version** option is not selected. After you create your image, perform your qualification tests in a separate fleet before deploying to your production fleet. After you finish your qualification tests, you can update your production fleet with the image.
**To create an image that uses a newer version of the WorkSpaces Applications agent**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2/home](https://console.aws.amazon.com/appstream2/home).
1. Do either of the following:
+ If you have an image builder that you want to use to create the image, start the image builder and then connect to it. If the image builder is not running the latest version of the WorkSpaces Applications agent, you are prompted to choose whether to start the image builder with the latest agent. Make sure that this option is selected, choose **Start**, and then connect to the image builder.
+ If you do not have an image builder that you want to use to create the image, launch a new image builder. In **Step 1: Choose Image**, choose an AWS base image or a custom image. In **Step 2: Configure Image Builder**, if the image that you choose is not running the latest version of the WorkSpaces Applications agent, the **WorkSpaces Applications** section displays. In the **Agent version** list, select the latest agent version. Complete the remaining steps to create the image builder, and then connect to it. For more information, see [Launch an Image Builder to Install and Configure Streaming Applications](tutorial-image-builder-create.md).
1. On the image builder desktop, open Image Assistant and follow the steps to create your new image. For the **Configure Image** step in Image Assistant, make sure that **Always use the latest agent version** is not selected. For more information, see [Tutorial: Create a Custom WorkSpaces Applications Image by Using the WorkSpaces Applications Console](tutorial-image-builder.md).
If you decide later to always use the latest version of the WorkSpaces Applications agent, you must create a new image and select that option.
1. Create a new fleet or modify an existing one. When you configure the fleet, select the new image that you created. For more information, see [Create an Amazon WorkSpaces Applications Fleet and Stack](set-up-stacks-fleets.md).
1. Create a new stack or modify an existing one and associate it with your fleet.
1. Connect to your fleet and test your applications for compatibility.
# WorkSpaces Applications Agent Release Notes
The Amazon WorkSpaces Applications agent software runs on your streaming instances, enabling end users to connect to and start their streaming applications. Starting December 7, 2017, your streaming instances can be automatically updated with the latest features, performance improvements, and security updates that are available from AWS. Before December 7, 2017, agent updates were included with new base image releases.
To use the latest WorkSpaces Applications agent software, you need to rebuild your images by using new base images published by AWS on or after December 7, 2017. When you do this, the option to enable automatic updates of the agent is selected by default in the Image Assistant. We recommend that you leave this option selected so that any new image builder or fleet instance that is launched from your image always uses the latest version of the agent. For more information, see [Tutorial: Create a Custom WorkSpaces Applications Image by Using the WorkSpaces Applications Console](tutorial-image-builder.md).
The following table describes the latest updates that are available in released versions of the WorkSpaces Applications agent for Windows instances.
| Amazon WorkSpaces Applications agent version | Changes |
| --- | --- |
| 03-30-2026 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 02-09-2026 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 02-04-2026 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 12-06-2025 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 10-02-2025 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 09-30-2025 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 07-15-2025 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 05-29-2025 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 03-05-2025 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 02-07-2025 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 10-31-2024 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 10-21-2024 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 09-18-2024 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 05-21-2024 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 04-15-2024 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 01-17-2024 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 12-07-2023 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 09-06-2023 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 05-30-2023 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 05-08-2023 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 04-13-2023 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 03-21-2023 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 10-13-2022 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 06-20-2022 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 03-14-2022 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 02-21-2022 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 12-20-2021 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 10-19-2021 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 08-02-2021 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 07-01-2021 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 06-25-2021 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 05-17-2021 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 03-04-2021 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 12-17-2020 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 01-04-2021 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 12-17-2020 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 10-08-2020 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 09-01-2020 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 07-30-2020 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 05-27-2020 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 04-20-2020 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 02-19-2020 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 01-13-2020 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 11-13-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 10-08-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 09-23-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 09-03-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 08-08-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 07-26-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 06-19-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 05-07-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 04-02-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 03-07-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 01-22-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 01-08-2019 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 12-19-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 12-17-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 12-04-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 11-14-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 10-30-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 10-24-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 10-01-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 08-29-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 07-26-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 06-19-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 06-06-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 05-31-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 05-21-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 03-19-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 01-24-2018 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
| 12-07-2017 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/agent-software-versions.html) |
# Tutorial: Create a Custom WorkSpaces Applications Image by Using the WorkSpaces Applications Console
This tutorial describes how to create WorkSpaces Applications images that are based on Microsoft Windows Server operating systems. If you want to create custom images that are based on the Rocky Linux or Red Hat Enterprise Linux operating systems, see [Tutorial: Create a Custom Linux-Based WorkSpaces Applications Image](tutorial-create-linux-image.md).
In this tutorial, you will learn how to create a custom Amazon WorkSpaces Applications image that contains applications you can stream to your users, and default application and Windows settings to enable your users to get started with their applications quickly. To complete this tutorial, you must already have an image builder. If you don't have an image builder, see [Launch an Image Builder to Install and Configure Streaming Applications](tutorial-image-builder-create.md).
**Important**
This tutorial includes information that applies to the latest base image release. For more information, see [WorkSpaces Applications Base Image and Managed Image Update Release Notes](base-image-version-history.md).
**Topics**
+ [Step 1: Install Applications on the Image Builder](#tutorial-image-builder-install)
+ [Step 2: Create an WorkSpaces Applications Application Catalog](#tutorial-image-builder-add)
+ [Step 3: Create Default Application and Windows Settings](#tutorial-image-builder-create-default-app-settings)
+ [Step 4: Test Applications](#tutorial-image-builder-test-applications)
+ [Step 5: Optimize Applications](#tutorial-image-builder-optimize)
+ [Step 6: Finish Creating Your Image](#tutorial-image-builder-finish-create-image)
+ [Step 7 (Optional): Tag and Copy an Image](#tutorial-image-builder-tag-copy)
+ [Step 8: Clean Up](#tutorial-image-builder-finish)
## Step 1: Install Applications on the Image Builder
In this step, you connect an image builder and install your applications on the image builder.
**Important**
To complete this step, you must log into the image builder with the local **Administrator** account or a domain account that has local administrator permissions. Do not rename or delete the local built-in **Administrator** account. If you rename or delete this account, the image builder will not start and image creation will fail.
**To install applications on the image builder**
1. Connect to the image builder by doing either of the following:
+ [Use the WorkSpaces Applications console](managing-image-builders-connect-console.md) (for web connections only)
+ [Create a streaming URL](managing-image-builders-connect-streaming-URL.md) (for web or WorkSpaces Applications client connections)
**Note**
If the image builder that you want to connect to is joined to an Active Directory domain and your organization requires smart card sign in, you must create a streaming URL and use the WorkSpaces Applications client for the connection. For information about smart card sign in, see [Smart Cards](feature-support-USB-devices-qualified.md#feature-support-USB-devices-qualified-smart-cards).
1. Install applications from an application website or other download source. Install the applications you want before proceeding to the next step.
**Note**
Download and install applications only from sites that you trust.
If an application requires the Windows operating system to restart, let it do so. Before the operating system restarts, you are disconnected from your image builder. After the restart is complete, connect to the image builder again, then finish installing the application.
## Step 2: Create an WorkSpaces Applications Application Catalog
In this step, create an WorkSpaces Applications application catalog by specifying applications (*.exe*), batch scripts (*.bat*), and application shortcuts (*.lnk*) for your image. For each application that you plan to stream, you can specify the name, display name, executable file to launch, and icon to display. If you choose an application shortcut, these values are prepopulated for you.
**Important**
To complete this step, you must be logged into the image builder with the local **Administrator** account or a domain account that has local administrator permissions.
**To create an WorkSpaces Applications application catalog**
1. From the image builder desktop, open Image Assistant. Image Assistant guides you through the image creation process.
![\[Row of icons representing different functions in Image Assistant interface.\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/images/Image-Builder-Desktop-Image-Assistant.png)
1. In **1. Add Apps**, choose **\$1 Add App**, and navigate to the location of the application, script, or shortcut to add. Choose **Open**.
1. In the **App Launch Settings** dialog box, keep or change the default settings for **Name**, **Display Name**, and **Icon Path**. Optionally, you can specify launch parameters (additional arguments passed to the application when it is launched) and a working directory for the application. When you're done, choose **Save**.
The **Display Name** and **Icon Path** settings determine how your application name and icon appear in the application catalog. The catalog displays to users when they sign in to an WorkSpaces Applications streaming session.
1. Repeat steps 2 and 3 for each application in Image Assistant and confirm that the applications appear on the **Add Apps** tab. When you're done, choose **Next** to continue using Image Assistant to create your image.
## Step 3: Create Default Application and Windows Settings
In this step, you create default application and Windows settings for your WorkSpaces Applications users. Doing this enables your users to get started with applications quickly during their WorkSpaces Applications streaming sessions, without the need to create or configure these settings themselves.
**Important**
To complete this step, you must be logged into the image builder with the local **Template User** account or a domain user account that does not have local administrator permissions.
**To create default application and Windows settings for your users**
1. In Image Assistant, in **2. Configure Apps**, choose **Switch user**. This disconnects you from the current session and displays the login menu.
1. Do either of the following:
+ If your image builder is not joined to an Active Directory domain, on the **Local User** tab, choose **Template User**. This account enables you to create your default application and Windows settings.
+ If your image builder is joined to an Active Directory domain, choose **Directory User**, and log in as a domain user that does not have local administrator permissions.
1. From the image builder desktop, open Image Assistant, which displays the applications that you added when you created the application catalog.
1. Choose the application for which you want to create default application settings.
1. After the application opens, create these settings as needed.
1. When you're done, close the application, and return to Image Assistant.
1. If you specified more than one application in Image Assistant, repeat steps 4 through 6 for each application as needed.
1. If you want default Windows settings, create them now. When you're done, return to Image Assistant.
1. Choose **Switch user** and log in with the same account that you used to create the application catalog (an account that has local administrator permissions).
1. In Image Assistant, in **2. Configure Apps**, do either of the following:
+ If your image builder is not joined to an Active Directory domain, choose **Save settings**.
+ If your image builder is joined to an Active Directory domain, in the **Choose which user settings to copy **list, choose the same account that you used to log into the image builder when you created the default application and Windows settings, then choose **Save settings**.
The **Choose which settings to copy** list displays any account that currently has settings saved on the image builder.
1. When you're done, choose **Next** to continue creating your image.
## Step 4: Test Applications
In this step, verify that the applications you've added open correctly and perform as expected. To do so, start a new Windows session as a user who has the same permissions as your users.
**Important**
To complete this step, you must log in to the image builder with the **Test User** account or a domain account that does not have local administrator permissions.
**To test your applications**
1. In Image Assistant, in **3. Test**, do either of the following:
+ If your image builder is not joined to an Active Directory domain, choose **Switch user**.
+ If your image builder is joined to an Active Directory domain, you require a domain account to test your applications, and the user already has settings on the image builder, you must reset the application settings for that user. To do so, select the user from the **User to reset** list, and choose **Reset**. When you're done, choose **Switch user**.
**Note**
If your image builder is new and no users have settings on the image builder, the list does not display any users.
1. Choose the user to use for testing by doing either of the following:
+ If your image builder is not joined to an Active Directory domain, choose **Test User**. This account enables you to test your applications by using the same policies and permissions as your users.
+ If your image builder is joined to an Active Directory domain, choose **Directory User**, specify the credentials for a domain account that does not have local administrator permissions, then choose **Log in**.
1. From the image builder desktop, open Image Assistant, which displays the applications that you specified when you created the application catalog.
1. Choose the application that you want to test, to confirm that it opens correctly and that any default application settings you created are applied.
1. After the application opens, test it as needed. When you're done, close the application and return to Image Assistant.
1. If you specified more than one application in Image Assistant, repeat steps 4 and 5 to test each application as needed.
1. When you're done, choose **Switch user**, then do either of the following:
+ If your image builder is not joined to an Active Directory domain, on the **Local User** tab, choose **Administrator**.
+ If your image builder is joined to an Active Directory domain and you logged in as a domain user with local administrator permissions to specify applications in Image Assistant, log in as that user.
1. Choose **Next** to continue creating your image.
## Step 5: Optimize Applications
In this step, Image Assistant opens your applications one after another, identifies their launch dependencies, and performs optimizations to ensure that applications launch quickly. These are required steps that are performed on all applications in the list.
**To optimize your applications**
1. In Image Assistant, in **4. Optimize**, choose **Launch**.
1. WorkSpaces Applications automatically launches the first application in your list. When the application completely starts, provide any required input to perform the first run experience for the application. For example, a web browser may prompt you to import settings before it is completely up and running.
1. After you complete the first run experience and verify that the application performs as expected, choose **Continue**. If you added more than one application to your image, each application opens automatically. Repeat this step for each application as needed, leaving all applications running.
1. When you're done, the next tab in Image Assistant, **5. Configure Image**, automatically displays.
## Step 6: Finish Creating Your Image
In this step, choose an image name and finish creating your image.
**To create the image**
1. Type a unique image name, and an optional image display name and description. The image name cannot begin with "Amazon," "AWS," or "AppStream."
You can also add one or more tags to the image. To do so, choose **Add Tag**, and type the key and value for the tag. To add more tags, repeat this step. For more information, see [Tagging Your Amazon WorkSpaces Applications Resources](tagging-basic.md). When you're done, choose **Next**.
**Note**
If you choose a base image that is published by AWS on or after December 7, 2017, the option **Always use the latest agent version** appears, selected by default. We recommend that you leave this option selected so that streaming instances that are launched from the image always use the latest version of the agent. If you disable this option, you can't enable it again after you finish creating the image. For information about the latest release of the WorkSpaces Applications agent, see [WorkSpaces Applications Agent Release Notes](agent-software-versions.md).
1. In **6. Review**, verify the image details. To make changes, choose **Previous** to navigate to the appropriate Image Assistant tab, make your changes, and then proceed through the steps in Image Assistant as needed.
1. After you finish reviewing the image details, choose **Disconnect and Create Image**.
1. The remote session disconnects within a few moments. When the **Lost Connectivity** message appears, close the browser tab. While the image is created, the image builder status appears as **Snapshotting**. You cannot connect to the image builder until this process finishes.
1. Return to the console and navigate to **Images**, **Image Registry**. Verify that your new image appears in the list.
While your image is being created, the image status in the image registry of the console appears as **Pending** and you cannot connect to it.
1. Choose the **Refresh** icon periodically to update the status. After your image is created, the image status changes to **Available** and the image builder is automatically stopped.
To continue creating images, start the image builder and connect to it from the console, or create a new image builder.
**Note**
After you create your image, you are responsible for maintaining updates for the Windows operating system. To do so, you can use managed WorkSpaces Applications image updates. You are also responsible for maintaining updates for your applications and their dependencies. For more information, see [Keep Your Amazon WorkSpaces Applications Image Up-to-Date](keep-image-updated.md).
To add other applications, update existing applications, or change image settings, you must start and reconnect to the image builder that you used to create the image. Or, if you deleted that image builder, launch a new image builder that is based on your image. Then, make your changes and create a new image.
## Step 7 (Optional): Tag and Copy an Image
You can add one or more tags to an image during image creation or after you create an image. You can also copy the image within the same Region or to a new Region within the same Amazon Web Services account. Copying a source image results in an identical but distinct destination image. AWS does not copy any user-defined tags, however. Also, you can only copy custom images that you create, not the base images that are provided by AWS.
**Note**
You can copy up to two images at the same time to a destination. If the destination to which you are copying an image is at the image limit, you receive an error. To copy the image in this case, you must first remove images from the destination. After the destination is below the image quota (also referred to as limit), initiate the image copy from the source Region. For more information, see [Amazon WorkSpaces Applications Service Quotas](limits.md).
**To add tags to an existing image**
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, select the image to which you want to add tags.
1. Choose **Tags**, choose **Add/Edit Tags**, choose **Add Tag**, specify the key and value for the tag, and then choose **Save**.
For more information, see [Tagging Your Amazon WorkSpaces Applications Resources](tagging-basic.md).
**To copy an image**
Copying an image across geographically diverse regions enables you to stream applications from multiple regions based on the same image. By streaming your applications in closer proximity to your users, you can improve your users' experience streaming applications with WorkSpaces Applications.
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, select the image that you want to copy.
1. Choose **Actions**, **Copy**.
1. In the **Copy Image** dialog box, specify the following information, and then choose **Copy Image:**
+ For **Destination region**, choose the region to which to copy the new image.
+ For **Name**, specify a name that the image will have when it is copied to the destination.
+ For **Description** (optional), specify a description that the image will have when it is copied to the destination.
1. To check on the progress of the copy operation, return to the console and navigate to **Images**, **Image Registry**. Use the navigation bar to switch to the destination region (if applicable), and confirm that your new image appears in the list of images.
The new image first appears with a status of **Copying** in the image registry of your console. After the image is successfully created, the status of the image changes to **Available**, which means that you can use the image to launch a stack and stream your applications.
## Step 8: Clean Up
Finally, stop your running image builders to free up resources and avoid unintended charges to your account. We recommend stopping any unused, running image builders. For more information, see [WorkSpaces Applications Pricing](https://aws.amazon.com/appstream2/pricing/).
**To stop a running image builder**
1. In the navigation pane, choose **Images**, **Image Builders**, and select the running image builder instance.
1. Choose **Actions**, **Stop**.
# Administer Your Amazon WorkSpaces Applications Images
Available images are listed in the **Image Registry** in the WorkSpaces Applications console, and categorized by visibility as follows:
+ **Public** — Base images that are owned and made available by AWS. Base images include the latest Windows operating system and the WorkSpaces Applications agent software. You can use these base images to create new images that include your own applications. For information about the base images released by AWS, see [WorkSpaces Applications Base Image and Managed Image Update Release Notes](base-image-version-history.md).
+ **Private** — Images that you create and own, and that you have not shared with other AWS accounts.
+ **Shared with others** — Images that you create and own, and that you have shared with one or more AWS accounts in the same AWS Region. When you share an image with another AWS account, you can specify whether the image can be used for an image builder (to create a new image), for a fleet, or both.
+ **Shared with me** — Images that are created and owned by another AWS account in the same AWS Region, and that are shared with your AWS account. Depending on the permissions that the owner provided when sharing the image with your account, you can use this image for image builders, for fleets, or both.
**Topics**
+ [Delete a Private Image in Amazon WorkSpaces Applications](delete-private-image.md)
+ [Copy an Image That You Own to Another AWS Region in Amazon WorkSpaces Applications](copy-image-different-region.md)
+ [Share an Image That You Own With Another AWS Account in Amazon WorkSpaces Applications](share-image-with-another-account.md)
+ [Stop Sharing an Image That You Own in Amazon WorkSpaces Applications](stop-sharing-image-with-all-accounts.md)
+ [Keep Your Amazon WorkSpaces Applications Image Up-to-Date](keep-image-updated.md)
+ [Windows Update and Antivirus Software on Amazon WorkSpaces Applications](windows-update-antivirus-software.md)
+ [Programmatically Create a New Image in Amazon WorkSpaces Applications](create-image-programmatically.md)
+ [Manage License Included Applications on Your Image in Amazon WorkSpaces Applications](license-included-applications.md)
+ [Import Image](import-image.md)
+ [Export Image](export-image.md)
# Delete a Private Image in Amazon WorkSpaces Applications
You can delete your private images when you no longer need them. You can't delete an image that is used by fleets or shared with other AWS accounts. To delete an image that is used by fleets or shared, you must first remove the image from any fleets and remove all image sharing permissions. After you delete an image, you can't recover it.
**To delete a private image**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, select the private image you want to delete.
1. Choose **Actions**, **Delete**, then choose **Delete** again.
The image is removed from the image registry and deleted.
# Copy an Image That You Own to Another AWS Region in Amazon WorkSpaces Applications
**Important**
For Asia Pacific (Malaysia), Europe (Milan), Europe (Spain), and Israel (Tel Aviv) AWS Regions: Cross-region image copying is only supported for images with WorkSpaces Applications agent versions released on/after October 02, 2025, or images using managed updates released on/after September 05, 2025. Older versions are not eligible for copying between regions. Update your images to meet these minimum version requirements to enable cross-region copy functionality.
You can copy images that you own to another AWS Region. Using the same image across different AWS Regions can help simplify global deployments of your applications on WorkSpaces Applications. By deploying your applications in the AWS Regions that are geographically closest to your users, you can help provide your users with a more responsive experience.
**To copy an image that you own to another AWS Region**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, select the image that you want to copy to another AWS Region.
1. Choose **Actions**, **Copy**.
1. In the **Copy image** dialog box, in **Destination region**, select the AWS Region that you want to copy the image to.
1. Type a unique name and optionally, a description for the image in **Destination region**.
1. Choose **Copy Image**.
# Share an Image That You Own With Another AWS Account in Amazon WorkSpaces Applications
WorkSpaces Applications images are a regional resource, so you can share an image that you own with other AWS accounts within the same AWS Region. Doing so can be helpful in several different scenarios. For example, if you separate your development and production resources by using different AWS accounts, you can create an image by using your development account. Then you can share the image with your production account. If your organization is an independent software vendor (ISV), you can share optimized images with your customers. Optimized images that have the required applications already installed and configured let your customers get started with your applications quickly, so that they won't need to install and configure those applications themselves.
When you share an image with another AWS account, you specify whether the destination account can use the image in a fleet or create new images by creating an image builder. You continue to own images that you share. This way, you can add, change, or remove permissions as needed for your shared images.
If you share an image with an account and grant the account fleet permissions, the shared image can be used to create or update fleets in that account. If you remove these permissions later, the account can no longer use the image. For fleets in the account that use the shared image, the desired capacity is set to 0, which prevents new fleet instances from being created. Existing sessions continue until the streaming session ends. For new fleet instances to be created, the fleet in that account must be updated with a valid image.
If you share an image with an account and grant the account image builder permissions, the shared image can be used to create image builders and images in that account. If you remove these permissions later, image builders and images that were created from your image are not affected.
**Important**
After you share an image with an account, you can't control image builders or images in the account that are created from your image. For this reason, grant image builder permissions to an account only if you want to enable the account to make a copy of your image, and retain access to the copy after you stop sharing your image.
**To share an image that you own with another AWS account**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, select the image that you want to share.
1. Choose **Actions**, **Share**.
1. In the **Share image** dialog box, choose **Add account**.
1. Type the 12-digit AWS account ID of the account that you want to share the image with, and then select whether the account can do one or both of the following:
+ Use the image to launch an image builder, if you want to create a new image.
+ Use the image with a fleet.
To remove an account from the list of accounts that the image is shared with, in the row for the account you want to remove, choose the X icon to the right of the **Use for fleet **option.
1. To share the image with more AWS accounts, repeat step 6 for each account that you want to share the image with.
1. Choose **Share Image**.
**To add or update image sharing permissions for an image that you own**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, select the image that you want to change the permissions for.
1. Below the image list, choose the **Permissions** tab for the image you selected, then choose **Edit**.
1. In the **Edit image permissions** dialog box, select or clear one or both of the following image sharing options as needed for one or more AWS accounts. If you clear both options for an account, the image is no longer shared with that account.
+ Use the image to launch an image builder, if you want to create a new image.
+ Use the image with a fleet.
To remove an account from the list of accounts that the image is shared with, in the row for the account you want to remove, choose the X icon to the right of the **Use for fleet **option.
1. To edit image sharing permissions for more AWS accounts, repeat step 5 for each account you want to update permissions for.
1. Choose **Update image sharing permissions**.
# Stop Sharing an Image That You Own in Amazon WorkSpaces Applications
Follow these steps to stop sharing an image that you own with any other AWS account.
**To stop sharing an image that you own with any other AWS account**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, select the image that you want to change the permissions for.
1. Below the image list, choose the **Permissions** tab for the image you selected, then choose **Edit**.
1. In the **Edit image permissions** dialog box, in the row for all AWS accounts that the image is shared with, choose the X icon to the right of the **Use for fleet **option.
1. Choose **Update image sharing permissions**.
# Keep Your Amazon WorkSpaces Applications Image Up-to-Date
You can keep your WorkSpaces Applications image up-to-date by doing either of the following:
+ [Update an Image by Using Managed WorkSpaces Applications Image Updates](keep-image-updated-managed-image-updates.md) – This update method provides the latest operating system updates and driver updates, and the latest WorkSpaces Applications agent software.
+ [Update the WorkSpaces Applications Agent Software by Using Managed WorkSpaces Applications Agent Versions](keep-image-updated-manage-image-versions.md) – This update method provides the latest WorkSpaces Applications agent software.
# Update an Image by Using Managed WorkSpaces Applications Image Updates
WorkSpaces Applications provides an automated way to update your image with the latest operating system updates, license included application updates, driver updates, and WorkSpaces Applications agent software. With managed WorkSpaces Applications image updates, you select the image that you want to update. WorkSpaces Applications creates an image builder in the same AWS account and Region to install the updates and create the new image. After the new image is created, you can test it on a pre-production fleet before updating your production fleets or sharing the image with other AWS accounts.
**Note**
Managed WorkSpaces Applications Image Updates is available for Microsoft Windows Server, Red Hat Enterprise Linux, and Rocky Linux operating systems.
**Note**
After your new image is created, you're responsible for maintaining updates for the operating system. To do so, you can continue using managed WorkSpaces Applications image updates.
You are responsible for maintaining updates for the Amazon EC2 Windows Paravirtual (PV) driver, ENA driver, and AWS NVMe driver. For more information about how to update the drivers, see [Manage device drivers for your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/manage-device-drivers.html).
You're also responsible for maintaining your applications and their dependencies. To add other applications, update existing applications, or change image settings, you must start and reconnect to the image builder that you used to create the image. Or, if you deleted that image builder, launch a new image builder that is based on your image. Then, make your changes and create a new image.
## Prerequisites
The following are prerequisites and considerations for working with managed image updates.
+ Make sure that your WorkSpaces Applications account quotas (also referred to as limits) are sufficient to support the creation of a new image builder and a new image. To request a quota increase, you can use the Service Quotas console at [https://console.aws.amazon.com/servicequotas/](https://console.aws.amazon.com/servicequotas/). For information about default WorkSpaces Applications quotas, see [Amazon WorkSpaces Applications Service Quotas](limits.md).
+ You must own the image that you update. You can't update an image that is shared with you.
+ When WorkSpaces Applications creates an image builder to install the latest operating system updates, driver updates, and WorkSpaces Applications agent software, and creates the new image, you're charged for the image builder instance while it's updating.
+ Supported images must be created from a base image released on 2017-07-24T00:00:00Z or later.
+ English and Japanese are supported display languages. For more information, see [Specify a Default Display Language](configure-default-display-language.md).
+ Use the latest version of SSM Agent. For version information, see [WorkSpaces Applications Base Image and Managed Image Update Release Notes](base-image-version-history.md). For installation information, see [Manually install SSM Agent on EC2 instances for Windows Server](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-win.html).
## How to Update an Image by Using Managed WorkSpaces Applications Image Updates
To update an WorkSpaces Applications image with the latest patches, driver updates, and WorkSpaces Applications agent software, perform the following steps.
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, choose the image that you want to update. Verify that the status of the image is **Available**.
1. Choose **Actions**, **Update**.
1. In the **Update image** dialog box, do the following:
+ For **New image name**, enter an image name that is unique within the AWS account and Region. The image name can't begin with "Amazon," "AWS," or "AppStream."
+ For **New image display name**, you can optionally enter a name to display for the image.
+ For **New image description**, you can optionally provide a description for the image.
+ For **Tags**, you can choose **Add Tag**, and type the key and value for the tag. To add more tags, repeat this step. For more information, see [Tagging Your Amazon WorkSpaces Applications Resources](tagging-basic.md).
1. Choose **Update image**.
If your current image is already up to date, a message notifies you.
1. In the navigation pane, choose **Images**, and then choose **Image Builder**.
1. In the list of image builders, verify that a new image builder appears in the **Updating** state. The name of the image builder includes a random 10-digit suffix.
The image builder is the smallest size in the instance family that you chose for the new image in step 5. No subnet is specified because the image builder is not attached to your virtual private cloud (VPC).
1. Choose **Image Registry** and verify that your new image appears in the list.
While your image is being created, the image status in the image registry of the console appears as **Creating**.
1. After your image is created, WorkSpaces Applications performs a qualification process to verify that the image works as expected.
During this time, the image builder, which is also used for this process, appears in the **Image Builder** list with a status of **Pending Qualification**.
1. After the qualification process successfully completes, a **Success** message appears at the top of the console and the image status in the image registry appears as **Available**.
In addition, the image builder that WorkSpaces Applications created is deleted automatically.
**Note**
Depending on the volume of operating system updates, it might take several hours for an image update to complete. If an issue prevents the image from being updated, a red icon with an exclamation point appears next to the image name, and the image status in the image registry appears as **Failed**. If this occurs, select the image, choose the **Notifications** tab, and review any error notifications. For more information, see the information in the [Image Internal Service](troubleshooting-notification-codes.md#troubleshooting-notification-codes-image) section of the documentation for troubleshooting notification codes.
If the qualification process is not successful, the image builder that WorkSpaces Applications created is still deleted automatically.
1. After WorkSpaces Applications creates the new image, test the image on a pre-production fleet. After you verify that your applications work as expected, update your production fleet with the new image.
# Update the WorkSpaces Applications Agent Software by Using Managed WorkSpaces Applications Agent Versions
WorkSpaces Applications provides an automated way to update your image builder with newer WorkSpaces Applications agent software. Doing so enables you to create a new image whenever a new version of the agent is released. You can then test the image before updating your production fleets. For more information about how to manage the WorkSpaces Applications agent software, see [Manage WorkSpaces Applications Agent Versions](base-images-agent.md).
**Note**
You're responsible for installing and maintaining the updates for the Windows operating system, your applications, and their dependencies.
To keep your WorkSpaces Applications image updated with the latest Windows operating system updates, do one of the following:
+ Install your applications on the latest base image each time a new image is released.
+ Install the updates for the Windows operating system, your applications, and their dependencies on an existing image builder.
+ Install the updates for the Windows operating system, your applications, and their dependencies on a new image builder from an existing image.
After you create a new image with the latest Windows operating system, applications and their dependencies, and the WorkSpaces Applications agent software, test the image on a development fleet. After you verify that your applications work as expected, update your production fleet with the new image.
# Windows Update and Antivirus Software on Amazon WorkSpaces Applications
WorkSpaces Applications streaming instances are non-persistent. When a user streaming session ends, WorkSpaces Applications terminates the instance used by the session and, depending on your scaling policies, provisions a new instance to replace it in your fleet. All fleet instances are provisioned from the same image. Because images cannot be changed once created, all fleet instances used in user streaming sessions have only the Windows and application updates that were installed on the underlying image when the image was created. In addition, because a fleet instance used for a streaming session terminates at the end of the session, any updates made to Windows or to applications on the instance during the streaming session will not persist to future sessions by the same user or other users.
**Note**
If you enabled application settings persistence for your stack, WorkSpaces Applications persists Windows and application configuration changes made by a user to future sessions for the same user if those configuration changes are stored in the user’s Windows profile. However, the application settings persistence feature persists only Windows and application configuration settings. It does not persist software updates to Windows or applications on the streaming instance.
For these reasons, WorkSpaces Applications takes the following approach to Windows Update and antivirus software on WorkSpaces Applications instances.
## Windows Update
Windows Update is not enabled by default on WorkSpaces Applications base images. If you enable Windows Update on an image builder and then try to create an image, Image Assistant displays a warning and disables Windows Update during the image creation process. To ensure that your fleet instances have the latest Windows updates installed, we recommend that you install Windows updates on your image builder, create a new image, and update your fleet with the new image on a regular basis.
## Antivirus Software
If you choose to install antivirus software on your image, we recommend that you do not enable automatic updates for the antivirus software. Otherwise, the antivirus software may attempt to update itself with the latest definition files or other updates during user sessions. This may affect performance. In addition, any updates made to the antivirus software will not persist beyond the current user session. To ensure that your fleet instances always have the latest antivirus updates, we recommend that you do either of the following:
+ Update your image builder and create a new image on a regular basis (for example, by using the [Image Assistant CLI operations](https://docs.aws.amazon.com/appstream2/latest/developerguide/programmatically-create-image.html)).
+ Use an antivirus application that delegates scanning or other operations to an always-up-to-date external server.
**Note**
Even if you do not enable automatic updates for your antivirus software, the antivirus software may perform hard drive scans or other operations that may impact the performance of your fleet instances during user sessions.
On WorkSpaces Applications Windows Server 2025/2022/2019/2016 base images published on or after September 10, 2019, Windows Defender is not enabled by default. On WorkSpaces Applications Windows Server 2016 and Windows Server 2019 base images published on June 24, 2019, Windows Defender is enabled by default.
**To enable Windows Defender manually**
If Windows Defender is not enabled on your base image, you can enable it manually. To do so, complete the following steps.
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 **Images**, **Image Builder**.
1. Choose the image builder on which to enable Windows Defender, verify that it is in the **Running** state, and choose **Connect**.
1. Log in to the image builder with the local **Administrator** account or with a domain account that has local administrator permissions.
1. Open Registry Editor.
1. Navigate to the following location in the registry: **HKLM\$1SOFTWARE\$1Policies\$1Microsoft\$1Windows Defender\$1DisableAntiSpyware**.
1. To edit this registry key, double-click it, or right-click the registry key, and choose **Modify**.
1. In the **Edit DWORD (32-bit) Value** dialog box, in **Value data**, change **1** to **0**.
1. Choose **OK**.
1. Close Registry Editor.
1. Open the Microsoft Management Console (MMC) **Services** snap-in (`services.msc`).
1. In the list of services, do one of the following.
If you are using Microsoft Windows Server 2022/2025, do either of the following:
+ Right-click **Microsoft Defender Antivirus Service**, and choose **Start**.
+ Double-click **Microsoft Defender Antivirus Service**, choose **Start** in the properties dialog box, and then choose **OK**.
If you are using Microsoft Windows Server 2019 or 2016, do either of the following:
+ Right-click **Windows Defender Antivirus Service**, and choose **Start**.
+ Double-click **Windows Defender Antivirus Service**, choose **Start** in the properties dialog box, and then choose **OK**.
1. Close the **Services** snap-in.
# Programmatically Create a New Image in Amazon WorkSpaces Applications
You can create WorkSpaces Applications images programmatically by connecting to an image builder and using the Image Assistant command line interface (CLI) operations. For more information, see [Create Your Amazon WorkSpaces Applications Image Programmatically by Using the Image Assistant CLI Operations](programmatically-create-image.md).
# Manage License Included Applications on Your Image in Amazon WorkSpaces Applications
You can stream the following Microsoft license included applications using WorkSpaces Applications. You can install these applications on your Windows Image, use this custom image to create fleet(s), and then stream these applications. All of the following applications are available in 32-bit and 64-bit architecture:
+ Microsoft Office LTSC Professional Plus 2021/2024
+ Microsoft Visio LTSC Professional 2021/2024
+ Microsoft Project Professional 2021/2024
+ Microsoft Office LTSC Standard 2021/2024
+ Microsoft Visio LTSC Standard 2021/2024
+ Microsoft Project Standard 2021/2024
**Important**
Microsoft Office, Visio, and Project must follow the same versions. For example, you can't mix 2021 applications with 2024 applications.
Microsoft Office, Visio, and Project must follow the same architecture. For example, you can't mix 32-bit applications with 64-bit applications.
Microsoft Office, Visio, and Project 2021 Standard/Professional versions are supported on Microsoft Windows Server 2019/2022/2025. Microsoft Office, Visio, and Project 2024 Standard/Professional versions are supported on Microsoft Windows Server 2022 and 2025.
To enable this feature, you must use an WorkSpaces Applications Image Builder that uses an WorkSpaces Applications agent released on or after October 2, 2025. For more information, see [Manage WorkSpaces Applications Agent Versions](base-images-agent.md) . Or, your image must use managed WorkSpaces Applications image updates released on or after October 3, 2025. For more information, see [Keep Your Amazon WorkSpaces Applications Image Up-to-Date](keep-image-updated.md).
Outbound TCP on port 1688 must be open on the management network interface of all streaming instances.
All users streaming through a fleet powered by an image with one or more licensed apps incur billing for these apps monthly, regardless of usage. The application entitlement feature doesn't restrict access for specific users.
License included applications on Image Builder aren't activated because they are installed for administrative purposes. Activation occurs when users stream through a fleet instance.
**Topics**
+ [View the list of license included applications installed on your image](view-list-image.md)
+ [View the list of license included applications on your image builder](view-list-apps.md)
+ [Install or uninstall license included applications](install-uninstall-apps.md)
+ [Enable updates for license included applications on image builder](updates-image-builder.md)
+ [Enable updates for license included applications on image builder with Powershell](enable-updates-managed-powershell.md)
+ [Enable updates for license included applications on image builder with Managed Image Update](enable-updates-managed.md)
# View the list of license included applications installed on your image
**View the list of license included applications installed on your image**
To view the list of license included applications installed on your image, follow these steps.
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. Choose **Images** in the left navigation pane and the **Image Registry** tab.
1. Select an image, and choose **View Details**.
1. Review the list of all the installed applications under **License included applications**.
# View the list of license included applications on your image builder
**View the list of license included applications on your image builder**
To view the list of license included applications on your image builder, follow these steps.
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. Choose **Images** in the left navigation pane and the **Image builder** tab.
1. Select an image builder, and choose **View details**.
1. Review the list of applications and their statuses under **License included applications**.
# Install or uninstall license included applications
**Install or uninstall license included applications**
To install or uninstall one or more license included application(s) on your image, follow these steps.
1. Complete one of the following options:
+ Launch an image Builder and configure license included applications. For more information, see [Launch an Image Builder to Install and Configure Streaming Applications](tutorial-image-builder-create.md).
+ Manage license included applications on your image builder. For more information, see [Attribute-Based Application Entitlements Using a Third-Party SAML 2.0 Identity Provider](application-entitlements-saml.md).
1. When you have an image created with one or more license included applications, you can use this image to create fleets. Users connecting to this fleet can access these applications.
**Important**
All the users streaming through a fleet powered by an image with one or more licensed apps will incur billing for these apps monthly, regardless of usage. The application entitlement feature does not restrict access for specific users.
If you encounter failures during license included app installation or uninstallation, you will see a failure status on your Image Builder's details page. To troubleshoot these issues, we recommend connecting to your Image Builder and enabling verbose logging. For more information see [How to enable Microsoft 365 Apps for enterprise logging](https://learn.microsoft.com/en-us/troubleshoot/microsoft-365-apps/diagnostic-logs/how-to-enable-office-365-proplus-uls-logging). If the problem persists after reviewing the logs and troubleshooting, contact AWS Support for help.
# Enable updates for license included applications on image builder
**Enable updates for license included applications on image builder**
Updates for all license included applications are disabled by default. You can enable updates for these applications on the image builder with an image that includes one or more of these applications. Updates on fleet instances remain disabled to prevent installation during session setup.
There are three options for enabling updates for license included applications on image builder.
To enable updates for license included applications on image builder with the application menu, follow these steps.
1. Open any license included application.
1. Choose **File**, **Account**, **Update Options**, and **Enable Updates**.
# Enable updates for license included applications on image builder with Powershell
To enable updates for license included applications on image builder with Powershell, follow these steps.
+ Run the following command with PowerShell as an administrator:
`Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Office\ClickToRun\Configuration" -Name UpdatesEnabled -Value True `
# Enable updates for license included applications on image builder with Managed Image Update
To enable updates for license included applications on image builder with Managed Image Update, follow these steps.
+ Use Managed Image Update to receive updates on Microsoft license included applications. For more information, see
[Update an Image by Using Managed WorkSpaces Applications Image Updates](keep-image-updated-managed-image-updates.md).
# Import Image
You can create WorkSpaces Applications images by importing your customized EC2 AMIs. Here's how it works:
1. Customize your EC2 AMI using any preferred method including [EC2 Image Builder](https://docs.aws.amazon.com/imagebuilder/).
1. Import your customized AMI into WorkSpaces Applications to create a WorkSpaces Applications image
1. Optionally, use Image Builder for additional image customization
Images created through AMI import are of `type = "custom"`, while WorkSpaces Applications provided images are of `type = "native"`.
You can use stream.\$1 instance types for images with `type = "native"`. To use any of the following instance type you must import your AMI and create an image with `type = "custom"`.
+ GeneralPurpose.\$1
+ MemoryOptimized.\$1
+ ComputeOptimized.\$1
+ Accelerated.\$1
## Prerequisites for image import
All these prerequisites are important for a successful workflow execution. Supported AMI configurations and other mandatory requirements are listed below.
### Required AMI Properties
EBS
+ Less or equal to 500GB size
+ You can import an AMI with < 200 GB, however, the imported image will use minimum 200GB.
+ GP2
+ You can import an AMI with gp2 or gp3 EBS volume type, however, the imported image will use gp2.
+ One volume per image
+ `/dev/sda1` Root Device Name
+ Image Type: Machine
+ Architecture: x86\$164
+ Virtualization Type: HVM
+ Boot Mode: UEFI
+ TPM Support: v2.0. This is required, Refer to [https://docs.aws.amazon.com/ec2/latest/windows-ami-reference/ami-windows-tpm.html\$1ami-windows-tpm-find](https://docs.aws.amazon.com/ec2/latest/windows-ami-reference/ami-windows-tpm.html#ami-windows-tpm-find) to find a TPM enabled AMI.
+ ENA Support: true
+ Platform: Windows
+ Platform Details: Windows
### Operating System Properties
Windows Server 2022/2025 **Full Base**
+ Windows Server **Core** is not supported
+ Windows with SQL Server is not supported
Agents
+ EC2 Launch V2 Version >= 2.1.1
+ SSM Agent required
Drivers
+ EC2 ENA Driver Version >= 2.9.0
+ EC2 NVMe Driver Version >= 1.6.0
Library Support
+ .NET Framework 4.8 or greater
+ Installed by default in Windows Server 2022/2025
+ PowerShell 5.1 or greater
+ Installed by default in Windows Server 2022/2025
+ Windows Features: Remote Desktop Services Licensing and Remote Desktop Services Session Host must not be installed
+ Ports: Ports 8000, 8300, and 8443 must be unblocked and unoccupied
+ Boot Mode: UEFI
If you want to use image with graphics instances such as Accelerated.g4dn, Accelerated.g5, Accelerated.G6, or Accelerated.G6e you much install proper GRID driver on your AMI. For more details please refer to [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nvidia-GRID-driver.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nvidia-GRID-driver.html). If the drivers are not setup correctly the streaming will work, however, graphics card may not available.
**Important**
"Owner Account Id" of the AMI must be your AWS account id. You cannot import a public EC2 AMI.
Perform any Windows updates and disable automatic Windows updates before importing the image.
Import of encrypted EC2 AMIs is currently not supported
### IAM Role Requirements
**Important**
"Create an IAM role with the following permissions to use for image import:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowModifyImageAttributeWithTagCondition",
"Effect": "Allow",
"Action": "ec2:ModifyImageAttribute",
"Resource": "*"
},
{
"Sid": "AllowDescribeImages",
"Effect": "Allow",
"Action": "ec2:DescribeImages",
"Resource": "*"
}
]
}
```
Add the following trust relationship for this IAM role
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appstream.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
## To import an image
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 **Images** and then choose **Image registry**.
1. Choose **Import Image**.
1. **AMI ID** - Enter an AMI ID for AMI that you would like to import to WorkSpaces Applications. You can also search for your AMI using this field.
1. **Image name** - Enter a unique name for the image that will be created because of import operation.
1. **Display name** *(Optional)* - Enter a to display for the image.
1. **Description** *(Optional)* – Enter a description for the image.
1. **IAM Role** - Select the IAM role that you have created for image import. For more details refer to [IAM Role Requirements](#iam-role-requirements).
1. **Manage WorkSpaces Applications agent** – Select this option if you want to always use the latest WorkSpaces Applications agent version, your streaming instances are automatically updated with the latest features, performance improvements, and security updates that are available from AWS when a new agent version is released.
1. **Runtime validation** *(Optional)*: Select this option and service will provision an instance with the image being imported and run streaming tests.
+
**Note**
These streaming tests will be executed in the background, you cannot connect to this instance via WorkSpaces Applications client.
+ We recommend using this option to get higher confidence that your image is suitable for WorkSpaces Applications.
+ You will be billed for the hourly price of that instance.
+ You can avoid running runtime validation if you are re-importing your AMI after making minor changes that may not affect the streaming test, and if runtime validation passed the last time, you imported this AMI.
+ **Choose instance type** *(Optional)*: Select the right instance family, type, and size for running the streaming test. It is recommended that you use the same instance which you are planning to use for fleet creation.
1. **Applications catalog and launch performance manifest** *(Optional)*: Provide details to create applications catalog for your end users and improve the launch performance of your applications.
+ **Application catalog**: To create an application catalog specify details about the applications installed your image. For each application that you plan to stream, you can specify the name, display name, executable file to launch, and icon to display.
+ **Launch performance**: Adding files to the application optimization manifest reduces the time that it takes for the application to launch for the first time on a new fleet instance. The optimization manifest is a line-delimited text file that is per application.
To learn more refer to [Applications Details](applications-details.md).
1. **Tags** *(Optional)* - Choose **Add Tag** and type the key and value for the tag. To add more tags, repeat this step. For more information, see [Tagging Your Amazon WorkSpaces Applications Resources](tagging-basic.md).
1. **Import Image** – Review all the information you have entered and choose **Import Image**. Service will run compatibility checks to make sure AMI is compatible with WorkSpaces Applications.
+ If the static checks fail, you will receive an error straight away.
+ If the static checks pass, your import request will be submitted and depending upon the options you have selected it could take 30-60 min to create a new WorkSpaces Applications image with `type = "custom"`
# Applications Details
Applications details contains information about pre-warm manifests and app catalog configurations.
## Application PreWarm Manifests
When creating WorkSpaces Applications images you may specify applications to be made available to your users. To speed up the application's launch time you can prepare a PreWarm manifest. This is essentially a catalog of the files that your application needs to launch when users launch your application. During instance provisioning these files will be prepared ahead of session connections to speed up application launch times in user sessions.
Prewarm manifests must be pre-created on your AMI before being imported into the WorkSpaces Applications environment. You can choose to either create one common Prewarm manifest file or one per each application. This changes how you will import your AMI later.
### Common Prewarm Manifest
For each application you wish to prewarm, launch the application and perform any initial interactions your users may perform. Then, use the following command targeting the directory where your applications data is stored.
```
dir -path "C:\Path\To\Folder\To\Optimize" -Recurse -ErrorAction SilentlyContinue | %{$_.FullName} | Out-File "C:\ProgramData\Amazon\Photon\Prewarm\PrewarmManifest.txt" -encoding UTF8 -append
```
This will append the files to optimize for each application into the common `C:\\ProgramData\\Amazon\\Photon\\Prewarm\\PrewarmManifest.txt` file. There is no additional action needed to perform application prewarming. WorkSpaces Applications will look for the prewarm file at the above location and use it if it is present.
This process is optional and as the size of the prewarm manifest increases, fleet provisioning time will also increase. So take care to balance optimization with fleet provisioning.
### Application Specific Manifests
During image import, you may wish to specify separate application manifest files per application for easier tracking of the prewarm assets per application. To do this perform the same steps as above, but instead of creating a common `C:\\ProgramData\\Amazon\\Photon\\Prewarm\\PrewarmManifest.txt` file, create a file per application on your AMI.
For each application you wish to prewarm, launch the application and perform any initial interactions your users may perform. Then, use the following command targeting the directory where your applications data is stored.
```
dir -path "C:\Path\To\Folder\To\Optimize" -Recurse -ErrorAction SilentlyContinue | %{$_.FullName} | Out-File "C:\Path\To\My\PreWarm.txt" -encoding UTF8 -append
```
We will use these application prewarm files during the image import process. Again this is completely optional. You may choose to use this method, the Common Prewarm Manifest method, or no Prewarm manifest at all.
## Application Catalog Configs
`AppCatalogConfig` which allows you to specify the applications you wish to register to your WorkSpaces Applications image during AMI import. The `AppCatalogConfig` is a JSON list of Application configuration objects of the following structure.
```
[
{
"Name": "Rufus", //Required and must be unique among the list of applications
"DisplayName": "Rufus",
"AbsoluteAppPath": "Rufus", //Required
"AbsoluteIconPath": "Rufus",
"AbsoluteManifestPath": "Rufus",
"WorkingDirectory": "Rufus",
"LaunchParameters": "Rufus"
}
...
// Up to 50 applications total
]
```
The only required fields per application are the `Name` and the `AbsoluteAppPath`. The details of each field as follows:
Name [**Required**]
+ A given name for your application to identify it
+ Between 1 and 100 characters
+ Allowed characters regex `^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,99}$`
+ Must be unique in a given AppCatalogConfig
DisplayName
+ The display name for a given application to display to users
+ Between 0 and 100 characters
+ Allowed characters regex `^[a-zA-Z0-9][a-zA-Z0-9_. -]{0,99}$`
AbsoluteAppPath [**Required**]
+ The path to the executable to launch your application
+ This is the executable that will be launched when users select your application
+ Between 1 and 32767 characters
+ This character length upper limit is to support extended file paths in Windows. Ensure your AMI and application is properly configured to support Windows extended file paths if using file paths larger than 260 characters.
+ Use escaped file path strings such as
+ `"C:\\Windows\\System32\\notepad.exe"`
AbsoluteManifestPath
+ Only applicable if you are using [Application Specific Manifests](#application-specific-manifests)
+ Path to prewarm manifest file for this application
+ Between 0 and 32767 characters
+ This character length upper limit is to support extended file paths in Windows. Ensure your AMI and application is properly configured to support Windows extended file paths if using file paths larger than 260 characters.
+ Use escaped file path strings such as
+ `"C:\\Path\\To\\PrewarmManifest.txt"`
AbsoluteIconPath
+ Path to icon file on the AMI to use for the application.
+ This icon will be shown to users when streaming to this image.
+ If none is provided the icon will be derived from the executable itself.
+ Take care to select icon files with appropriately handled background transparency for a good client experience for your users
+ Use PNG images
+ Between 1 and 32767 characters
+ This character length upper limit is to support extended file paths in Windows. Ensure your AMI and application is properly configured to support Windows extended file paths if using file paths larger than 260 characters.
+ Use escaped file path strings such as
+ `"C:\\Path\\To\\ApplicationIcon.png"`
WorkingDirectory
+ The working directory to launch your application in
+ Between 0 and 32767 characters
+ This character length upper limit is to support extended file paths in Windows. Ensure your AMI and application is properly configured to support Windows extended file paths if using file paths larger than 260 characters.
+ Use escaped file path strings such as
+ `"C:\\Path\\To\\Working\\Directory"`
LaunchParameters
+ A string to use as the launch parameters for the executable specified in `AbsoluteAppPath`
+ Between 0 and 1024 characters
+ Use escaped strings with the full list of required launch parameters such as the following example which shows how you may use PowerShell scripts as your applications by using the PowerShell executable as your app with a script provided in the launch parameters
+ AbsoluteAppPath
+ `"C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"`
+ LaunchParameters
+ `"-File \"C:\\Path\\To\\App\\Script.ps1\""`
### Sample AppCatalogConfig
This is a bare bones example of an AppCatalogConfig for Notepad, Google Chrome, and Mozilla Firefox
```
[
{
"Name": "Notepad",
"DisplayName": "Notepad",
"AbsoluteAppPath": "C:\\Windows\\System32\\notepad.exe"
},
{
"Name": "Chrome",
"DisplayName": "Chrome",
"AbsoluteAppPath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
"LaunchParameters": "https://www.amazon.com/"
},
{
"Name": "Firefox",
"DisplayName": "Firefox",
"AbsoluteAppPath": "C:\\Program Files\\Mozilla Firefox\\firefox.exe",
"LaunchParameters": "https://aws.amazon.com/"
}
]
```
# Export Image
You can export your images to create EC2 AMIs. Later you can [Import Image](import-image.md) those AMIs back to create WorkSpaces Applications images. This helps you to use your own AMI customization tools for customizing of your images.
**Note**
During export following components will be removed from your images
WorkSpaces Applications agent
Microsoft license included applications, which were added using Image Builder
Only Microsoft Windows Server 2022 and 2025 images can be exported.
## IAM Role Requirements
**Important**
Create an IAM role with the following permissions to use for export import:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowCopyImage",
"Effect": "Allow",
"Action": "ec2:CopyImage",
"Resource": "*"
},
{
"Sid": "AllowDescribeImages",
"Effect": "Allow",
"Action": "ec2:DescribeImages",
"Resource": "*"
},
{
"Sid": "AllowCreateTags",
"Effect": "Allow",
"Action": "ec2:CreateTags",
"Resource": "*"
}
]
}
```
Add the following trust relationship for this IAM role
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appstream.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
## To export an image
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, select the private image you want to export.
1. Choose **Actions**, **Export**.
1. In the **Export image** dialog box, type a unique **AMI name** and optionally **AMI Description** for the AMI.
1. **IAM Role** - Select the IAM role that you have created for image export.
1. You optionally copy tags from your Image to AMI by checking the **Copy tags in export** checkbox.
1. Choose **Export Image**.
# Create Your Amazon WorkSpaces Applications Image Programmatically by Using the Image Assistant CLI Operations
You can create Amazon WorkSpaces Applications images by connecting to an image builder and using the Image Assistant graphical user interface (GUI) or command line interface (CLI) operations. The Image Assistant CLI operations provide functionality that is similar to the Image Assistant GUI. With these operations, you can programmatically do the following:
+ Manage the applications that are included in an image.
+ Save, update, and reset default application settings.
+ Enable or disable the WorkSpaces Applications dynamic application framework.
+ Specify tags.
+ Create an image.
You can use these operations to integrate WorkSpaces Applications image creation with your continuous integration or deployment software development process.
To work with the Image Assistant CLI operations, use the command line shell of your choice on an image builder. For example, you can use the Windows command prompt or PowerShell.
**Note**
The image builder must use a version of the WorkSpaces Applications agent that is released on or after July 26, 2019. If you don't have an image builder, you must create one. For more information, see [Launch an Image Builder to Install and Configure Streaming Applications](tutorial-image-builder-create.md).
**Topics**
+ [Creating Default Application and Windows Settings with the Image Assistant CLI operations](create-default-app-windows-settings-image-assistant.md)
+ [Optimizing the Launch Performance of Your Applications with the Image Assistant CLI Operations](optimize-app-launch-performance-image-assistant-cli.md)
+ [Process Overview for Programmatically Creating an Amazon WorkSpaces Applications Image](process-overview-creating-image-programmatically-image-assistant-cli.md)
+ [Image Assistant CLI Operations for Creating and Managing Your Amazon WorkSpaces Applications Image](cli-operations-managing-creating-image-image-assistant.md)
# Creating Default Application and Windows Settings with the Image Assistant CLI operations
You can create default application and Windows settings so that your users can get started with their applications quickly. When you create these settings, WorkSpaces Applications replaces the Windows default user profile with the profile that you configure. The Windows default user profile is then used to create the initial settings for users in the fleet instance. If you create these settings by using the Image Assistant CLI operations, your application installer, or the automation, should modify the Windows default user profile directly.
To overwrite the Windows default user profile with that of another Windows user, you can also use the Image Assistant `update-default-profile` CLI operation.
For more information about configuring default application and Windows settings, see *Creating Default Application and Windows Settings for Your WorkSpaces Applications Users* in [Default Application and Windows Settings and Application Launch Performance in Amazon WorkSpaces Applications](customizing-appstream-images.md).
# Optimizing the Launch Performance of Your Applications with the Image Assistant CLI Operations
WorkSpaces Applications lets you optimize the launch performance of your applications for your users’ streaming sessions. When you do so by using the Image Assistant CLI operations, you can specify the files to optimize for your application launch. Adding files to the application optimization manifest reduces the time that it takes for the application to launch for the first time on a new fleet instance. However, this also increases the time that it takes for the fleet instances to be made available to users. The optimization manifest is a line-delimited text file that is per application.
**Note**
If you onboard application optimization manifests by using both the Image Assistant CLI operations and the Image Assistant GUI, the manifests are merged.
Following is an example of an application optimization manifest file:
```
C:\Program Files (x86)\Notepad++\autoCompletion
C:\Program Files (x86)\Notepad++\localization
C:\Program Files (x86)\Notepad++\plugins
C:\Program Files (x86)\Notepad++\themes
C:\Program Files (x86)\Notepad++\updater
C:\Program Files (x86)\Notepad++\userDefineLangs
C:\Program Files (x86)\Notepad++\change.log
C:\Program Files (x86)\Notepad++\config.xml
C:\Program Files (x86)\Notepad++\contextMenu.xml
C:\Program Files (x86)\Notepad++\doLocalConf.xml
C:\Program Files (x86)\Notepad++\functionList.xml
C:\Program Files (x86)\Notepad++\langs.model.xml
C:\Program Files (x86)\Notepad++\license.txt
C:\Program Files (x86)\Notepad++\notepad++.exe
C:\Program Files (x86)\Notepad++\readme.txt
C:\Program Files (x86)\Notepad++\SciLexer.dll
C:\Program Files (x86)\Notepad++\shortcuts.xml
C:\Program Files (x86)\Notepad++\stylers.model.xml
```
For more information about optimizing the launch performance of your applications, see *Optimizing the Launch Performance of Your Applications* in [Default Application and Windows Settings and Application Launch Performance in Amazon WorkSpaces Applications](customizing-appstream-images.md).
# Process Overview for Programmatically Creating an Amazon WorkSpaces Applications Image
You can use the Image Assistant CLI operations with your application installation automation to create a fully programmatic WorkSpaces Applications image creation workflow. After your application installation automation completes, but before the image is created, use the Image Assistant CLI operations to specify the following:
+ The executable files that your users can launch
+ The optimization manifests for your applications
+ Other WorkSpaces Applications image metadata
The following high-level overview describes the process for programmatically creating an WorkSpaces Applications image.
1. Use your application installation automation to install the required applications on your image builder. This installation may include applications that your users will launch, any dependencies, and background applications.
1. Determine the files and folders to optimize.
1. If applicable, use the Image Assistant `add-application` CLI operation to specify the application metadata and optimization manifest for the WorkSpaces Applications image.
1. To specify additional applications for the WorkSpaces Applications image, repeat steps 1 through 3 for each application as needed.
1. If applicable, use the Image Assistant `update-default-profile` CLI operation to overwrite the default Windows profile and create default application and Windows settings for your users.
1. Use the Image Assistant `create-image` CLI operation to create the image.
# Image Assistant CLI Operations for Creating and Managing Your Amazon WorkSpaces Applications Image
This section describes the Image Assistant CLI operations that you can use to create and manage your WorkSpaces Applications image.
On Windows image builders, the executable file that includes the command line interface is located at: C:\$1Program Files\$1Amazon\$1Photon\$1ConsoleImageBuilder\$1Image-Assistant.exe. For your convenience, this executable file is included in the Windows PATH variable. This lets you call the Image Assistant CLI operations without specifying the absolute path to the executable file. To call these operations, type the **image-assistant.exe** command.
On Linux image builders, the image assistant tool is located at /usr/local/appstream/image-assistant/AppStreamImageAssistant, with a symbolic link at /bin/AppStreamImageAssistant.
## `help` operation
Retrieves a list of all Image Assistant CLI operations. For each operation in the list, a description and usage syntax is provided. To display help for a specific operation, type the name of the operation and specify the **--help** parameter. For example:
```
add-application --help
```
**Synopsis**
```
help
```
**Output**
Prints to standard out the list of available operations with a description of their function.
## `add-application` operation
Adds the application to the application list for WorkSpaces Applications users. Applications in this list are included in the application catalog. The application catalog displays to users when they sign in to an WorkSpaces Applications streaming session.
**Note**
If you need to make changes to an application configuration, remove the application and add the application with the updated settings.
**Synopsis**
```
add-application
--name
--absolute-app-path
[--display-name ]
[--absolute-icon-path ]
[--working-directory ]
[--launch-parameters <""-escaped value>]
[--absolute-manifest-path ]
```
**Options**
**`--name` (string)**
A unique name for the application. The maximum length is 256 characters. You can add up to 50 applications. You cannot use whitespace characters.
**`--absolute-app-path` (string)**
The absolute path to the executable file, batch file, or script for the application. The path must point to a valid file.
**`--display-name` (string)**
The name to display for the application in the application catalog. If you don't specify a display name, WorkSpaces Applications creates a name that is derived from the executable file name. The name is created without the file extension and with underscores in place of spaces. The maximum length is 256 characters.
**`--absolute-icon-path` (string)**
The absolute path to the icon for the application. The path must point to a valid icon file that is one of the following types: .jpg, .png, or .bmp. The maximum dimensions are: 256 px x 256 px. If you don't specify a path, the default icon for the executable file is used, if available. If a default icon is not available for the executable file, a default WorkSpaces Applications application icon is used.
**`--working-directory` (string)**
The initial working directory for the application when the application is launched.
**`--absolute-manifest-path` (string)**
The path to a new line-delimited text file. The file specifies the absolute paths of the files to optimize before the fleet instance is made available to a user for streaming. The path must point to a valid text file.
**Message output**
| Exit code | Message printed to standard out | Description |
| --- | --- | --- |
| 0 | \$1"status": 0, "message": "Success"\$1 | The application was added successfully. |
| 1 | \$1"status": 1, "message": "Administrator privileges are required to perform this operation"\$1 | Administrator privileges are required to complete the operation. |
| 1 | \$1"status": 1, "message": "Unable to add more than 50 apps to the catalog."\$1 | The application could not be added because the maximum number of applications that can be added to the WorkSpaces Applications application catalog is 50. |
| 1 | \$1"status": 1, "message": "Name is not unique"\$1 | An application with that name already exists in the WorkSpaces Applications application catalog. |
| 1 | \$1"status": 1, "message": "File not found (absolute-app-path)"\$1 | The file that was specified for absolute-app-path could not be found. |
| 1 | \$1"status": 1, "message": "Unsupported file extension"\$1 | The Absolute-app-path parameter only supports the following file types: .exe and .bat. |
| 1 | \$1"status": 1, "message": "Directory not found (working-directory)" | The directory that was specified for working-directory could not be found. |
| 1 | \$1"status": 1, "message": "Optimization-manifest not found: "\$1 | The file that was specified for optimization-manifest could not be found. |
| 1 | \$1"status": 1, "message": "File not found: "\$1 | A file that was specified within the optimization manifest could not be found. |
| 255 | \$1"status": 255, "message": \$1 | An unexpected error occurred. Try the request again. If the error persists, contact AWS Support for assistance. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/). |
## `remove-application` operation
Removes an application from the application list for the WorkSpaces Applications image. The application is not uninstalled or modified, but users will not be able to launch it from the WorkSpaces Applications application catalog.
**Synopsis**
```
remove-application
--name
```
**Options**
**`--name` (string)**
The unique identifier of the application to remove.
**Message output**
| Exit code | Message printed to standard out | Description |
| --- | --- | --- |
| 0 | \$1"status": 0, "message": "Success"\$1 | The application was removed successfully. |
| 1 | \$1"status": 1, "message": "Administrator privileges are required to perform this operation"\$1 | Administrator privileges are required to complete the operation. |
| 1 | \$1"status": 1, "message": "App not found"\$1 | The application that was specified could not be found in the WorkSpaces Applications application catalog. |
| 255 | \$1"status": 255, "message": \$1 | An unexpected error occurred. Try the request again. If the error persists, contact AWS Support for assistance. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/). |
## `list-applications` operation
Lists all of the applications that are specified in the application catalog.
**Synopsis**
```
list-applications
```
**Message output**
| Exit code | Message printed to standard out | Description |
| --- | --- | --- |
| 0 | \$1"status": 0, "message": "Success", "applications": [ \$1..app1.. \$1, \$1 ..app2.. \$1]\$1 | List of applications in the WorkSpaces Applications application catalog. |
| 255 | \$1"status": 255, "message": \$1 | An unexpected error occurred. Try the request again. If the error persists, contact AWS Support for assistance. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/). |
## `update-default-profile` operation
Copies the specified Windows user’s profile to the Windows default user profile. New users who stream inherit the settings stored in the specified profile.
**Note**
This operation is not supported by the Linux image assistant CLI tool.
**Synopsis**
```
update-default-profile
[--profile ]
```
**Options**
**`--profile` (string)**
The name of the user whose Windows profile will be copied to the Windows default user profile. Use the following format for the name:
"\$1"
If your image builder isn’t joined to a Microsoft Active Directory domain, enter a period "." for the domain. If you don’t specify a user, the WorkSpaces Applications Template User account is used.
**Message output**
| Exit code | Message printed to standard out | Description |
| --- | --- | --- |
| 0 | \$1"status": 0, "message": "Success"\$1 | The user settings were successfully copied to the default Windows profile. |
| 1 | \$1"status": 1, "message": "Administrator privileges are required to perform this operation"\$1 | Administrator privileges are required to complete the operation. |
| 1 | \$1"status": 1, "message": "Unable to copy file or folder: . "\$1 | The user settings could not be copied because a file or folder was unavailable. |
| 1 | \$1"status": 1, "message": "Cannot copy a domain user when not joined to a domain""\$1 | A Microsoft Active Directory domain user was specified, but the image builder is not joined to an Active Directory domain. |
| 255 | \$1"status": 255, "message": \$1 | An unexpected error occurred. Try the request again. If the error persists, contact AWS Support for assistance. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/). |
## `reset-user-profile` operation
Deletes the Windows user profile for the specified user.
**Note**
This operation is not supported by the Linux image assistant CLI tool.
**Synopsis**
```
reset-user-profile
[--profile ]
```
**Options**
**`--profile` (string)**
The name of the Windows user whose Windows profile will be deleted. Use the following format for the name:
"\$1"
If your image builder isn’t joined to a Microsoft Active Directory domain, enter a period "." for the domain.
**Message output**
| Exit code | Message printed to standard out | Description |
| --- | --- | --- |
| 0 | \$1"status": 0, "message": "Success"\$1 | The specified user settings were deleted successfully. |
| 1 | \$1"status": 1, "message": "Administrator privileges are required to perform this operation"\$1 | Administrator privileges are required to complete the operation. |
| 1 | \$1"status": 1, "message": "Unable to copy file or folder: . "\$1 | The user settings could not be reset because a file or folder was unavailable. |
| 1 | \$1"status": 1, "message": "Cannot copy a domain user when not joined to a domain""\$1 | A Microsoft Active Directory domain user was specified, but the image builder is not joined to an Active Directory domain. |
| 255 | \$1"status": 255, "message": \$1 | An unexpected error occurred. Try the request again. If the error persists, contact AWS Support for assistance. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/). |
## `create-image` operation
Starts the image creation workflow, resulting in an WorkSpaces Applications image that can be used for WorkSpaces Applications fleets.
**Synopsis**
```
create-image
--name
[--description ]
[--display-name ]
[--enable-dynamic-app-catalog] | [--no-enable-dynamic-app-catalog]
[--use-latest-agent-version] | [--no-use-latest-agent-version]
[--tags ]
[--dry-run]
```
**Options**
**`--name` (string)**
The name for the WorkSpaces Applications image. The name must be unique within the Amazon Web Services account and AWS Region. The maximum length is 100 characters. Allowed characters are:
a-z, A-Z, 0-9, underscores (\$1), hyphens (-), and periods (.)
The image name cannot start with any of the following prefixes: 'aws', 'appstream', and 'amazon’. These prefixes are reserved for AWS use.
**`--description` (string)**
The description to display for the image. The maximum length is 256 characters.
**`--display-name` (string)**
The name to display for the image. The maximum length is 256 characters.
**`--enable-dynamic-app-catalog` \$1 `--no-enable-dynamic-app-catalog`**
Enables or disables support for the WorkSpaces Applications dynamic application framework. If you don't specify either parameter, support for the dynamic application framework is not enabled.
The dynamic application framework provides operations within an WorkSpaces Applications streaming instance that you can use to build a dynamic app provider. Dynamic app providers can use these operations to modify the catalog of applications that your users can access in real time. For more information, see [Use the WorkSpaces Applications Dynamic Application Framework to Build a Dynamic App Provider](build-dynamic-app-provider.md).
**`--use-latest-agent-version` \$1 `--no-use-latest-agent-version`**
Specifies whether to pin the image to the version of the WorkSpaces Applications agent that is currently installed, or to always use the latest agent version. If you don't specify either parameter, the image is pinned to the version of the WorkSpaces Applications agent that is currently installed. For more information, see [Manage WorkSpaces Applications Agent Versions](base-images-agent.md).
**`--tags` (string)**
The tags to associate with the image. A tag is a key-value pair. Use the following format:
--tags "mykey" "myval" "mykey2" "myval2"
For more information about tags, see [Tagging Your Amazon WorkSpaces Applications Resources](tagging-basic.md).
**`--dry-run` (string)**
Performs validation without creating the image. Use this command to identify whether your image has any issues before you create it.
**Message output**
| Exit code | Message printed to standard out | Description |
| --- | --- | --- |
| 0 | \$1"status": 0, "message": "Success"\$1 | The workflow to create the image was initiated successfully. |
| 1 | \$1"status": 1, "message": "Administrator privileges are required to perform this operation"\$1 | Administrator privileges are required to complete the operation. |
| 1 | \$1"status": 1, "message": "An image with the given name already exists"\$1 | An image with the specified name already exists in the Amazon Web Services account. |
| 1 | \$1"status": 1, "message": "Invalid value (tags)"\$1 | The specified tags are not valid. |
| 255 | \$1"status": 255, "message": \$1 | An unexpected error occurred. Try the request again. If the error persists, contact AWS Support for assistance. For more information, see [AWS Support Center](https://console.aws.amazon.com/support/home#/). |
# Create Your Linux-Based Images
You can create Linux-based Amazon WorkSpaces Applications images by connecting to a Linux image builder, installing the applications you need, creating default application settings and environment variables, and using a command line interface (CLI) tool or Image Assistant (GUI) tool to add these applications to the application catalog. To open the GUI tool, search for **Image Assistant** in the list of applications.
**Topics**
+ [Creating Default Application Settings for Your Users](create-default-app-settings.md)
+ [Creating Default Environment Variables for Your Linux Users](create-default-variables-linux.md)
+ [Optimizing the Launch Performance of Your Linux Applications](optimize-launch-performance.md)
+ [Creating Session Scripts](create-session-scripts.md)
+ [Using the Image Assistant CLI Tool for Linux](image-assistant-cli.md)
+ [Enabling and Disabling Webcam Support](webcam-support.md)
+ [Enabling and Disabling Heavy File Sync Mode for Home Folders](heavy-file-sync.md)
+ [Tutorial: Create a Custom Linux-Based WorkSpaces Applications Image](tutorial-create-linux-image.md)
+ [Tutorial: Enable Japanese Support for Your Linux Images](enable-japanese-support-linux.md)
# Creating Default Application Settings for Your Users
Follow these steps to create default application settings for your users.
**Topics**
+ [Step 1: Install Linux Applications on the Image Builder](#app-settings-image-install)
+ [Step 2: Create a TemplateUser Account](#app-settings-template-user)
+ [Step 3: Create Default Application Settings](#app-settings-image-create-default-app-settings)
+ [Step 4: Save Default Application Settings](#app-settings-image-save-default-app-settings)
+ [Step 5: Test Default Application Settings (optional)](#app-settings-image-test-applications)
+ [Step 6: Clean Up](#app-settings-image-finish)
## Step 1: Install Linux Applications on the Image Builder
In this step, you connect a Linux image builder and install your applications on the image builder.
**To install applications on the image builder**
1. Connect to the image builder by doing either of the following:
+ [Use the WorkSpaces Applications console](managing-image-builders-connect-console.md) (for web connections only)
+ [Create a streaming URL](managing-image-builders-connect-streaming-URL.md) (for web or WorkSpaces Applications client connections)
**Note**
You will be logged in as an ImageBuilderAdmin user to the Linux GNOME desktop and have root admin privileges.
1. Install the applications that you need. For example, to install a Chromium browser from a public yum repo, first open the Terminal application, then run the following command:
**[ImageBuilderAdmin]\$1 sudo yum update && sudo yum install chromium.x86\$164**
## Step 2: Create a TemplateUser Account
In this step, you create a TemplateUser account, which creates default application settings for your streaming users.
**To create a TemplateUser Account**
1. Create a TemplateUser account that has no root permissions. For example, in a Terminal window, run the following commands to create TemplateUser on the image builder:
**[ImageBuilderAdmin]\$1 sudo useradd -m TemplateUser**
**[ImageBuilderAdmin]\$1 echo -e '<*password*>\$1n<*password*>\$1n' \$1 sudo passwd TemplateUser**
1. Switch to the TemplateUser account:
**[ImageBuilderAdmin]\$1 su - TemplateUser**
## Step 3: Create Default Application Settings
In this step, you create default application settings for your WorkSpaces Applications users. Doing this enables your users to get started with applications quickly during their WorkSpaces Applications streaming sessions, without the need to create or configure these settings themselves.
**To create default application settings for your users**
1. Launch the application that you want to create the default settings for. For example, in a Terminal window, run following command to launch Chromium browser:
**[TemplateUser]\$1 chromium-browser**
1. Configure the settings of the application. For example, set the home page of the Chromium browser as **https://aws.amazon.com**.
1. Close the applications.
1. Log out:
**[TemplateUser]\$1 logout**
## Step 4: Save Default Application Settings
In this step, you copy the default application settings you added to the **/etc/skel/** directory, and make them available to your streaming users.
**To save default application settings**
+ Run the following command in a Terminal window to copy the default application settings for your streaming users:
**[ImageBuilderAdmin]\$1 sudo cp -r -f /home/TemplateUser/. /etc/skel**
## Step 5: Test Default Application Settings (optional)
In this step, verify that the applications you've added run correctly, and the default application settings work as expected.
**To test your applications and default settings on an image builder**
1. Create a test user that has no root permissions. For example, in a **Terminal** window, run the following commands to create **test-user** on the image builder:
**[ImageBuilderAdmin]\$1 sudo useradd -m test-user**
**[ImageBuilderAdmin]\$1 echo -e '*password*>\$1n<*password*>\$1n' \$1 sudo passwd test-user**
1. Switch to the test user:
**[ImageBuilderAdmin]\$1 su - test-user**
1. Launch the application (e.g., Chromium) as the test user:
**[test-user]\$1 /usr/bin/chromium-browser**
1. Verify that the default settings are available for the test user (e.g., the Chromium home page is https://aws.amazon.com/).
1. Log out:
**[test-user]\$1 logout**
## Step 6: Clean Up
Finally, your last step is to clean up.
**To clean up**
1. Delete TemplateUser:
**[ImageBuilderAdmin]\$1 sudo killall -u TemplateUser**
**[ImageBuilderAdmin]\$1 sudo userdel -r TemplateUser**
1. Delete test-user (not required if you skipped step 5):
**[ImageBuilderAdmin]\$1 sudo killall -u test-user**
**ImageBuilderAdmin]\$1 sudo userdel -r test-user**
# Creating Default Environment Variables for Your Linux Users
You can create environment variables on a Linux Image Builder instance. Creating environment variables makes them available on streaming instances created from that image.
**Note**
On Linux fleet instances, environment variables set using the Image Assistant (GUI) tool and the default system environment variables are exported through the /etc/profile.d/appstream\$1system\$1vars.sh script. To access these environment variables, you must explicitly source the /etc/profile.d/appstream\$1system\$1vars.sh script in your applications.
**To create environment variables for your users**
1. If the folder `/etc/profile` doesn’t exist, run the following command to create it:
**[ImageBuilderAdmin]\$1 sudo mkdir -p /etc/profile.d**
1. To create a new shell script file (for example, my-environment.sh) in this folder, run the following command:
**[ImageBuilderAdmin]\$1 vim my-environment.sh**
1. On first line of the script file, add the following content:
**\$1\$1/bin/sh **
1. For each subsequent line, add an **export** command to set the environment variables for your image. The following example adds `$HOME/bin` to the `PATH` variable:
**export PATH=”\$1HOME/bin:\$1PATH”**
1. Press the **Esc** key to return to command mode in vim, then run the following command to save your script and exit vim:
**:x**
1. Run the following command to allow the script to run as a program:
**[ImageBuilderAdmin]\$1 chmod \$1x my-environment.sh**
# Optimizing the Launch Performance of Your Linux Applications
If you are using the Image Assistant GUI tool, the tool optimizes launch performance for your applications automatically.
If you are using the Image Assistant CLI, use the following steps to optimize launch performance manually. When you create and add files to an application optimization manifest, the application will launch faster when first started on a new fleet instance. However, this also increases the time that it takes for the fleet instances to be made available to users. The optimization manifest is one line-delimited text file for every application.
You can create a manifest file (such as <*your-app*>-manifest.txt) either manually or by following with the steps below.
**To create a manifest file**
1. Make sure that the application that you are trying to optimize is launched and running.
1. From a terminal in the Linux image builder, run the following command:
**ps -ef \$1 grep <*application-process-name*>**
1. Search for the smallest PID number from the last step's output. This is the PID for the root parent process of the application.
1. Keep the application running and make sure to use the initial components required by your users. This ensures that these components are captured by the optimization process.
1. Create a script file (e.g., `~/getfilestool.sh`) with the following content:
```
#!/bin/bash
## usage getfilestool.sh $pid
lsof -p $(pstree -p $1 | grep -o '([0-9]\+)' | grep -o '[0-9]\+' | tr '\012' ,)|grep REG | sed -n '1!p' | awk '{print $9}'|awk 'NF'
```
1. Make sure that the file can be run with the following command:
**[ImageBuilderAdmin]\$1 chmod u\$1x \$1/getfilestool.sh**
1. Run the following command to capture all of the running files from the root parent process found in step 3, and save it to a temporary manifest file.
**[ImageBuilderAdmin]\$1 sudo \$1/getfilestool.sh <*root-parent-pid*> > /tmp/-manifest.txt **
1. Verify the content of the optimization manifest, which is a line-delimited text file for every application.
You can specify the optimization manifest on a per-application basis by using the Image Assistant command line interface (CLI) tool. For more information, see [Using the Image Assistant CLI Tool for Linux](image-assistant-cli.md).
# Creating Session Scripts
WorkSpaces Applications provides on-instance session scripts on both Windows- and Linux-based streaming instances. For more information about session scripts, see [Use Session Scripts to Manage Your Amazon WorkSpaces Applications Users' Streaming Experience](use-session-scripts.md).
Session scripts are specified within an WorkSpaces Applications image. To locate the session scripts configuration file on a Linux instance, navigate to `/opt/appstream/SessionScripts/config.json`. The following code is a sample `config.json` file that specifies a session start script named “`test-session-start`” and a session end script named “`test-session-stop`” together with their runtime parameters. Make sure that the scripts referenced in `config.json` have run permissions and a command interpreter is defined (for example, \$1\$1/bin/bash).
```
{
"SessionStart": {
"Executables": [
{
"Context": "system",
"Filename": "/opt/appstream/SessionScripts/test-session-start",
"Arguments": "arg1",
"S3LogEnabled": true
}
],
"WaitingTime": 30
},
"SessionTermination": {
"Executables": [
{
"Context": "system",
"Filename": "/opt/appstream/SessionScripts/test-session-stop",
"Arguments": "arg2",
"S3LogEnabled": true
}
],
"WaitingTime": 30
}
}
```
# Using the Image Assistant CLI Tool for Linux
On a Linux-based image builder, you can use the Image Assistant CLI tool **AppStreamImageAssistant** to create and manage your WorkSpaces Applications image. The tool is located at `/usr/local/appstream/image-assistant/AppStreamImageAssistant` with a symbolic link at `/bin/AppStreamImageAssistant`. This CLI tool for Linux supports many of the same operations as the Image Assistant CLI tool for Windows. For more information on these operations, see [Image Assistant CLI Operations for Creating and Managing Your Amazon WorkSpaces Applications Image](cli-operations-managing-creating-image-image-assistant.md).
# Enabling and Disabling Webcam Support
WorkSpaces Applications supports real-time audio-video (AV) by redirecting local webcam video input to WorkSpaces Applications streaming sessions. This capability enables your users to use their local webcam for video and audio conferencing within an WorkSpaces Applications streaming session. With real-time AV and support for real-time audio, your users can collaborate by using familiar video and audio conferencing applications without having to leave their WorkSpaces Applications streaming session.
To use this feature, you must use a Linux WorkSpaces Applications image that uses a Linux WorkSpaces Applications agent released on or after September 21, 2022.
**Note**
Real-time AV is not supported for stream.standard.small instances powered by Rocky Linux or Red Hat Enterprise Linux. Users don't see the Camera and Mic icons on the client toolbar.
The real-time AV feature is enabled by default for Linux streaming sessions. To configure webcam permissions for your users on a Linux image builder, create `/etc/appstream/appstream.conf` and add the following contents:
**Note**
Specify **1** to enable webcam, or **0** to disable webcam.
```
[webcam]
permission = 1
```
# Enabling and Disabling Heavy File Sync Mode for Home Folders
You can enable Amazon Simple Storage Service Home Folders options for your organization. When you enable Amazon S3 Home Folders for an WorkSpaces Applications stack, users of the stack can access a persistent storage folder during their application streaming sessions. No further configuration is required for your users to access their home folder. Data stored by users in their home folder is automatically backed up to an Amazon S3 bucket in your AWS account, and is made available to those users in subsequent sessions. For more information, see [Enable and Administer Home Folders for Your WorkSpaces Applications Users](home-folders.md).
To ensure a smooth experience and address some existing limitations, where an inconsistent file sync might be observed when users save large text files from their streaming instances to their Home Folders, WorkSpaces Applications administrators can turn on the **heavy\$1sync** configuration option if large file uploads to Amazon S3 is a common user scenario while using WorkSpaces Applications. Turning on this option means that it might add some latency to the home folder file sync process, but completeness of all syncs to Amazon S3 is guaranteed.
This feature is available on all Red Hat Enterprise Linux images, and Linux WorkSpaces Applications images that use a Linux WorkSpaces Applications agent released on or after September 12, 2024.
The heavy sync feature is disabled by default for Red Hat Enterprise Linux and Rocky Linux streaming sessions. To configure heavy sync permission for your users on a Red Hat Enterprise Linux or Rocky Linux image builder, create `/etc/appstream/appstream.conf` and add the following contents:
**Note**
Specify **1** to enable heavy sync, or **0** to disable heavy sync.
```
[storage]
heavy_sync = 1
```
# Tutorial: Create a Custom Linux-Based WorkSpaces Applications Image
This tutorial describes how to create a custom Linux-based Amazon WorkSpaces Applications image that contains applications which you can stream to your users.
**Important**
Don't create a user named "as2-streaming-user" in your image builder. This is a reserved username for Fleet. If you create this username outside of the WorkSpaces Applications workflow, you might experience streaming issues in Fleets.
**Topics**
+ [Step 1: Install Linux Applications on the Image Builder](#tutorial-linux-image-install)
+ [Step 2: Generate Application Optimization Manifest File](#tutorial-linux-image-manifest)
+ [Step 3: Create an WorkSpaces Applications Application Catalog](#tutorial-linux-image-catalog)
+ [Step 4: Create Default Application Settings and Environment Variables](#tutorial-linux-image-create-default-app-settings)
+ [Step 5: Test Applications and Settings](#tutorial-linux-image-test-applications)
+ [Step 6: Finish Creating Your Image](#tutorial-linux-image-finish-create-image)
+ [Step 7 (Optional): Tag and Copy an Image](#tutorial-linux-image-tag-copy)
+ [Step 8: Clean Up](#tutorial-linux-image-finish)
## Step 1: Install Linux Applications on the Image Builder
In this step, you connect a Linux image builder and install your applications on the image builder.
**To install applications on the image builder**
1. Connect to the image builder by doing either of the following:
+ [Use the WorkSpaces Applications console](managing-image-builders-connect-console.md) (for web connections only)
+ [Create a streaming URL](managing-image-builders-connect-streaming-URL.md) (for web or WorkSpaces Applications client connections)
**Note**
You will be logged in as an ImageBuilderAdmin user to the Linux GNOME desktop and have root admin privileges.
1. Install the applications that you need. For example, to install a Chromium browser from a public yum repo, first open the Terminal application, then run the following command:
**[ImageBuilderAdmin]\$1 sudo yum update && sudo yum install chromium.x86\$164**
**Note**
Download and install applications only from sites that you trust.
## Step 2: Generate Application Optimization Manifest File
In this step, you generate a manifest file for each application you installed in step 1.
**To generate a manifest file for optimizing the launch performance of an application**
1. Make sure the application (e.g., Chromium) that you are trying to optimize is launched and running.
1. In a Terminal window, run the following command to list processes related to the application:
**[ImageBuilderAdmin]\$1 ps -ef \$1 grep chromium **
1. Find the root parent PID from the output of the command above. The following is an example output, and the root parent PID is 16712:
**Example**
```
[ImageBuilderAdmin]$ ps -ef | grep chromium
ImageBu+ 16712 4128 0 Aug26 ? 00:00:44 /usr/lib64/chromium- browser/chromium-browser --enable-plugins --enable-extensions -- enable-user- scripts --enable-printing --enable-gpu-rasterization -- enable-sync --auto-ssl- client-auth
ImageBu+ 16726 16712 0 Aug26 ? 00:00:00 /usr/lib64/chromium- browser/chromium-browser --type=zygote --no-zygote-sandbox ImageBu+ 16727 16712 0 Aug26 ? 00:00:00 /usr/lib64/chromium- browser/chromium- browser --type=zygote
ImageBu+ 16731 16727 0 Aug26 ? 00:00:00 /usr/lib64/chromium- browser/chromium-browser --type=zygot
```
1. Keep the application running and make sure to use the initial components required by your users. This ensures that these components are captured by the optimization process.
1. Create script file (e.g., `~/getfilestool.sh`) with the following content:
```
#!/bin/bash
## usage getfilestool.sh $pid
lsof -p $(pstree -p $1 | grep -o '([0-9]\+)' | grep -o '[0-9]\+' | tr '\012' ,)|grep REG | sed -n '1!p' | awk '{print $9}'|awk 'NF'
```
1. Verify that the file can be run by running the following command:
**[ImageBuilderAdmin]\$1 chmod u\$1x \$1/getfilestool.sh**
1. Run the following command to capture all running files from the root parent process found in step 3 above, and save it to a temporary manifest file:
**[ImageBuilderAdmin]\$1 sudo \$1/getfilestool.sh 16712 > /tmp/chromium-manifest.txt **
1. Verify the content of the optimization manifest, which is a line-delimited text file for each application.
## Step 3: Create an WorkSpaces Applications Application Catalog
In this step, you use the CLI tool `AppStreamImageAssistant` on the image builder to create an WorkSpaces Applications application catalog by specifying applications for your image. For each application that you plan to stream, you can specify the name, display name, executable file to launch, and icon to display.
**To create an WorkSpaces Applications application catalog**
1. From the image builder desktop, open **Terminal** either from the side panel or by opening the app grid.
1. Run **AppStreamImageAssistant --help** to see the list of available commands. You will use these commands to add applications and create an Image.
1. Run the following command to add an installed application (e.g., Chromium) to the application list for WorkSpaces Applications users:
```
AppStreamImageAssistant add-application \
--name Chromium \
--absolute-app-path /usr/lib64/chromium-browser/chromium-browser \
--display-name Chromium \
--absolute-icon-path /usr/share/icons/hicolor/256x256/apps/chromium-browser.png \
--absolute-manifest-path /tmp/chromium-manifest.txt
```
Alternatively, run the following command:
```
AppStreamImageAssistant add-application \
--name="Chromium" \
--absolute-app-path="/usr/lib64/chromium-browser/chromium-browser" \
--display-name="Chromium" \
--absolute-icon-path="/usr/share/icons/hicolor/256x256/apps/chromium-browser.png" \
--absolute-manifest-path="/tmp/chromium-manifest.txt"
```
1. To add more applications, repeat step 3 for each additional application.
1. To see the list of applications that have been added in the catalog, along with metadata like icon paths and launch parameters, run the following command:
**AppStreamImageAssistant list-applications**
1. To remove applications from the catalog, run the following command:
**AppStreamImageAssistant remove-application –-name *application\$1name***
## Step 4: Create Default Application Settings and Environment Variables
In this step, you create default application settings and environment variables for your WorkSpaces Applications users. Doing this enables your users to get started with applications quickly during their WorkSpaces Applications streaming sessions, without the need to create or configure these settings themselves.
**To create default application and environment variables for your users**
1. Launch the application that you want create the default settings for. For example, in a Terminal window, run following command to launch Chromium browser:
**[ImageBuilderAdmin]\$1 chromium-browser**
1. Configure the settings of the application. For example, set the home page of the Chromium browser as **https://aws.amazon.com**.
1. Make sure the Chromium application is closed, and then run the following commands to copy the configuration for Chromium to **/etc/skel**:
**[ImageBuilderAdmin]\$1 sudo mkdir /etc/skel/.config**
**[ImageBuilderAdmin]\$1 sudo cp -R \$1/.config/chromium /etc/skel/.config**
1. Set the environment variables and add it to the script file. For example, run the following commands:
**[ImageBuilderAdmin]\$1 echo "export *FOO*=*BAR*" \$1 sudo tee -a /etc/profile.d/myenvvars.sh**
**[ImageBuilderAdmin]\$1 sudo chmod \$1x /etc/profile.d/myenvvars.sh**
## Step 5: Test Applications and Settings
In this step, verify that the applications you've added run correctly, and the default application settings and environment variables work as expected.
**To test your applications and default settings on an image builder**
1. Create a test user that has no root permissions. For example, in a **Terminal** window, run the following commands to create **test-user** on the image builder:
**[ImageBuilderAdmin]\$1 sudo useradd -m test-user**
**[ImageBuilderAdmin]\$1 echo -e 'Pa55w0rdas2\$1\$1\$1\$1nPa55w0rdas2\$1\$1\$1\$1n' \$1 sudo passwd test-user**
1. Switch to the test user:
**[ImageBuilderAdmin]\$1 su - test-user**
1. Launch the application (e.g., Chromium) as the test user:
**[test-user]\$1 /usr/bin/chromium-browser**
1. Verify that the default settings are available for the test user (e.g., the Chromium home page is https://aws.amazon.com/).
1. Verify that the environment variables are available for the test user. For example, run the following command:
**[test-user]\$1 echo \$1*FOO***
This command should display the output ***BAR*** in the terminal.
1. Run the following commands to delete the test user before creating an image from this image builder:
**\$1 logout test user**
**[test-user]\$1 logout**
**\$1 kill test user's running processes**
**[ImageBuilderAdmin]\$1 sudo killall -u test-user**
**\$1 delete user**
**[ImageBuilderAdmin]\$1 sudo userdel -r test-user**
## Step 6: Finish Creating Your Image
In this step, choose an image name and finish creating your image.
**To create the image**
1. In a **Terminal** window, create an image from your Image Builder by running **AppStreamImageAssistant create-image**. This image contains your installed and registered applications, plus any session scripts and default application settings that you have configured.
To see the list of available options, run **AppStreamImageAssistant create-image --help**. For more information, see the **create-image** operation in [Create Your Amazon WorkSpaces Applications Image Programmatically by Using the Image Assistant CLI Operations](programmatically-create-image.md).
1. The remote session disconnects after a few moments. When the **Lost Connectivity** message appears, close the browser tab. While the image is created, the image builder status appears as **Snapshotting**. You cannot connect to the image builder until this process finishes.
1. Return to the console and navigate to **Images**, **Image Registry**. Verify that your new image appears in the list.
While your image is being created, the image status in the image registry of the console appears as **Pending**. You can't connect to images that are in a **Pending** status.
1. Choose the **Refresh** icon to update the status. After your image is created, the image status changes to **Available** and the image builder is automatically stopped.
To continue creating images, start the image builder and connect to it from the console, or create a new image builder.
## Step 7 (Optional): Tag and Copy an Image
You can add one or more tags to an image during image creation or after you create an image. You can also copy the image within the same Region or to a new Region within the same Amazon Web Services account. Copying a source image results in an identical but distinct destination image. AWS does not copy any user-defined tags, however. Also, you can only copy custom images that you create, not the base images that are provided by AWS.
**Note**
You can copy up to two images at the same time to a destination. If the destination to which you are copying an image is at the image limit, you receive an error. To copy the image in this case, you must first remove images from the destination. After the destination is below the image quota (also referred to as limit), initiate the image copy from the source Region. For more information, see [Amazon WorkSpaces Applications Service Quotas](limits.md).
**To add tags to an existing image**
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, select the image to which you want to add tags.
1. Choose **Tags**, choose **Add/Edit Tags**, and then choose **Add Tag**. Specify the key and value for the tag, and then choose **Save**.
For more information, see [Tagging Your Amazon WorkSpaces Applications Resources](tagging-basic.md).
**To copy an image**
Copying an image across geographically diverse regions enables you to stream applications from multiple regions based on the same image. By streaming your applications in closer proximity to your users, you can improve your users' experience streaming applications with WorkSpaces Applications.
1. In the navigation pane, choose **Images**, **Image Registry**.
1. In the image list, select the image that you want to copy.
1. Choose **Actions**, **Copy**.
1. In the **Copy Image** dialog box, specify the following information, and then choose **Copy Image**:
+ For **Destination region**, choose the region to which to copy the new image.
+ For **Name**, specify a name that the image will have when it is copied to the destination.
+ For **Description** (optional), specify a description that the image will have when it is copied to the destination.
1. To check on the progress of the copy operation, return to the console and navigate to **Images**, **Image Registry**. Use the navigation bar to switch to the destination region (if applicable), and confirm that your new image appears in the list of images.
The new image first appears with a status of **Copying** in the image registry of your console. After the image is successfully created, the status of the image changes to **Available**, which means that you can use the image to launch a stack and stream your applications.
## Step 8: Clean Up
Finally, you can stop your running image builders to free up resources and avoid unintended charges to your account. We recommend stopping any unused, running image builders. For more information, see [WorkSpaces Applications Pricing](https://aws.amazon.com/appstream2/pricing/).
**To stop a running image builder**
1. In the navigation pane, choose **Images**, **Image Builders**, and select the running image builder instance.
1. Choose **Actions**, **Stop**.
# Tutorial: Enable Japanese Support for Your Linux Images
This tutorial describes how to enable Japanese support for a Linux image. This enables applications on the image to display Japanese characters, and streaming users to use the Japanese input method in the streaming sessions from the image.
**Topics**
+ [Step 1: Install Japanese Font and Input Method](#tutorial-japanese-font)
+ [Step 2: Set the System Time Zone](#tutorial-japanese-zone)
+ [Step 3: Set the System Locale and Display Language](#tutorial-japanese-locale)
+ [Step 4: Configure the Input Methods](#tutorial-japanese-input)
+ [Step 5: Set the Keyboard Layout](#tutorial-japense-keyboard)
+ [Step 6: Verify on Image Builder](#tutorial-japense-verify)
+ [Step 7: Create the Image](#tutorial-japanese-create)
## Step 1: Install Japanese Font and Input Method
In this step, you connect a Linux image builder and install the font and input method packages of your choice.
**To install Japanese font and input method**
1. Connect to the image builder by doing either of the following:
+ [Use the WorkSpaces Applications console](managing-image-builders-connect-console.md) (for web connections only)
+ [Create a streaming URL](managing-image-builders-connect-streaming-URL.md) (for web or WorkSpaces Applications client connections)
**Note**
You will be logged in as an ImageBuilderAdmin user to the Linux GNOME desktop and have root admin privileges.
1. Install the font and input method that you need. To do this, open the Terminal application, then run the following commands:
**sudo yum install vlgothic-p-fonts.noarch**
**sudo yum install ibus-kkc.x86\$164**
1. In addition to the above commands, for Rocky Linux and Red Hat Enterprise Linux, run the following command:
**sudo yum install glibc-langpack-ja**
## Step 2: Set the System Time Zone
To set the system time zone, run the following command:
**sudo timedatectl set-timezone "Asia/Tokyo"**
## Step 3: Set the System Locale and Display Language
To set the system locale and display language, run the following commands.
**To set the system locale and display language**
1. Update the `cloud-init config` file by running the command **sudo vim /etc/cloud/cloud.cfg**, and change **locale** to **locale: ja\$1JP.utf8**, then save and close the file.
1. Update the system settings by running **sudo localectl set-locale LANG=ja\$1JP.utf8**.
1. Update the Gnome shell settings by running **sudo gsettings set org.gnome.system.locale region "ja\$1JP.utf8"**.
## Step 4: Configure the Input Methods
Configure the input methods for the application you want to add to the image. For more information about how install an application, generate a manifest file, and create default settings, see [Tutorial: Create a Custom Linux-Based WorkSpaces Applications Image](tutorial-create-linux-image.md). In this step, we assume that you’ve already installed the application Firefox, which is located at `/usr/local/firefox/firefox`.
**To configure the input methods**
1. Create a script by running the command **sudo vim /usr/local/bin/update-input-method.sh**, and add the following content to the script:
```
#!/bin/bash
function start_process()
{
command=$1
process_name=$2
process_count=$(pgrep $process_name -c)
echo "$(date) current $process_name count: $process_count"
while [ $process_count -lt 1 ]
do
echo "$(date) starting $process_name"
eval $command
sleep 1
process_count=$(pgrep $process_name -c)
done
echo "$(date) $process_name started"
}
start_process "ibus-daemon --xim &" "ibus-daemon"
start_process "/usr/libexec/ibus-engine-kkc --ibus &" "ibus-engine-kkc"
gsettings set org.gnome.desktop.input-sources sources "[('ibus','kkc'), ('xkb', 'us')]"
gsettings set org.gnome.desktop.wm.keybindings switch-input-source "['space']"
gsettings set org.gnome.desktop.wm.keybindings switch-input-source-backward "['space']"
echo "$(date) updated input source and switch shortcut"
```
In the script above, the first input source (‘ibus’, ‘kkc’) is the default input method. You can change the default input method by changing the order of input sources. In addition, “Control\$1Space” and “Shift\$1Control\$1Space” are specified as shortcut key combinations for switching between input methods. You can specify your own key combinations that your users can use to switch input methods during streaming sessions.
1. Create the script for launching the application (Firefox) that you will add to the image. To do this, run the command **sudo vim /usr/local/bin/firefox-jp.sh**, then add the following content to the script:
```
#!/bin/bash
# Gather required environment variables from the GNOME shell session
while IFS= read -r -d $'\0' env_var; do
case "$env_var" in
DBUS_SESSION_BUS_ADDRESS=*|\
GTK_IM_MODULE=*|\
QT_IM_MODULE=*|\
XMODIFIERS=*|\
XAUTHORITY=*)
echo "$env_var"
export "$env_var"
;;
esac
done < "/proc/$(pgrep -u as2-streaming-user gnome-shell | head -n1)/environ"
/usr/local/bin/update-input-method.sh > /var/tmp/update-input-method.log 2>&1 &
/usr/local/firefox/firefox &
```
1. Add run permission to both scripts by running following the commands:
**sudo chmod \$1x /usr/local/bin/update-input-method.sh**
**sudo chmod \$1x /usr/local/bin/firefox-jp.sh**
1. If you already created the optimization manifest file for the application run the following commands to add the application launch script to the application catalog:
```
sudo AppStreamImageAssistant add-application \
--name firefox \
--absolute-app-path /usr/local/bin/firefox-jp.sh \
--display-name firefox \
--absolute-icon-path /usr/local/firefox/browser/chrome/icons/default/default128.png \
--absolute-manifest-path /tmp/firefox-manifest.txt
```
Alternatively, you can also configure the input methods by adding the script update-input-method.sh as a separate application to the application catalog for the image. During streaming sessions, your users can launch this application to enable Japanese input, and switch between input methods with specified shortcut keys within the same session.
## Step 5: Set the Keyboard Layout
Set the keyboard layout to match the keyboards your users will use during streaming sessions. You can use the command **localectl list-keymaps** to list all the available keymaps, and use the command **sudo localectl set-keymap jp106** to set the keymap to the Japanese keyboard of 106 keys, for example.
## Step 6: Verify on Image Builder
To verify on image builder, first reboot the image builder by running the command **sudo shutdown -r now**. After reboot, connect to the image builder again, and verify that everything, including time zone, locale, language, and input method, works as expected.
## Step 7: Create the Image
Create the image on the image builder. For more information, see [Tutorial: Create a Custom Linux-Based WorkSpaces Applications Image](tutorial-create-linux-image.md). Make sure to create default application settings, including the regional settings you just configured. For more information, see "Creating Default Application Settings for Your Users" in [Create Your Linux-Based Images](create-linux-based-images.md).
All of the Linux fleet instances created from this image will have the same default time zone, locale, language, and input method settings that you configured for the image.
# Use Session Scripts to Manage Your Amazon WorkSpaces Applications Users' Streaming Experience
WorkSpaces Applications provides on-instance session scripts. You can use these scripts to run your own custom scripts when specific events occur in users' streaming sessions. For example, you can use custom scripts to prepare your WorkSpaces Applications environment before your users' streaming sessions begin. You can also use custom scripts to clean up streaming instances after users complete their streaming sessions.
Session scripts are specified within an WorkSpaces Applications image. These scripts are run within the user context or the system context. If your session scripts use the standard out to write information, error, or debugging messaging, these can be optionally saved to an Amazon S3 bucket within your Amazon Web Services account.
**Topics**
+ [Run Scripts Before Streaming Sessions Begin](run-scripts-before-streaming-sessions-begin.md)
+ [Run Scripts After Streaming Sessions End](run-scripts-after-streaming-sessions-end.md)
+ [Create and Specify Session Scripts](create-specify-session-scripts.md)
+ [Session Scripts Configuration File](session-script-configuration-file.md)
+ [Using Windows PowerShell Files](using-powershell-files-with-session-scripts.md)
+ [Logging Session Script Output](logging-session-output.md)
+ [Use Storage Connectors with Session Scripts](use-storage-connectors-with-session-scripts.md)
+ [Enable Amazon S3 Bucket Storage for Session Script Logs](enable-S3-bucket-storage-session-script-logs.md)
+ [Use Session Scripts on Multi-Session Fleets](session-scripts-multi-session-fleets.md)
# Run Scripts Before Streaming Sessions Begin
You can configure your scripts to run for a maximum of 60 seconds before your users' applications launch and their streaming sessions begin. Doing so enables you to customize the WorkSpaces Applications environment before users start streaming their applications. When the session scripts run, a loading spinner displays for your users. When your scripts complete successfully or the maximum waiting time elapses, your users' streaming session will begin. If your scripts don't complete successfully, an error message displays for your users. However, your users are not prevented from using their streaming session.
When you specify a file name on a Windows instance, you must use a double backslash. For example:
C:\$1\$1Scripts\$1\$1Myscript.bat
If you don't use a double backslash, an error displays to notify you that the .json file is incorrectly formatted.
**Note**
When your scripts complete successfully, they must return a value of 0. If your scripts return a value other than 0, WorkSpaces Applications displays the error message to the user.
When you run scripts before streaming sessions begin and the WorkSpaces Applications dynamic application framework is not enabled, the following process occurs:
![\[WorkSpaces Applications workflow diagram showing connection, application selection, and session launch steps.\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/images/session-scripts-without-DAF-non-domain-joined2.png)
1. Your users connect to an WorkSpaces Applications fleet instance that is not domain-joined. They connect by using one of the following access methods:
+ WorkSpaces Applications user pool
+ SAML 2.0
+ WorkSpaces Applications API
1. The application catalog displays in the WorkSpaces Applications portal, and your users choose an application to launch.
1. One of the following occurs:
+ If application settings persistence is enabled for your users, the application settings Virtual Hard Disk (VHD) file that stores your users' customizations and Windows settings is downloaded and mounted. Windows user login is required in this case.
For information about application settings persistence, see [Enable Application Settings Persistence for Your WorkSpaces Applications Users](app-settings-persistence.md).
+ If application settings persistence is not enabled, the Windows user is already logged in.
1. Your session scripts start. If persistent storage is enabled for your users, storage connector mounting also starts. For information about persistent storage, see [Enable and Administer Persistent Storage for Your WorkSpaces Applications Users](persistent-storage.md).
**Note**
The storage connector mount doesn't need to complete for the streaming session to start. If the session scripts complete before the storage connector mount completes, the streaming session starts.
For information about monitoring the mount status of storage connectors, see [Use Storage Connectors with Session Scripts](use-storage-connectors-with-session-scripts.md).
1. Your session scripts complete or time out.
1. The users' streaming session starts.
1. The application that your users chose launches.
For information about the WorkSpaces Applications dynamic application framework, see [Use the WorkSpaces Applications Dynamic Application Framework to Build a Dynamic App Provider](build-dynamic-app-provider.md).
When you run scripts before streaming sessions begin and the WorkSpaces Applications dynamic application framework is enabled, the following process occurs:
![\[WorkSpaces Applications workflow from user login to application launch, including SAML authentication and session scripts.\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/images/session-scripts-with-DAF-domain-joined2.png)
1. Your users visit the SAML 2.0 application portal for your organization, and they choose the WorkSpaces Applications stack.
1. They connect to an WorkSpaces Applications fleet instance that is domain-joined.
1. If application settings persistence is enabled for your users, the application settings VHD file that stores your users' customizations and Windows settings is downloaded and mounted.
1. Windows user logon occurs.
1. The application catalog displays in the WorkSpaces Applications portal and your users choose an application to launch.
1. Your session scripts start. If persistent storage is enabled for your users, storage connector mounting also starts.
**Note**
The storage connector mount doesn't need to complete for the streaming session to start. If the session scripts complete before the storage connector mount completes, the streaming session starts.
For information about monitoring the mount status of storage connectors, see [Use Storage Connectors with Session Scripts](use-storage-connectors-with-session-scripts.md).
1. Your session scripts complete or time out.
1. The users' streaming session starts.
1. The application that your users chose launches.
# Run Scripts After Streaming Sessions End
You can also configure your scripts to run after users' streaming sessions end. For example, you can run a script when users select **End Session** from the WorkSpaces Applications toolbar, or when they reach the maximum allowed duration for the session. You can also use these session scripts to clean up your WorkSpaces Applications environment before a streaming instance is terminated. For example, you can use scripts to release file locks or upload log files. When you run scripts after streaming sessions end, the following process occurs:
![\[Flowchart showing WorkSpaces Applications session termination process with scripts and storage actions.\]](http://docs.aws.amazon.com/appstream2/latest/developerguide/images/session-scripts-termination.png)
1. Your users' WorkSpaces Applications streaming session ends.
1. Your session termination scripts start.
1. The session termination scripts complete or time out.
1. Windows user logout occurs.
1. One or both of the following occur in parallel, if applicable:
+ If application settings persistence is enabled for your users, the application settings VHD file that stores your users' customizations and Windows settings is unmounted and uploaded to an Amazon S3 bucket in your account.
+ If persistent storage is enabled for your users, the storage connector completes a final synchronization and is unmounted.
1. The fleet instance is terminated.
# Create and Specify Session Scripts
You can configure and specify session scripts for Always-on, On-demand, and Elastic fleets.
**To configure and specify session scripts for Always-on and On-demand fleets**
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the navigation pane, choose **Images**, **Image Builder**.
1. Choose an image builder that is in the **Running** state, and choose **Connect**.
1. When prompted, choose **Administrator**.
1. Navigate to `C:\AppStream\SessionScripts`, and open the `config.json` configuration file.
For information about session script parameters, see [Session Scripts Configuration File](session-script-configuration-file.md).
1. After you finish making your changes, save and close the `config.json` file.
1. On the image builder desktop, open **Image Assistant**.
1. (Optional) Specify any additional applications that you want to include in the image.
1. Follow the necessary steps in Image Assistant to finish creating your image.
If the session scripts configuration can't be validated (for example, if the .json file is not correctly formatted), you are notified when you choose **Disconnect and create image**.
**Note**
To locate the session scripts configuration file for Linux-based image builders, navigate to `/opt/appstream/SessionScripts/config.json`.
**To configure and specify session scripts for Elastic fleets**
1. Create a zip file that contains the session scripts and config.json file. The scripts files will be copied to the following locations. You must use these locations for your config.json.
+ For Windows, use `C:\AppStream\SessionScripts\SessionScript`.
+ For Linux, use `/opt/appstream/SessionScripts/SessionScript`.
**Note**
In order to run the session script files, make sure that the .zip file only contains the session scripts and `config.json` files, and not the containing folder. For more information, see [Session Scripts Configuration File](session-script-configuration-file.md).
1. Upload the zip file to an Amazon S3 bucket in your account.
**Note**
Your VPC must provide access to the Amazon S3 bucket. For more information, see [Using Amazon S3 VPC Endpoints for WorkSpaces Applications Features](managing-network-vpce-iam-policy.md).
You must have your S3 bucket and WorkSpaces Applications fleet in the same AWS Region.
You must have IAM permissions to perform the `S3:GetObject` action on the session scripts object in the Amazon S3 bucket. To learn more about storing the session scripts in an Amazon S3 bucket, see [Store Application Icon, Setup Script, Session Script, and VHD in an S3 Bucket](store-s3-bucket.md).
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the navigation pane, choose **Fleets**.
1. Choose an Elastic fleet that you want to update, and then choose **View Details**.
1. On the **Session scripts settings** tab, choose **Edit**.
1. For **Session scripts object in S3**, either enter the S3 URI that represents the session scripts object, or choose **Browse S3** to navigate to your S3 buckets and find the session scripts object.
1. After you finish making your changes, choose **Save Changes**.
1. At this point, session scripts are available for all fleet instances launched.
**Note**
You can also configure the session scripts when you create a new Elastic fleet.
# Session Scripts Configuration File
To locate the session scripts configuration file in a Windows instance, navigate to C:\$1AppStream\$1SessionScripts\$1config.json. On a Linux instance, navigate to /opt/appstream/SessionScripts/config.json. The file is formatted as follows.
**Note**
The configuration file is in .json format. Verify that any text you type in this file is in valid .json format.
```
{
"SessionStart": {
"executables": [
{
"context": "system",
"filename": "",
"arguments": "",
"s3LogEnabled": true
},
{
"context": "user",
"filename": "",
"arguments": "",
"s3LogEnabled": true
}
],
"waitingTime": 30
},
"SessionTermination": {
"executables": [
{
"context": "system",
"filename": "",
"arguments": "",
"s3LogEnabled": true
},
{
"context": "user",
"filename": "",
"arguments": "",
"s3LogEnabled": true
}
],
"waitingTime": 30
}
}
```
You can use the following parameters in the session scripts configuration file.
***SessionStart/SessionTermination ***
The session scripts to run in the appropriate session event based on the name of the object.
**Type**: String
**Required**: No
**Allowed values:** **SessionStart**, **SessionTermination**
***WaitingTime***
The maximum duration of the session scripts in seconds.
**Type**: Integer
**Required**: No
**Constraints:** The maximum duration is 60 seconds. If the session scripts don't complete within this duration, they will be stopped. If you require a script to continue running, launch it as a separate process.
***Executables***
The details for the session scripts to run.
**Type**: String
**Required**: Yes
**Constraints:** The maximum number of scripts that can run per session event is 2 (one for the user context, one for the system context).
***Context***
The context in which to run the session script.
**Type**: String
**Required**: Yes
**Allowed values:** **user**, **system**
***Filename***
The full path to the session script to run. If this parameter is not specified, the session script is not run.
**Type**: String
**Required**: No
**Constraints:** The maximum length for the file name and full path is 1,000 characters.
**Allowed values:** **.bat**, **.exe**, **.sh**
You can also use Windows PowerShell files. For more information, see [Using Windows PowerShell Files](using-powershell-files-with-session-scripts.md).
***Arguments***
The arguments for your session script or executable file.
**Type**: String
**Required**: No
**Length constraints:** The maximum length is 1,000 characters.
***S3LogEnabled***
When the value for this parameter is set to **True**, an S3 bucket is created within your Amazon Web Services account to store the logs created by the session script. By default, this value is set to **True**. For more information, see the *Logging Session Script Output* section later in this topic.
**Type**: Boolean
**Required**: No
**Allowed values:** **True**, **False**
# Using Windows PowerShell Files
To use Windows PowerShell files, specify the full path to the PowerShell file in the **filename** parameter:
```
"filename":
"C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
```
Then specify your session script in the **arguments** parameter:
```
"arguments": "-File \"C:\\path\\to\\session\\script.ps1\"",
```
Finally, verify that the PowerShell Execution Policy allows your PowerShell file to run.
# Logging Session Script Output
When this option is enabled in the configuration file, WorkSpaces Applications automatically captures the output from the session script that is written to the standard out. This output is uploaded to an Amazon S3 bucket in your account. You can review the log files for troubleshooting or debugging purposes.
**Note**
The log files are uploaded when the session script returns a value, or the value set in **WaitingTime** has elapsed, whichever comes first.
# Use Storage Connectors with Session Scripts
When WorkSpaces Applications storage connectors are enabled, they begin mounting when the session start scripts run. If your script relies on the storage connectors being mounted, you can wait for the connectors to be available. WorkSpaces Applications maintains the mount status of the storage connectors in the Windows registry on Windows instances, at the following key:
HKEY\$1LOCAL\$1MACHINE\$1SOFTWARE\$1Amazon\$1AppStream\$1Storage\$1\$1
The registry key values are as follows:
+ Provided user name — The user ID provided through the access mode. The access modes and value for each mode are as follows:
+ User Pool — The email address for the user
+ Streaming URL — The UserID
+ SAML — The NameID. If the user name includes a slash (for example, a domain user’s SAMAccountName), the slash is replaced by a "-" character.
+ Storage connector — The connector for the persistent storage option that is enabled for the user. The storage connector values are as follows:
+ HomeFolder
+ GoogleDrive
+ OneDrive
Each storage connector registry key contains a **MountStatus** DWORD value. The following table lists the possible values for **MountStatus**.
**Note**
To view these registry keys, you must have Microsoft .NET Framework version 4.7.2 or later installed on your image.
| Value | Description |
| --- | --- |
| 0 | Storage connector not be enabled for this user |
| 1 | Storage connector mounting is in progress |
| 2 | Storage connector mounted successfully |
| 3 | Storage connector mounting failed |
| 4 | Storage connector mounting is enabled, but not mounted yet |
On Linux instances, you can check the home folder mount status by looking at the value of appstream\$1home\$1folder\$1mount\$1status in the file \$1/.config/appstream-home-folder/appstream-home-folder-mount-status.
| Value | Description |
| --- | --- |
| True | Home folder is mounted successfully |
| False | Home folder is not mounted yet |
# Enable Amazon S3 Bucket Storage for Session Script Logs
When you enable Amazon S3 logging in your session script configuration, WorkSpaces Applications captures standard output from your session script. The output is periodically uploaded to an S3 bucket within your Amazon Web Services account. For every AWS Region, WorkSpaces Applications creates a bucket in your account that is unique to your account and the 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 log files that are stored in each bucket are encrypted in transit using Amazon S3's SSL endpoints and at rest using Amazon S3-managed encryption keys. The buckets are named in a specific format as follows:
```
appstream-logs-region-code-account-id-without-hyphens-random-identifier
```
***region-code***
This is the AWS Region code in which the stack is created with Amazon S3 bucket storage enabled for session script logs.
***account-id-without-hyphens***
Your Amazon Web Services account identifier. The random ID ensures that there is no conflict with other buckets in that Region. The first part of the bucket name, `appstream-logs`, does not change across accounts or Regions.
For example, if you specify session scripts in an image 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-logs-us-west-2-1234567890123-abcdefg
```
Disabling session scripts does not delete any log files stored in the S3 bucket. To permanently delete log files, 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 session scripts are enabled, a unique folder is created for each streaming session that is started.
The path for the folder where the log files are stored in the S3 bucket in your account uses the following structure:
```
bucket-name/stack-name/fleet-name/access-mode/user-id-SHA-256-hash/session-id/SessionScriptsLogs/session-event
```
***bucket-name***
The name of the S3 bucket in which the session scripts are stored. The name format is described earlier in this section.
***stack-name***
The name of the stack the session came from.
***fleet-name***
The name of the fleet the session script is running on.
***access-mode***
The identity method of the user: `custom` for the WorkSpaces Applications API or CLI, `federated` for SAML, and `userpool` for users in the user pool.
***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 identifier.
***session-id***
The identifier of the user's streaming session. Each user streaming session generates a unique ID.
***session-event***
The event that generated the session script log. The event values are: `SessionStart` and `SessionTermination`.
The following example folder structure applies to a streaming session started from the test-stack and test-fleet. The session uses the API of user ID `testuser@mydomain.com`, from an AWS account ID of `123456789012`, and the settings group `test-stack` in the US West (Oregon) Region (us-west-2):
```
appstream-logs-us-west-2-1234567890123-abcdefg/test-stack/test-fleet/custom/a0bcb1da11f480d9b5b3e90f91243143eac04cfccfbdc777e740fab628a1cd13/05yd1391-4805-3da6-f498-76f5x6746016/SessionScriptsLogs/SessionStart/
```
This example folder structure contains one log file for a user context session start script, and one log file for a system context session start script, if applicable.
# Use Session Scripts on Multi-Session Fleets
When using session scripts on multi-session fleets, there are additional requirements and considerations to ensure optimal performance and security.
## Requirements
On a single-session fleet, for a given instance, the **SessionStart** and **SessionTermination** hooks are guaranteed to run only one time. This is because there is a 1:1 mapping of sessions to instances. When using multi-session fleets, there is an N:M mapping of sessions to instances, where each session runs its own **SessionStart** and **SessionTermination** hook. This means that the **SessionStart** and **SessionTermination** hooks can be run many times on a given instance, and in many different orderings. For the best experience, the following should be true of your session scripts when used on multi-session fleets:
+ Scripts are idempotent.
When an action has already been performed, scripts should handle more than one execution on the same instance with graceful handling.
+ Scripts are independent.
Because scripts run per session, if one session is running **SessionTermination** while another is running **SessionStart**, they should not interfere with each other, or with the experience of other sessions.
+ Scripts are performant.
On multi-session instances, multiple sessions can be provisioned concurrently. This means that there can be multiple concurrent executions of the session scripts. Scripts should be efficient, not consume excessive resources, and not impact the experience of other users on the instance or the stability of the sessions.
Many of these requirements can be met by keeping session script logic focused on the specific user session for which the script is running.
## Security Considerations
WorkSpaces Applications images should not be configured to allow write permission to session script files by any users. This introduces a critical attack vector for malicious users, where they could modify script files. These files could then be run as SYSTEM or another user, depending on your configuration.
**Important**
It is your responsibility to make sure that your WorkSpaces Applications images are configured securely. This is especially important for multi-session instances, where multiple users are using the same instance. If images are not configured securely, there is a security risk for all users of that instance.
The following should be true of your images and session scripts files:
+ Users do not have permission to modify session script files.
+ Users do not have permission to modify the session script config.json. Default behavior on the image restricts access to administrators.
Session scripts executables should be stored in a secure location where they are safe from modification at runtime.
If the service detects that a session script executable has been modified, it will fail any subsequent executions of that hook on that instance, upload log files to Amazon S3 (if Amazon S3 logging is enabled), and you will see the following message:
**The session script was not executed because the executable was modified after instance provisioning. Execution was skipped for security.**
If your use case requires modifying the session script executable at run time (for example, if you point to an EXE file which is modified by an automatic update process at runtime), this will fail the above checks. In this case, use a script to redirect execution to your modified executable. Leave the script unmodified at runtime when the service performs security checks.
If your session script files are excessively large (more than 100 MB), this can cause delays in instance and session provisioning, and the security checks will take additional time (depending on instance type and available resources). If your use case requires large session scripts, consider using smaller scripts to redirect execution. This will improve instance and session provisioning experiences.
Note that the service is only checking the executable defined in the session scripts config.json, and this is only a fallback/best effort mechanism. It is your responsibility to ensure that all code paths in session scripts executables are secure and cannot be modified by end users.