# Windows launch agents on Amazon EC2 Windows instances
Each AWS Windows AMI includes a Windows launch agent that's pre-configured with default settings. Launch agents perform tasks during instance startup and run if an instance is stopped and later started, or restarted. For information about a specific agent, see the detail pages in the following list.
For more information about AWS Windows AMIs, see the [AWS Windows AMI reference](https://docs.aws.amazon.com/ec2/latest/windows-ami-reference/windows-amis.html).
+ [Use the EC2Launch v2 agent to perform tasks during EC2 Windows instance launch](ec2launch-v2.md)
+ [Use the EC2Launch v1 agent to perform tasks during EC2 Windows instance launch](ec2launch.md)
+ [Use the EC2Config service to perform tasks during EC2 legacy Windows operating system instance launch](ec2config-service.md)
**Content**
+ [Compare Amazon EC2 launch agents](#ec2launch-agent-compare)
+ [Configure DNS Suffix for EC2 Windows launch agents](launch-agents-set-dns.md)
+ [Subscribe to EC2 Windows launch agent notifications](launch-agents-subscribe-notifications.md)
+ [Windows Service administration for EC2Launch v2 and EC2Config agents](launch-agents-service-admin.md)
## Compare Amazon EC2 launch agents
The following table shows the major functional differences between EC2Config, EC2Launch v1, and EC2Launch v2.
| Feature | EC2Config | EC2Launch v1 | EC2Launch v2 |
| --- | --- | --- | --- |
| Run as | Windows Service | PowerShell Scripts | Windows Service |
| Supports | Legacy OS only | Windows Server versions: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configure-launch-agents.html) | Windows Server versions: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configure-launch-agents.html) |
| Configuration file | XML | JSON | JSON/YAML |
| Set Administrator username | No | No | Yes |
| Compressed user data | No | No | Yes |
| Local user data baked on AMI | No | No | Yes, configurable |
| Task configuration in user data | No | No | Yes |
| Configurable wallpaper | No | No | Yes |
| Customize task run order | No | No | Yes |
| Configurable tasks | 15 | 9 | 20 at launch |
| Supports Windows Event Viewer | Yes | No | Yes |
| Number of Event Viewer event types | 2 | 0 | 30 |
**Note**
EC2Config documentation is provided for historical reference only. The operating system versions it runs on are no longer supported by Microsoft. We strongly recommend that you upgrade to the latest launch service.
# Configure DNS Suffix for EC2 Windows launch agents
With Amazon EC2 launch agents, you can configure a list of DNS suffixes that Windows instances use for domain name resolution. The launch agents override the standard Windows settings in the `System\CurrentControlSet\Services\Tcpip\Parameters\SearchList` registry key by adding the following values to the DNS suffix search list:
+ The domain of the instance
+ The suffixes that result from devolution of the instance domain
+ NV domain
+ The domains specified by each network interface cards
All launch agents support DNS suffix configuration. For more information, see your specific launch agent version:
+ For information about the `setDnsSuffix` task and how to configure DNS suffixes in EC2Launch v2, see [setDnsSuffix](ec2launch-v2-task-definitions.md#ec2launch-v2-setdnssuffix).
+ For information about DNS suffix list setup and how to enable or disable devolution for EC2Launch v1, see [Configure the EC2Launch v1 agent on your Windows instance](ec2launch-config.md).
+ For information about DNS suffix list setup and how to enable or disable devolution for EC2Config, see [EC2Config settings files](ec2config-service.md#UsingConfigXML_WinAMI).
**Domain name devolution**
Domain name devolution is an Active Directory behavior that allows computers in a child domain to access resources in the parent domain without using a fully qualified domain name. By default, domain name devolution continues until there are only two nodes left in the domain name progression.
Launch agents perform devolution on the domain name if the instance is connected to a domain, and add the results to the DNS suffix search list that's maintained in the **`System\CurrentControlSet\Services\Tcpip\Parameters\SearchList`** registry key. The agents use the settings from the following registry keys, to determine the devolution behavior.
+ **`System\CurrentControlSet\Services\Tcpip\Parameters\UseDomainNameDevolution`**
+ When not set, disables devolution
+ When set to `1`, enables devolution (default)
+ When set to `0`, disables devolution
+ **`System\CurrentControlSet\Services\Dnscache\Parameters\DomainNameDevolutionLevel`**
+ When not set, use level of `2` (default)
+ When set to `3` or greater, use value to set level
When you disable devolution or change your devolution settings to a higher level, the `System\CurrentControlSet\Services\Tcpip\Parameters\SearchList` registry key stil contains the suffixes that were added previously. They are not automatically removed. You can manually update the list, or you can clear the list and let your agent run through the process to set up the new list.
**Note**
To clear the DNS suffix list from the registry, you can run the following command.
```
PS C:\> Invoke-CimMethod -ClassName Win32_NetworkAdapterConfiguration -MethodName "SetDNSSuffixSearchOrder" -Arguments @{ DNSDomainSuffixSearchOrder = $null } | Out-Null
```
**Devolution examples**
The following examples show domain name progression through the devolution process.
`corp.example.com`
+ Progresses to `example.com`
`locale.region.corp.example.com`
1. Progresses to `region.corp.example.com`
1. Progresses to `corp.example.com`
1. Progresses to `example.com`
`locale.region.corp.example.com` with a setting of `DomainNameDevolutionLevel=3`
1. Progresses to `region.corp.example.com`
1. Progresses to `corp.example.com`. The progression stops here, due to the level setting.
# Subscribe to EC2 Windows launch agent notifications
Amazon SNS can notify you when new versions of the EC2 launch agents are released. Use the following procedure to subscribe to these notifications.
**Subscribe to EC2Config notifications**
1. Open the Amazon SNS console at [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home).
1. In the navigation bar, change the Region to **US East (N. Virginia)**, if necessary. You must select this Region because the SNS notifications that you are subscribing to were created in this Region.
1. In the navigation pane, choose **Subscriptions**.
1. Choose **Create subscription**.
1. In the **Create subscription** dialog box, do the following:
1. For **Topic ARN**, use the following Amazon Resource Name (ARN) that matches the agent you want to receive notifications for:
+ **EC2Launch v2**:
```
arn:aws:sns:us-east-1:309726204594:amazon-ec2launch-v2
```
+ **EC2Launch or EC2Config**:
```
arn:aws:sns:us-east-1:801119661308:ec2-windows-ec2config
```
1. For **Protocol**, choose `Email`.
1. For **Endpoint**, enter the email address where you want to receive the notifications.
1. Choose **Create subscription**.
1. You'll receive a email asking you to confirm your subscription. Open the email and follow the directions to complete your subscription.
Whenever a new version of the launch agent is released, we send notifications to subscribers. If you no longer want to receive these notifications, use the following procedure to unsubscribe.
**Unsubscribe from launch agent notifications**
1. Open the Amazon SNS console.
1. In the navigation pane, choose **Subscriptions**.
1. Select the subscription and then choose **Actions**, **Delete subscriptions**. When prompted for confirmation, choose **Delete**.
# Windows Service administration for EC2Launch v2 and EC2Config agents
If you've logged into your instance as a user with administrative rights, you can manage the EC2Launch v2 and EC2Config launch agents just as you would any other Windows service. EC2Launch v1 is a set of PowerShell scripts that is managed via scheduled task by default. This section covers service administration for EC2Launch v2 and EC2Config.
To apply updated settings to your instance, you can stop and restart the EC2Launch v2 agent or the EC2Config service launch agent from the Microsoft Management Console (MMC) interface for Services. Similarly, when you install a new version of the launch agent, you must stop the agent first, then restart it when the installation is complete.
**Note**
You must open the MMC Services interface as an administrator to select these actions. To do this, you can select **Run as administrator** from the context menu. Alternatively, to open the interface using your keyboard, follow these steps:
Using the `Tab` key or arrow keys, select the **Services** menu item from the **Administrative Tools** menu.
Use the following keyboard combination to open as an administrator: `Ctrl` \$1 `Shift` \$1 `Enter`.
The following procedures list steps to stop and start the launch agent on your instance.
**Stop the launch agent**
1. Launch and connect to your Windows instance.
1. Select **Administrative Tools** from the Windows **Start** menu.
1. Open the **Services** console as an administrator, as described at the beginning of this section.
1. In the list of services, select the agent that's running on your instance (**EC2Launch** or **EC2Config**), then choose **Stop** from the **Action** menu. Alternatively, you can use the context menu to stop the agent.
**Restart the launch agent**
1. Launch and connect to your Windows instance.
1. Select **Administrative Tools** from the Windows **Start** menu.
1. Open the **Services** console as an administrator, as described at the beginning of this section.
1. In the list of services, select the agent that's running on your instance (**EC2Launch** or **EC2Config**), then choose **Start** or **Restart** from the **Action** menu. Alternatively, you can use the context menu to restart the agent.
If you don't need to update the configuration settings, create your own AMI, or use AWS Systems Manager, you can delete or uninstall the launch agent.
*Delete*
Deleting a service removes its registry subkey.
*Uninstall*
Uninstalling a service removes the files, the registry subkey, and any shortcuts to the service.
**Delete the launch agent**
1. Launch and connect to your Windows instance.
1. Start a Windows Command Prompt window.
1. Run one of the following commands to delete the launch agent.
+ Run the following command to delete the EC2Launch or EC2Launch v2:
```
sc delete ec2launch
```
+ Run the following command to delete the EC2Config service:
```
sc delete ec2config
```
**Uninstall the launch agent**
1. Launch and connect to your Windows instance.
1. Choose **Windows System**, then **Control Panel** from the Windows **Start** menu.
1. Choose **Programs and Features** to open the list of programs that are installed on your instance.
1. Select your launch agent from the list (**Amazon EC2Launch** or **EC2ConfigService**), then choose **Uninstall** from the **File** menu. Alternatively, you can use the context menu.
**Note**
You can see what launch agent version is installed in the **Version** column.
# Use the EC2Launch v2 agent to perform tasks during EC2 Windows instance launch
All supported instances of Amazon EC2 that are launched from AWS Windows Server 2022 and Windows Server 2025 AMIs include the EC2Launch v2 launch agent (`EC2Launch.exe`) by default. We also provide Windows Server 2016 and 2019 AMIs with EC2Launch v2 installed as the default launch agent. These AMIs are provided in addition to the Windows Server 2016 and 2019 AMIs that include EC2Launch v1. You can search for Windows AMIs that include EC2Launch v2 by default by entering the following prefix in your search from the **AMIs** page in the Amazon EC2 console: `EC2LaunchV2-Windows_Server-*`.
To compare launch agent version features, see [Compare Amazon EC2 launch agents](configure-launch-agents.md#ec2launch-agent-compare).
EC2Launch v2 performs tasks during instance startup and runs if an instance is stopped and later started, or restarted. EC2Launch v2 can also perform tasks on demand. Some of these tasks are automatically enabled, while others must be enabled manually. The EC2Launch v2 service supports all EC2Config and EC2Launch features.
This service uses a configuration file to control its operation. You can update the configuration file using either a graphical tool or by directly editing it as a single .yml file (`agent-config.yml`). For more information about file locations, see [EC2Launch v2 directory structure](#ec2launch-v2-directory).
EC2Launch v2 publishes Windows event logs to help you troubleshoot errors and set triggers. For more information, see [Windows event logs](ec2launchv2-troubleshooting.md#ec2launchv2-windows-event-logs).
**Supported OS versions**
The EC2Launch v2 agent supports the following Windows Server operating system (OS) versions:
+ Windows Server 2025
+ Windows Server 2022
+ Windows Server 2019 (Long-Term Servicing Channel and Semi-Annual Channel)
+ Windows Server 2016
**Tasks that run by default**
The EC2Launch v2 agent runs the following tasks one time only by default during the initial instance launch. Tasks are organized according to the order in which they run within their launch stage.
`Boot` stage
+ extendRootPartition
`PreReady` stage
+ activateWindows
+ setDnsSuffix
+ setAdminAccount
+ setWallpaper
`PostReady` stage
+ startSsm
## EC2Launch v2 concepts
The following concepts are useful to understand when considering EC2Launch v2.
**agent-config**
`agent-config` is a file that is located in the configuration folder for EC2Launch v2. It includes configuration for the boot, network, PreReady, and PostReady stages. This file is used to specify the instance configuration for tasks that should run when the AMI is either booted for the first time or for subsequent times.
By default, the EC2Launch v2 installation installs an `agent-config` file that includes recommended configurations that are used in standard Amazon Windows AMIs. You can update the configuration file to alter the default boot experience for your AMI that EC2Launch v2 specifies. For more information about file locations, see [EC2Launch v2 directory structure](#ec2launch-v2-directory).
**Frequency**
Task frequency determines when tasks should run, depending on the boot context. Most tasks have only one allowed frequency. You can specify a frequency for `executeScript` tasks.
You will see the following frequencies in the [EC2Launch v2 task configuration](ec2launch-v2-settings.md#ec2launch-v2-task-configuration).
+ Once – The task runs once, when the AMI has booted for the first time (finished Sysprep).
+ Always – The task runs every time that the launch agent runs. The launch agent runs when:
+ an instance starts or restarts
+ the EC2Launch service runs
+ `EC2Launch.exe run` is invoked
**Stage**
A stage is a logical grouping of tasks that the EC2Launch v2 agent runs. Some tasks can run only in a specific stage. Others can run in multiple stages. When using `agent-config.yml`, you must specify a list of stages, and a list of tasks to run within each stage.
The service runs stages in the following order:
Stage 1: Boot
Stage 2: Network
Stage 3: PreReady
Windows is ready
After the PreReady stage completes, the service sends the `Windows is ready` message to the Amazon EC2 console.
Stage 4: PostReady
User data runs during the *PostReady* stage. Some script versions run before the `agent-config.yml` file *PostReady* stage, and some run after, as follows:
Before `agent-config.yml`
+ YAML user data version 1.1
+ XML user data
After `agent-config.yml`
+ YAML user data version 1.0 (legacy version for backwards compatibility)
For example stages and tasks, see [Example: `agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-example-agent-config).
When you use user data, you must specify a list of tasks for the launch agent to run. The stage is implied. For example tasks, see [Example: user data](ec2launch-v2-settings.md#ec2launch-v2-example-user-data).
EC2Launch v2 runs the list of tasks in the order that you specify in `agent-config.yml` and in user data. Stages run sequentially. The next stage starts after the previous stage completes. Tasks also run sequentially.
**Task**
You can invoke a task to perform an action on an instance. You can configure tasks in the `agent-config.yml` file or through user data. For a list of available tasks for EC2Launch v2, see [EC2Launch v2 tasks](#ec2launch-v2-tasks). For task configuration schema and details, see [EC2Launch v2 task configuration](ec2launch-v2-settings.md#ec2launch-v2-task-configuration).
**User data**
User data is data that is configurable when you launch an instance. You can update user data to dynamically change how custom AMIs or quickstart AMIs are configured. EC2Launch v2 supports 60 kB user data input length. User data includes only the UserData stage, and therefore runs after the `agent-config` file. You can enter user data when you launch an instance using the launch instance wizard, or you can modify user data from the EC2 console. For more information about working with user data, see [How Amazon EC2 handles user data for Windows instances](user-data.md#ec2-windows-user-data).
## EC2Launch v2 task overview
EC2Launch v2 can perform the following tasks at each boot:
+ Set up new and optionally customized wallpaper that renders information about the instance.
+ Set the attributes for the administrator account that is created on the local machine.
+ Add DNS suffixes to the list of search suffixes. Only suffixes that do not already exist are added to the list.
+ Set drive letters for any additional volumes and extend them to use available space.
+ Write files from the configuration to the disk.
+ Run scripts specified in the EC2Launch v2 config file or from `user-data`. Scripts from `user-data` can be plain text or zipped and provided as a base64 format.
+ Run a program with given arguments.
+ Set the computer name.
+ Send instance information to the Amazon EC2 console.
+ Send the RDP certificate thumbprint to the Amazon EC2 console.
+ Dynamically extend the operating system partition to include any unpartitioned space.
+ Run user data. For more information about specifying user data, see [EC2Launch v2 task configuration](ec2launch-v2-settings.md#ec2launch-v2-task-configuration).
+ Set non-persistent static routes to reach the metadata service and AWS KMS servers.
+ Set non-boot partitions to `mbr` or `gpt`.
+ Start the Systems Manager service following Sysprep.
+ Optimize ENA settings.
+ Enable OpenSSH for later Windows versions.
+ Enable Jumbo Frames.
+ Set Sysprep to run with EC2Launch v2.
+ Publish Windows event logs.
## EC2Launch v2 directory structure
EC2Launch v2 should be installed in the following directories:
+ Service binaries: `%ProgramFiles%\Amazon\EC2Launch`
+ Service data (settings, log files, and state files): `%ProgramData%\Amazon\EC2Launch`
**Note**
By default, Windows hides files and folders under `C:\ProgramData`. To view EC2Launch v2 directories and files, you must either enter the path in Windows Explorer or change the folder properties to show hidden files and folders.
The `%ProgramFiles%\Amazon\EC2Launch` directory contains binaries and supporting libraries. It includes the following subdirectories:
+ `settings`
+ `EC2LaunchSettingsUI.exe` – user interface for modifying the `agent-config.yml` file
+ `YamlDotNet.dll` – DLL for supporting some operations in the user interface
+ `tools`
+ `ebsnvme-id.exe` – tool for examining the metadata of the EBS volumes on the instance
+ `AWSAcpiSpcrReader.exe` – tool for determining the correct COM port to use
+ `EC2LaunchEventMessage.dll` – DLL for supporting the Windows event logging for EC2Launch
+ `service`
+ `EC2LaunchService.exe` – Windows service executable that is launched when the launch agent runs as a service
+ `EC2AgentTelemetry.dll` – DLL for supporting EC2 agent telemetry
+ `EC2Launch.exe` – main EC2Launch executable
+ `EC2LaunchAgentAttribution.txt` – attribution for code used within EC2 Launch
The `%ProgramData%\Amazon\EC2Launch` directory contains the following subdirectories. All of the data produced by the service, including logs, configuration, and state, is stored in this directory.
+ `config` – Configuration
The service configuration file is stored in this directory as `agent-config.yml`. This file can be updated to modify, add, or remove default tasks run by the service. Permission to create files in this directory is restricted to the administrator account to prevent privilege escalation.
+ `log` – Instance logs
Logs for the service (`agent.log`), performance (`bench.log`), and telemetry (`telemetry.log`) are stored in this directory. When `agent.log` reaches 1 MB in size, it is automatically rotated and a backup file is created with a timestamp format (for example, `agent-2026-03-02T18-56-39.188.log`). Only one backup log file is maintained at a time.
+ `state` – Service state data
The state that the service uses to determine which tasks should run is stored here. There is a `.run-once` file that indicates whether the service has already run after Sysprep (so tasks with a frequency of once will be skipped on the next run). This subdirectory includes a `state.json` and `previous-state.json` to track the status of each task.
+ `sysprep` – Sysprep
This directory contains files that are used to determine which operations to perform by Sysprep when it creates a customized Windows AMI that can be reused.
+ `wallpaper` – Wallpaper
This wallpaper images is stored in this directory.
## Telemetry
Telemetry is additional information that helps AWS to better understand your requirements, diagnose issues, and deliver features to improve your experience with AWS services.
EC2Launch v2 version `2.1.592` and later collect telemetry, such as usage metrics and errors. This data is collected from the Amazon EC2 instance on which EC2Launch v2 runs. This includes all Windows AMIs owned by AWS.
The following types of telemetry are collected by EC2Launch v2:
+ **Usage information** — agent commands, install method, and scheduled run frequency.
+ **Errors and diagnostic information** — agent installation error codes, run error codes, and error call stacks.
Examples of collected data from version 2.0.592 through 2.1.1:
```
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IsTelemetryEnabled=true
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentCommandErrorCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AdminPasswordTypeCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IpConflictDetectionCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentErrorLocation=addroutes.go:49
```
Starting with version 2.2.63, EC2 Agent telemetry data is formatted as a JSON object:
```
{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... }
```
Telemetry is enabled by default. You can disable telemetry collection at any time.
**Disable telemetry on an instance**
To disable telemetry for a single instance, you can either set a system environment variable, or use the MSI to modify the installation.
To disable telemetry by setting a system environment variable, run the following command as an administrator.
```
setx /M EC2LAUNCH_TELEMETRY 0
```
To disable telemetry using the MSI, run the following command after you [download the MSI](ec2launch-v2-install.md).
```
msiexec /i ".\AmazonEC2Launch.msi" Remove="Telemetry" /q
```
**Topics**
+ [
## EC2Launch v2 concepts
](#ec2launch-v2-concepts)
+ [
## EC2Launch v2 task overview
](#ec2launch-v2-tasks)
+ [
## EC2Launch v2 directory structure
](#ec2launch-v2-directory)
+ [
## Telemetry
](#ec2launch-v2-telemetry)
+ [
# Install the latest version of EC2Launch v2
](ec2launch-v2-install.md)
+ [
# Configure EC2Launch v2 settings for Windows instances
](ec2launch-v2-settings.md)
+ [
# Task definitions for EC2Launch v2 startup tasks
](ec2launch-v2-task-definitions.md)
+ [
# Troubleshoot issues with the EC2Launch v2 agent
](ec2launchv2-troubleshooting.md)
+ [
# EC2Launch v2 version histories
](ec2launchv2-versions.md)
# Install the latest version of EC2Launch v2
You can use one of the following methods to install the EC2Launch v2 agent on your EC2 instance:
+ Download the agent from Amazon S3 and install with Windows PowerShell. For download URLs, see [EC2Launch v2 downloads on Amazon S3](#lv2-download-s3).
+ Install with SSM Distributor.
+ Install from an EC2 Image Builder component when you create a custom image.
+ Launch your instance from an AMI that has EC2Launch v2 pre-installed.
**Warning**
AmazonEC2Launch.msi uninstalls previous versions of the EC2 launch services, such as EC2Launch (v1) and EC2Config.
For install steps, select the tab that matches your preferred method.
------
#### [ PowerShell ]
To install the latest version of EC2Launch v2 agent with Windows PowerShell, follow these steps.
1. Create your local directory.
```
New-Item -Path "$env:USERPROFILE\Desktop\EC2Launchv2" -ItemType Directory
```
1. Set the URL for your download location. Run the following command with the Amazon S3 URL you'll use. For download URLs, see [EC2Launch v2 downloads on Amazon S3](#lv2-download-s3)
```
$Url = "Amazon S3 URL/AmazonEC2Launch.msi"
```
1. Use the following compound command to download the agent and run the install
```
$DownloadFile = "$env:USERPROFILE\Desktop\EC2Launchv2\" + $(Split-Path -Path $Url -Leaf)
Invoke-WebRequest -Uri $Url -OutFile $DownloadFile
msiexec /i "$DownloadFile"
```
**Note**
If you receive an error when downloading the file, and you are using Windows Server 2016 or earlier, TLS 1.2 might need to be enabled for your PowerShell terminal. You can enable TLS 1.2 for the current PowerShell session with the following command and then try again:
```
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
```
1. The **msiexec** command installs EC2Launch v2 in the following location on Windows Server instances: `%ProgramFiles%\Amazon\EC2Launch`. To verify that the install ran, you can check the local file system on your instance.
------
#### [ AWS Systems Manager Distributor ]
To configure automatic updates for EC2Launch v2 with AWS Systems Manager Quick Setup, see [Automatically install and update with Distributor Quick Setup](#lv2-distributor-quick-setup).
You can also perform a one-time install of the `AWSEC2Launch-Agent` package from AWS Systems Manager Distributor. For instructions on how to install a package from Systems Manager Distributor, see [Install or update packages](https://docs.aws.amazon.com/systems-manager/latest/userguide/distributor-working-with-packages-deploy.html) in the *AWS Systems Manager User Guide*.
------
#### [ EC2 Image Builder component ]
You can install the `ec2launch-v2-windows` component when you build a custom image with EC2 Image Builder. For instructions on how to build a custom image with EC2 Image Builder, see [Create an image pipeline using the EC2 Image Builder console wizard](https://docs.aws.amazon.com/imagebuilder/latest/userguide/start-build-image-pipeline.html) in the *EC2 Image Builder User Guide*.
------
#### [ AMI ]
EC2Launch v2 is preinstalled by default on AMIs for the Windows Server 2022 and above operating systems:
+ Windows\$1Server-*version*-English-Full-Base
+ Windows\$1Server-*version*-English-Core-Base
+ Windows\$1Server-*version*-English-Core-EKS\$1Optimized
+ Windows Server *version* AMIs with all other languages
+ Windows Server *version* AMIs with SQL installed
EC2Launch v2 is also preinstalled on the following Windows Server AMIs. You can find these AMIs from the Amazon EC2 console, or by using the following search prefix: `EC2LaunchV2-` in the AWS CLI.
+ EC2LaunchV2-Windows\$1Server-2019-English-Core-Base
+ EC2LaunchV2-Windows\$1Server-2019-English-Full-Base
+ EC2LaunchV2-Windows\$1Server-2016-English-Core-Base
+ EC2LaunchV2-Windows\$1Server-2016-English-Full-Base
------
## Automatically install and update EC2Launch v2 with AWS Systems Manager Distributor Quick Setup
With AWS Systems Manager Distributor Quick Setup, you can set up automatic updates for EC2Launch v2. The following process sets up a Systems Manager Association on your instance that automatically updates the EC2Launch v2 agent at a frequency that you specify. The Association that the Distributor Quick Setup creates can include instances within an AWS account and Region, or instances within an AWS Organization. For more information about setting up an organization, see [Tutorial: Creating and configuring an organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_tutorials_basic.html) in the *AWS Organizations User Guide*.
Before you begin, make sure that your instances meet all of the prerequisites.
### Prerequisites
To set up automatic updates with Distributor Quick Setup, your instances must meet the following prerequisites.
+ You have at least one running instance that supports EC2Launch v2. See supported operating systems for [EC2Launch v2](ec2launch-v2.md).
+ You've performed the Systems Manager set-up tasks on your instances. For more information, see [Setting up Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-setting-up-ec2.html) in the *AWS Systems Manager User Guide*.
+ EC2Launch v2 must be the only launch agent installed on your instance. If you have more than one launch agent installed, your Distributor Quick Setup configuration will fail. Before you configure EC2Launch v2 with a Distributor Quick Setup, uninstall EC2Config or EC2Launch v1 launch agents, if they exist.
### Configure Distributor Quick Setup for EC2Launch v2
To create a configuration for EC2Launch v2 with Distributor Quick Setup, use the following settings when you complete the steps for [Distributor package deployment](https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup-distributor.html):
+ **Software packages:** Amazon EC2Launch v2 agent.
+ **Update frequency:** Select a frequency from the list.
+ **Targets:** Choose from the available deployment options.
To check the status of your configuration, navigate to the Systems Manager Quick Setup **Configurations** tab in the AWS Management Console.
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Quick Setup**.
1. In the **Configurations** tab, select the row that's associated with the configuration that you created. The **Configurations** tab lists your configurations, and includes a summary of key details, such as **Region**, **Deployment status**, and **Association status**.
**Note**
The association name for every EC2Launch v2 Distributor configuration begins with the following prefix: `AWS-QuickSetup-Distributor-EC2Launch-Agent-`.
1. To view details, select the configuration and choose **View details**.
For more information and troubleshooting steps, see [Troubleshooting Quick Setup results](https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup-results-troubleshooting.html) in the *AWS Systems Manager User Guide*.
## EC2Launch v2 downloads on Amazon S3
To install the latest version of EC2Launch v2, download the installer from the following location:
+ [https://s3.amazonaws.com/amazon-ec2launch-v2/windows/amd64/latest/AmazonEC2Launch.msi](https://s3.amazonaws.com/amazon-ec2launch-v2/windows/amd64/latest/AmazonEC2Launch.msi)
## Configure install options
When you install or upgrade EC2Launch v2, you can configure installation options with the EC2Launch v2 install dialog or with the **msiexec** command in a command line shell.
The first time the EC2Launch v2 installer runs on an instance, it initializes launch agent settings on your instance as follows:
+ It creates the local path and writes the launch agent file to it. This is sometimes referred to as a *clean install*.
+ It creates the `EC2LAUNCH_TELEMETRY` environment variable if it doesn't already exist, and sets it based on your configuration.
For configuration details, select the tab that matches the configuration method that you'll use.
------
#### [ Amazon EC2Launch Setup dialog ]
When you install or upgrade EC2Launch v2, you can configure the following installation options through the EC2Launch v2 install dialog.**Basic Install** options
**Send Telemetry**
When you include this feature in the setup dialog, the installer sets the `EC2LAUNCH_TELEMETRY` environment variable to a value of `1`. If you disable **Send Telemetry**, the installer sets the environment variable to a value of `0`.
When the EC2Launch v2 agent runs, it reads the `EC2LAUNCH_TELEMETRY` environment variable to determine whether to upload telemetry data. If the value equals `1`, it uploads the data. Otherwise, it doesn't upload.
**Default configuration**
The default configuration for EC2Launch v2 is to overwrite the local launch agent if it exists already. The first time you run an install on an instance, the default configuration performs a clean install. If you disable the default configuration on the initial install, the installation fails.
If you run the install again on the instance, you can disable the default configuration to perform an upgrade that doesn't replace the `%ProgramData%/Amazon/EC2Launch/config/agent-config.yml` file.
**Example: Upgrade EC2Launch v2 with telemetry**
The following example shows the EC2Launch v2 setup dialog configured to upgrade the current installation and enable telemetry. This configuration performs an install without replacing the agent configuration file, and sets the `EC2LAUNCH_TELEMETRY` environment variable to a value of `1`.
![\[EC2Launch v2 upgrade configuration.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/ec2launchv2-clean-default-config.png)
------
#### [ Command line ]
When you install or upgrade EC2Launch v2, you can configure the following installation options with the **msiexec** command in a command line shell.`ADDLOCAL` parameter values
**Basic** (required)
Install the launch agent. If this value is not present in the `ADDLOCAL` parameter, the installation ends.
**Clean**
When you include the `Clean` value in the `ADDLOCAL` parameter, the installer writes the agent configuration file to the following location: `%ProgramData%/Amazon/EC2Launch/config/agent-config.yml`. If the agent configuration file already exists, it overwrites the file.
When you leave the `Clean` value out of the `ADDLOCAL` parameter, the installer performs an upgrade that doesn't replace the agent configuration file.
**Telemetry**
When you include the `Telemetry` value in the `ADDLOCAL` parameter, the installer sets the `EC2LAUNCH_TELEMETRY` environment variable to a value of `1`.
When you leave the `Telemetry` value out of the `ADDLOCAL` parameter, the installer sets the environment variable to a value of `0`.
When the EC2Launch v2 agent runs, it reads the `EC2LAUNCH_TELEMETRY` environment variable to determine whether to upload telemetry data. If the value equals `1`, it uploads the data. Otherwise, it doesn't upload.
**Example: install EC2Launch v2 with telemetry**
```
& msiexec /i "C:\Users\Administrator\Desktop\EC2Launchv2\AmazonEC2Launch.msi" ADDLOCAL="Basic,Clean,Telemetry" /q
```
------
## Verify the EC2Launch v2 version
Use one of the following procedures to verify the version of EC2Launch v2 that is installed on your instances.
------
#### [ PowerShell ]
Verify the installed version of EC2Launch v2 with Windows PowerShell, as follows.
1. Launch an instance from your AMI and connect to it.
1. Run the following command in PowerShell to verify the installed version of EC2Launch v2:
```
& "C:\Program Files\Amazon\EC2Launch\EC2Launch.exe" version
```
------
#### [ Windows Control Panel ]
Verify the installed version of EC2Launch v2 in the Windows Control Panel, as follows.
1. Launch an instance from your AMI and connect to it.
1. Open the Windows Control Panel and choose **Programs and Features**.
1. Look for `Amazon EC2Launch` in the list of installed programs. Its version number appears in the **Version** column.
------
To view the latest updates for the AWS Windows AMIs, see [Windows AMI version history](https://docs.aws.amazon.com/ec2/latest/windows-ami-reference/ec2-windows-ami-version-history.html) in the *AWS Windows AMI Reference*.
For the latest version of EC2Launch v2, see [EC2Launch v2 version history](ec2launchv2-versions.md#ec2launchv2-version-history).
You can receive notifications when new versions of the EC2Launch v2 service are released. For more information, see [Subscribe to EC2 Windows launch agent notifications](launch-agents-subscribe-notifications.md).
# Configure EC2Launch v2 settings for Windows instances
This section contains information about how to configure settings for EC2Launch v2.
**Topics**
+ [
## Change settings using the EC2Launch v2 settings dialog box
](#ec2launch-v2-ui)
+ [
## Configure EC2Launch v2 using the CLI
](#ec2launch-v2-cli)
+ [
## EC2Launch v2 task configuration
](#ec2launch-v2-task-configuration)
+ [
## EC2Launch v2 exit codes and reboots
](#ec2launch-v2-exit-codes-reboots)
+ [
## EC2Launch v2 and Sysprep
](#ec2launch-v2-sysprep)
## Change settings using the EC2Launch v2 settings dialog box
The following procedure describes how to use the EC2Launch v2 settings dialog box to enable or disable settings.
**Note**
If you improperly configure custom tasks in the agent-config.yml file, and you attempt to open the Amazon EC2Launch settings dialog box, you will receive an error. For example schema, see [Example: `agent-config.yml`](#ec2launch-v2-example-agent-config).
1. Launch and connect to your Windows instance.
1. From the Start menu, choose **All Programs**, and then navigate to **EC2Launch settings**. Before you choose **Shutdown with Sysprep** or **Shutdown without Sysprep**, make sure that you save any changes that you want to apply when you run the shutdown.
![\[EC2 Launch settings application.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/ec2launchv2-settings.png)
1. On the **General** tab of the **EC2Launch settings** dialog box, you can enable or disable the following settings.
1. **Set Computer Name**
If this setting is enabled (it is disabled by default), the current host name is compared to the desired host name at each boot. If the host names do not match, the host name is reset, and the system then optionally reboots to pick up the new host name. If a custom host name is not specified, it is generated using the hexadecimal-formatted private IPv4 address, for example, `ip-AC1F4E6`. To prevent your existing host name from being modified, do not enable this setting.
1. **Extend Boot Volume**
This setting dynamically extends `Disk 0`/`Volume 0` to include any unpartitioned space. This can be useful when the instance is booted from a root volume that has a custom size.
1. **Set Administrator Account**
When enabled, you can set the username and password attributes for the administrator account that is created on your local machine. If this feature is not enabled, an administrator account is not created on the system following Sysprep. Provide a password in `adminPassword` only if `adminPasswordtype` is `Specify`.
The password types are defined as follows:
1. `Random`
EC2Launch generates a password and encrypts it using the user's key. The system disables this setting after the instance is launched so that this password persists if the instance is rebooted or stopped and started.
1. `Specify`
EC2Launch uses the password that you specify in `adminPassword`. If the password does not meet the system requirements, EC2Launch generates a random password instead. The password is stored in `agent-config.yml` as clear text and is deleted after Sysprep sets the administrator password. EC2Launch encrypts the password using the user's key.
1. `Do not set`
EC2Launch uses the password that you specify in the unattend.xml file. If you don't specify a password in unattend.xml, the administrator account is disabled.
1. **Start SSM Service**
When selected, the Systems Manager service is enabled to start following Sysprep. EC2Launch v2 performs all of the tasks described [earlier](ec2launch-v2.md#ec2launch-v2-tasks), and the SSM Agent processes requests for Systems Manager capabilities, such as Run Command and State Manager.
You can use Run Command to upgrade your existing instances to use the latest version of the EC2Launch v2 service and SSM Agent. For more information, see [Update SSM Agent using Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command-tutorial-update-software.html) in the *AWS Systems Manager User Guide*.
1. **Optimize ENA**
When selected, ENA settings are configured to ensure that ENA Receive Side Scaling and Receive Queue Depth settings are optimized for AWS. For more information, see [Configure Receive side scaling CPU affinity](enhanced-networking-os.md#windows-rss-cpu-affinity).
1. **Enable SSH**
This setting enables OpenSSH for later Windows versions to allow for remote system administration.
1. **Enable Jumbo Frames**
Select to enable Jumbo Frames. Jumbo Frames can have unintended effects on your network communications, so ensure you understand how Jumbo Frames will impact your system before enabling. For more information about Jumbo Frames, see [Jumbo frames (9001 MTU)](network_mtu.md#jumbo_frame_instances).
1. **Prepare for Imaging**
Select whether you want your EC2 instance to shut down with or without Sysprep. When you want to run Sysprep with EC2Launch v2, choose **Shutdown with Sysprep**.
1. On the **DNS Suffix** tab, you can select whether you want to add a DNS suffix list for DNS resolution of servers running in EC2, without providing the fully qualified domain name. DNS suffixes can contain the variables `$REGION` and `$AZ`. Only suffixes that do not already exist will be added to the list.
![\[EC2 Launch settings application.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/ec2launchv2-dns.png)
1. On the **Wallpaper** tab, you can configure your instance wallpaper with a background image, and specify instance details for the wallpaper to display. Amazon EC2 generates the details each time you log in.
You can configure your wallpaper with the following controls.
+ **Display instance details on wallpaper** – This checkbox activates or deactivates instance detail display on the wallpaper.
+ **Image path (.jpg)** – Specify the path to the image to use as the wallpaper background.
+ **Select attributes to display on wallpaper** – Select the check boxes for the instance details that you want to appear on the wallpaper. Clear the check boxes for previously selected instance details that you want to remove from the wallpaper.
+ **Display Instance Tags on wallpaper** – Select one of the following settings to display instance tags on the wallpaper:
+ **None** – Don't display any instance tags on the wallpaper.
+ **Show all** – Display all instance tags on the wallpaper.
+ **Show filtered** – Display specified instance tags on the wallpaper. When you select this setting, you can add instance tags that you want to display on your wallpaper in the **Instance tag filter** box.
**Note**
You must enable tags in metadata to show tags on the wallpaper. For more information about instance tags and metadata, see [View tags for your EC2 instances using instance metadata](work-with-tags-in-IMDS.md).
![\[EC2 Launch settings Wallpaper tab.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/ec2launchv2-wallpaper-02.png)
1. On the **Volumes** tab, select whether you want to initialize the volumes that are attached to the instance. Enabling sets drive letters for any additional volumes and extends them to use available space. If you select **All**, all of the storage volumes are initialized. If you select **Devices**, only devices that are specified in the list are initialized. You must enter the device for each device to be initialized. Use the devices listed on the EC2 console, for example, `xvdb` or `/dev/nvme0n1`. The dropdown list displays the storage volumes that are attached to the instance. To enter a device that is not attached to the instance, enter it in the text field.
**Name**, **Letter**, and **Partition** are optional fields. If no value is specified for **Partition**, storage volumes larger than 2 TB are initialized with the `gpt` partition type, and those smaller than 2 TB are initialized with the `mbr` partition type. If devices are configured, and a non-NTFS device either contains a partition table, or the first 4 KB of the disk contain data, then the disk is skipped and the action logged.
![\[EC2 Launch settings application.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/ec2launchv2-volumes.png)
## Configure EC2Launch v2 using the CLI
You can use the Command Line Interface (CLI) to configure your EC2Launch settings and manage the service. The following section contains descriptions and usage information for the CLI commands that you can use to manage EC2Launch v2.
**Topics**
+ [
### collect-logs
](#ec2launch-v2-collect-logs)
+ [
### get-agent-config
](#ec2launch-v2-get-agent-config)
+ [
### list-volumes
](#ec2launch-v2-list-volumes)
+ [
### reset
](#ec2launch-v2-reset)
+ [
### run
](#ec2launch-v2-run)
+ [
### status
](#ec2launch-v2-settings-status)
+ [
### sysprep
](#ec2launch-v2-settings-sysprep)
+ [
### validate
](#ec2launch-v2-validate)
+ [
### version
](#ec2launch-v2-version)
+ [
### wallpaper
](#ec2launch-v2-wallpaper)
### collect-logs
Collects log files for EC2Launch, zips the files, and places them in a specified directory.
**Example**
```
ec2launch collect-logs -o C:\Mylogs.zip
```
**Usage**
`ec2launch collect-logs [flags]`
**Flags**
`-h`, `--help`
help for `collect-logs`
`-o`, `--output string`
path to zipped output log files
### get-agent-config
Prints `agent-config.yml` in the format specified (JSON or YAML). If no format is specified, `agent-config.yml` is printed in the format previously specified.
**Example**
```
ec2launch get-agent-config -f json
```
**Usage**
`ec2launch get-agent-config [flags]`
**Flags**
`-h`, `--help`
help for `get-agent-config`
`-f`, `--format string`
output format of `agent-config` file: `json`, `yaml`
### list-volumes
Lists all of the storage volumes attached to the instance, including ephemeral and EBS volumes.
**Example**
```
ec2launch list-volumes
```
**Usage**
`ec2launch list-volumes`
**Flags**
`-h`, `--help`
help for `list-volumes`
### reset
The main goal of this task is to reset the agent for the next time that it runs. To do that, the **reset** command deletes all of the agent state data for EC2Launch v2 from the local `EC2Launch` directory (see [EC2Launch v2 directory structure](ec2launch-v2.md#ec2launch-v2-directory)). Reset optionally deletes the service and Sysprep logs.
Script behavior depends on what mode the agent runs the scripts in – inline, or detached.
Inline (default)
The EC2Launch v2 agent runs scripts one at a time (`detach: false`). This is the default setting.
When your inline script issues a **reset** or **sysprep** command, it runs immediately and resets the agent. The current task finishes, then the agent shuts down without running any further tasks.
For example, if the task that issues the command would have been followed by a `startSsm` task (included by default after user data runs), the task doesn't run and the Systems Manager service never starts.
Detached
The EC2Launch v2 agent runs scripts concurrently with other tasks (`detach: true`).
When your detached script issues a **reset** or **sysprep** command, those commands wait for the agent to finish before they run. Tasks after the executeScript will still run.
**Example**
```
ec2launch reset -c
```
**Usage**
`ec2launch reset [flags]`
**Flags**
`-c`, `--clean`
cleans instance logs before `reset`
`-h`, `--help`
help for `reset`
### run
Runs EC2Launch v2.
**Example**
```
ec2launch run
```
**Usage**
`ec2launch run [flags]`
**Flags**
`-h`, `--help`
help for `run`
### status
Gets the status of the EC2Launch v2 agent. Optionally blocks the process until the agent is finished. The process exit code determines the agent state:
+ `0` –the agent ran and was successful.
+ `1` – the agent ran and failed.
+ `2` – the agent is still running.
+ `3` – the agent is in an unknown state. The agent state is not running or stopped.
+ `4` – an error occurred when attempting to retrieve the agent state.
+ `5` – the agent is not running and the status of the last known run is unknown. This could mean one of the following:
+ both the `state.json` and `previous-state.json` are deleted.
+ the `previous-state.json` is corrupted.
This is the agent state after running the [`reset`](#ec2launch-v2-reset) command.
**Example:**
```
ec2launch status -b
```
**Usage**
`ec2launch status [flags]`
**Flags**
`-b`,`--block`
blocks the process until the agent finishes running
`-h`,`--help`
help for `status`
### sysprep
The main goal of this task is to reset the agent for the next time that it runs. To do that, the **sysprep** command resets the agent state, updates the `unattend.xml` file, disables RDP, and runs Sysprep.
Script behavior depends on what mode the agent runs the scripts in – inline, or detached.
Inline (default)
The EC2Launch v2 agent runs scripts one at a time (`detach: false`). This is the default setting.
When your inline script issues a **reset** or **sysprep** command, it runs immediately and resets the agent. The current task finishes, then the agent shuts down without running any further tasks.
For example, if the task that issues the command would have been followed by a `startSsm` task (included by default after user data runs), the task doesn't run and the Systems Manager service never starts.
Detached
The EC2Launch v2 agent runs scripts concurrently with other tasks (`detach: true`).
When your detached script issues a **reset** or **sysprep** command, those commands wait for the agent to finish before they run. Tasks after the executeScript will still run.
**Example:**
```
ec2launch sysprep
```
**Usage**
`ec2launch sysprep [flags]`
**Flags**
`-c`,`--clean`
cleans instance logs before `sysprep`
`-h`,`--help`
help for Sysprep
`-s`,`--shutdown`
shuts down the instance after `sysprep`
### validate
Validates the `agent-config` file `C:\ProgramData\Amazon\EC2Launch\config\agent-config.yml`.
**Example**
```
ec2launch validate
```
**Usage**
`ec2launch validate [flags]`
**Flags**
-h` `, `--help`
help for `validate`
### version
Gets the executable version.
**Example**
```
ec2launch version
```
**Usage**
`ec2launch version [flags]`
**Flags**
`-h`, `--help`
help for `version`
### wallpaper
Sets new wallpaper to the wallpaper path that is provided (.jpg file), and displays the selected instance details.
#### Syntax
```
ec2launch wallpaper ^
--path="C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg" ^
--all-tags ^
--attributes=hostName,instanceId,privateIpAddress,publicIpAddress,ipv6Address,instanceSize,availabilityZone,architecture
```
#### Inputs
Parameters
**--allowed-tags [*tag-name-1*, *tag-name-n*]**
(Optional) Base64 encoded JSON array of instance tag names to display on the wallpaper. You can use this tag or the `--all-tags`, but not both.
**--attributes *attribute-string-1*, *attribute-string-n***
(Optional) A comma-separated list of `wallpaper` attribute strings to apply settings to the wallpaper.
**[--path \$1 -p] *path-string***
(Required) Specifies the `wallpaper` background image file path.Flags
**--all-tags**
(Optional) Displays all of the instance tags on the wallpaper. You can use this tag or the `--allowed-tags`, but not both.
**[--help \$1 -h]**
Displays help for the **wallpaper** command.
## EC2Launch v2 task configuration
This section includes the configuration schema, tasks, details, and examples for `agent-config.yml` and user data.
**Topics**
+ [
### Schema: `agent-config.yml`
](#ec2launch-v2-schema-agent-config)
+ [
### Configure EC2Launch v2 user data scripts that run during launch or reboot
](#ec2launch-v2-schema-user-data)
### Schema: `agent-config.yml`
The structure of the `agent-config.yml` file is shown below. Note that a task cannot be repeated in the same stage. For task properties, see the task descriptions that follow.
#### Document structure: agent-config.yml
**JSON**
```
{
"version": "1.1",
"config": [
{
"stage": "string",
"tasks": [
{
"task": "string",
"inputs": {
...
}
},
...
]
},
...
]
}
```
**YAML**
```
version: 1.1
config:
- stage: string
tasks:
- task: string
inputs:
...
...
...
```
#### Example: `agent-config.yml`
The following example shows settings for the `agent-config.yml` configuration file.
```
version: 1.1
config:
- stage: boot
tasks:
- task: extendRootPartition
- stage: preReady
tasks:
- task: activateWindows
inputs:
activation:
type: amazon
- task: setDnsSuffix
inputs:
suffixes:
- $REGION.ec2-utilities.amazonaws.com
- task: setAdminAccount
inputs:
password:
type: random
- task: setWallpaper
inputs:
path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
attributes:
- hostName
- instanceId
- privateIpAddress
- publicIpAddress
- instanceSize
- availabilityZone
- architecture
- stage: postReady
tasks:
- task: startSsm
```
### Configure EC2Launch v2 user data scripts that run during launch or reboot
The following JSON and YAML examples show the document structure for user data. Amazon EC2 parses each task named in the `tasks` array that you specify in the document. Each task has its own set of properties and requirements. For details, see the [Task definitions for EC2Launch v2 startup tasks](ec2launch-v2-task-definitions.md).
**Note**
A task must only appear once in the user data tasks array.
#### Document structure: user data
**JSON**
```
{
"version": "1.1",
"tasks": [
{
"task": "string",
"inputs": {
...
},
},
...
]
}
```
**YAML**
```
version: 1.1
tasks:
- task: string
inputs:
...
...
```
#### Example: user data
For more information about user data, see [How Amazon EC2 handles user data for Windows instances](user-data.md#ec2-windows-user-data).
The following YAML document example shows a PowerShell script that EC2Launch v2 runs as user data to create a file.
```
version: 1.1
tasks:
- task: executeScript
inputs:
- frequency: always
type: powershell
runAs: localSystem
content: |-
New-Item -Path 'C:\PowerShellTest.txt' -ItemType File
```
You can use an XML format for the user data that's compatible with previous versions of the launch agent. EC2Launch v2 runs the script as an `executeScript` task in the `UserData` stage. To conform with EC2Launch v1 and EC2Config behavior, the user data script runs as an attached/inline process by default.
You can add optional tags to customize how your script runs. For example, to run the user data script when the instance reboots in addition to one time when the instance launches, you can use the following tag:
`true`
**Example:**
```
$file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
true
```
You can specify one or more PowerShell arguments with the `` tag. If no arguments are passed, EC2Launch v2 adds the following argument by default: `-ExecutionPolicy Unrestricted`.
**Example:**
```
$file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
-ExecutionPolicy Unrestricted -NoProfile -NonInteractive
```
To run an XML user data script as a detached process, add the following tag to your user data.
`true`
**Example:**
```
$file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
true
```
**Note**
The detach tag is not supported on previous launch agents.
#### Change log: user data
The following table lists changes for user data, and cross-references them to the EC2Launch v2 agent version that applies.
| User data version | Details | Introduced in |
| --- | --- | --- |
| 1.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-v2-settings.html) | EC2Launch v2 version 2.0.1245 |
| 1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-v2-settings.html) | EC2Launch v2 version 2.0.0 |
\$1 When used with the default `agent-config.yml` file.
## EC2Launch v2 exit codes and reboots
You can use EC2Launch v2 to define how exit codes are handled by your scripts. By default, the exit code of the last command that is run in a script is reported as the exit code for the entire script. For example, if a script includes three commands and the first command fails but the following ones succeed, the run status is reported as `success` because the final command succeeded.
If you want a script to reboot an instance, then you must specify `exit 3010` in your script, even when the reboot is the last step in your script. `exit 3010` instructs EC2Launch v2 to reboot the instance and call the script again until it returns an exit code that is not `3010`, or until the maximum reboot count has been reached. EC2Launch v2 permits a maximum of 5 reboots per task. If you attempt to reboot an instance from a script by using a different mechanism, such as `Restart-Computer`, then the script run status will be inconsistent. For example, it may get stuck in a restart loop or not perform the restart.
If you are using an XML user data format that is compatible with older agents, the user data may run more times than you intend it to. For more information, see [Service runs user data more than once](ec2launchv2-troubleshooting.md#ec2launchv2-troubleshooting-user-data-more-than-once) in the Troubleshooting section.
## EC2Launch v2 and Sysprep
The EC2Launch v2 service runs Sysprep, a Microsoft tool that enables you to create a customized Windows AMI that can be reused. When EC2Launch v2 calls Sysprep, it uses the files in `%ProgramData%\Amazon\EC2Launch` to determine which operations to perform. You can edit these files indirectly using the **EC2Launch settings** dialog box, or directly using a YAML editor or a text editor. However, there are some advanced settings that aren't available in the **EC2Launch settings** dialog box, so you must edit those entries directly.
If you create an AMI from an instance after updating its settings, the new settings are applied to any instance that's launched from the new AMI. For information about creating an AMI, see [Create an Amazon EBS-backed AMI](creating-an-ami-ebs.md).
# Task definitions for EC2Launch v2 startup tasks
Each task that EC2Launch v2 runs during launch or startup has its own set of properties and requirements. Task details include settings for how often a task runs – once, or always, what stage of the agent boot process it runs in, syntax, and YAML document examples. For more information, review the task details shown in this reference.
**Topics**
+ [
## activateWindows
](#ec2launch-v2-activatewindows)
+ [
## enableJumboFrames
](#ec2launch-v2-enablejumboframes)
+ [
## enableOpenSsh
](#ec2launch-v2-enableopenssh)
+ [
## executeProgram
](#ec2launch-v2-executeprogram)
+ [
## executeScript
](#ec2launch-v2-executescript)
+ [
## extendRootPartition
](#ec2launch-v2-extendrootpartition)
+ [
## initializeVolume
](#ec2launch-v2-initializevolume)
+ [
## optimizeEna
](#ec2launch-v2-optimizeena)
+ [
## setAdminAccount
](#ec2launch-v2-setadminaccount)
+ [
## setDnsSuffix
](#ec2launch-v2-setdnssuffix)
+ [
## setHostName
](#ec2launch-v2-sethostname)
+ [
## setWallpaper
](#ec2launch-v2-setwallpaper)
+ [
## startSsm
](#ec2launch-v2-startssm)
+ [
## sysprep
](#ec2launch-v2-task-sysprep)
+ [
## writeFile
](#ec2-launch-v2-writefile)
## activateWindows
Activates Windows against a set of AWS KMS servers. Activation is skipped if the instance is detected as Bring-Your-Own-License (BYOL).
*Frequency* — once
*AllowedStages* — `[PreReady]`
*Inputs* —
`activation`: (map)
`type`: (string) activation type to use, set to `amazon`
*Example*
```
task: activateWindows
inputs:
activation:
type: amazon
```
## enableJumboFrames
Enables Jumbo Frames, which increase the maximum transmission unit (MTU) of the network adapter. For more information, see [Jumbo frames (9001 MTU)](network_mtu.md#jumbo_frame_instances).
*Frequency* — always
*AllowedStages* — `[PostReady, UserData]`
*Inputs* — none
*Example*
```
task: enableJumboFrames
```
## enableOpenSsh
Enables Windows OpenSSH and adds the public key for the instance to the authorized keys folder.
*Frequency* — once
*AllowedStages* — `[PreReady, UserData]`
*Inputs* — none
*Example*
The following example shows how to enable OpenSSH on an instance, and to add the public key for the instance to the authorized keys folder. This configuration works only on instances running Windows Server 2019 and later versions.
```
task: enableOpenSsh
```
## executeProgram
Runs a program with optional arguments and a specified frequency.
**Stages:** You can run the `executeProgram` task during the `PreReady`, `PostReady`, and `UserData` stages.
**Frequency:** configurable, see *Inputs*.
**Inputs**
This section contains one or more programs for the **executeProgram** task to run (inputs). Each input can include the following configurable settings:
**frequency (string)**
(Required) Specify exactly one of the following values:
+ `once`
+ `always`
**path (string)**
(Required) The file path for the executable to run.
**arguments (list of strings)**
(Optional) A comma separated list of arguments to provide to the program as input.
**runAs (string)**
(Required) Must be set to `localSystem`
**Output**
All of the tasks write logfile entries to the `agent.log` file. Additional output from the `executeProgram` task is stored separately in a dynamically named folder, as follows:
`%LocalAppData%\Temp\EC2Launch#########\outputfilename.tmp`
The exact path to the output files is included in the `agent.log` file, for example:
```
Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\ExecuteProgramInputs.tmp
Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp
Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp
```
**Output files for the `executeProgram` task**
`ExecuteProgramInputs.tmp`
Contains the path for the executable, and all of the input parameters that the `executeProgram` task passes to it when it runs.
`Output.tmp`
Contains runtime output from the program that the `executeProgram` task runs.
`Err.tmp`
Contains runtime error messages from the program that the `executeProgram` task runs.
**Examples**
The following examples show how to run an executable file from a local directory on an instance with the `executeProgram` task.
**Example 1: Setup executable with one argument**
This example shows an `executeProgram` task that runs a setup executable in quiet mode.
```
task: executeProgram
inputs:
- frequency: always
path: C:\Users\Administrator\Desktop\setup.exe
arguments: ['-quiet']
```
**Example 2: VLC executable with two arguments**
This example shows an `executeProgram` task that runs a VLC executable file with two arguments passed as input parameters.
```
task: executeProgram
inputs:
- frequency: always
path: C:\vlc-3.0.11-win64.exe
arguments: ['/L=1033','/S']
runAs: localSystem
```
## executeScript
Runs a script with optional arguments and a specified frequency. Script behavior depends on what mode the agent runs the scripts in – inline, or detached.
Inline (default)
The EC2Launch v2 agent runs scripts one at a time (`detach: false`). This is the default setting.
When your inline script issues a **reset** or **sysprep** command, it runs immediately and resets the agent. The current task finishes, then the agent shuts down without running any further tasks.
For example, if the task that issues the command would have been followed by a `startSsm` task (included by default after user data runs), the task doesn't run and the Systems Manager service never starts.
Detached
The EC2Launch v2 agent runs scripts concurrently with other tasks (`detach: true`).
When your detached script issues a **reset** or **sysprep** command, those commands wait for the agent to finish before they run. Tasks after the executeScript will still run.
**Stages:** You can run the `executeScript` task during the `PreReady`, `PostReady`, and `UserData` stages.
**Frequency:** configurable, see *Inputs*.
**Inputs**
This section contains one or more scripts for the **executeScript** task to run (inputs). Each input can include the following configurable settings:
**frequency (string)**
(Required) Specify exactly one of the following values:
+ `once`
+ `always`
**type (string)**
(Required) Specify exactly one of the following values:
+ `batch`
+ `powershell`
**arguments (list of strings)**
(Optional) A list of string arguments to pass to the shell (not to the PowerShell script). This parameter isn't supported for `type: batch`. If no arguments are passed, EC2Launch v2 adds the following argument by default: `-ExecutionPolicy Unrestricted`.
**content (string)**
(Required) Script content.
**runAs (string)**
(Required) Specify exactly one of the following values:
+ `admin`
+ `localSystem`
**detach (Boolean)**
(Optional) The EC2Launch v2 agent defaults to run scripts one at a time (`detach: false`). To run the script concurrently with other tasks, set the value to `true` (`detach: true`).
Script exit codes (including `3010`) have no effect when `detach` is set to `true`.
**Output**
All of the tasks write logfile entries to the `agent.log` file. Additional output from script that the `executeScript` task runs is stored separately in a dynamically named folder, as follows:
`%LocalAppData%\Temp\EC2Launch#########\outputfilename.ext`
The exact path to the output files is included in the `agent.log` file, for example:
```
Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\UserScript.ps1
Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp
Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp
```
**Output files for the `executeScript` task**
`UserScript.ext`
Contains the script that the `executeScript` task ran. The file extension depends on the type of script you specified in the `type` parameter for the `executeScript` task, as follows:
+ If the type is `batch`, then the file extension is `.bat`.
+ If the type is `powershell`, then the file extension is `.ps1`.
`Output.tmp`
Contains runtime output from the script that the `executeScript` task runs.
`Err.tmp`
Contains runtime error messages from the script that the `executeScript` task runs.
**Examples**
The following examples show how to run an inline script with the `executeScript` task.
**Example 1: Hello world output text file**
This example shows an `executeScript` task that runs a PowerShell script to create a "Hello world" text file on the `C:` drive.
```
task: executeScript
inputs:
- frequency: always
type: powershell
runAs: admin
content: |-
New-Item -Path 'C:\PowerShellTest.txt' -ItemType File
Set-Content 'C:\PowerShellTest.txt' "Hello world"
```
**Example 2: Run two scripts**
This example shows that the `executeScript` task can run more than one script, and the script type doesn't necessarily need to match.
The first script (`type: powershell`) writes a summary of the processes that are currently running on the instance to a text file located on the `C:` drive.
The second script (`batch`) writes the system information to the `Output.tmp` file.
```
task: executeScript
inputs:
- frequency: always
type: powershell
runAs: localSystem
content: |
Get-Process | Out-File -FilePath C:\Process.txt
- frequency: always
type: batch
runAs: localSystem
content: |
systeminfo
```
**Example 3: Idempotent system configuration with reboots**
This example shows an `executeScript` task that runs an idempotent script to perform the following system configuration with a reboot between each step:
+ Rename the computer.
+ Join the computer to the domain.
+ Enable Telnet.
The script ensures that each operation runs one time only. This prevents a reboot loop and makes the script idempotent.
```
task: executeScript
inputs:
- frequency: always
type: powershell
runAs: localSystem
content: |-
$name = $env:ComputerName
if ($name -ne $desiredName) {
Rename-Computer -NewName $desiredName
exit 3010
}
$domain = Get-ADDomain
if ($domain -ne $desiredDomain)
{
Add-Computer -DomainName $desiredDomain
exit 3010
}
$telnet = Get-WindowsFeature -Name Telnet-Client
if (-not $telnet.Installed)
{
Install-WindowsFeature -Name "Telnet-Client"
exit 3010
}
```
## extendRootPartition
Extends the root volume to use all of the available space on the disk.
*Frequency* — once
*AllowedStages* — `[Boot]`
*Inputs* — none
*Example*
```
task: extendRootPartition
```
## initializeVolume
Initializes empty volumes that are attached to the instance so that they're activated and partitioned. The launch agent skips initialization if it detects that the volume is not empty. A volume is considered empty if the first 4 KiB of the volume are empty, or if the volume doesn't have a [Windows-recognizable drive layout](https://learn.microsoft.com/en-us/windows/win32/api/winioctl/ns-winioctl-drive_layout_information_ex).
The `letter` input parameter is always applied when this task runs, regardless of whether the drive is already initialized.
The `initializeVolume` task performs the following actions.
+ Set disk attributes `offline` and `readonly` to false.
+ Create a partition. If no partition type is specified in the `partition` input parameter, the following defaults apply:
+ If the disk size is smaller than 2 TB, set the partition type to `mbr`.
+ If the disk size is 2 TB or larger, set the partition type to `gpt`.
+ Format the volume as NTFS.
+ Set the volume label as follows:
+ Use the value of the `name` input parameter, if specified.
+ If the volume is ephemeral, and no name was specified, set the volume label to `Temporary Storage Z`.
+ If the volume is ephemeral (SSD or HDD – not Amazon EBS), create an `Important.txt` file at the root of the volume with the following content:
```
This is an 'Instance Store' disk and is provided at no additional charge.
*This disk offers increased performance since it is local to the host
*The number of Instance Store disks available to an instance vary by instance type
*DATA ON THIS DRIVE WILL BE LOST IN CASES OF IMPAIRMENT OR STOPPING THE INSTANCE. PLEASE ENSURE THAT ANY IMPORTANT DATA IS BACKED UP FREQUENTLY
For more information, please refer to: Instance store temporary block storage for EC2 instances.
```
+ Set the drive letter to the value specified in the `letter` input parameter.
**Stages:** You can run the `initializeVolume` task during the `PostReady` and `UserData` stages.
**Frequency:** always.
**Inputs**
You can configure runtime parameters as follows:
**devices (list of maps)**
(Conditional) Configuration for each device that the launch agent initializes. This is required if the `initialize` input parameter is set to `devices`.
+ **device (string, required)** – Identifies the device during instance creation. For example, `xvdb`, `xvdf`, or `\dev\nvme0n1`.
+ **letter (string, optional)** – One character. The drive letter to assign.
+ **name (string, optional)** – The volume name to assign.
+ **partition (string, optional)** – Specify one of the following values for the type of partition to create, or let the launch agent default based on volume size:
+ mbr
+ gpt
**initialize (string)**
(Required) Specify exactly one of the following values:
+ `all`
+ `devices`
**Examples**
The following examples show sample input configurations for the `initializeVolume` task.
**Example 1: Initialize two volumes on an instance**
This example shows an `initializeVolume` task that initializes two secondary volumes on an instance. The device named `DataVolume2` in the example is ephemeral.
```
task: initializeVolume
inputs:
initialize: devices
devices:
- device: xvdb
name: DataVolume1
letter: D
partition: mbr
- device: /dev/nvme0n1
name: DataVolume2
letter: E
partition: gpt
```
**Example 2: Initialize EBS volumes attached to an instance**
This example shows an `initializeVolume` task that initializes all empty EBS volumes that are attached to the instance.
```
task: initializeVolume
inputs:
initialize: all
```
## optimizeEna
Optimizes ENA settings based on the current instance type; might reboot the instance.
*Frequency* — always
*AllowedStages* — `[PostReady, UserData]`
*Inputs* — none
*Example*
```
task: optimizeEna
```
## setAdminAccount
Sets attributes for the default administrator account that is created on the local machine.
*Frequency* — once
*AllowedStages* — `[PreReady]`
*Inputs* —
`name`: (string) name of the administrator account
`password`: (map)
`type`: (string) strategy to set the password, either as `static`, `random`, or `doNothing`
`data`: (string) stores data if the `type` field is static
*Example*
```
task: setAdminAccount
inputs:
name: Administrator
password:
type: random
```
## setDnsSuffix
Adds DNS suffixes to the list of search suffixes. Only suffixes that do not already exist are added to the list. For more information about how launch agents set DNS suffixes, see [Configure DNS Suffix for EC2 Windows launch agents](launch-agents-set-dns.md).
*Frequency* — always
*AllowedStages* — `[PreReady]`
*Inputs* —
`suffixes`: (list of strings) list of one or more valid DNS suffixes; valid substitution variables are `$REGION` and `$AZ`
*Example*
```
task: setDnsSuffix
inputs:
suffixes:
- $REGION.ec2-utilities.amazonaws.com
```
## setHostName
Sets the hostname of the computer to a custom string or, if `hostName` is not specified, the private IPv4 address.
*Frequency* — always
*AllowedStages* — `[PostReady, UserData]`
*Inputs* —
`hostName`: (string) optional host name, which must be formatted as follows.
+ Must be 15 characters or less
+ Must contain only alphanumeric (a-z, A-Z, 0-9) and hyphen (-) characters.
+ Must not consist entirely of numerical characters.
`reboot`: (boolean) denotes whether a reboot is permitted when the hostname is changed
*Example*
```
task: setHostName
inputs:
reboot: true
```
## setWallpaper
Creates the `setwallpaper.lnk` shortcut file in the startup folder of each existing user except for `Default User`. This shortcut file runs when the user logs in for the first time after instance boot. It sets up the instance with a custom wallpaper that displays the instance attributes.
The shortcut file path is:
```
$env:SystemDrive/Users//AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk
```
**Note**
When you remove the `setWallpaper` task, it does not delete this shortcut file. For more information, see [`setWallpaper` task is not enabled but the wallpaper resets at reboot](ec2launchv2-troubleshooting.md#ec2launchv2-troubleshooting-wallpaper-resets).
**Stages:** You can configure wallpaper during the `PreReady` and `UserData` stages.
**Frequency:** `always`
**Wallpaper configuration**
You can use the following settings to configure your wallpaper.
**Inputs**
Input parameters that you provide, and attributes that you can set to configure your wallpaper:
**path (string)**
(Required) The filename path of the local .jpg format image file to use for your wallpaper image.
**attributes (list of strings)**
(Optional) You can add one or more of the following attributes to your wallpaper:
+ `architecture`
+ `availabilityZone`
+ `hostName`
+ `instanceId`
+ `instanceSize`
+ `privateIpAddress`
+ `publicIpAddress`
+ `ipv6Address`
**instanceTags**
(Optional) You can use exactly one of the following options for this setting.
+ **AllTags** (string) – Add all instance tags to your wallpaper.
```
instanceTags: AllTags
```
+ **instanceTags** (list of strings) – Specify a list of instance tag names to add to your wallpaper. For example:
```
instanceTags:
- Tag 1
- Tag 2
```
**Example**
The following example shows wallpaper configuration inputs that set the file path for the wallpaper background image, along with instance tags named `Tag 1` and `Tag 2`, and attributes that include the host name, instance ID, and private and public IP addresses for the instance.
```
task: setWallpaper
inputs:
path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
attributes:
- hostName
- instanceId
- privateIpAddress
- publicIpAddress
instanceTags:
- Tag 1
- Tag 2
```
**Note**
You must enable tags in metadata to show tags on the wallpaper. For more information about instance tags and metadata, see [View tags for your EC2 instances using instance metadata](work-with-tags-in-IMDS.md).
## startSsm
Starts the Systems Manager (SSM) service following Sysprep.
*Frequency* — always
*AllowedStages* — `[PostReady, UserData]`
*Inputs* — none
*Example*
```
task: startSsm
```
## sysprep
Resets the service state, updates `unattend.xml`, disables RDP, and runs Sysprep. This task runs only after all other tasks are completed.
*Frequency* — once
*AllowedStages* — `[UserData]`
*Inputs* —
`clean`: (boolean) cleans instance logs before running Sysprep
`shutdown`: (boolean) shuts down the instance after running Sysprep
*Example*
```
task: sysprep
inputs:
clean: true
shutdown: true
```
## writeFile
Writes a file to a destination.
*Frequency* — see *Inputs*
*AllowedStages* — `[PostReady, UserData]`
*Inputs* —
`frequency`: (string) one of `once` or `always`
`destination`: (string) path to which to write the content
`content`: (string) text to write to the destination
*Example*
```
task: writeFile
inputs:
- frequency: once
destination: C:\Users\Administrator\Desktop\booted.txt
content: Windows Has Booted
```
# Troubleshoot issues with the EC2Launch v2 agent
This section shows common troubleshooting scenarios for EC2Launch v2, information about viewing Windows event logs, and console log output and messages.
**Topics**
+ [Common scenarios](#ec2launchv2-troubleshooting-scenarios)
+ [
## Windows event logs
](#ec2launchv2-windows-event-logs)
+ [
## EC2Launch v2 console log output
](#ec2launchv2-console-output)
## Common troubleshooting scenarios
This section shows common troubleshooting scenarios and steps for resolution.
**Topics**
+ [
### Service fails to set the wallpaper
](#ec2launchv2-troubleshooting-wallpaper)
+ [
### Service fails to run user data
](#ec2launchv2-troubleshooting-user-data)
+ [
### Service runs a task only one time
](#ec2launchv2-troubleshooting-task-once)
+ [
### Service fails to run a task
](#ec2launchv2-troubleshooting-task-failed)
+ [
### Service runs user data more than once
](#ec2launchv2-troubleshooting-user-data-more-than-once)
+ [
### Scheduled tasks from EC2Launch v1 fail to run after migration to EC2Launch v2
](#ec2launchv2-troubleshooting-scheduled-tasks-migration)
+ [
### Service initializes an EBS volume that is not empty
](#ec2launchv2-troubleshooting-ebs-initialize)
+ [
### `setWallpaper` task is not enabled but the wallpaper resets at reboot
](#ec2launchv2-troubleshooting-wallpaper-resets)
+ [
### Service stuck in running status
](#ec2launchv2-troubleshooting-service-stuck-running)
+ [
### Invalid `agent-config.yml` prevents opening EC2Launch v2 settings dialog box
](#ec2launchv2-troubleshooting-invalid-agent-config)
+ [
### `task:executeScript should be unique and only invoked once`
](#ec2launchv2-troubleshooting-executescript)
### Service fails to set the wallpaper
**Resolution**
1. Check that `%AppData%\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\setwallpaper.lnk` exists.
1. Check `%ProgramData%\Amazon\EC2Launch\log\agent.log` to see if any errors occurred.
### Service fails to run user data
**Possible cause**: Service may have failed before running user data.
**Resolution**
1. Check `%ProgramData%\Amazon\EC2Launch\state\previous-state.json`.
1. See if `boot`, `network`, `preReady`, and `postReadyLocalData` have all been marked as success.
1. If one of the stages failed, check `%ProgramData%\Amazon\EC2Launch\log\agent.log` for specific errors.
### Service runs a task only one time
**Resolution**
1. Check the frequency of the task.
1. If the service already ran after Sysprep, and the task frequency is set to `once`, the task will not run again.
1. Set the frequency of the task to `always` if you want it to run the task every time EC2Launch v2 runs.
### Service fails to run a task
**Resolution**
1. Check the latest entries in `%ProgramData%\Amazon\EC2Launch\log\agent.log`.
1. If no errors occurred, try running the service manually from `"%ProgramFiles%\Amazon\EC2Launch\EC2Launch.exe" run` to see if the tasks succeed.
### Service runs user data more than once
**Resolution**
User data is handled differently between EC2Launch v1 and EC2Launch v2. EC2Launch v1 runs user data as a scheduled task on the instance when `persist` is set to `true`. If `persist` is set to `false`, the task is not scheduled even when it exits with a reboot or is interrupted while running.
EC2Launch v2 runs user data as an agent task and tracks its run state. If user data issues a computer restart or if user data was interrupted while running, the run state persists as `pending` and the user data will run again at the next instance boot. If you want to prevent the user data script from running more than once, make the script idempotent.
The following example idempotent script sets the computer name and joins a domain.
```
$name = $env:computername
if ($name -ne $desiredName) {
Rename-Computer -NewName $desiredName
}
$domain = Get-ADDomain
if ($domain -ne $desiredDomain)
{
Add-Computer -DomainName $desiredDomain
}
$telnet = Get-WindowsFeature -Name Telnet-Client
if (-not $telnet.Installed)
{
Install-WindowsFeature -Name "Telnet-Client"
}
false
```
### Scheduled tasks from EC2Launch v1 fail to run after migration to EC2Launch v2
**Resolution**
The migration tool does not detect any scheduled tasks linked to EC2Launch v1 scripts; therefore, it does not automatically set up those tasks in EC2Launch v2. To configure these tasks, edit the [`agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-task-configuration) file, or use the [EC2Launch v2 settings dialog box](ec2launch-v2-settings.md#ec2launch-v2-ui). For example, if an instance has a scheduled task that runs `InitializeDisks.ps1`, then after you run the migration tool, you must specify the volumes you want to initialize in the EC2Launch v2 settings dialog box. See Step 6 of the procedure to [Change settings using the EC2Launch v2 settings dialog box](ec2launch-v2-settings.md#ec2launch-v2-ui).
### Service initializes an EBS volume that is not empty
**Resolution**
Before it initializes a volume, EC2Launch v2 attempts to detect whether it is empty. If a volume is not empty, it skips the initialization. Any volumes that are detected as not empty are not initialized. A volume is considered empty if the first 4 KiB of a volume are empty, or if a volume does not have a [Windows-recognizable drive layout](https://learn.microsoft.com/en-us/windows/win32/api/winioctl/ns-winioctl-drive_layout_information_ex). A volume that was initialized and formatted on a Linux system does not have a Windows-recognizable drive layout, for example MBR or GPT. Therefore, it will be considered as empty and initialized. If you want to preserve this data, do not rely on EC2Launch v2 empty drive detection. Instead, specify volumes that you would like to initialize in the [EC2Launch v2 settings dialog box](ec2launch-v2-settings.md#ec2launch-v2-ui) (see step 6) or in the [`agent-config.yml`](ec2launch-v2-task-definitions.md#ec2launch-v2-initializevolume).
### `setWallpaper` task is not enabled but the wallpaper resets at reboot
The `setWallpaper` task creates the `setwallpaper.lnk` shortcut file in the startup folder of each existing user. This shortcut file runs when the user logs in for the first time after instance boot. It sets up the instance with a custom wallpaper that displays the instance attributes. Removing the `setWallpaper` task does not delete this shortcut file. You must manually delete this file or delete it using a script.
The shortcut path is:
`$env:SystemDrive/Users//AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk`
**Resolution**
Manually delete this file, or delete it using a script.
**Example PowerShell script to delete shortcut file**
```
foreach ($userDir in (Get-ChildItem "C:\Users" -Force -Directory).FullName)
{
$startupPath = Join-Path $userDir -ChildPath "AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup"
if (Test-Path $startupPath)
{
$wallpaperSetupPath = Join-Path $startupPath -ChildPath "setwallpaper.lnk"
if (Test-Path $wallpaperSetupPath)
{
Remove-Item $wallpaperSetupPath -Force -Confirm:$false
}
}
}
```
### Service stuck in running status
**Description**
EC2Launch v2 is blocked, with log messages (`agent.log`) similar to the following:
```
2022-02-24 08:08:58 Info: *****************************************************************************************
2022-02-24 08:08:58 Info: EC2Launch Service starting
2022-02-24 08:08:58 Info: Windows event custom log exists: Amazon EC2Launch
2022-02-24 08:08:58 Info: ACPI SPCR table not supported. Bailing Out
2022-02-24 08:08:58 Info: Serial port is in use. Waiting for Serial Port...
2022-02-24 08:09:00 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:02 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:04 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:06 Info: ACPI SPCR table not supported. Use default console port.
```
**Possible cause**
SAC is enabled and using the serial port. For more information, see [Use SAC to troubleshoot your Windows instance](troubleshoot-using-serial-console.md#troubleshooting-sac).
**Resolution**
Try the following steps to resolve this issue:
+ Disable the service that is using the serial port.
+ If you want the service to continue to use the serial port, write custom scripts to perform launch agent tasks and invoke them as scheduled tasks.
### Invalid `agent-config.yml` prevents opening EC2Launch v2 settings dialog box
**Description**
EC2Launch v2 settings attempts to parse the `agent-config.yml` file before it opens the dialog box. If the YAML configuration file does not follow the supported schema, the dialog box will show the following error:
`Unable to parse configuration file agent-config.yml. Review configuration file. Exiting application.`
**Resolution**
1. Verify that the configuration file follows the [supported schema](ec2launch-v2-settings.md#ec2launch-v2-schema-agent-config).
1. If you want to start from scratch, copy the default configuration file into `agent-config.yml`. You can use the [example `agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-example-agent-config) provided in the Task Configuration section.
1. You can also start over by deleting `agent-config.yml`. EC2Launch v2 settings generates an empty configuration file.
### `task:executeScript should be unique and only invoked once`
**Description**
A task cannot be repeated in the same stage.
**Resolution**
Some tasks must be input as an array, such as [**executeScript**](ec2launch-v2-task-definitions.md#ec2launch-v2-executescript) and [**executeProgram**](ec2launch-v2-task-definitions.md#ec2launch-v2-executeprogram). For an example of how to write the script as an array, see [**executeScript**](ec2launch-v2-task-definitions.md#ec2launch-v2-executescript).
## Windows event logs
EC2Launch v2 publishes Windows event logs for important events, such as service starting, Windows is ready, and task success and failure. Event identifiers uniquely identify a particular event. Each event contains stage, task, and level information, and a description. You can set triggers for specific events using the event identifier.
Event IDs provide information about an event and uniquely identify some events. The least significant digit of an event ID indicates the severity of an event.
| Event | Least significant digit |
| --- | --- |
| Success | . . .0 |
| Informational | . . .1 |
| Warning | . . .2 |
| Error | . . .3 |
Service-related events that are generated when the service starts or stops include a single digit event identifier.
| Event | Single digit identifier |
| --- | --- |
| Success | 0 |
| Informational | 1 |
| Warning | 2 |
| Error | 3 |
The event messages for `EC2LaunchService.exe` events begin with `Service:`. The event messages for `EC2Launch.exe` events do not begin with `Service:`.
Four digit event IDs include information about the stage, task, and severity of an event.
**Topics**
+ [
### Event ID format
](#ec2launchv2-windows-event-logs-format)
+ [
### Event ID examples
](#ec2launchv2-windows-event-logs-id-examples)
+ [
### Windows event log schema
](#ec2launch-v2-windows-event-logs-schema)
### Event ID format
The following table shows the format of an EC2Launch v2 event identifier.
| 3 | 2 1 | 0 |
| --- | --- | --- |
| S | T | L |
The letters and numbers in the table represent the following event type and definitions.
| Event type | Definition |
| --- | --- |
| S (Stage) | 0 - Service-level message 1 - Boot 2 - Network 3 - PreReady 5 - Windows is Ready 6 - PostReady 7 - User Data |
| T (Task) | The tasks represented by the corresponding two values are different for each stage. To view the complete list of events, see [Windows Event log schema](#ec2launch-v2-windows-event-logs-schema). |
| L (Level of the event) | 0 - Success 1 - Informational 2 - Warning 3 - Error |
### Event ID examples
The following are example event IDs.
+ `5000` - Windows is ready to use
+ `3010` - Activate windows task in PreReady stage was successful
+ `6013` - Set wallpaper task in PostReady Local Data stage encountered an error
### Windows event log schema
| MessageId/Event Id | Event message |
| --- | --- |
| . . .0 | Success |
| . . .1 | Informational |
| . . .2 | Warning |
| . . .3 | Error |
| x | EC2Launch service-level logs |
| 0 | EC2Launch service exited successfully |
| 1 | EC2Launch service informational logs |
| 2 | EC2Launch service warning logs |
| 3 | EC2Launch service error logs |
| 10 | Replace state.json with previous-state.json |
| 100 | Serial Port |
| 200 | Sysprep |
| 300 | PrimaryNic |
| 400 | Metadata |
| x000 | Stage (1 digit), Task (2 digits), Status (1 digit) |
| 1000 | Boot |
| 1010 | Boot - extend\$1root\$1partition |
| 2000 | Network |
| 2010 | Network - add\$1routes |
| 3000 | PreReady |
| 3010 | PreReady - activate\$1windows |
| 3020 | PreReady - install\$1egpu\$1manager |
| 3030 | PreReady - set\$1monitor\$1on |
| 3040 | PreReady - set\$1hibernation |
| 3050 | PreReady - set\$1admin\$1account |
| 3060 | PreReady - set\$1dns\$1suffix |
| 3070 | PreReady - set\$1wallpaper |
| 3080 | PreReady - set\$1update\$1schedule |
| 3090 | PreReady - output\$1log |
| 3100 | PreReady - enable\$1open\$1ssh |
| 5000 | Windows is Ready to use |
| 6000 | PostReadyLocalData |
| 7000 | PostReadyUserData |
| 6010/7010 | PostReadyLocal/UserData - set\$1wallpaper |
| 6020/7020 | PostReadyLocal/UserData - set\$1update\$1schedule |
| 6030/7030 | PostReadyLocal/UserData - set\$1hostname |
| 6040/7040 | PostReadyLocal/UserData - execute\$1program |
| 6050/7050 | PostReadyLocal/UserData - execute\$1script |
| 6060/7060 | PostReadyLocal/UserData - manage\$1package |
| 6070/7070 | PostReadyLocal/UserData - initialize\$1volume |
| 6080/7080 | PostReadyLocal/UserData - write\$1file |
| 6090/7090 | PostReadyLocal/UserData - start\$1ssm |
| 7100 | PostReadyUserData - enable\$1open\$1ssh |
| 6110/7110 | PostReadyLocal/UserData - enable\$1jumbo\$1frames |
## EC2Launch v2 console log output
This section contains sample console log output for EC2Launch v2 and lists all of the EC2Launch v2 console log error messages to help you to troubleshoot issues. For more information about instance console output and how to access it, see [Instance console output](troubleshoot-unreachable-instance.md#instance-console-console-output).
**Topics**
+ [
### EC2Launch v2 console log output
](#ec2launchv2-console-log-output)
+ [
### EC2Launch v2 console log messages
](#ec2launchv2-console-log-messages)
### EC2Launch v2 console log output
The following is sample console log output for EC2Launch v2. Some values in this example are substituted with representative text surrounded by curly braces.
```
2025/07/22 21:26:53Z: Windows sysprep configuration complete.
2025/07/22 21:26:53Z: Message: Waiting for access to metadata...
2025/07/22 21:26:53Z: Message: Meta-data is now available.
2025/07/22 21:26:53Z: AMI Origin Version: 2024.12.13
2025/07/22 21:26:53Z: AMI Origin Name: Windows_Server-2022-English-Full-Base
2025/07/22 21:26:53Z: OS: Microsoft Windows NT 10.0.20348
2025/07/22 21:26:53Z: OsVersion: 10.0
2025/07/22 21:26:53Z: OsProductName: Windows Server 2022 Datacenter
2025/07/22 21:26:53Z: OsBuildLabEx: 20348.1.amd64fre.fe_release.210507-1500
2025/07/22 21:26:53Z: OsCurrentBuild: 20348
2025/07/22 21:26:53Z: OsReleaseId: 2009
2025/07/22 21:26:53Z: Language: en-US
2025/07/22 21:26:53Z: TimeZone: UTC
2025/07/22 21:26:53Z: Offset: UTC +0000
2025/07/22 21:26:53Z: Launch: EC2 Launch v2.2.63
2025/07/22 21:26:53Z: AMI-ID: ami-1234567890abcdef1
2025/07/22 21:26:53Z: Instance-ID: i-1234567890abcdef0
2025/07/22 21:26:54Z: Instance Type: t3.xlarge
2025/07/22 21:26:54Z: Driver: AWS NVMe Driver v1.6.0.35
2025/07/22 21:26:54Z: SubComponent: 1.6.0.35; EnableSCSIPersistentReservations: 0
2025/07/22 21:26:54Z: Driver: AWS PV Driver Package v8.5.0
2025/07/22 21:26:55Z: Driver: Amazon Elastic Network Adapter v2.8.0.0
2025/07/22 21:26:55Z: HOSTNAME: EC2AMAZ-9FJG5CC
2025/07/22 21:26:55Z: RDPCERTIFICATE-SUBJECTNAME: {certificate subject name}
2025/07/22 21:26:55Z: RDPCERTIFICATE-THUMBPRINT: {thumbprint hash}
2025/07/22 21:26:56Z: SSM: Amazon SSM Agent v3.3.2746.0
2025/07/22 21:26:57Z: User data format: no_user_data
2025/07/22 21:26:57Z: EC2LaunchTelemetry: IsTelemetryEnabled=true
2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64
2025/07/22 21:26:57Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentCommandErrorCode=1
2025/07/22 21:26:57Z: EC2LaunchTelemetry: AdminPasswordTypeCode=0
2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentErrorLocation=execute_windows.go:410
2025/07/22 21:26:57Z: EC2LaunchTelemetry: IpConflictDetectionCode=0
2025/07/22 21:26:57Z: Message: Windows is Ready to use
{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2", ...}
{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2", ...}
```
### EC2Launch v2 console log messages
The following is a list of all of the EC2Launch v2 console log messages.
```
Error EC2Launch service is stopping. {error message}
```
Stopped service error details:
+ `Error setting up EC2Launch agent folders`
+ `See instance logs for detail`
+ `Error stopping service`
+ `Error initializing service`
```
Windows sysprep configuration complete
```
```
Invalid administrator username: {invalid username}
```
```
Invalid administrator password
Username: {username}
Password: {encrypted password}
```
The following message is an information block that contains AMI details:
```
AMI Origin Version: {amiVersion}
AMI Origin Name: {amiName}
Microsoft Windows NT {currentVersion}.{currentBuildNumber}
OsVersion: {currentVersion}
OsProductName: {productName}
OsBuildLabEx: {buildLabEx}
OsCurrentBuild: {currentBuild}
OsReleaseId: {releaseId}
Language: {language}
TimeZone: {timeZone}
Offset: UTC {offset}
Launch agent: EC2Launch {BuildVersion}
AMI-ID: {amiId}
Instance-ID: {instanceId}
Instance Type: {instanceType}
HOSTNAME: {computer name}
RDPCERTIFICATE-SUBJECTNAME: {certificate subject name}
RDPCERTIFICATE-THUMBPRINT: {thumbprint hash}
SqlServerBilling: {sql billing}
SqlServerInstall: {sql patch leve, edition type}
Driver: AWS NVMe Driver {version}
Driver: Inbox NVMe Driver {version}
Driver: AWS PV Driver Package {version}
SSM: Amazon SSM Agent {version}
AWS VSS Version: {version}
```
```
Windows sysprep configuration complete.
Windows is being configured. 'SysprepState is {state}'
Windows is still being configured. 'SysprepState is {state}'
Windows is Ready to use
Waiting for access to metadata...
Meta-data is now available.
Metadata is not available for this instance.
Timed out waiting for access to metadata.
User data format: {format}
```
EC2Launch v2 telemetry messages include the launch telemetry property values. Starting with version 2.2.63, EC2 agent telemetry data is formatted as a JSON object.
```
EC2LaunchTelemetry: {telemetry property}
```
```
{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... }
```
# EC2Launch v2 version histories
**Topics**
+ [
## EC2Launch v2 version history
](#ec2launchv2-version-history)
## EC2Launch v2 version history
To ensure that you have the latest launch agent installed, see [Install the latest version of EC2Launch v2](ec2launch-v2-install.md). You can receive notifications when new versions of the EC2Launch v2 agent are released. For more information, see [Subscribe to EC2 Windows launch agent notifications](launch-agents-subscribe-notifications.md).
The following table describes the released versions of EC2Launch v2.
| Version | Details | Release date |
| --- | --- | --- |
| 2.4.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | March 5, 2026 |
| 2.3.237 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | February 25, 2026 |
| 2.3.108 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | December 29, 2025 |
| 2.3.56 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | November 4, 2025 |
| 2.3.5 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | September 15, 2025 |
| 2.2.63 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | July 29, 2025 |
| 2.1.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | May 14, 2025 |
| 2.0.2107 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | March 27, 2025 |
| 2.0.2081 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | February 4, 2025 |
| 2.0.2046 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | October 3, 2024 |
| 2.0.1981 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | August 6, 2024 |
| 2.0.1948 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | July 1, 2024 |
| 2.0.1924 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | June 10, 2024 |
| 2.0.1914 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | June 5, 2024 |
| 2.0.1881 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | May 8, 2024 |
| 2.0.1815 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | March 6, 2024 |
| 2.0.1739 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | January 17, 2024 |
| 2.0.1702 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | January 4, 2024 |
| 2.0.1643 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | October 4, 2023 |
| 2.0.1580 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | September 5, 2023 |
| 2.0.1521 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | July 3, 2023 |
| 2.0.1303 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | May 3, 2023 |
| 2.0.1245 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | March 8, 2023 |
| 2.0.1173 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | February 6, 2023 |
| 2.0.1121 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | January 4, 2023 |
| 2.0.1082 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | December 7, 2022 |
| 2.0.1011 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | November 11, 2022 |
| 2.0.1009 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | November 8, 2022 |
| 2.0.982 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | October 31, 2022 |
| 2.0.863 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | July 6, 2022 |
| 2.0.698 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | January 30, 2022 |
| 2.0.674 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | November 15, 2021 |
| 2.0.651 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | October 7, 2021 |
| 2.0.592 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | August 31, 2021 |
| 2.0.548 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | August 4, 2021 |
| 2.0.470 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | July 20, 2021 |
| 2.0.285 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | March 8, 2021 |
| 2.0.207 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | February 2, 2021 |
| 2.0.160 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | December 4, 2020 |
| 2.0.153 | Adds Sysprep functionality in UserData. | November 3, 2020 |
| 2.0.146 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | October 6, 2020 |
| 2.0.124 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | September 10, 2020 |
| 2.0.104 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launchv2-versions.html) | August 12, 2020 |
| 2.0.0 | Initial release. | June 30, 2020 |
# Use the EC2Launch v1 agent to perform tasks during EC2 Windows instance launch
Amazon managed AMIs for Windows Server 2016 and 2019 include a set of Windows Powershell scripts called EC2Launch. EC2Launch performs tasks during the initial instance boot. For information about the EC2Launch versions that are included in AWS Windows AMIs, see the [AWS Windows AMI Reference](https://docs.aws.amazon.com/ec2/latest/windows-ami-reference/windows-amis.html).
**Note**
The latest launch agent for Windows Server 2016 and later operating system versions is EC2Launch v2, which replaces both EC2Config and EC2Launch, and comes pre-installed on AWS Windows Server 2016 and 2019 AMIs with names that begin with `EC2LaunchV2-Windows_Server-*`. You can also manually install and configure the agent on Windows Server 2016 and 2019. For more information, see [Install EC2Launch v2](ec2launch-v2-install.md).
To use EC2Launch with IMDSv2, the version must be 1.3.2002730 or later.
You can use the following Windows PowerShell command to verify the installed version of EC2Launch.
```
Test-ModuleManifest -Path "C:\ProgramData\Amazon\EC2-Windows\Launch\Module\Ec2Launch.psd1" | Select Version
```
## EC2Launch tasks
EC2Launch performs the following tasks by default during the initial instance boot:
+ Sets up new wallpaper that renders information about the instance.
+ Sets the computer name to the private IPv4 address of the instance.
+ Sends instance information to the Amazon EC2 console.
+ Sends the RDP certificate thumbprint to the EC2 console.
+ Sets a random password for the administrator account.
+ Adds DNS suffixes.
+ Dynamically extends the operating system partition to include any unpartitioned space.
+ Executes user data (if specified). For more information about specifying user data, see [Run commands when you launch an EC2 instance with user data input](user-data.md).
+ Sets persistent static routes to reach the metadata service and AWS KMS servers.
**Important**
If a custom AMI is created from this instance, these routes are captured as part of the OS configuration and any new instances launched from the AMI will retain the same routes, regardless of subnet placement. In order to update the routes, see [Update metadata/KMS routes for Server 2016 and later when launching a custom AMI](ec2launch-sysprep.md#update-metadata-KMS).
The following tasks help to maintain backward compatibility with the EC2Config service. You can also configure EC2Launch to perform these tasks during startup:
+ Initialize secondary EBS volumes.
+ Send Windows Event logs to the EC2 console logs.
+ Send the *Windows is ready to use* message to the EC2 console.
## EC2Launch directory structure
EC2Launch is installed by default on Windows Server 2016 and later AMIs in the root directory `C:\ProgramData\Amazon\EC2-Windows\Launch`.
**Note**
By default, Windows hides files and folders under `C:\ProgramData`. To view EC2Launch directories and files, you must either type the path in Windows Explorer or change the folder properties to show hidden files and folders.
The `Launch` directory contains the following subdirectories.
+ `Scripts` — Contains the PowerShell scripts that make up EC2Launch.
+ `Module` — Contains the module for building scripts related to Amazon EC2.
+ `Config` — Contains script configuration files that you can customize.
+ `Sysprep` — Contains Sysprep resources.
+ `Settings` — Contains an application for the Sysprep graphical user interface.
+ `Library` — Contains shared libraries for EC2 launch agents.
+ `Log` — Contains subdirectories for scripts and the log files that are generated by the scripts.
## Telemetry
Telemetry is additional information that helps AWS to better understand your requirements, diagnose issues, and deliver features to improve your experience with AWS services.
EC2Launch version `1.3.2003498` and later collect telemetry, such as usage metrics and errors. This data is collected from the Amazon EC2 instance on which EC2Launch runs. This includes all Windows AMIs owned by AWS.
The following types of telemetry are collected by EC2Launch:
+ **Usage information** — agent commands, install method, and scheduled run frequency.
+ **Errors and diagnostic information** — agent installation and run error codes.
Examples of collected data:
```
2021/07/15 21:44:12Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2021/07/15 21:44:12Z: EC2LaunchTelemetry: IsUserDataScheduledPerBoot=true
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentCommandCode=1
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentCommandErrorCode=5
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentInstallCode=2
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentInstallErrorCode=0
```
Telemetry is enabled by default. You can disable telemetry collection at any time. If telemetry is enabled, EC2Launch sends telemetry data without additional customer notifications.
Your choice to enable or disable telemetry is collected.
You can opt in or out of telemetry collection. Your selection to opt in or out of telemetry is collected to ensure that we adhere to your telemetry option.
**Telemetry visibility**
When telemetry is enabled, it appears in the Amazon EC2 console output as follows:
```
2021/07/15 21:44:12Z: Telemetry:
```
**Disable telemetry on an instance**
To disable telemetry by setting a system environment variable, run the following command as an administrator:
```
setx /M EC2LAUNCH_TELEMETRY 0
```
To disable telemetry during installation, run `install.ps1` as follows:
```
. .\install.ps1 -EnableTelemetry:$false
```
**Topics**
+ [
## EC2Launch tasks
](#ec2launch-tasks)
+ [
## EC2Launch directory structure
](#ec2launch-directories)
+ [
## Telemetry
](#ec2launch-telemetry)
+ [
# Install the latest version of EC2Launch
](ec2launch-download.md)
+ [
# Configure the EC2Launch v1 agent on your Windows instance
](ec2launch-config.md)
+ [
# EC2Launch version history
](ec2launch-version-details.md)
# Install the latest version of EC2Launch
Use the following procedure to download and install the latest version of EC2Launch on your instances.
**To download and install the latest version of EC2Launch**
1. If you have already installed and configured EC2Launch on an instance, make a backup of the EC2Launch configuration file. The installation process does not preserve changes in this file. By default, the file is located in the `C:\ProgramData\Amazon\EC2-Windows\Launch\Config` directory.
1. Download [EC2-Windows-Launch.zip](https://s3.amazonaws.com/ec2-downloads-windows/EC2Launch/latest/EC2-Windows-Launch.zip) to a directory on the instance.
1. Download [install.ps1](https://s3.amazonaws.com/ec2-downloads-windows/EC2Launch/latest/install.ps1) to the same directory where you downloaded `EC2-Windows-Launch.zip`.
1. Run `install.ps1`
1. If you made a backup of the EC2Launch configuration file, copy it to the `C:\ProgramData\Amazon\EC2-Windows\Launch\Config` directory.
**To download and install the latest version of EC2Launch using PowerShell**
If you have already installed and configured EC2Launch on an instance, make a backup of the EC2Launch configuration file. The installation process does not preserve changes in this file. By default, the file is located in the `C:\ProgramData\Amazon\EC2-Windows\Launch\Config` directory.
To install the latest version of EC2Launch using PowerShell, run the following commands from a PowerShell window as an administrator:
```
mkdir $env:USERPROFILE\Desktop\EC2Launch
$Url = "https://s3.amazonaws.com/ec2-downloads-windows/EC2Launch/latest/EC2-Windows-Launch.zip"
$DownloadZipFile = "$env:USERPROFILE\Desktop\EC2Launch\" + $(Split-Path -Path $Url -Leaf)
Invoke-WebRequest -Uri $Url -OutFile $DownloadZipFile
$Url = "https://s3.amazonaws.com/ec2-downloads-windows/EC2Launch/latest/install.ps1"
$DownloadZipFile = "$env:USERPROFILE\Desktop\EC2Launch\" + $(Split-Path -Path $Url -Leaf)
Invoke-WebRequest -Uri $Url -OutFile $DownloadZipFile
& $env:USERPROFILE\Desktop\EC2Launch\install.ps1
```
**Note**
If you receive an error when downloading the file, and you are using Windows Server 2016, TLS 1.2 might need to be enabled for your PowerShell terminal. You can enable TLS 1.2 for the current PowerShell session with the following command and then try again:
```
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
```
Verify the installation by checking the launch agent. Run the following commands from a PowerShell window as an administrator:
```
Import-Module C:\ProgramData\Amazon\EC2-Windows\Launch\Module\Ec2Launch.psm1
Import-LocalizedData -BaseDirectory C:\ProgramData\Amazon\EC2-Windows\Launch\Module\ -FileName 'Ec2Launch.psd1' -BindingVariable moduleManifest
$moduleManifest.Get_Item('ModuleVersion')
```
# Configure the EC2Launch v1 agent on your Windows instance
After your instance has been initialized the first time, you can configure EC2Launch to run again and perform different start-up tasks.
**Topics**
+ [
## Configure initialization tasks
](#ec2launch-inittasks)
+ [
## Schedule EC2Launch to run on every boot
](#run-on-every-boot)
+ [
## Initialize drives and map drive letters
](#ec2launch-mapping)
+ [
## Send Windows event logs to the EC2 console
](#ec2launch-sendlogs)
+ [
## Send Windows is ready message after a successful boot
](#ec2launch-sendwinisready)
## Configure initialization tasks
Specify settings in the `LaunchConfig.json` file to enable or disable the following initialization tasks:
+ Set the computer name to the instance private IPv4 address.
+ Set the monitor to always stay on.
+ Set up new wallpaper.
+ Add DNS suffix list.
**Note**
This adds a DNS suffix lookup for the following domain and configures other standard suffixes. For more information about how launch agents set DNS suffixes, see [Configure DNS Suffix for EC2 Windows launch agents](launch-agents-set-dns.md).
```
region.ec2-utilities.amazonaws.com
```
+ Extend the boot volume size.
+ Set the administrator password.
**To configure initialization settings**
1. On the instance to configure, open the following file in a text editor: `C:\ProgramData\Amazon\EC2-Windows\Launch\Config\LaunchConfig.json`.
1. Update the following settings as needed and save your changes. Provide a password in `adminPassword` only if `adminPasswordtype` is `Specify`.
```
{
"setComputerName": false,
"setMonitorAlwaysOn": true,
"setWallpaper": true,
"addDnsSuffixList": true,
"extendBootVolumeSize": true,
"handleUserData": true,
"adminPasswordType": "Random | Specify | DoNothing",
"adminPassword": "password that adheres to your security policy (optional)"
}
```
The password types are defined as follows:
`Random`
EC2Launch generates a password and encrypts it using the user's key. The system disables this setting after the instance is launched so that this password persists if the instance is rebooted or stopped and started.
`Specify`
EC2Launch uses the password you specify in `adminPassword`. If the password does not meet the system requirements, EC2Launch generates a random password instead. The password is stored in `LaunchConfig.json` as clear text and is deleted after Sysprep sets the administrator password. EC2Launch encrypts the password using the user's key.
`DoNothing`
EC2Launch uses the password you specify in the `unattend.xml` file. If you don't specify a password in `unattend.xml`, the administrator account is disabled.
1. In Windows PowerShell, run the following command to schedule the script to run as a Windows Scheduled Task. The script runs one time during the next boot and then disables these tasks from running again.
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 -Schedule
```
## Schedule EC2Launch to run on every boot
You can schedule EC2Launch to run on every boot instead of only the initial boot.
To enable EC2Launch to run on every boot:
1. Open Windows PowerShell and run the following command:
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 -SchedulePerBoot
```
1. Or, run the executable with the following command:
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Settings\Ec2LaunchSettings.exe
```
Then select `Run EC2Launch on every boot`. You can specify that your EC2 instance `Shutdown without Sysprep` or `Shutdown with Sysprep`.
**Note**
When you enable EC2Launch to run on every boot, the following happens the next time EC2Launch runs:
If `AdminPasswordType` is still set to `Random`, EC2Launch will generate a new password at the next boot. After that boot, `AdminPasswordType` is automatically set to `DoNothing` to prevent EC2Launch from generating new passwords on subsequent boots. To prevent EC2Launch from generating a new password on the first boot, manually set `AdminPasswordType` to `DoNothing` before you reboot.
`HandleUserData` will be set back to `false` unless the user data has `persist` set to `true`. For more information, see [User data scripts](user-data.md#user-data-scripts).
## Initialize drives and map drive letters
Specify settings in the `DriveLetterMappingConfig.json` file to map drive letters to volumes on your EC2 instance. The script initializes drives that are not already initialized and partitioned. For more information about getting volume details in Windows, see [Get-Volume](https://learn.microsoft.com/en-us/powershell/module/storage/get-volume) in the Microsoft documentation.
**To map drive letters to volumes**
1. Open the `C:\ProgramData\Amazon\EC2-Windows\Launch\Config\DriveLetterMappingConfig.json` file in a text editor.
1. Specify the following volume settings and save your changes:
```
{
"driveLetterMapping": [
{
"volumeName": "sample volume",
"driveLetter": "H"
}
]
}
```
1. Open Windows PowerShell and use the following command to run the EC2Launch script that initializes the disks:
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeDisks.ps1
```
To initialize the disks each time the instance boots, add the `-Schedule` flag as follows:
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeDisks.ps1 -Schedule
```
## Send Windows event logs to the EC2 console
Specify settings in the `EventLogConfig.json` file to send Windows Event logs to EC2 console logs.
**To configure settings to send Windows Event logs**
1. On the instance, open the `C:\ProgramData\Amazon\EC2-Windows\Launch\Config\EventLogConfig.json` file in a text editor.
1. Configure the following log settings and save your changes:
```
{
"events": [
{
"logName": "System",
"source": "An event source (optional)",
"level": "Error | Warning | Information",
"numEntries": 3
}
]
}
```
1. In Windows PowerShell, run the following command so that the system schedules the script to run as a Windows Scheduled Task each time the instance boots.
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\SendEventLogs.ps1 -Schedule
```
The logs can take three minutes or more to appear in the EC2 console logs.
## Send Windows is ready message after a successful boot
The EC2Config service sent the "Windows is ready" message to the EC2 console after every boot. EC2Launch sends this message only after the initial boot. For backwards compatibility with the EC2Config service, you can schedule EC2Launch to send this message after every boot. On the instance, open Windows PowerShell and run the following command. The system schedules the script to run as a Windows Scheduled Task.
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\SendWindowsIsReady.ps1 -Schedule
```
# EC2Launch version history
To download and install the latest version of EC2Launch, see [Install the latest version of EC2Launch](ec2launch-download.md).
The following table describes the released versions of EC2Launch.
| Version | Details | Release date |
| --- | --- | --- |
| 1.4.299 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 3 March 2026 |
| 1.4.183 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 4 February 2026 |
| 1.4.6 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 13 October 2025 |
| 1.3.2005119 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 11 February 2025 |
| 1.3.2005065 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 22 October 2024 |
| 1.3.2005008 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 6 August 2024 |
| 1.3.2004959 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 2 July 2024 |
| 1.3.2004891 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 31 May 2024 |
| 1.3.2004617 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 15 January 2024 |
| 1.3.2004592 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) For more information about access permissions and user account permissions of EC2Launch directories, see [EC2Launch directory structure](ec2launch.md#ec2launch-directories). | 2 January 2024 |
| 1.3.2004491 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 9 November 2023 |
| 1.3.2004462 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 18 October 2023 |
| 1.3.2004438 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 4 October 2023 |
| 1.3.2004256 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 7 July 2023 |
| 1.3.2004052 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 8 March 2023 |
| 1.3.2003975 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 24 December 2022 |
| 1.3.2003961 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 6 December 2022 |
| 1.3.2003923 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 9 November 2022 |
| 1.3.2003919 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 8 November 2022 |
| 1.3.2003857 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 3 October 2022 |
| 1.3.2003824 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 30 August 2022 |
| 1.3.2003691 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 21 June 2022 |
| 1.3.2003639 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 10 May 2022 |
| 1.3.2003498 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 31 January 2022 |
| 1.3.2003411 | Changed password generation logic to exclude passwords with low complexity. | 04 August 2021 |
| 1.3.2003364 | Updated Install-EgpuManager with IMDSv2 support. | 07 June 2021 |
| 1.3.2003312 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 04 May 2021 |
| 1.3.2003284 | Improved permission model by updating location for storing user data to LocalAppData. | 23 March 2021 |
| 1.3.2003236 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 11 February 2021 |
| 1.3.2003210 | Localization fix for install.ps1. | 7 January 2021 |
| 1.3.2003205 | Security fix for install.ps1 to update permissions on %ProgramData%AmazonEC2-WindowsLaunchModuleScripts directory. | 28 December 2020 |
| 1.3.2003189 | Added w32tm resync after adding routes. | 4 December 2020 |
| 1.3.2003155 | Updated instance type information. | 25 August 2020 |
| 1.3.2003150 | Added OsCurrentBuild and OsReleaseId to console output . | 22 April 2020 |
| 1.3.2003040 | Fixed IMDS version 1 fallback logic. | 7 April 2020 |
| 1.3.2002730 | Added support for IMDS V2. | 3 March 2020 |
| 1.3.2002240 | Fixed minor issues. | 31 October 2019 |
| 1.3.2001660 | Fixed automatic login issue for users without password after first time executing Sysprep. | 2 July 2019 |
| 1.3.2001360 | Fixed minor issues. | 27 March 2019 |
| 1.3.2001220 | All PowerShell scripts signed. | 28 February 2019 |
| 1.3.2001200 | Fixed issue with InitializeDisks.ps1 where running the script on a node in a Windows Server Failover Cluster would format drives on remote nodes whose drive letter matched the local drive letter. | 27 February 2019 |
| 1.3.2001160 | Fixed missing wallpaper in Windows 2019. | 22 February 2019 |
| 1.3.2001040 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 21 January 2019 |
| 1.3.2000930 | Fix for adding routes to metadata on ipv6-enabled ENIs. | 2 January 2019 |
| 1.3.2000760 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 5 December 2018 |
| 1.3.2000630 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 9 November 2018 |
| 1.3.2000430.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 19 September 2018 |
| 1.3.200039.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 15 August 2018 |
| 1.3.2000080 | Fixed minor issues. | |
| 1.3.610 | Fixed issue with redirecting output and errors to files from user data. | |
| 1.3.590 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | |
| 1.3.580 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | |
| 1.3.550 | Added a `-NoShutdown` option to enable Sysprep with no shutdown. | |
| 1.3.540 | Fixed minor issues. | |
| 1.3.530 | Fixed minor issues. | |
| 1.3.521 | Fixed minor issues. | |
| 1.3.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | |
| 1.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | |
| 1.1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | |
| 1.1.1 | Initial release. | |
# Use the EC2Config service to perform tasks during EC2 legacy Windows operating system instance launch
**Note**
EC2Config has reached the end of support. The operating system versions that it runs on are no longer supported by Microsoft. We strongly recommend that you upgrade to the latest launch agent.
The latest launch agent for Windows Server 2022 and later operating system versions is [EC2Launch v2](ec2launch-v2.md), which replaces both EC2Config and EC2Launch, and comes pre-installed on AWS Windows Server 2022 and 2025 AMIs. You can also manually install and configure the agent on Windows Server 2016 and 2019. For more information, see [Install EC2Launch v2](ec2launch-v2-install.md).
Windows AMIs for Windows Server versions prior to Windows Server 2016 include an optional service, the EC2Config service (`EC2Config.exe`). EC2Config starts when the instance boots and performs tasks during startup and each time you stop or start the instance. EC2Config can also perform tasks on demand. Some of these tasks are automatically enabled, while others must be enabled manually. Although optional, this service provides access to advanced features that aren't otherwise available. This service runs in the LocalSystem account.
The EC2Config service runs Sysprep, a Microsoft tool that enables you to create a customized Windows AMI that can be reused. When EC2Config calls Sysprep, it uses the files in `%ProgramFiles%\Amazon\EC2ConfigService\Settings` to determine which operations to perform. You can edit these files indirectly using the **EC2 Service Properties** system dialog, or directly using an XML editor or a text editor. However, there are some advanced settings that aren't available in the **Ec2 Service Properties** system dialog, so you must edit those entries directly.
If you create an AMI from an instance after updating its settings, the new settings are applied to any instance that's launched from the new AMI. For information about creating an AMI, see [Create an Amazon EBS-backed AMI](creating-an-ami-ebs.md).
EC2Config uses settings files to control its operation. You can update these settings files using either a graphical tool or by directly editing XML files. The service binaries and additional files are contained in the `%ProgramFiles%\Amazon\EC2ConfigService` directory.
**Topics**
+ [
## EC2Config and AWS Systems Manager
](#ec2config-ssm)
+ [
## EC2Config tasks
](#UsingConfig_Ovw)
+ [
## EC2Config settings files
](#UsingConfigXML_WinAMI)
+ [
# Install the latest version of EC2Config
](UsingConfig_Install.md)
+ [
# Configure .NET proxy settings for the EC2Config service
](ec2config-proxy.md)
+ [
# Set EC2Config service properties from the system dialog on your EC2 Windows instance
](set-ec2config-service-properties.md)
+ [
# Troubleshoot issues with the EC2Config launch agent
](repair-ec2config.md)
+ [
# EC2Config version history
](ec2config-version-details.md)
## EC2Config and AWS Systems Manager
The EC2Config service processes Systems Manager requests on instances created from AMIs for versions of Windows Server prior to Windows Server 2016 that were published before November 2016.
Instances created from AMIs for versions of Windows Server prior to Windows Server 2016 that were published after November 2016 include the EC2Config service *and* SSM Agent. EC2Config performs all of the tasks described earlier, and SSM Agent processes requests for Systems Manager capabilities like Run Command and State Manager.
You can use Run Command to upgrade your existing instances to use to the latest version of the EC2Config service and SSM Agent. For more information, see [Update SSM Agent using Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command-tutorial-update-software.html) in the *AWS Systems Manager User Guide*.
## EC2Config tasks
EC2Config runs initial startup tasks when the instance is first started and then disables them. To run these tasks again, you must explicitly enable them prior to shutting down the instance, or by running Sysprep manually. These tasks are as follows:
+ Set a random, encrypted password for the administrator account.
+ Generate and install the host certificate used for Remote Desktop Connection.
+ Dynamically extend the operating system partition to include any unpartitioned space.
+ Execute the specified user data (and Cloud-Init, if it's installed). For more information about specifying user data, see [Run commands when you launch an EC2 instance with user data input](user-data.md).
EC2Config performs the following tasks every time the instance starts:
+ Change the host name to match the private IP address in Hex notation (this task is disabled by default and must be enabled in order to run at instance start).
+ Configure the key management server (AWS KMS), check for Windows activation status, and activate Windows as necessary.
+ Mount all Amazon EBS volumes and instance store volumes, and map volume names to drive letters.
+ Write event log entries to the console to help with troubleshooting (this task is disabled by default and must be enabled in order to run at instance start).
+ Write to the console that Windows is ready.
+ Add a custom route to the primary network adapter to enable the following IP addresses when a single NIC or multiple NICs are attached: `169.254.169.250`, `169.254.169.251`, and `169.254.169.254`. These addresses are used by Windows Activation and when you access instance metadata.
**Note**
If the Windows OS is configured to use IPv4, these IPv4 link-local addresses can be used. If the Windows OS has the IPv4 network protocol stack disabled and uses IPv6 instead, add `[fd00:ec2::250]` in place of `169.254.169.250` and `169.254.169.251`. Then add `[fd00:ec2::254]` in place of `169.254.169.254`.
EC2Config performs the following task every time a user logs in:
+ Display wallpaper information to the desktop background.
While the instance is running, you can request that EC2Config perform the following task on demand:
+ Run Sysprep and shut down the instance so that you can create an AMI from it. For more information, see [Create an Amazon EC2 AMI using Windows Sysprep](ami-create-win-sysprep.md).
## EC2Config settings files
The settings files control the operation of the EC2Config service. These files are located in the `C:\Program Files\Amazon\Ec2ConfigService\Settings` directory:
+ `ActivationSettings.xml`—Controls product activation using a key management server (AWS KMS).
+ `AWS.EC2.Windows.CloudWatch.json`—Controls which performance counters to send to CloudWatch and which logs to send to CloudWatch Logs.
+ `BundleConfig.xml`—Controls how EC2Config prepares an instance store-backed instance for AMI creation.
+ `Config.xml`—Controls the primary settings.
+ `DriveLetterConfig.xml`—Controls drive letter mappings.
+ `EventLogConfig.xml`—Controls the event log information that's displayed on the console while the instance is booting.
+ `WallpaperSettings.xml`—Controls the information that's displayed on the desktop background.
**ActivationSettings.xml**
This file contains settings that control product activation. When Windows boots, the EC2Config service checks whether Windows is already activated. If Windows is not already activated, it attempts to activate Windows by searching for the specified AWS KMS server.
+ `SetAutodiscover`—Indicates whether to detect a AWS KMS automatically.
+ `TargetKMSServer`—Stores the private IP address of a AWS KMS. The AWS KMS must be in the same Region as your instance.
+ `DiscoverFromZone`—Discovers the AWS KMS server from the specified DNS zone.
+ `ReadFromUserData`—Gets the AWS KMS server from UserData.
+ `LegacySearchZones`—Discovers the AWS KMS server from the specified DNS zone.
+ `DoActivate`—Attempts activation using the specified settings in the section. This value can be `true` or `false`.
+ `LogResultToConsole`—Displays the result to the console.
**BundleConfig.xml**
This file contains settings that control how EC2Config prepares an instance for AMI creation.
+ `AutoSysprep`—Indicates whether to use Sysprep automatically. Change the value to `Yes` to use Sysprep.
+ `SetRDPCertificate`—Sets a self-signed certificate to the Remote Desktop server. This enables you to securely RDP into the instances. Change the value to `Yes` if the new instances should have the certificate.
This setting is not used for instances with operating system versions prior to Windows Server 2016, because they can generate their own certificates.
+ `SetPasswordAfterSysprep`—Sets a random password on a newly launched instance, encrypts it with the user launch key, and outputs the encrypted password to the console. Change the value of this setting to `No` if the new instances should not be set to a random encrypted password.
**Config.xml**
*Plug-ins*
+ `Ec2SetPassword`—Generates a random encrypted password each time you launch an instance. This feature is disabled by default after the first launch so that reboots of this instance don't change a password set by the user. Change this setting to `Enabled` to continue to generate passwords each time you launch an instance.
This setting is important if you are planning to create an AMI from your instance.
+ `Ec2SetComputerName`—Sets the host name of the instance to a unique name based on the IP address of the instance and reboots the instance. To set your own host name, or prevent your existing host name from being modified, you must disable this setting.
+ `Ec2InitializeDrives`—Initializes and formats all volumes during startup. This feature is enabled by default.
+ `Ec2EventLog`—Displays event log entries in the console. By default, the three most recent error entries from the system event log are displayed. To specify the event log entries to display, edit the `EventLogConfig.xml` file located in the `EC2ConfigService\Settings` directory. For information about the settings in this file, see [Eventlog Key](https://learn.microsoft.com/en-us/windows/win32/eventlog/eventlog-key).
+ `Ec2ConfigureRDP`—Sets up a self-signed certificate on the instance, so users can securely access the instance using Remote Desktop. This setting is not used for instances with operating system versions prior to Windows Server 2016, because they can generate their own certificates.
+ `Ec2OutputRDPCert`—Displays the Remote Desktop certificate information to the console so that the user can verify it against the thumbprint.
+ `Ec2SetDriveLetter`—Sets the drive letters of the mounted volumes based on user-defined settings. By default, when an Amazon EBS volume is attached to an instance, it can be mounted using the drive letter on the instance. To specify your drive letter mappings, edit the `DriveLetterConfig.xml` file located in the `EC2ConfigService\Settings` directory.
+ `Ec2WindowsActivate`—The plug-in handles Windows activation. It checks to see if Windows is activated. If not, it updates the AWS KMS client settings, and then activates Windows.
To modify the AWS KMS settings, edit the `ActivationSettings.xml` file located in the `EC2ConfigService\Settings` directory.
+ `Ec2DynamicBootVolumeSize`—Extends Disk 0/Volume 0 to include any unpartitioned space.
+ `Ec2HandleUserData`—Creates and runs scripts created by the user on the first launch of an instance after Sysprep is run. Commands wrapped in script tags are saved to a batch file, and commands wrapped in PowerShell tags are saved to a .ps1 file (corresponds to the User Data checkbox on the Ec2 Service Properties system dialog).
+ `Ec2ElasticGpuSetup`—Installs the Elastic GPU software package if the instance is associated with an elastic GPU.
+ `Ec2FeatureLogging`—Sends Windows feature installation and corresponding service status to the console. Supported only for the Microsoft Hyper-V feature and corresponding vmms service.
*Global Settings*
+ `ManageShutdown`—Ensures that instances launched from Amazon S3-backed AMIs do not terminate while running Sysprep.
+ `SetDnsSuffixList`—Sets the DNS suffix of the network adapter for Amazon EC2. This allows DNS resolution of servers running in Amazon EC2 without providing the fully qualified domain name.
**Note**
This adds a DNS suffix lookup for the following domain and configures other standard suffixes. For more information about how launch agents set DNS suffixes, see [Configure DNS Suffix for EC2 Windows launch agents](launch-agents-set-dns.md).
```
region.ec2-utilities.amazonaws.com
```
+ `WaitForMetaDataAvailable`—Ensures that the EC2Config service will wait for metadata to be accessible and the network available before continuing with the boot. This check ensures that EC2Config can obtain information from metadata for activation and other plug-ins.
+ `ShouldAddRoutes`—Adds a custom route to the primary network adapter to enable the following IP addresses when multiple NICs are attached: 169.254.169.250, 169.254.169.251, and 169.254.169.254. These addresses are used by Windows Activation and when you access instance metadata.
+ `RemoveCredentialsfromSyspreponStartup`—Removes the administrator password from `Sysprep.xml` the next time the service starts. To ensure that this password persists, edit this setting.
**DriveLetterConfig.xml**
This file contains settings that control drive letter mappings. By default, a volume can be mapped to any available drive letter. You can mount a volume to a particular drive letter as follows.
```
. . .
```
+ `VolumeName`—The volume label. For example, `My Volume`. To specify a mapping for an instance storage volume, use the label `Temporary Storage X`, where `X` is a number from 0 to 25.
+ `DriveLetter`—The drive letter. For example, `M:`. The mapping fails if the drive letter is already in use.
**EventLogConfig.xml**
This file contains settings that control the event log information that's displayed on the console while the instance is booting. By default, we display the three most recent error entries from the System event log.
+ `Category`—The event log key to monitor.
+ `ErrorType`—The event type (for example, `Error`, `Warning`, `Information`.)
+ `NumEntries`—The number of events stored for this category.
+ `LastMessageTime`—To prevent the same message from being pushed repeatedly, the service updates this value every time it pushes a message.
+ `AppName`—The event source or application that logged the event.
**WallpaperSettings.xml**
This file contains settings that control the information that's displayed on the desktop background. The following information is displayed by default.
+ `Hostname`—Displays the computer name.
+ `Instance ID`—Displays the ID of the instance.
+ `Public IP Address`—Displays the public IP address of the instance.
+ `Private IP Address`—Displays the private IP address of the instance.
+ `Availability Zone`—Displays the Availability Zone in which the instance is running.
+ `Instance Size`—Displays the type of instance.
+ `Architecture`—Displays the setting of the `PROCESSOR_ARCHITECTURE` environment variable.
You can remove any of the information that's displayed by default by deleting its entry. You can add additional instance metadata to display as follows.
```
display_namemetadatameta-data/path
```
You can add additional System environment variables to display as follows.
```
display_nameEnvironmentVariablevariable-name
```
**InitializeDrivesSettings.xml**
This file contains settings that control how EC2Config initializes drives.
By default, EC2Config initialize drives that were not brought online with the operating system. You can customize the plugin as follows.
```
setting
```
Use a settings group to specify how you want to initialize drives:
*FormatWithTRIM*
Enables the TRIM command when formatting drives. After a drive has been formatted and initialized, the system restores TRIM configuration.
Starting with EC2Config version 3.18, the TRIM command is disabled during the disk format operation by default. This improves formatting times. Use this setting to enable TRIM during the disk format operation for EC2Config version 3.18 and later.
*FormatWithoutTRIM*
Disables the TRIM command when formatting drives and improves formatting times in Windows. After a drive has been formatted and initialized, the system restores TRIM configuration.
*DisableInitializeDrives*
Disables formatting for new drives. Use this setting to initialize drives manually.
# Install the latest version of EC2Config
**Note**
The latest launch agent for Windows Server 2022 and later operating system versions is [EC2Launch v2](ec2launch-v2.md), which replaces both EC2Config and EC2Launch. EC2Launch v2 comes pre-installed on AWS Windows Server 2022 and 2025 AMIs. You can also manually install and configure the agent on Windows Server 2016 and 2019. For more information, see [Install EC2Launch v2](ec2launch-v2-install.md).
For information about how to receive notifications for EC2Config updates, see [Subscribe to EC2 Windows launch agent notifications](launch-agents-subscribe-notifications.md). For information about the changes in each version, see the [EC2Config version history](ec2config-version-details.md).
## Before you begin
+ Verify that you have .NET framework 3.5 SP1 or greater.
+ By default, Setup replaces your settings files with default settings files during installation and restarts the EC2Config service when the installation is completed. If you changed EC2Config service settings, copy the `config.xml` file from the `%Program Files%\Amazon\Ec2ConfigService\Settings` directory. After you update the EC2Config service, you can restore this file to retain your configuration changes.
## Verify the EC2Config version
Use the following procedure to verify the version of EC2Config that is installed on your instances.
**To verify the installed version of EC2Config**
1. Launch an instance from your AMI and connect to it.
1. In Control Panel, select **Programs and Features**.
1. In the list of installed programs, look for `Ec2ConfigService`. Its version number appears in the **Version** column.
## Update EC2Config
Use the following procedure to download and install the latest version of EC2Config on your instances.
**To download and install the latest version of EC2Config**
1. Download and unzip the [EC2Config installer](https://s3.amazonaws.com/ec2-downloads-windows/EC2Config/EC2Install.zip).
1. Run `EC2Install.exe`. For a complete list of options, run `EC2Install` with the `/?` option. By default, setup displays prompts. To run the command with no prompts, use the `/quiet` option.
**Important**
To keep the custom settings from the `config.xml` file that you saved, run `EC2Install` with the `/norestart` option, restore your settings, and then restart the EC2Config service manually.
1. If you are running EC2Config version 4.0 or later, you must restart SSM Agent on the instance from the Microsoft Services snap-in.
**Note**
The updated EC2Config version information will not appear in the instance System Log or Trusted Advisor check until you reboot or stop and start your instance.
**To download and install the latest version of EC2Config using PowerShell**
To download, unzip, and install the latest version of EC2Config using PowerShell, run the following commands from a PowerShell window:
```
$Url = "https://s3.amazonaws.com/ec2-downloads-windows/EC2Config/EC2Install.zip"
$DownloadZipFile = "$env:USERPROFILE\Desktop\" + $(Split-Path -Path $Url -Leaf)
$ExtractPath = "$env:USERPROFILE\Desktop\"
Invoke-WebRequest -Uri $Url -OutFile $DownloadZipFile
$ExtractShell = New-Object -ComObject Shell.Application
$ExtractFiles = $ExtractShell.Namespace($DownloadZipFile).Items()
$ExtractShell.NameSpace($ExtractPath).CopyHere($ExtractFiles)
Start-Process $ExtractPath
Start-Process `
-FilePath $env:USERPROFILE\Desktop\EC2Install.exe `
-ArgumentList "/S"
```
**Note**
If you receive an error when downloading the file, and you are using Windows Server 2016 or earlier, TLS 1.2 might need to be enabled for your PowerShell terminal. You can enable TLS 1.2 for the current PowerShell session with the following command and then try again:
```
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
```
Verify the installation by checking `C:\Program Files\Amazon\` for the `Ec2ConfigService` directory.
# Configure .NET proxy settings for the EC2Config service
You can configure the EC2Config service to communicate through a proxy using one of the following methods: the AWS SDK for .NET, the `system.net` element, or Microsoft Group Policy and Internet Explorer. Using the AWS SDK for .NET is the preferred method because you can specify sign-in credentials.
**Topics**
+ [
## Configure proxy settings using the AWS SDK for .NET (Preferred)
](#sdk-proxy)
+ [
## Configure proxy settings using the system.net element
](#system-proxy)
+ [
## Configure proxy settings using Microsoft Group Policy and Microsoft Internet Explorer
](#ie-proxy)
## Configure proxy settings using the AWS SDK for .NET (Preferred)
You can configure proxy settings for the EC2Config service by specifying the `proxy` element in the `Ec2Config.exe.config` file. For more information, see [Configuration Files Reference for AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config-ref.html#net-dg-config-ref-elements-proxy).
**To specify the proxy element in Ec2Config.exe.config**
1. Edit the `Ec2Config.exe.config` file on an instance where you want the EC2Config service to communicate through a proxy. By default, the file is located in the following directory: `%ProgramFiles%\Amazon\Ec2ConfigService`.
1. Add the following `aws` element to the `configSections`. Do not add this to any existing `sectionGroups`.
**For EC2Config versions 3.17 or earlier**
```
```
**For EC2Config versions 3.18 or later**
```
```
1. Add the following `aws` element to the `Ec2Config.exe.config` file.
```
```
1. Save your changes.
## Configure proxy settings using the system.net element
You can specify proxy settings in a `system.net` element in the `Ec2Config.exe.config` file. For more information, see [defaultProxy element (network settings)](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/network/defaultproxy-element-network-settings).
**To specify the system.net element in Ec2Config.exe.config**
1. Edit the `Ec2Config.exe.config` file on an instance where you want the EC2Config service to communicate through a proxy. By default, the file is located in the following directory: `%ProgramFiles%\Amazon\Ec2ConfigService`.
1. Add a `defaultProxy` entry to `system.net`. For more information, see [defaultProxy element (network settings)](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/network/defaultproxy-element-network-settings).
For example, the following configuration routes all traffic to use the proxy that is currently configured for Internet Explorer, with the exception of the metadata and licensing traffic, which will bypass the proxy.
```
```
1. Save your changes.
## Configure proxy settings using Microsoft Group Policy and Microsoft Internet Explorer
The EC2Config service runs under the Local System user account. You can specify instance-wide proxy settings for this account in Internet Explorer after you change Group Policy settings on the instance.
**To configure proxy settings using Group Policy and Internet Explorer**
1. On an instance where you want the EC2Config service to communicate through a proxy, open a Command prompt as an Administrator, type **gpedit.msc**, and press Enter.
1. In the Local Group Policy Editor, under **Local Computer Policy**, choose **Computer Configuration**, **Administrative Templates**, **Windows Components**, **Internet Explorer**.
1. In the right-pane, choose **Make proxy settings per-machine (rather than per-user)** and then choose **Edit policy setting**.
1. Choose **Enabled**, and then choose **Apply**.
1. Open Internet Explorer, and then choose the **Tools** button.
1. Choose **Internet Option**, and then choose the **Connections** tab.
1. Choose **LAN settings**.
1. Under **Proxy server**, choose the **Use a proxy server for your LAN** option.
1. Specify address and port information and then choose **OK**.
# Set EC2Config service properties from the system dialog on your EC2 Windows instance
The following procedure describes how to use the **EC2 Service Properties** system dialog to enable or disable settings.
1. Launch and connect to your Windows instance.
1. From the **Start** menu, click **All Programs**, and then click **EC2ConfigService Settings**.
![\[EC2Config service properties shown in the General tab.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/EC2ConfigProperties_General.png)
1. On the **General** tab of the **EC2 Service Properties** system dialog, you can enable or disable the following settings.
**Set Computer Name**
If this setting is enabled (it is disabled by default), the host name is compared to the current internal IP address at each boot; if the host name and internal IP address do not match, the host name is reset to contain the internal IP address and then the system reboots to pick up the new host name. To set your own host name, or to prevent your existing host name from being modified, do not enable this setting.
**User Data**
User data execution enables you to specify scripts in the instance metadata. By default, these scripts are run during the initial launch. You can also configure them to run the next time you reboot or start the instance, or every time you reboot or start the instance.
If you have a large script, we recommend that you use user data to download the script, and then run it.
For more information, see [User data execution](user-data.md#user-data-execution).
**Event Log**
Use this setting to display event log entries on the console during boot for easy monitoring and debugging.
Click **Settings** to specify filters for the log entries sent to the console. The default filter sends the three most recent error entries from the system event log to the console.
**Wallpaper Information**
Use this setting to display system information on the desktop background. The following is an example of the information displayed on the desktop background.
![\[Wallpaper Information displayed on the desktop background.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/EC2ConfigProperties_Wallpaper.png)
The information displayed on the desktop background is controlled by the settings file `EC2ConfigService\Settings\WallpaperSettings.xml`.
**Enable Hibernation**
Use this setting to allow EC2 to signal the operating system to perform hibernation.
1. Click the **Storage** tab. You can enable or disable the following settings.
![\[Storage tab within EC2 Service Properties.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/EC2ConfigProperties_Storage.png)
**Root Volume**
This setting dynamically extends Disk 0/Volume 0 to include any unpartitioned space. This can be useful when the instance is booted from a root volume that has a custom size.
**Initialize Drives**
This setting formats and mounts all volumes attached to the instance during start.
**Drive Letter Mapping**
The system maps the volumes attached to an instance to drive letters. For Amazon EBS volumes, the default is to assign drive letters going from D: to Z:. For instance store volumes, the default depends on the driver. AWS PV drivers and Citrix PV drivers assign instance store volumes drive letters going from Z: to A:. Red Hat drivers assign instance store volumes drive letters going from D: to Z:.
To choose the drive letters for your volumes, click **Mappings**. In the **DriveLetterSetting** dialog box, specify the **Volume Name** and **Drive Letter** values for each volume, click **Apply**, and then click **OK**. We recommend that you select drive letters that avoid conflicts with drive letters that are likely to be in use, such as drive letters in the middle of the alphabet.
![\[DriveLetterSetting dialog box.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/EC2ConfigProperties_driver_letter_mapping.png)
After you specify a drive letter mapping and attach a volume with same label as one of the volume names that you specified, EC2Config automatically assigns your specified drive letter to that volume. However, the drive letter mapping fails if the drive letter is already in use. Note that EC2Config doesn't change the drive letters of volumes that were already mounted when you specified the drive letter mapping.
1. To save your settings and continue working on them later, click **OK** to close the **EC2 Service Properties** system dialog. If you have finished customizing your instance and want to create an AMI from that instance, see [Create an Amazon EC2 AMI using Windows Sysprep](ami-create-win-sysprep.md).
# Troubleshoot issues with the EC2Config launch agent
The following information can help you troubleshoot issues with the EC2Config service.
## Update EC2Config on an unreachable instance
Use the following procedure to update the EC2Config service on a Windows Server instance that is inaccessible using Remote Desktop.
**To update EC2Config on an Amazon EBS-backed Windows instance that you can't connect to**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Locate the affected instance. Select the instance and choose **Instance state**, and then choose **Stop instance**.
**Warning**
When you stop an instance, the data on instance store volumes is lost. To preserve this data, back it up to persistent storage.
1. Choose **Launch instances** and create a temporary `t2.micro` instance in the same Availability Zone as the affected instance. Use a different AMI than the one that you used to launch the affected instance.
**Important**
If you do not create the instance in the same Availability Zone as the affected instance you will not be able to attach the root volume of the affected instance to the new instance.
1. In the EC2 console, choose **Volumes**.
1. Locate the root volume of the affected instance. Detach the volume and then attach the volume to the temporary instance that you created earlier. Attach it with the default device name (xvdf).
1. Use Remote Desktop to connect to the temporary instance, and then use the Disk Management utility to make the volume available for use.
1. [Download](https://s3.amazonaws.com/ec2-downloads-windows/EC2Config/EC2Install.zip) the latest version of the EC2Config service. Extract the files from the `.zip` file to the `Temp` directory on the drive you attached.
1. On the temporary instance, open the Run dialog box, type **regedit**, and press Enter.
1. Choose `HKEY_LOCAL_MACHINE`. From the **File** menu, choose **Load Hive**. Choose the drive and then navigate to and open the following file: `Windows\System32\config\SOFTWARE`. When prompted, specify a key name.
1. Select the key you just loaded and navigate to `Microsoft\Windows\CurrentVersion`. Choose the `RunOnce` key. If this key doesn't exist, choose `CurrentVersion` from the context (right-click) menu, choose **New** and then choose **Key**. Name the key `RunOnce`.
1. From the context (right-click) menu choose the `RunOnce` key, choose **New** and then choose **String Value**. Enter `Ec2Install` as the name and `C:\Temp\Ec2Install.exe /quiet` as the data.
1. Choose the `HKEY_LOCAL_MACHINE\specified key name\Microsoft\Windows NT\CurrentVersion\Winlogon` key. From the context (right-click) menu choose **New**, and then choose **String Value**. Enter **AutoAdminLogon** as the name and **1** as the value data.
1. Choose the `HKEY_LOCAL_MACHINE\specified key name\Microsoft\Windows NT\CurrentVersion\Winlogon>` key. From the context (right-click) menu choose **New**, and then choose **String Value**. Enter **DefaultUserName** as the name and **Administrator** as the value data.
1. Choose the `HKEY_LOCAL_MACHINE\specified key name\Microsoft\Windows NT\CurrentVersion\Winlogon` key. From the context (right-click) menu choose **New**, and then choose **String Value**. Type **DefaultPassword** as the name and enter a password in the value data.
1. In the Registry Editor navigation pane, choose the temporary key that you created when you first opened Registry Editor.
1. From the **File** menu, choose **Unload Hive**.
1. In Disk Management Utility, choose the drive you attached earlier, open the context (right-click) menu, and choose **Offline**.
1. In the Amazon EC2 console, detach the affected volume from the temporary instance and reattach it to your instance with the device name `/dev/sda1`. You must specify this device name to designate the volume as a root volume.
1. [Stop and start Amazon EC2 instances](Stop_Start.md) the instance.
1. After the instance starts, check the system log and verify that you see the message Windows is ready to use.
1. Open Registry Editor and choose `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon`. Delete the String Value keys you created earlier: **AutoAdminLogon**, **DefaultUserName**, and **DefaultPassword**.
1. Delete or stop the temporary instance you created in this procedure.
# EC2Config version history
The following table describes the released versions of EC2Config. For information about the updates for SSM Agent, see [Systems Manager SSM Agent Release Notes](https://github.com/aws/amazon-ssm-agent/blob/master/RELEASENOTES.md).
**Important**
EC2Config has reached the end of support. Only the latest version of the EC2Config agent is available for download. Prior versions are marked as private.
| Version | Details | Release date |
| --- | --- | --- |
| 4.9.5777 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 17 June 2024 |
| 4.9.5554 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 4 October 2023 |
| 4.9.5467 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 1 August 2023 |
| 4.9.5288 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 8 March 2023 |
| 4.9.5231 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 14 February 2023 |
| 4.9.5103 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 5 December 2022 |
| 4.9.5064 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 16 November 2022 |
| 4.9.4588 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 31 May 2022 |
| 4.9.4556 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 1 March 2022 |
| 4.9.4536 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 31 January 2022 |
| 4.9.4508 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 6 October 2021 |
| 4.9.4500 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 7 September 2021 |
| 4.9.4419 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 2 June 2021 |
| 4.9.4381 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 4 May 2021 |
| 4.9.4326 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 3 March 2021 |
| 4.9.4279 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 11 December 2020 |
| 4.9.4222 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 7 April 2020 |
| 4.9.4122 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 4 March 2020 |
| 4.9.3865 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 31 October 2019 |
| 4.9.3519 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 18 June 2019 |
| 4.9.3429 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 25 April 2019 |
| 4.9.3289 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 11 February 2019 |
| 4.9.3270 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 22 January 2019 |
| 4.9.3230 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 10 January 2019 |
| 4.9.3160 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 15 December 2018 |
| 4.9.3067 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 8 November 2018 |
| 4.9.3034 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 24 October 2018 |
| 4.9.2986 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 11 October 2018 |
| 4.9.2953 | New version of SSM Agent (2.3.117.0) | 2 October 2018 |
| 4.9.2926 | New version of SSM Agent (2.3.68.0) | 18 September 2018 |
| 4.9.2905 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 17 September 2018 |
| 4.9.2854 | New version of SSM Agent (2.3.13.0) | 17 August 2018 |
| 4.9.2831 | New version of SSM Agent (2.2.916.0) | 7 August 2018 |
| 4.9.2818 | New version of SSM Agent (2.2.902.0) | 31 July 2018 |
| 4.9.2756 | New version of SSM Agent (2.2.800.0) | 27 June 2018 |
| 4.9.2688 | New version of SSM Agent (2.2.607.0) | 25 May 2018 |
| 4.9.2660 | New version of SSM Agent (2.2.546.0) | 11 May 2018 |
| 4.9.2644 | New version of SSM Agent (2.2.493.0) | 26 April 2018 |
| 4.9.2586 | New version of SSM Agent (2.2.392.0) | 28 March 2018 |
| 4.9.2565 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 13 March 2018 |
| 4.9.2549 | New version of SSM Agent (2.2.325.0) | 8 March 2018 |
| 4.9.2461 | New version of SSM Agent (2.2.257.0) | 15 February 2018 |
| 4.9.2439 | New version of SSM Agent (2.2.191.0) | 6 February 2018 |
| 4.9.2400 | New version of SSM Agent (2.2.160.0) | 16 January 2018 |
| 4.9.2327 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 2 January 2018 |
| 4.9.2294 | New version of SSM Agent (2.2.103.0) | 4 December 2017 |
| 4.9.2262 | New version of SSM Agent (2.2.93.0) | 15 November 2017 |
| 4.9.2246 | New version of SSM Agent (2.2.82.0) | 11 November 2017 |
| 4.9.2218 | New version of SSM Agent (2.2.64.0) | 29 October 2017 |
| 4.9.2212 | New version of SSM Agent (2.2.58.0) | 23 October 2017 |
| 4.9.2203 | New version of SSM Agent (2.2.45.0) | 19 October 2017 |
| 4.9.2188 | New version of SSM Agent (2.2.30.0) | 10 October 2017 |
| 4.9.2180 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | 5 October 2017 |
| 4.9.2143 | New version of SSM Agent (2.2.16.0) | 1 October 2017 |
| 4.9.2140 | New version of SSM Agent (2.1.10.0) | |
| 4.9.2130 | New version of SSM Agent (2.1.4.0) | |
| 4.9.2106 | New version of SSM Agent (2.0.952.0) | |
| 4.9.2061 | New version of SSM Agent (2.0.922.0) | |
| 4.9.2047 | New version of SSM Agent (2.0.913.0) | |
| 4.9.2031 | New version of SSM Agent (2.0.902.0) | |
| 4.9.2016 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 4.9.1981 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 4.9.1964 | New version of SSM Agent (2.0.842.0) | |
| 4.9.1951 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 4.9.1925 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 4.9.1900 | New version of SSM Agent (2.0.805.0) | |
| 4.9.1876 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 4.9.1863 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 4.9.1791 | New version of SSM Agent (2.0.767.0) | |
| 4.9.1775 | New version of SSM Agent (2.0.761.0) | |
| 4.9.1752 | New version of SSM Agent (2.0.755.0) | |
| 4.9.1711 | New version of SSM Agent (2.0.730.0) | |
| 4.8.1676 | New version of SSM Agent (2.0.716.0) | |
| 4.7.1631 | New version of SSM Agent (2.0.682.0) | |
| 4.6.1579 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 4.5.1534 | New version of SSM Agent (2.0.645.1) | |
| 4.4.1503 | New version of SSM Agent (2.0.633.0) | |
| 4.3.1472 | New version of SSM Agent (2.0.617.1) | |
| 4.2.1442 | New version of SSM Agent (2.0.599.0) | |
| 4.1.1378 | New version of SSM Agent (2.0.558.0) | |
| 4.0.1343 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 3.19.1153 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 3.18.1118 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 3.17.1032 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2config-version-details.html) | |
| 3.16.930 | Added support to log "Window is Ready to use" event to Windows Event Log on start. | |
| 3.15.880 | Fix to allow uploading Systems Manager Run Command output to S3 bucket names with '.' character. | |
| 3.14.786 | Added support to override InitializeDisks plugin settings. For example: To speed up SSD disk initialize, you can temporarily disable TRIM by specifying this in userdata: FormatWithoutTRIM