Configure a Windows instance using EC2Launch
EC2Launch is a set of Windows PowerShell scripts that replaced the EC2Config service on Windows Server 2016 and later AMIs. The latest launch service for all supported Windows Server versions is EC2Launch v2, which replaces both EC2Config and EC2Launch.
Contents
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 Work 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 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
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
.
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.
All EC2Launch directories inherit their permissions from C:\ProgramData
, with the exception of the following:
-
C:\ProgramData\Amazon\EC2-Windows\Launch\Module\Scripts
— This folder inherits all initial permissions fromC:\ProgramData
when it is created, but removes access for normal users toCreateFiles
in the directory.
Configure 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
Specify settings in the LaunchConfig.json
file to enable or
disable the following initialization tasks:
-
Set the computer name.
-
Set the monitor to always stay on.
-
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 ifadminPasswordtype
isSpecify
.{ "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 inLaunchConfig.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 inunattend.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.exeThen select
Run EC2Launch on every boot
. You can specify that your EC2 instanceShutdown without Sysprep
orShutdown with Sysprep
.
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 toDoNothing
so that the password does not change on each boot. -
HandleUserData
will be set back tofalse
unless the user data haspersist
set totrue
. 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.ps1To 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 -ScheduleThe 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