Use the EC2Launch v1 agent to perform tasks during EC2 Windows instance launch - Amazon Elastic Compute Cloud
EC2Launch tasksEC2Launch directory structureTelemetry

Use the EC2Launch v1 agent to perform tasks during EC2 Windows instance launch

EC2Launch is a set of Windows PowerShell scripts that replaced the EC2Config service on Windows Server 2016 and 2019 AMIs. Many of these AMIs are still available. EC2Launch v2 is the latest launch agent for all supported Windows versions, which replaces both EC2Config and EC2Launch. For more information, see Use the EC2Launch v2 agent to perform tasks during EC2 Windows instance launch.

Note

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.

  • 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.

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.

For more information about Windows Server 2019, see Compare Features in Windows Server Versions on Microsoft.com.

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.

  • Logs — Contains log files generated by 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: <Data>
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
More topics for EC2Launch