Menu
Amazon Elastic Compute Cloud
User Guide for Windows Instances

Configuring a Windows Instance Using EC2Launch

To accommodate the change from .NET Framework to .NET Core, the EC2Config service has been deprecated on Windows Server 2016 AMIs and replaced by EC2Launch. EC2Launch is a bundle of Windows PowerShell scripts that perform many of the tasks performed by the EC2Config service.

For more information about Windows Server 2016, see What's New with Windows Server 2016 and Getting Started with Nano Server on Microsoft.com.

Overview of EC2Launch

EC2Launch is a set of Windows PowerShell scripts that replaces the EC2Config service on Windows Server 2016 AMIs. EC2Launch performs the following tasks by default during the initial instance boot:

  • Sets up new wallpaper that renders information about the instance. (Doesn't apply to Nano Server.)

  • Sets the computer name.

  • Sends instance information to the Amazon EC2 console.

  • Sends the RDP certificate thumbprint to the EC2 console. (Doesn't apply to Nano Server.)

  • 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 Configuring Instances with User Data.

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 AMIs with the following root directory and sub-directories:

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.

  • Root directory: C:\ProgramData\Amazon\EC2-Windows\Launch

  • Scripts directory: This directory includes the PowerShell scripts that make up EC2Launch.

  • Module directory: This directory includes the Ec2Launch PowerShell module for building scripts related to Amazon EC2.

  • Config directory: This directory includes the script configuration files that you can customize, as described later.

  • Sysprep directory: This directory includes Sysprep resources.

  • Settings directory: This directory includes an application for the Sysprep graphical user interface.

  • Logs directory: This directory includes log files generated by scripts.

Installing 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 following directory: C:\ProgramData\Amazon\EC2-Windows\Launch\Config.

  2. Download EC2Launch.zip from the following location to a directory on the instance:

    https://s3.amazonaws.com/ec2-downloads-windows/EC2Launch/latest/EC2-Windows-Launch.zip

  3. Download the Install.ps1 PowerShell script from the following location to the same directory where you downloaded EC2Launch.zip:

    https://s3.amazonaws.com/ec2-downloads-windows/EC2Launch/latest/install.ps1

  4. Run Install.ps1

  5. Replace your backup of the EC2Launch configuration file in the C:\ProgramData\Amazon\EC2-Windows\Launch\Config directory.

Configuring EC2Launch

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

Configure Initialization Tasks

Enable or disable tasks in the LaunchConfig.json configuration file to change initialization tasks like the following:

  • Set the computer name.

  • Set up new wallpaper.

  • Add DNS suffix list.

  • Extend the boot volume size.

  • Specify the administrator password.

Note

If you want to change the default setting for the administrator password, you must specify one of the following options.

  • Random: EC2Launch generates a password, encrypts it with the user's key, and displays the encrypted password to the console.

  • Specify: Specify a password that meets your system and organizational requirements. EC2Launch encrypts the password and sends it to the EC2 console so you can retrieve it later, if necessary.

  • DoNothing: Choose this option if you entered a password in an unattend.xml file for an unattended installation. If you are not using an unattend.xml file, choose one of the other options. If you choose this option and don't specify a password in an unattend.xml file, the system sets the password to match the password of the parent AMI.

To configure initialization settings

  1. On the instance you want to configure, open the following file in a simple text editor.

    C:\ProgramData\Amazon\EC2-Windows\Launch\Config\LaunchConfig.json

  2. Type true, false, or a specific setting beside the tasks that you want to configure. For example:

    Copy
    { "setComputerName": false, "setWallpaper": true, "addDnsSuffixList": true, "extendBootVolumeSize": true, "adminPasswordType": "Random, Specify, DoNothing", "adminPassword": "Password that adheres to your security policy." }

    Note

    Enter a password only if you entered Specify for adminPasswordtype.

  3. Save your changes.

  4. In Windows PowerShell, run the following command so that the system schedules the script to run as a Windows Scheduled Task.

    Copy
    C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 –Schedule

    The script will execute only one time during the next boot and then disable these tasks from running again.

Initialize Drives and Drive Letter Mappings

Specify settings in the DriveLetterMapping.json file to initialize and format drives and map drive letters to EBS 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

  1. On the instance you want to configure, open the following file in a simple text editor.

    C:\ProgramData\Amazon\EC2-Windows\Launch\Config\DriveLetterMapping.json

  2. Specify the volume settings as in the following example:

    Copy
    { "driveLetterMapping": [ { "volumeName": "Temporary Storage 0", "driveLetter": "H" } ] }
  3. Save your changes.

  4. In Windows PowerShell, run the following command so that the system schedules the script to run as a Windows Scheduled Task.

    Copy
    C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeDisks.ps1

    The script will execute once when the instance boots. If you need to initialize disks each time the instance starts (an option that is backwards compatible with EC2Config) run the following command:

    Copy
    C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeDisks.ps1 –Schedule

    The script will execute each time the instance boots.

Note

You can also initialize attached disks at the instance launch by adding the following path to the PowerShell script in Amazon EC2 user data.

Copy
<powershell> C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeDisks.ps1 </powershell>

Send Windows Event Logs to the EC2 Console

Specify settings in the EventLogFilter.json configuration file to send Windows Event logs to EC2 console logs.

To configure settings to send Windows Event logs

  1. On the instance you want to configure, open the following file in a simple text editor.

    C:\ProgramData\Amazon\EC2-Windows\Launch\Config\EventLogFilter.json

  2. Configure the log settings as in the following example:

    Copy
    { "events": [ { "logName": "System", "source": "An event source (optional)", "level": "Error", "numEntries": 3 } ] }
  3. Save your changes.

  4. In Windows PowerShell, run the following command so that the system schedules the script to run as a Windows Scheduled Task.

    Copy
    C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\SendEventLogsToConsole.ps1 –Schedule

    The logs can take three minutes or more to appear in the EC2 console logs. The script will execute each time the instance boots.

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 you want to configure, open Windows PowerShell and run the following command. The system schedules the script to run as a Windows Scheduled Task.

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

The script will execute each time the instance boots.

Using Sysprep with EC2Launch

Sysprep simplifies the process of duplicating a customized installation of Windows Server 2016. 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

Sysprep is not supported on Windows Server 2016 Nano Server. Also, don't 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 execute 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 executes 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 (with a desktop experience), you can run Sysprep with EC2Launch manually or by using the EC2 Launch Settings application.

Note

Sysprep is not supported on the Nano Server installation.

Use one of the following procedures to create a standardized AMI using Sysprep and EC2Launch.

To run Sysprep using the EC2Launch Settings application

  1. In the Amazon EC2 console locate or create a Windows Server 2016, Standard edition AMI that you want to duplicate.

  2. Launch and connect to your Windows instance.

  3. Customize it.

  4. Search for and run the EC2LaunchSettings application. It is located in the following directory, by default: C:\ProgramData\Amazon\EC2-Windows\Launch\Settings.

    
                                EC2 Launch Settings application
  5. Specify the desired options in the application. The options you specify configure the LaunchConfig.json file.

  6. Select an option for the Administrator password.

    • Random: EC2Launch generates a password, encrypts it with the user's key, and displays the encrypted password to the console. The system disables this setting after the first launch so that this password persists if the instance is rebooted or stopped and started.

    • Specify: Specify a password that meets your system and organizational requirements. If you specify a password that doesn't meet the system requirements, the system will generate a random password. The password is stored in LaunchConfig.json file as clear text and is deleted once the password is set on the next boot. When Sysprep runs, it sets the administrator password. If you shut down now, the password is set immediately. When the service starts again, the administrator password is removed. You can retrieve the password from the EC2 console.

    • DoNothing: Choose this option if you entered a password in an unattend.xml file for an unattended installation. If you are not using an unattend.xml file, choose one of the other options. If you choose this option and don't specify a password in an unattend.xml file, the system sets the password to match the password of the parent AMI.

      For more information about administrator passwords and Sysprep unattend.xml files, see AdministratorPassword.

      Note

      You can choose this option if you plan to choose Shutdown without Sysprep in the next step.

  7. Choose Shutdown with Sysprep to begin creating a standardized AMI.

To manually run Sysprep using EC2Launch

  1. In the Amazon EC2 console locate or create a Windows Server 2016, Standard edition AMI that you want to duplicate.

  2. Launch and connect to your Windows instance.

  3. Customize it.

  4. Specify settings in the LaunchConfig.json file. The file is located in the following directory, by default: C:\ProgramData\Amazon\EC2-Windows\Launch\Config.

    For Administrator password, choose one of the following:

    • Random: EC2Launch generates a password, encrypts it with the user's key, and displays the encrypted password to the console. The system disables this setting after the first launch so that this password persists if the instance is rebooted or stopped and started.

    • Specify: Specify a password that meets your system and organizational requirements. If you specify a password that doesn't meet the system requirements, the system will generate a random password. The password is stored in LaunchConfig.json file as clear text and is deleted once the password is set on the next boot. When Sysprep runs, it sets the administrator password. If you shut down now, the password is set immediately. When the service starts again, the administrator password is removed. You can retrieve the password from the EC2 console.

    • DoNothing: Choose this option if you entered a password in an unattend.xml file for an unattended installation. If you are not using an unattend.xml file, choose one of the other options. If you choose this option and don't specify a password in an unattend.xml file, the system sets the password to match the password of the parent AMI.

      For more information about administrator passwords and Sysprep unattend.xml files, see AdministratorPassword.

      Note

      You can choose this option if you plan to choose Shutdown without Sysprep in the next step.

  5. Specify settings in the unattend.xml and other batch files, if you want. If plan to attended 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.

  6. 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 execute the SysprepInstance.ps1 script in the next step.

  7. 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 finally to stopped. At this point, it's safe to create an AMI from this instance.