EC2Launch v2 settings - Amazon Elastic Compute Cloud

EC2Launch v2 settings

This section contains information about how to use the EC2Launch v2 dialog box to enable or disable EC2Launch settings, the EC2Launch directory structure, CLI commands to update EC2Launch settings, details to manually configure the agent-config.yml file, and information about how EC2Launch uses Sysprep.

Change settings using the EC2Launch v2 settings dialog box

The following procedure describes how to use the EC2Launch v2 settings dialog box to enable or disable settings.

  1. Launch and connect to your Windows instance.

  2. From the Start menu, choose All Programs, and then navigate to EC2Launch settings.

    
                            EC2 Launch settings application
  3. On the General tab of the EC2Launch settings dialog box, you can enable or disable the following settings.

    1. Set Computer Name

      If this setting is enabled (it is disabled by default), the host name is compared to the current internal IP address at each boot. If the host name and the internal IP address do not match, the host name is reset to contain the internal IP address, and then the system reboots to pick up the new host name. To set your own host name, or to prevent your existing host name from being modified, do not enable this setting.

    2. Extend Boot Volume

      This setting dynamically extends Disk 0/Volume 0 to include any unpartitioned space. This can be useful when the instance is booted from a root device volume that has a custom size.

    3. Set Administrator Account

      When enabled, you can set the username and password attributes for the administrator account that is created on your local machine. If this feature is not enabled, an administrator account is not created on the system following Sysprep. Provide a password in adminPassword only if adminPasswordtype is Specify.

      The password types are defined as follows:

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

      2. Specify

        EC2Launch uses the password that you specify in adminPassword. If the password does not meet the system requirements, EC2Launch generates a random password instead. The password is stored in agent-config.yml as clear text and is deleted after Sysprep sets the administrator password. EC2Launch encrypts the password using the user's key.

      3. DoNothing

        EC2Launch uses the password that you specify in the unattend.xml file. If you don't specify a password in unattend.xml, the administrator account is disabled.

    4. Start SSM Service

      When selected, the Systems Manager service is enabled to start following Sysprep. EC2Launch v2 performs all of the tasks described earlier, and the SSM Agent processes requests for Systems Manager capabilities, such as Run Command and State Manager.

      You can use Run Command to upgrade your existing instances to use the latest version of the EC2Launch v2 service and SSM Agent. For more information, see Update SSM Agent by using Run Command in the AWS Systems Manager User Guide.

    5. Optimize ENA

      When selected, ENA settings are configured to ensure that ENA Receive Side Scaling and Receive Queue Depth settings are optimized for AWS. For more information, see Configure RSS CPU Affinity.

    6. Enable SSH

      This setting enables OpenSSH for later Windows versions to allow for remote system administration.

    7. Enable Jumbo Frames

      Select to enable Jumbo Frames. Jumbo Frames can have unintended effects on your network communications, so ensure you understand how Jumbo Frames will impact your system before enabling. For more information about Jumbo Frames, see Jumbo frames (9001 MTU).

    8. Prepare for Imaging

      Select whether you want your EC2 instance to shut down with or without Sysprep. When you want to run Sysprep with EC2Launch v2, choose Shutdown with Sysprep.

  4. On the DNS Suffix tab, you can select whether you want to add a DNS suffix list for DNS resolution of servers running in EC2, without providing the fully qualified domain name. DNS suffixes can contain the variables $REGION and $AZ. Only suffixes that do not already exist will be added to the list.

    
                            EC2 Launch settings application
  5. On the Wallpaper tab, you can enable the display of selected instance details on the wallpaper. You also have the option of choosing a custom image. The details are generated each time that you log in. Clear the check box to remove instance details from the wallpaper.

    
                            EC2 Launch settings application
  6. On the Volumes tab, select whether you want to initialize the volumes that are attached to the instance. Enabling sets drive letters for any additional volumes and extends them to use available space. If you select All, all of the storage volumes are initialized. If you select Devices, only devices that are specified in the list are initialized. You must enter the device for each device to be initialized. Use the devices listed on the EC2 console, for example, xvdb or /dev/nvme0n1. Name, Letter, and Partition are optional fields. If no value is specified for Partition, storage volumes larger than 2 TB are initialized with the GPT partition type, and those smaller than 2 TB are initialized with the MBR partition type. If devices are configured, and a non-NTFS device either contains a partition table, or the first 4 KB of the disk contain data, then the disk is skipped and the action logged.

    
                            EC2 Launch settings application

