Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

EC2Launch v2 settings

This section contains information about how to configure settings for EC2Launch v2.

Change settings using the EC2Launch v2 settings dialog box

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:

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

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.

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

get-agent-config

Prints agent-config.yml in the format specified (JSON or YAML). If no format is specified, agent-config.yml is printed in the format previously specified.

Example

ec2launch get-agent-config -f json

Example 2

The following PowerShell commands show how to edit and save the agent-config file in JSON format.

$config = ec2launch get-agent-config --format json | ConvertFrom-Json
$jumboFrame =@"
{
   "task": "enableJumboFrames"
}
"@
$config.config | %{if($_.stage -eq 'postReady'){$_.tasks += (ConvertFrom-Json -InputObject $jumboFrame)}}
$config | ConvertTo-Json -Depth 6 | Out-File -encoding UTF8 $env:ProgramData/Amazon/EC2Launch/config/agent-config.yml

Usage

ec2launch get-agent-config [flags]

Flags

-h, --help

help for get-agent-config

-f, --format string

output format of agent-config file: json, yaml

list-volumes

Lists all of the storage volumes attached to the instance, including ephemeral and EBS volumes.

Example

ec2launch list-volumes

Usage

ec2launch list-volumes

Flags

-h, --help

help for list-volumes

reset

Deletes the .run-once 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

-b, --block

blocks the reset command until the service stops. If the reset command is run with the --block flag as part of the executeScript task, the detach argument must be set to true. For more information, see Example 4 under executeScript .

-c, --clean

cleans instance logs before reset

-h, --help

help for reset

run

Runs EC2Launch v2.

Example

ec2launch run

Usage

ec2launch run [flags]

Flags

-h, --help

help for run

status

Gets the status of the EC2Launch service. Optionally blocks the process until the service is finished. The process exit code determines the service state:

Example:

ec2launch status -b

Usage

ec2launch status [flags]

Flags

-b,--block

blocks the process until the services finishes running

-h,--help

help for status

sysprep

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

Example:

ec2launch sysprep

Usage

ec2launch sysprep [flags]

Flags

-b,--block

blocks the sysprep command until the service stops. If the reset command is run with the --block flag as part of the executeScript task, the detach argument must be set to true. For more information, see Example 4 under executeScript .

-c,--clean

cleans instance logs before sysprep

-h,--help

help for Sysprep

-s,--shutdown

shuts down the instance after sysprep

validate

Validates the agent-config file C:\ProgramData\Amazon\EC2Launch\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.

Syntax

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

Inputs

EC2Launch v2 task configuration

This section includes the configuration schema, tasks, details, and examples for agent-config.yml and user data.

Schema: agent-config.yml

The structure of the agent-config.yml file is shown below. Note that a task cannot be repeated in the same stage. For task properties, see the task descriptions that follow.

Document structure: agent-config.yml

JSON

{
    "version": "1.0",
    "config": [
        {
            "stage": "string",
            "tasks": [
                {
                    "task": "string",
                    "inputs": {
                        ...
                    }
                },
                ...
            ]
        },
        ...
    ]
}

YAML

version: 1.0
config:
- stage: string
  tasks:
  - task: string
    inputs:
      ...
  ...
...

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: 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

Schema: user data

The following JSON and YAML examples show the document structure for user data. Amazon EC2 parses each task named in the tasks array that you specify in the document. Each task has its own set of properties and requirements. For details, see the Task definitions.

Document structure: user data

JSON

{
    "version": "1.1",
    "tasks": [
        {
            "task": "string",
            "inputs": {
                ...
            },
        },
        ...
    ]
}

YAML

version: 1.1
tasks:
- task: string
  inputs:
    ...
...

Change log: user data

The following table lists changes for user data, and cross-references them to the EC2Launch v2 agent version that applies.

* When used with the default agent-congif.yml file.

Example: user data

For more information about user data, see Run commands on your Windows instance at launch.

The following example shows settings for user data.

version: 1.1
tasks:
- task: executeScript
  inputs:
  - frequency: always
    type: powershell
    runAs: localSystem
    content: |-
      New-Item -Path 'C:\PowerShellTest.txt' -ItemType File

The following format is compatible with the previous version of this service. It is run as an executeScript task in the UserData stage. To mimic the behavior of the previous version, it will be set to run as a detached process.

<powershell>
  $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
  New-Item $file -ItemType file
</powershell>
<persist>true</persist>

Task definitions

Each task has its own set of properties and requirements. For details, see the individual tasks that you want to include in your document.

activateWindows

Activates Windows against a set of Amazon KMS servers. Activation is skipped if the instance is detected as Bring-Your-Own-License (BYOL).

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

The following example shows how to enable OpenSSH on an instance, and to add the public key for the instance to the authorized keys folder. This configuration works only on instances running Windows Server 2019 and later versions.

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

The following example shows how to run an executable file that is already on an instance.

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

Example 2

The following example shows how to run an executable file that is already on an instance. This configuration installs a VLC .exe file that is present on the C: drive of the instance. /L=1033 and /S are VLC arguments passed as a string list with the VLC .exe file.

task: executeProgram
	inputs:
	- frequency: always
	  path: C:\vlc-3.0.11-win64.exe 
	  arguments: ['/L=1033','/S']
	  runAs: localSystem

