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