The following is an example configuration YAML file created from the settings entered in the EC2Launch dialog.

version: 1.0 config: - stage: boot tasks: - task: extendRootPartition - stage: preReady tasks: - task: activateWindows inputs: activation: type: amazon - task: setDnsSuffix inputs: suffixes: - $REGION.ec2-utilities.amazonaws.com - task: setAdminAccount inputs: password: type: random - task: setWallpaper inputs: path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg attributes: - hostName - instanceId - privateIpAddress - publicIpAddress - instanceSize - availabilityZone - architecture - memory - network - stage: postReady tasks: - task: startSsm

EC2Launch v2 directory structure

EC2Launch v2 should be installed in the following directories:

  • Service binaries: %ProgramFiles%\Amazon\EC2Launch

  • Service data (settings, log files, and state files): %ProgramData%\Amazon\EC2Launch

Note

By default, Windows hides files and folders under C:\ProgramData. To view EC2Launch v2 directories and files, you must either enter the path in Windows Explorer or change the folder properties to show hidden files and folders.

The %ProgramFiles%\Amazon\EC2Launch directory contains binaries and supporting libraries. It includes the following subdirectories:

  • settings

    • EC2LaunchSettingsUI.exe — user interface for modifying the agent-config.yml file

    • YamlDotNet.dll — DLL for supporting some operations in the user interface

  • tools

    • ebsnvme-id.exe — tool for examining the metadata of the EBS volumes on the instance

    • AWSAcpiSpcrReader.exe — tool for determining the correct COM port to use

    • EC2LaunchEventMessage.dll — DLL for supporting the Windows event logging for EC2Launch.

  • EC2Launch.exe — main EC2Launch executable

  • EC2LaunchAgentAttribution.txt — attribution for code used within EC2 Launch

The %ProgramData%\Amazon\EC2Launch directory contains the following subdirectories. All of the data produced by the service, including logs, configuration, and state, is stored in this directory.

  • config — Configuration

    The service configuration file is stored in this directory as agent-config.yml. This file can be updated to modify, add, or remove tasks run by the service by default.

  • log — Instance logs

    Logs for the service (agent.log), console (console.log), performance (bench.log), and errors (error.log) are stored in this directory. Log files are appended to on subsequent executions of the service.

  • state — Service state data

    The state that the service uses to determine which tasks should run is stored here. There is a .run- once file that indicates whether the service has already run after Sysprep (so tasks with a frequency of once will be skipped on the next run). This subdirectory includes a state.json and previous- state.json to track the status of each task.

  • sysprep — Sysprep

    This directory contains files that are used to determine which operations to perform by Sysprep when it creates a customized Windows AMI that can be reused.

Configure EC2Launch v2 using the CLI

You can use the Command Line Interface (CLI) to configure your EC2Launch settings and manage the service. The following section contains descriptions and usage information for the CLI commands that you can use to manage EC2Launch v2.

collect-logs

Collects log files for EC2Launch, zips the files, and places them in a specified directory.

Example

ec2launch collect-logs -o C:\Mylogs.zip

Usage

ec2launch collect-logs [flags]

Flags

-h, --help

help for collect-logs

-o, --output string

path to zipped output log files

reset

Deletes the .runonce file so that tasks specified to run once will run on the next execution; optionally deletes the service and sysprep logs.

Example

ec2launch reset -c

Usage

ec2launch reset [flags]

Flags

-c, --clean

cleans instance logs before reset

-h, --help

help for reset

run

Deletes the .runonce file so that tasks specified to run once will run on the next execution; optionally deletes the service and sysprep logs.

Example

ec2launch run

Usage

ec2launch run [flags]

Flags

-h, --help

help for reset

sysprep

Resets the service state, updates unattend.xml, disables RDP, and executes Sysprep.

Example:

ec2launch sysprep

Usage

ec2launch sysprep [flags]

Flags

-c,--clean

cleans instance logs before Sysprep

-h,--help

help for Sysprep

-s,--shutdown

shuts down the instance after Sysprep (default true)

validate

Validates the agent-config file C:\ProgramData\Amazon\EC2LaunchAgent\config\agent-config.yml.

Example

ec2launch validate

Usage

ec2launch validate [flags]

Flags

-h , --help

help for validate

version

Gets the executable version.

Example

ec2launch version

Usage

ec2launch version [flags]

Flags

-h, --help

