Configuring a Windows Instance Using EC2Launch

EC2Launch is a set of Windows PowerShell scripts that replaces the EC2Config service on Windows Server 2016 and later AMIs.

Contents

EC2Launch Tasks
Installing the Latest Version of EC2Launch
Verify the EC2Launch Version
EC2Launch Directory Structure
Configuring EC2Launch
Using Sysprep with EC2Launch
EC2Launch Version History

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.
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 Working with Instance User Data.
Sets persistent static routes to reach the metadata service and 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 Updating 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.

Verify the EC2Launch Version

Use the following Windows PowerShell command to verify the installed version of EC2Launch.


PS C:\> Test-ModuleManifest -Path "C:\ProgramData\Amazon\EC2-Windows\Launch\Module\Ec2Launch.psd1" | Select Version

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.
Logs — Contains log files generated by scripts.

Configuring EC2Launch

After your instance has been initialized the first time, you can configure EC2Launch to run again and perform different start-up tasks.

Tasks

Configure Initialization Tasks
Schedule EC2Launch to Run on Every Boot
Initialize Drives and Map Drive Letters
Send Windows Event Logs to the EC2 Console
Send Windows Is Ready Message After A Successful Boot

Configure Initialization Tasks

Specify settings in the LaunchConfig.json file to enable or disable the following initialization tasks:

Set the computer name.
Set up new wallpaper.
Add DNS suffix list.
Extend the boot volume size.
Set the administrator password.

To configure initialization settings

On the instance to configure, open the following file in a text editor: C:\ProgramData\Amazon\EC2-Windows\Launch\Config\LaunchConfig.json.
Update the following settings as needed and save your changes. Provide a password in adminPassword only if adminPasswordtype is Specify.
```
{
  "setComputerName": false,
  "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.
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.
```
PS C:\> 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:

Open Windows PowerShell and run the following command:


PS C:\> C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 -SchedulePerBoot

Or, run the executable with the following command:
```
PS C:\> 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 changes will be made to the LaunchConfig.json the next time EC2Launch runs:

AdminPasswordType will be set back to DoNothing so that the password does not change on each boot.
HandleUserData will be set back to false unless the user data has persist set to true. For more information about user data scripts, see User Data Scripts in the Amazon EC2 User Guide.

Similarly, if you do not want your password reset on the next boot, you should set AdminPasswordType to DoNothing before rebooting.

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 performs this operation if the drives have not already been initialized and partitioned.

To map drive letters to volumes

Open the C:\ProgramData\Amazon\EC2-Windows\Launch\Config\DriveLetterMappingConfig.json file in a text editor.

Specify the following volume settings and save your changes:


{
  "driveLetterMapping": [
    {
      "volumeName": "sample volume",
      "driveLetter": "H"
    }
  ]
}

Open Windows PowerShell and use the following command to run the EC2Launch script that initializes the disks:
```
PS C:\> C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeDisks.ps1
```
To initialize the disks each time the instance boots, add the -Schedule flag as follows:
```
PS C:\> 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

On the instance, open the C:\ProgramData\Amazon\EC2-Windows\Launch\Config\EventLogConfig.json file in a text editor.

Configure the following log settings and save your changes:


{
  "events": [
    {
      "logName": "System",
      "source": "An event source (optional)",
      "level": "Error | Warning | Information",
      "numEntries": 3
    }
  ]
}

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.
```
PS C:\> 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.


PS C:\> C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\SendWindowsIsReady.ps1 -Schedule

Using Sysprep with EC2Launch

Sysprep simplifies the process of duplicating a customized installation of Windows Server 2016 and later. EC2Launch offers a default answer file and batch files for Sysprep that automate and secure the image-preparation process on your AMI. Modifying these files is optional. These files are located in the following directory by default: C:\ProgramData\Amazon\EC2-Windows\Launch\Sysprep.

Important

Do not use Sysprep to create an instance backup. Sysprep removes system-specific information. If you remove this information there might be unintended consequences for an instance backup.

The EC2Launch answer file and batch files for Sysprep include the following:

Unattend.xml: This is the default answer file. If you run SysprepInstance.ps1 or choose ShutdownWithSysprep in the user interface, the system reads the setting from this file.
BeforeSysprep.cmd: Customize this batch file to run commands before EC2Launch runs Sysprep.
SysprepSpecialize.cmd: Customize this batch file to run commands during the Sysprep specialize phase.

Running Sysprep with EC2Launch

On the full installation of Windows Server 2016 and later (with a desktop experience), you can run Sysprep with EC2Launch manually or by using the EC2 Launch Settings application.

To run Sysprep using the EC2Launch Settings application

In the Amazon EC2 console, locate or create a Windows Server 2016 or later AMI.
Launch a Windows instance from the AMI.
Connect to your Windows instance and customize it.
Search for and run the EC2LaunchSettings application. It is located in the following directory by default: C:\ProgramData\Amazon\EC2-Windows\Launch\Settings.
Select or clear options as needed. These settings are stored in the LaunchConfig.json file.
For Administrator Password, do one of the following:
- Choose 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.
- Choose Specify and type a password that meets the system requirements. The password is stored in LaunchConfig.json as clear text and is deleted after Sysprep sets the administrator password. If you shut down now, the password is set immediately. EC2Launch encrypts the password using the user's key.
- Choose DoNothing and specify a password in the unattend.xml file. If you don't specify a password in unattend.xml, the administrator account is disabled.
Choose Shutdown with Sysprep.

To manually run Sysprep using EC2Launch

In the Amazon EC2 console locate or create a Windows Server 2016 or later Datacenter edition AMI that you want to duplicate.
Launch and connect to your Windows instance.
Customize the instance.
Specify settings in the LaunchConfig.json file. This file is located in the C:\ProgramData\Amazon\EC2-Windows\Launch\Config directory by default.

For adminPasswordType, specify one of the following values:

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, EC2Lauch 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.
(Optional) Specify settings in unattend.xml and other configuration files. If plan to attend to the installation, then you don't need to make changes in these files. The files are located in the following directory by default: C:\ProgramData\Amazon\EC2-Windows\Launch\Sysprep.
In Windows PowerShell, run ./InitializeInstance.ps1 -Schedule. The script is located in the following directory, by default: C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts. This script schedules the instance to initialize during the next boot. You must run this script before you run the SysprepInstance.ps1 script in the next step.
In Windows PowerShell, run ./SysprepInstance.ps1. The script is located in the following directory by default: C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts.

You are logged off the instance and the instance shuts down. If you check the Instances page in the Amazon EC2 console, the instance state changes from running to stopping, and then to stopped. At this point, it is safe to create an AMI from this instance.

Updating metadata/KMS routes for Server 2016 and later when launching a custom AMI

To update metadata/KMS routes for Server 2016 and later when launching a custom AMI

Use EC2LaunchSettings GUI (C:\ProgramData\Amazon\EC2-Windows\Launch\Settings\Ec2LaunchSettings.exe) to shut down with Sysprep.
Or, shut down without Sysprep before creating an AMI. This sets the EC2 Launch Initialize tasks to run at the next boot, which will set routes based on the subnet being launched into.
Or, manually reschedule EC2 Launch initialize tasks before creating an AMI from PowerShell.

Important

Please take note of the default password reset behavior before rescheduling tasks.

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »