# Use the EC2Launch v1 agent to perform tasks during EC2 Windows instance launch
Amazon managed AMIs for Windows Server 2016 and 2019 include a set of Windows Powershell scripts called EC2Launch. EC2Launch performs tasks during the initial instance boot. For information about the EC2Launch versions that are included in AWS Windows AMIs, see the [AWS Windows AMI Reference](https://docs.aws.amazon.com/ec2/latest/windows-ami-reference/windows-amis.html).
**Note**
The latest launch agent for Windows Server 2016 and later operating system versions is EC2Launch v2, which replaces both EC2Config and EC2Launch, and comes pre-installed on AWS Windows Server 2016 and 2019 AMIs with names that begin with `EC2LaunchV2-Windows_Server-*`. You can also manually install and configure the agent on Windows Server 2016 and 2019. For more information, see [Install EC2Launch v2](ec2launch-v2-install.md).
To use EC2Launch with IMDSv2, the version must be 1.3.2002730 or later.
You can use the following Windows PowerShell command to verify the installed version of EC2Launch.
```
Test-ModuleManifest -Path "C:\ProgramData\Amazon\EC2-Windows\Launch\Module\Ec2Launch.psd1" | Select Version
```
## EC2Launch tasks
EC2Launch performs the following tasks by default during the initial instance boot:
+ Sets up new wallpaper that renders information about the instance.
+ Sets the computer name to the private IPv4 address of the instance.
+ Sends instance information to the Amazon EC2 console.
+ Sends the RDP certificate thumbprint to the EC2 console.
+ Sets a random password for the administrator account.
+ Adds DNS suffixes.
+ Dynamically extends the operating system partition to include any unpartitioned space.
+ Executes user data (if specified). For more information about specifying user data, see [Run commands when you launch an EC2 instance with user data input](user-data.md).
+ Sets persistent static routes to reach the metadata service and AWS KMS servers.
**Important**
If a custom AMI is created from this instance, these routes are captured as part of the OS configuration and any new instances launched from the AMI will retain the same routes, regardless of subnet placement. In order to update the routes, see [Update metadata/KMS routes for Server 2016 and later when launching a custom AMI](ec2launch-sysprep.md#update-metadata-KMS).
The following tasks help to maintain backward compatibility with the EC2Config service. You can also configure EC2Launch to perform these tasks during startup:
+ Initialize secondary EBS volumes.
+ Send Windows Event logs to the EC2 console logs.
+ Send the *Windows is ready to use* message to the EC2 console.
## EC2Launch directory structure
EC2Launch is installed by default on Windows Server 2016 and later AMIs in the root directory `C:\ProgramData\Amazon\EC2-Windows\Launch`.
**Note**
By default, Windows hides files and folders under `C:\ProgramData`. To view EC2Launch directories and files, you must either type the path in Windows Explorer or change the folder properties to show hidden files and folders.
The `Launch` directory contains the following subdirectories.
+ `Scripts` — Contains the PowerShell scripts that make up EC2Launch.
+ `Module` — Contains the module for building scripts related to Amazon EC2.
+ `Config` — Contains script configuration files that you can customize.
+ `Sysprep` — Contains Sysprep resources.
+ `Settings` — Contains an application for the Sysprep graphical user interface.
+ `Library` — Contains shared libraries for EC2 launch agents.
+ `Log` — Contains subdirectories for scripts and the log files that are generated by the scripts.
## Telemetry
Telemetry is additional information that helps AWS to better understand your requirements, diagnose issues, and deliver features to improve your experience with AWS services.
EC2Launch version `1.3.2003498` and later collect telemetry, such as usage metrics and errors. This data is collected from the Amazon EC2 instance on which EC2Launch runs. This includes all Windows AMIs owned by AWS.
The following types of telemetry are collected by EC2Launch:
+ **Usage information** — agent commands, install method, and scheduled run frequency.
+ **Errors and diagnostic information** — agent installation and run error codes.
Examples of collected data:
```
2021/07/15 21:44:12Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2021/07/15 21:44:12Z: EC2LaunchTelemetry: IsUserDataScheduledPerBoot=true
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentCommandCode=1
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentCommandErrorCode=5
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentInstallCode=2
2021/07/15 21:44:12Z: EC2LaunchTelemetry: AgentInstallErrorCode=0
```
Telemetry is enabled by default. You can disable telemetry collection at any time. If telemetry is enabled, EC2Launch sends telemetry data without additional customer notifications.
Your choice to enable or disable telemetry is collected.
You can opt in or out of telemetry collection. Your selection to opt in or out of telemetry is collected to ensure that we adhere to your telemetry option.
**Telemetry visibility**
When telemetry is enabled, it appears in the Amazon EC2 console output as follows:
```
2021/07/15 21:44:12Z: Telemetry:
```
**Disable telemetry on an instance**
To disable telemetry by setting a system environment variable, run the following command as an administrator:
```
setx /M EC2LAUNCH_TELEMETRY 0
```
To disable telemetry during installation, run `install.ps1` as follows:
```
. .\install.ps1 -EnableTelemetry:$false
```
**Topics**
+ [EC2Launch tasks](#ec2launch-tasks)
+ [EC2Launch directory structure](#ec2launch-directories)
+ [Telemetry](#ec2launch-telemetry)
+ [Install the latest version of EC2Launch](ec2launch-download.md)
+ [Configure the EC2Launch v1 agent on your Windows instance](ec2launch-config.md)
+ [EC2Launch version history](ec2launch-version-details.md)
# Install the latest version of EC2Launch
Use the following procedure to download and install the latest version of EC2Launch on your instances.
**To download and install the latest version of EC2Launch**
1. If you have already installed and configured EC2Launch on an instance, make a backup of the EC2Launch configuration file. The installation process does not preserve changes in this file. By default, the file is located in the `C:\ProgramData\Amazon\EC2-Windows\Launch\Config` directory.
1. Download [EC2-Windows-Launch.zip](https://s3.amazonaws.com/ec2-downloads-windows/EC2Launch/latest/EC2-Windows-Launch.zip) to a directory on the instance.
1. Download [install.ps1](https://s3.amazonaws.com/ec2-downloads-windows/EC2Launch/latest/install.ps1) to the same directory where you downloaded `EC2-Windows-Launch.zip`.
1. Run `install.ps1`
1. If you made a backup of the EC2Launch configuration file, copy it to the `C:\ProgramData\Amazon\EC2-Windows\Launch\Config` directory.
**To download and install the latest version of EC2Launch using PowerShell**
If you have already installed and configured EC2Launch on an instance, make a backup of the EC2Launch configuration file. The installation process does not preserve changes in this file. By default, the file is located in the `C:\ProgramData\Amazon\EC2-Windows\Launch\Config` directory.
To install the latest version of EC2Launch using PowerShell, run the following commands from a PowerShell window as an administrator:
```
mkdir $env:USERPROFILE\Desktop\EC2Launch
$Url = "https://s3.amazonaws.com/ec2-downloads-windows/EC2Launch/latest/EC2-Windows-Launch.zip"
$DownloadZipFile = "$env:USERPROFILE\Desktop\EC2Launch\" + $(Split-Path -Path $Url -Leaf)
Invoke-WebRequest -Uri $Url -OutFile $DownloadZipFile
$Url = "https://s3.amazonaws.com/ec2-downloads-windows/EC2Launch/latest/install.ps1"
$DownloadZipFile = "$env:USERPROFILE\Desktop\EC2Launch\" + $(Split-Path -Path $Url -Leaf)
Invoke-WebRequest -Uri $Url -OutFile $DownloadZipFile
& $env:USERPROFILE\Desktop\EC2Launch\install.ps1
```
**Note**
If you receive an error when downloading the file, and you are using Windows Server 2016, TLS 1.2 might need to be enabled for your PowerShell terminal. You can enable TLS 1.2 for the current PowerShell session with the following command and then try again:
```
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
```
Verify the installation by checking the launch agent. Run the following commands from a PowerShell window as an administrator:
```
Import-Module C:\ProgramData\Amazon\EC2-Windows\Launch\Module\Ec2Launch.psm1
Import-LocalizedData -BaseDirectory C:\ProgramData\Amazon\EC2-Windows\Launch\Module\ -FileName 'Ec2Launch.psd1' -BindingVariable moduleManifest
$moduleManifest.Get_Item('ModuleVersion')
```
# Configure the EC2Launch v1 agent on your Windows instance
After your instance has been initialized the first time, you can configure EC2Launch to run again and perform different start-up tasks.
**Topics**
+ [Configure initialization tasks](#ec2launch-inittasks)
+ [Schedule EC2Launch to run on every boot](#run-on-every-boot)
+ [Initialize drives and map drive letters](#ec2launch-mapping)
+ [Send Windows event logs to the EC2 console](#ec2launch-sendlogs)
+ [Send Windows is ready message after a successful boot](#ec2launch-sendwinisready)
## Configure initialization tasks
Specify settings in the `LaunchConfig.json` file to enable or disable the following initialization tasks:
+ Set the computer name to the instance private IPv4 address.
+ Set the monitor to always stay on.
+ Set up new wallpaper.
+ Add DNS suffix list.
**Note**
This adds a DNS suffix lookup for the following domain and configures other standard suffixes. For more information about how launch agents set DNS suffixes, see [Configure DNS Suffix for EC2 Windows launch agents](launch-agents-set-dns.md).
```
region.ec2-utilities.amazonaws.com
```
+ Extend the boot volume size.
+ Set the administrator password.
**To configure initialization settings**
1. On the instance to configure, open the following file in a text editor: `C:\ProgramData\Amazon\EC2-Windows\Launch\Config\LaunchConfig.json`.
1. Update the following settings as needed and save your changes. Provide a password in `adminPassword` only if `adminPasswordtype` is `Specify`.
```
{
"setComputerName": false,
"setMonitorAlwaysOn": true,
"setWallpaper": true,
"addDnsSuffixList": true,
"extendBootVolumeSize": true,
"handleUserData": true,
"adminPasswordType": "Random | Specify | DoNothing",
"adminPassword": "password that adheres to your security policy (optional)"
}
```
The password types are defined as follows:
`Random`
EC2Launch generates a password and encrypts it using the user's key. The system disables this setting after the instance is launched so that this password persists if the instance is rebooted or stopped and started.
`Specify`
EC2Launch uses the password you specify in `adminPassword`. If the password does not meet the system requirements, EC2Launch generates a random password instead. The password is stored in `LaunchConfig.json` as clear text and is deleted after Sysprep sets the administrator password. EC2Launch encrypts the password using the user's key.
`DoNothing`
EC2Launch uses the password you specify in the `unattend.xml` file. If you don't specify a password in `unattend.xml`, the administrator account is disabled.
1. In Windows PowerShell, run the following command to schedule the script to run as a Windows Scheduled Task. The script runs one time during the next boot and then disables these tasks from running again.
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 -Schedule
```
## Schedule EC2Launch to run on every boot
You can schedule EC2Launch to run on every boot instead of only the initial boot.
To enable EC2Launch to run on every boot:
1. Open Windows PowerShell and run the following command:
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 -SchedulePerBoot
```
1. Or, run the executable with the following command:
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Settings\Ec2LaunchSettings.exe
```
Then select `Run EC2Launch on every boot`. You can specify that your EC2 instance `Shutdown without Sysprep` or `Shutdown with Sysprep`.
**Note**
When you enable EC2Launch to run on every boot, the following happens the next time EC2Launch runs:
If `AdminPasswordType` is still set to `Random`, EC2Launch will generate a new password at the next boot. After that boot, `AdminPasswordType` is automatically set to `DoNothing` to prevent EC2Launch from generating new passwords on subsequent boots. To prevent EC2Launch from generating a new password on the first boot, manually set `AdminPasswordType` to `DoNothing` before you reboot.
`HandleUserData` will be set back to `false` unless the user data has `persist` set to `true`. For more information, see [User data scripts](user-data.md#user-data-scripts).
## Initialize drives and map drive letters
Specify settings in the `DriveLetterMappingConfig.json` file to map drive letters to volumes on your EC2 instance. The script initializes drives that are not already initialized and partitioned. For more information about getting volume details in Windows, see [Get-Volume](https://learn.microsoft.com/en-us/powershell/module/storage/get-volume) in the Microsoft documentation.
**To map drive letters to volumes**
1. Open the `C:\ProgramData\Amazon\EC2-Windows\Launch\Config\DriveLetterMappingConfig.json` file in a text editor.
1. Specify the following volume settings and save your changes:
```
{
"driveLetterMapping": [
{
"volumeName": "sample volume",
"driveLetter": "H"
}
]
}
```
1. Open Windows PowerShell and use the following command to run the EC2Launch script that initializes the disks:
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeDisks.ps1
```
To initialize the disks each time the instance boots, add the `-Schedule` flag as follows:
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeDisks.ps1 -Schedule
```
## Send Windows event logs to the EC2 console
Specify settings in the `EventLogConfig.json` file to send Windows Event logs to EC2 console logs.
**To configure settings to send Windows Event logs**
1. On the instance, open the `C:\ProgramData\Amazon\EC2-Windows\Launch\Config\EventLogConfig.json` file in a text editor.
1. Configure the following log settings and save your changes:
```
{
"events": [
{
"logName": "System",
"source": "An event source (optional)",
"level": "Error | Warning | Information",
"numEntries": 3
}
]
}
```
1. In Windows PowerShell, run the following command so that the system schedules the script to run as a Windows Scheduled Task each time the instance boots.
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\SendEventLogs.ps1 -Schedule
```
The logs can take three minutes or more to appear in the EC2 console logs.
## Send Windows is ready message after a successful boot
The EC2Config service sent the "Windows is ready" message to the EC2 console after every boot. EC2Launch sends this message only after the initial boot. For backwards compatibility with the EC2Config service, you can schedule EC2Launch to send this message after every boot. On the instance, open Windows PowerShell and run the following command. The system schedules the script to run as a Windows Scheduled Task.
```
C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\SendWindowsIsReady.ps1 -Schedule
```
# EC2Launch version history
To download and install the latest version of EC2Launch, see [Install the latest version of EC2Launch](ec2launch-download.md).
The following table describes the released versions of EC2Launch.
| Version | Details | Release date |
| --- | --- | --- |
| 1.4.299 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 3 March 2026 |
| 1.4.183 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 4 February 2026 |
| 1.4.6 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 13 October 2025 |
| 1.3.2005119 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 11 February 2025 |
| 1.3.2005065 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 22 October 2024 |
| 1.3.2005008 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 6 August 2024 |
| 1.3.2004959 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 2 July 2024 |
| 1.3.2004891 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 31 May 2024 |
| 1.3.2004617 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 15 January 2024 |
| 1.3.2004592 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) For more information about access permissions and user account permissions of EC2Launch directories, see [EC2Launch directory structure](ec2launch.md#ec2launch-directories). | 2 January 2024 |
| 1.3.2004491 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 9 November 2023 |
| 1.3.2004462 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 18 October 2023 |
| 1.3.2004438 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 4 October 2023 |
| 1.3.2004256 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 7 July 2023 |
| 1.3.2004052 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 8 March 2023 |
| 1.3.2003975 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 24 December 2022 |
| 1.3.2003961 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 6 December 2022 |
| 1.3.2003923 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 9 November 2022 |
| 1.3.2003919 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 8 November 2022 |
| 1.3.2003857 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 3 October 2022 |
| 1.3.2003824 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 30 August 2022 |
| 1.3.2003691 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 21 June 2022 |
| 1.3.2003639 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 10 May 2022 |
| 1.3.2003498 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 31 January 2022 |
| 1.3.2003411 | Changed password generation logic to exclude passwords with low complexity. | 04 August 2021 |
| 1.3.2003364 | Updated Install-EgpuManager with IMDSv2 support. | 07 June 2021 |
| 1.3.2003312 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 04 May 2021 |
| 1.3.2003284 | Improved permission model by updating location for storing user data to LocalAppData. | 23 March 2021 |
| 1.3.2003236 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 11 February 2021 |
| 1.3.2003210 | Localization fix for install.ps1. | 7 January 2021 |
| 1.3.2003205 | Security fix for install.ps1 to update permissions on %ProgramData%AmazonEC2-WindowsLaunchModuleScripts directory. | 28 December 2020 |
| 1.3.2003189 | Added w32tm resync after adding routes. | 4 December 2020 |
| 1.3.2003155 | Updated instance type information. | 25 August 2020 |
| 1.3.2003150 | Added OsCurrentBuild and OsReleaseId to console output . | 22 April 2020 |
| 1.3.2003040 | Fixed IMDS version 1 fallback logic. | 7 April 2020 |
| 1.3.2002730 | Added support for IMDS V2. | 3 March 2020 |
| 1.3.2002240 | Fixed minor issues. | 31 October 2019 |
| 1.3.2001660 | Fixed automatic login issue for users without password after first time executing Sysprep. | 2 July 2019 |
| 1.3.2001360 | Fixed minor issues. | 27 March 2019 |
| 1.3.2001220 | All PowerShell scripts signed. | 28 February 2019 |
| 1.3.2001200 | Fixed issue with InitializeDisks.ps1 where running the script on a node in a Windows Server Failover Cluster would format drives on remote nodes whose drive letter matched the local drive letter. | 27 February 2019 |
| 1.3.2001160 | Fixed missing wallpaper in Windows 2019. | 22 February 2019 |
| 1.3.2001040 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 21 January 2019 |
| 1.3.2000930 | Fix for adding routes to metadata on ipv6-enabled ENIs. | 2 January 2019 |
| 1.3.2000760 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 5 December 2018 |
| 1.3.2000630 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 9 November 2018 |
| 1.3.2000430.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 19 September 2018 |
| 1.3.200039.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | 15 August 2018 |
| 1.3.2000080 | Fixed minor issues. | |
| 1.3.610 | Fixed issue with redirecting output and errors to files from user data. | |
| 1.3.590 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | |
| 1.3.580 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | |
| 1.3.550 | Added a `-NoShutdown` option to enable Sysprep with no shutdown. | |
| 1.3.540 | Fixed minor issues. | |
| 1.3.530 | Fixed minor issues. | |
| 1.3.521 | Fixed minor issues. | |
| 1.3.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | |
| 1.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | |
| 1.1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-version-details.html) | |
| 1.1.1 | Initial release. | |