help for version

wallpaper

Sets new wallpaper to the wallpaper path that is provided (.jpg file), and displays the selected instance details.

Example

ec2launch wallpaper -- path="C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg" -- attributes=hostName,instanceId,privateIpAddress,publicIpAddress,instanc eSize,availabilityZone,architecture,memory,network

Usage

ec2launch wallpaper [flags]

Flags

--attributes strings

wallpaper attributes

-h, --help

help for wallpaper

-p, --path string

wallpaper file path

EC2Launch v2 task configuration

The configuration tasks and details for configuring the agent-config.yml file are as follows.

activateWindows

Activates Windows against a set of KMS servers.

Frequency — once

AllowedStages[PreReady]

Inputs

activation: (map)

type: (string) activation type to use, set to amazon

Example

task: activateWindows inputs: - activation type: amazon

enableJumboFrames

Enables Jumbo Frames, which increase the maximum transmission unit (MTU) of the network adapter. For more information, see Jumbo frames (9001 MTU).

Frequency — always

AllowedStages[PostReady, UserData]

Inputs — none

Example

task: enableJumboFrames

enableOpenSsh

Enables Windows OpenSSH and adds the public key for the instance to the authorized keys folder.

Frequency — once

AllowedStages[PreReady, UserData]

Inputs — none

Example

task: enableOpenSsh

executeProgram

Executes a program with optional arguments and a specified frequency.

Frequency — see Inputs

AllowedStages[PostReady, UserData]

Inputs

frequency: (string) one of once or always

path: (string) path to the executable

arguments: (list of strings) list of string arguments to pass to the executable

runAs: (string) must be set to localSystem

Example

