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

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.

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 Migrate to EC2Launch v2 with the migration tool, or you can manually install and configure the agent on Windows Server 2016 and 2019.

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.

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