executeScript

Runs 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. This parameter is not supported when type is set to batch.

content: (string) contents of the script

runAs: (string) one of admin or localSystem

detach: (Boolean) defaults to false. Set to true if the script should run in detached mode, where EC2Launch runs it concurrently with other tasks. Script exit codes (including 3010) have no effect when detach is set to true.

Example

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

Example 2

The following example shows how to run a PowerShell script on an EC2 instance. This configuration creates a text file in the C: drive.

task: executeScript
	inputs:
	- frequency: always
	  type: powershell
	  runAs: admin
	  content: |-
	    New-Item -Path 'C:\PowerShellTest.txt' -ItemType File
	    Set-Content 'C:\PowerShellTest.txt' "hello world"

Example 3

The following example shows an idempotent script that reboots an instance multiple times.

task: executeScript
	inputs:
	- frequency: always
	  type: powershell
	  runAs: localSystem
	  content: |-
	    $name = $env:ComputerName
	     if ($name -ne $desiredName) {
	       Rename-Computer -NewName $desiredName
	       exit 3010
	     }
	     $domain = Get-ADDomain
	     if ($domain -ne $desiredDomain) 
	     {
	       Add-Computer -DomainName $desiredDomain
	       exit 3010
	     }
	    $telnet = Get-WindowsFeature -Name Telnet-Client
	    if (-not $telnet.Installed)
	    {
	      Install-WindowsFeature -Name "Telnet-Client"
	      exit 3010 
	    }

Example 4

You can run EC2Launch v2 CLI commands as part of scripts. reset and sysprep commands must include the --block flag because they depend on the agent finishing first. When the --block flag is used, the detach argument for this task must be set to true. A deadlock results when you use the --block flag in a non-detached script. The commands detect the potential deadlock and exit with an error. The following example shows a script that resets the agent state after the agent finishes running.

task: executeScript
	inputs:
	- frequency: always
	  type: powershell
	  runAs: localSystem
	  detach: true
	  content: |-
	    & 'C:\Program Files\Amazon\EC2Launch\ec2launch.exe' reset -c -b

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. A volume is considered empty if the first 4 KiB of a volume are empty, or if a volume does not have a Windows-recognizable drive layout. The volume letter field is always applied when this task runs, regardless of whether the drive is already 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 1

The following example shows inputs for the InitializeVolume task to set selected volumes to be initialized.

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

Example 2

The following example shows how to initialize EBS volumes that are attached to an instance. This configuration will initialize all empty EBS volumes that are attached to the instance. If a volume is not empty, then it will not be initialized.

task: initializeVolume
	inputs:
	  initialize: all  

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

data: (string) stores data if the type field is static

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 a custom string or, if hostName is not specified, the private IPv4 address.

Frequency — always

AllowedStages — [PostReady, UserData]

Inputs —

hostName: (string) optional host name, which must be formatted as follows.

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

Example

task: setHostName
	inputs:
	  reboot: true

setWallpaper

Creates the setwallpaper.lnk shortcut file in the startup folder of each existing user except for Default User. This shortcut file runs when the user logs in for the first time after instance boot. It sets up the instance with a custom wallpaper that displays the instance attributes.

The shortcut file path is:

$env:SystemDrive/Users/<user>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk

Stages: You can configure wallpaper during the PreReady, and UserData stages.

Frequency: always

Wallpaper configuration

You can use the following settings to configure your wallpaper.

Example

The following example shows wallpaper configuration inputs that set the file path for the wallpaper background image, along with instance tags named Tag 1 and Tag 2, and attributes that include the host name, instance ID, and private and public IP addresses for the instance.

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

startSsm

Starts the Systems Manager (SSM) service following Sysprep.

Frequency — always

AllowedStages — [PostReady, UserData]

Inputs — none

Example

task: startSsm

sysprep

Resets the service state, updates unattend.xml, disables RDP, and runs Sysprep. This task runs only after all other tasks are completed.

Frequency — once

AllowedStages — [UserData]

Inputs —

clean: (boolean) cleans instance logs before running Sysprep

shutdown: (boolean) shuts down the instance after running Sysprep

Example

task: sysprep
	inputs:
	  clean: true
	  shutdown: true

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

EC2Launch v2 exit codes and reboots

You can use EC2Launch v2 to define how exit codes are handled by your scripts. By default, the exit code of the last command that is run in a script is reported as the exit code for the entire script. For example, if a script includes three commands and the first command fails but the following ones succeed, the run status is reported as success because the final command succeeded.

If you want a script to reboot an instance, then you must specify exit 3010 in your script, even when the reboot is the last step in your script. exit 3010 instructs EC2Launch v2 to reboot the instance and call the script again until it returns an exit code that is not 3010, or until the maximum reboot count has been reached. EC2Launch v2 permits a maximum of 5 reboots per task. If you attempt to reboot an instance from a script by using a different mechanism, such as Restart-Computer, then the script run status will be inconsistent. For example, it may get stuck in a restart loop or not perform the restart.

If you are using an XML user data format that is compatible with older agents, the user data may run more times than you intend it to. For more information, see Service runs user data more than once in the Troubleshooting section.

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 Create a custom Windows AMI.