task: executeProgram inputs: - frequency: always path: C:\Users\Administrator\Desktop\setup.exe arguments: [‘—quiet']

executeScript

Executes a script with optional arguments and a specified frequency.

Frequency — see Inputs

AllowedStages[PostReady, UserData]

Inputs

frequency: (string) one of once or always

type: (string) one of batch or powershell

arguments: (list of strings) list of string arguments to pass to the shell

contents: (string) contents of the script

runAs: (string) one of admin or localSystem

Example

task: executeScript inputs: - frequency: always type: powershell content: | Get-Process | Out-File -FilePath .\Process.txt runAs: localSystem

extendRootPartition

Extends the root volume to use all of the available space on the disk.

Frequency — once

AllowedStages[Boot]

Inputs — none

Example

task: extendRootParitition

initializeVolume

Initializes volumes attached to the instance so that they are activated and partitioned. Any volumes that are detected as not empty are not initialized.

Frequency — always

AllowedStages[PostReady, UserData]

Inputs

initialize: (string) type of initialization strategy to use; one of all or devices

devices: (list of maps)

device: device identifier used when creating the instance; some examples are xvdb, xvdf, or /dev/nvme0n1

name: (string) drive name to assign

letter: (string) drive letter to assign

partition: (string) partitioning type to use; one of mbr or gpt

Example

task: initializeVolume inputs: initialize: devices devices: - device: xvdb name: MyVolumeOne letter: D partition: mbr - device: /dev/nvme0n1 name: MyVolumeTwo letter: E partition: gpt

The following examples show possible inputs for the InitializeVolume task to set all volumes to be initialized, and to set selected volumes to be initialized.

Example 1

initializeVolume: initialize: all

Example 2

initializeVolume: initialize: devices devices: - device: xvda name: First Volume Name letter: D partition: mbr - device: /dev/nvme0n1 name: Second Volume Name letter: E partition: gpt - device: xvdc name: Volume Next Available Letter - device: xvde

optimizeEna

Optimizes ENA settings based on the current instance type; might reboot the instance.

Frequency — always

AllowedStages[PostReady, UserData]

Inputs — none

Example

task: optimizeEna

setAdminAccount

Sets attributes for the default administrator account that is created on the local machine.

Frequency — once

AllowedStages[PreReady]

Inputs

name: (string) name of the administrator account

password: (map)

type: (string) strategy to set the password, either as static, random, or doNothing

doNothing: (string) stores data depending on the field type

data

Example

task: setAdminAccount inputs: name: Administrator password: type: random

setDnsSuffix

Adds DNS suffixes to the list of search suffixes. Only suffixes that do not already exist are added to the list.

Frequency — always

AllowedStages[PreReady]

Inputs

suffixes: (list of strings) list of one or more valid DNS suffixes; valid substitution variables are $REGION and $AZ

Example

task: setDnsSuffix inputs: suffixes: - $REGION.ec2-utilities.amazonaws.com

setHostName

Sets the hostname of the computer to the private IPv4 address.

Frequency — always

AllowedStages[PostReady, UserData]

Inputs

reboot: (boolean) denotes whether a reboot is permitted when the hostname is changed

Example

task: setHostName inputs: reboot: true

setWallpaper

Sets up the instance with custom wallpaper that displays instance attributes.

Frequency — always

AllowedStages[PreReady, UserData]

Inputs

path: (string) path to a local .jpg file to use as the wallpaper image

attributes: (list of strings) list of attributes to add to the wallpaper; one of hostName, instanceId, privateIpAddress, publicIpAddress, instanceSize, availabilityZone, architecture, memory, or network

Example

task: setWallpaper inputs: path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg attributes: - hostName - instanceId - privateIpAddress - publicIpAddress

startSsm

Frequency — always

AllowedStages[PostReady, UserData]

Inputs — none

Example

task: startSsm

writeFile

Writes a file to a destination.

Frequency — see Inputs

AllowedStages[PostReady, UserData]

Inputs

frequency: (string) one of once or always

destination: (string) path to which to write the content

content: (string) text to write to the destination

Example

task: writeFile inputs: - frequency: once destination: C:\Users\Administrator\Desktop\booted.txt content: Windows Has Booted

Example: agent-config.yml

The following example shows settings for the agent-config.yml configuration file.

version: 1.0 config: - stage: boot tasks: - task: extendRootPartition - stage: preReady tasks: - task: setDnsSuffix inputs: suffixes: - test1 - domain.test2 - $AZ.test3 - $REGION.domain.test4 - task: enableOpenSSH - task: setAdminAccount inputs: name: Admin password: type: static data: Demo - task: setWallpaper inputs: path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg attributes: - hostName - instanceId - privateIpAddress - publicIpAddress - instanceSize - availabilityZone - architecture - memory - network - stage: postReady tasks: - task: optimizeENA - task: startSSM - task: setHostName inputs: reboot: true - task: writeFile inputs: - frequency: always destination: C:\test.txt content: echo hello - task: executeScript inputs: - frequency: always type: powershell arguments: scriptarguments content: |- $file = "C:\Demo.txt" if(!(Test-Path $file -PathType Leaf)){ New-Item $file -ItemType file } Add-Content $file (Get-Date).ToString("MM-dd-yy-hh-mm") runAs: localSystem - frequency: once type: powershell content: |- $file = "C:\Demo2.txt" if(!(Test-Path $file -PathType Leaf)){ New-Item $file -ItemType file } Add-Content $file (Get-Date).ToString("MM-dd-yy-hh-mm") runAs: localSystem - task: executeProgram inputs: - frequency: always path: c:\temp\abc.exe arguments: - arg1 - arg2 - arg3 - frequency: once path: c:\temp\abc2.exe arguments: - arg1 - arg2 - arg3 - task: initializeVolume inputs: initialize: devices devices: - device: xvda name: First Volume Name letter: D partition: mbr - device: /dev/nvme0n1 name: Second Volume Name letter: E partition: gpt - device: xvdc name: Volume Next Available Letter - device: xvde

Example: user-data.yml

The following example shows settings for the user-data.yml configuration file.

version: 1.0 tasks: - task: executeScript inputs: - frequency: always type: powershell content: |- New-Item -Path 'C:\PowerShellTest.txt' -ItemType File Old format that is compatible with older version of service: <powershell> $file = $env:SystemRoot + "\Temp" + (Get- Date).ToString("MM-dd-yy-hh-mm") New-Item $file -ItemType file </powershell> <persist>true</persist>

EC2Launch v2 and Sysprep

The EC2Launch v2 service runs Sysprep, a Microsoft tool that enables you to create a customized Windows AMI that can be reused. When EC2Launch v2 calls Sysprep, it uses the files in %ProgramData%\Amazon\EC2Launch to determine which operations to perform. You can edit these files indirectly using the EC2Launch settings dialog box, or directly using a YAML editor or a text editor. However, there are some advanced settings that aren't available in the EC2Launch settings dialog box, so you must edit those entries directly.

If you create an AMI from an instance after updating its settings, the new settings are applied to any instance that's launched from the new AMI. For information about creating an AMI, see Creating a custom Windows AMI.